Uptime Kuma 설치 및 가용성 모니터링 가이드
Docker로 Uptime Kuma v2를 설치하고 HTTP 점검, 알림, 상태 페이지를 설정합니다. 업그레이드 전 SQLite 볼륨 백업 방법도 다룹니다.
VPC 안에 설치한 Uptime Kuma에서는 주문 API가 정상으로 표시되는데, 고객은 공개 게이트웨이에서 오류를 겪을 수 있습니다. 내부 점검 결과는 어느 경로가 정상인지 알려 줍니다. 모니터를 만들기 전에 어떤 장애를 어느 네트워크에서 잡을지 정해 두면 결과를 해석하기 쉽습니다.
Uptime Kuma는 직접 호스팅하는 가용성 모니터링 도구입니다. 주기적으로 서비스를 점검하고 알림을 보내며, 선택한 모니터의 결과를 상태 페이지에 공개할 수 있습니다. 여기서는 Docker에 Kuma v2 인스턴스 하나를 배포하고, 그 인스턴스에서 HTTP 점검을 실행합니다.
로컬 볼륨에 데이터 보관하기
v2 이미지를 실행할 수 있는 Docker 호스트를 준비합니다. 기본 SQLite 구성을 쓴다면 /app/data에는 POSIX 파일 잠금을 지원하는 파일 시스템이 필요합니다. 로컬 볼륨이나 디렉터리를 사용하세요. 일부 NFS 환경에서는 잠금 문제로 데이터베이스가 손상될 수 있습니다. 공식 설치 안내(영어)
docker run -d --restart=unless-stopped \
-p 127.0.0.1:3001:3001 \
-v uptime-kuma:/app/data \
--name uptime-kuma \
louislam/uptime-kuma:2
컨테이너를 교체해도 데이터는 볼륨에 남습니다. 호스트와 Docker가 작동하는 동안에는 재시작 정책을 통해 종료된 컨테이너를 다시 띄울 수 있습니다. 예제에서는 3001 포트를 루프백에 바인딩합니다. Docker Engine 28.0.0 이전 버전에서는 같은 레이어 2 네트워크의 다른 호스트도 루프백에 공개된 포트에 접근할 수 있습니다. Docker 호스트에서 http://127.0.0.1:3001을 열고 관리자 계정을 만듭니다. 다른 컴퓨터에서 초기 설정을 할 때는 SSH 터널을 사용합니다. HTTPS로 공개할 때는 리버스 프록시가 WebSocket 업그레이드를 전달하도록 설정하세요. Docker 포트 공개(영어) · Kuma 리버스 프록시 설정(영어)
호출자가 기대하는 응답 확인하기
읽기 전용 주문 서비스의 준비 상태 엔드포인트가 HTTP 200과 checkout-ready를 반환한다고 가정해 보겠습니다. 두 조건을 모두 확인하려면 HTTP(s) - Keyword 유형을 선택합니다. 일반 HTTP 모니터는 요청이 성공하고 허용한 상태 코드가 돌아왔는지 봅니다. Keyword 유형은 응답 본문에 지정한 문자열이 있는지도 확인합니다. 프록시 오류 페이지에는 없고 배포 후에도 그대로 유지되는 문자열을 고르세요.
| 모니터 유형 | 점검이 성공했을 때 확인되는 내용 |
|---|---|
| HTTP(s) / HTTP(s) - Keyword | 설정한 상태 코드 조건을 충족했다. Keyword 유형은 본문 조건도 충족했다. |
| TCP Port | 포트에 TCP로 연결했다. 데이터베이스 로그인이나 쿼리 성공은 별도로 확인한다. |
| Ping | 이 네트워크에서 보낸 ICMP에 대상이 응답했다. ICMP가 차단된 환경에서도 점검이 실패할 수 있다. |
| DNS | 지정한 리졸버에서 요청한 레코드 유형의 응답을 받았다. |
| Docker Container | 설정한 Docker 호스트에서 컨테이너 상태를 확인했다. 컨테이너에 헬스 체크가 있다면 그 결과도 판정에 사용한다. |
Docker Container 모니터에는 설정한 Docker 엔드포인트에 접근할 권한이 필요합니다. Docker 데몬 접근 권한이 있으면 호스트에 광범위한 영향을 줄 수 있으므로 HTTP 점검과 별개로 접근 범위를 관리하세요. Kuma v2.5.9 모니터 구현 · Docker 데몬 접근 보호(영어)
장애와 복구 알림 확인하기
점검 주기와 요청 제한 시간, 재시도 횟수와 간격을 정합니다. 재시도를 늘리면 짧은 장애가 알림 전에 해소될 수 있지만, 장애 감지도 그만큼 늦어집니다. 일반 HTTP 모니터에 재시도를 설정하면 실패 직후 Pending을 거쳐 Down으로 바뀔 수 있습니다.
알림 채널을 설정하고 테스트 메시지를 보낸 뒤 해당 모니터에서 그 채널을 활성화합니다. 테스트 엔드포인트가 실패 상태 코드를 반환하거나 본문에서 문자열이 빠지게 한 뒤 Down이 기록될 때까지 기다립니다. 정상 응답으로 되돌리고, 장애 알림과 복구 알림이 지정한 채널에 도착하는지 확인합니다. 채널 테스트와 함께 모니터에서 알림까지 이어지는 흐름도 검증할 수 있습니다.
상태 페이지에 공개할 점검 고르기
사용자에게 알리고 싶은 서비스에 해당하는 모니터를 골라 상태 페이지에 추가합니다. 이름은 운영팀 밖에서도 이해할 수 있게 붙입니다. 공유 전에 로그아웃 상태로 페이지를 열고 서비스 그룹, 최근 이력, 장애 설명을 확인합니다. 상태 페이지를 같은 Kuma 인스턴스에서 제공하면 그 인스턴스가 중단될 때 페이지도 영향을 받습니다.
고객이 공개 게이트웨이를 거쳐 서비스를 이용한다면 내부 Kuma 점검을 유지하면서 외부 경로에 별도의 HTTP 점검을 추가합니다. Guance HTTP 합성 테스트에서 공개 테스트 노드를 선택하고 내부 점검과 동일한 상태 코드와 응답 문자열 조건을 설정할 수 있습니다. 외부에서만 실패하면 DNS, TLS, 게이트웨이까지의 경로를 각각 살펴봅니다. 애플리케이션 로그와 트레이스를 별도로 수집하고 있다면 실패한 요청이 어디까지 도달했는지 확인할 수 있습니다. Kuma v2에도 지원되는 외부 지점에서 실행하는 별도의 Globalping 모니터 유형이 있습니다. 이 예제의 일반 HTTP와 TCP 점검은 Kuma 인스턴스에서 시작합니다.
비공개 서비스를 점검하려면 해당 서비스에 연결할 수 있는 네트워크에 Kuma를 배치합니다. Kuma 자체의 중단은 별도 호스트에서 접근 가능한 HTTPS 엔드포인트나 독립적인 하트비트로 감시합니다. Kuma가 멈춰도 알림이 도착할 수 있어야 합니다. 포트만 TCP로 점검하면 연결 여부를 확인할 수 있습니다. 가용성 모니터링으로 확인할 수 있는 것
업그레이드 전에 볼륨 백업하기
예제처럼 로컬 SQLite를 쓰는 경우 쓰기 작업을 하는 컨테이너를 정지한 뒤 데이터 디렉터리 전체를 아카이브합니다. 그동안 점검과 이 인스턴스가 제공하는 상태 페이지는 일시 중단됩니다. 백업 파일을 생성할 권한이 있는 디렉터리에서 실행하세요.
docker stop uptime-kuma &&
docker run --rm \
-v uptime-kuma:/data:ro -v "$PWD:/backup" \
busybox:1 tar -czf /backup/kuma-backup.tar.gz -C /data . &&
tar -tzf kuma-backup.tar.gz &&
docker start uptime-kuma
아카이브를 만들거나 확인하는 단계가 실패하면 docker start uptime-kuma로 모니터링을 재개하고 업그레이드 전에 다시 백업합니다. 검증한 아카이브는 Docker 호스트 외부에도 복사해 둡니다. 외부 데이터베이스를 사용한다면 해당 데이터베이스도 별도로 백업합니다. v1에서 v2로 옮길 때는 백업 후 v1을 중지한 상태로 기존 볼륨을 연결한 v2 컨테이너로 교체하고, 마이그레이션 로그를 확인합니다. SQLite 볼륨에 쓰는 인스턴스는 하나만 둡니다. 롤백할 때는 마이그레이션 전 아카이브를 별도 볼륨에 복원하고 이전 버전을 실행합니다. 공식 안내는 첫 v1 → v2 마이그레이션에 rootless 이미지를 권장하지 않습니다. v1에서 v2로 마이그레이션(영어)
