셀프호스팅 업타임 모니터링 Uptime Kuma

Ⅰ. Uptime Kuma 란?

 서비스가 지금 살아 있는지, 응답이 느려지지는 않았는지를 주기적으로 확인해 주는 도구를 가용성 모니터링(uptime monitoring)이라고 합니다. 예전에는 이런 확인을 UptimeRobot, Pingdom 같은 외부 SaaS에 맡기거나, Nagios처럼 설정 파일을 손으로 짜야 하는 도구로 처리했습니다. 두 방식 모두 아쉬운 점이 있었습니다. SaaS는 매달 비용이 나가고 확인 대상이 외부에서 접근 가능한 주소여야 하며, 사내망 안쪽의 장비는 볼 수 없습니다. Nagios 계열은 강력하지만 초기 설정이 무겁고, 단순히 "이 URL이 200을 주는지"만 보고 싶은 경우에는 과합니다.

 Uptime Kuma는 이 틈을 겨냥한 오픈소스 도구입니다. Node.js로 만든 단일 애플리케이션이고, 웹 화면에서 클릭 몇 번으로 감시 대상을 등록합니다. 설정 파일을 편집할 필요가 없고, 데이터는 내장 SQLite에 저장되므로 별도의 데이터베이스 서버도 필요하지 않습니다. 쉽게 말해 "내가 직접 돌리는 UptimeRobot" 정도의 역할을 합니다. 2026년 9월 기준 최신 버전은 2.5.0입니다.

Ⅱ. Uptime Kuma 주요 특징

ⅰ. 다양한 감시 유형: HTTP(S), TCP 포트, Ping, DNS 조회, HTTP 응답 안의 특정 키워드, JSON 값 조건, Docker 컨테이너 상태, gRPC 등을 지원합니다. 웹뿐 아니라 내부 서비스의 포트 수준 확인도 가능합니다.

ⅱ. 90여 종의 알림 연동: 텔레그램, 슬랙, 디스코드, 이메일(SMTP), 웹훅 등으로 장애를 통지합니다. 하나의 감시 대상에 여러 알림 채널을 붙일 수 있습니다.

ⅲ. 상태 페이지: 등록한 감시 대상을 모아 공개용 상태 페이지(status page)를 만들 수 있습니다. 이용자에게 서비스 상태를 보여 주는 용도로 씁니다.

ⅳ. 가벼운 설치: Docker 이미지 하나로 끝나며, 데이터는 볼륨 하나에 담깁니다. 별도 DB 컨테이너가 없어 소규모 환경에 부담이 적습니다.

ⅴ. 편의 기능: 재시도 횟수, 점검 창(maintenance), 응답 시간 그래프, 2단계 인증, 다국어(한국어 포함)를 기본으로 제공합니다.

Ⅲ. Uptime Kuma 동작 방식

 구성 요소는 크게 네 가지입니다.

ⅰ. 모니터(Monitor): 감시 대상 하나를 뜻합니다. 대상 주소, 확인 주기(기본 60초), 재시도 횟수 등을 지정합니다.

ⅱ. 하트비트(Heartbeat): 매 확인마다 성공/실패와 응답 시간을 기록한 점검 결과입니다. 이 값들이 쌓여 가동률과 그래프가 됩니다.

ⅲ. 알림(Notification): 상태가 정상에서 장애로 바뀌는 시점에 지정한 채널로 통지합니다.

ⅳ. 저장소: 위 데이터가 담기는 SQLite 파일입니다. 컨테이너 안 /app/data 경로에 있습니다.

 데이터 흐름은 대부분 능동(pull) 방식입니다. Uptime Kuma가 주기마다 대상에 직접 요청을 보내고 응답을 확인합니다. 예외적으로 푸시(push) 모니터가 있는데, 이때는 반대로 감시 대상 쪽이 정해진 주소로 주기적으로 신호를 보내고, 그 신호가 제때 오지 않으면 장애로 판단합니다. 크론 작업이나 배치처럼 밖에서 접근할 수 없는 작업의 생존 확인에 씁니다.

Ⅳ. Uptime Kuma 구성 및 동작 흐름도

 한 번의 확인이 알림으로 이어지는 흐름은 다음과 같습니다.

1) 모니터가 주기(기본 60초)마다 대상에 요청 전송         ⬇   2) 응답 코드 / 응답 시간 / 키워드 등을 판정         ⬇   3) 하트비트로 기록 (SQLite 저장)         ⬇   4) 상태 변화 시(정상→장애) 재시도 후 알림 발송         ⬇   5) 대시보드 / 상태 페이지에 결과 반영

 

 

배치 형태는 보통 두 가지입니다. 감시 대상과 같은 망 안에 인스턴스 하나를 두는 단일 배치가 가장 흔합니다. 여러 지역이나 여러 사내망을 함께 봐야 하면, 지역마다 인스턴스를 따로 두거나 각 위치에서 푸시 모니터로 중앙에 신호를 보내는 구성을 씁니다. Uptime Kuma 자체는 클러스터 기능이 없으므로, 이 분리는 도구가 아니라 배치로 해결합니다.

Ⅴ. Uptime Kuma 설치 방법

 가장 간단한 방법은 Docker입니다. 데이터 볼륨을 반드시 붙여야 컨테이너를 다시 만들어도 기록이 남습니다.

[root@feccle] # docker run -d --restart=unless-stopped \
  -p 3001:3001 \
  -v uptime-kuma:/app/data \
  --name uptime-kuma louislam/uptime-kuma:2

 

 Docker Compose로 관리하려면 다음과 같이 작성합니다.

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "3001:3001"
    volumes:
      - uptime-kuma:/app/data
volumes:
  uptime-kuma:

 띄운 뒤 브라우저에서 http://서버주소:3001 로 접속하면 첫 화면에서 관리자 계정을 만듭니다. 이 계정이 전체 설정과 인프라 지도를 여는 열쇠이므로 비밀번호를 신중하게 정합니다.

Ⅵ. Uptime Kuma 기본 사용법과 운영 시 고려사항

 화면에서 "Add New Monitor"를 누르고 유형(HTTP 등), 이름, 주소, 확인 주기, 재시도 횟수를 지정하면 감시가 시작됩니다. 알림은 설정 화면에서 채널(예: 텔레그램)을 먼저 등록한 뒤, 각 모니터에 연결합니다. 상태 페이지는 여러 모니터를 골라 공개 주소로 묶는 방식입니다.

 운영하면서 실제로 자주 겪는 문제와 조치는 다음과 같습니다.

ⅰ. 재시작하면 기록이 사라질 때: 볼륨을 붙이지 않고 실행한 경우입니다. -v uptime-kuma:/app/data 를 반드시 지정합니다. 백업은 이 볼륨(특히 kuma.db)만 복사하면 됩니다.

ⅱ. 리버스 프록시 뒤에서 화면이 안 뜰 때: 대시보드는 WebSocket으로 통신합니다. Nginx 등에서 Upgrade, Connection 헤더를 넘겨주지 않으면 화면이 계속 로딩만 됩니다. 프록시 설정에 WebSocket 업그레이드를 추가합니다.

ⅲ. 알림이 오지 않을 때: 알림 설정의 "Test" 버튼으로 먼저 채널 자체를 확인합니다. 정상인데도 안 오면, 재시도 횟수 때문에 아직 장애로 확정되지 않은 경우가 많습니다. 이메일은 SMTP 포트(465/587)와 TLS 설정을 다시 확인합니다.

ⅳ. 모니터가 수백 개로 늘며 느려질 때: SQLite는 쓰기가 한 번에 하나씩이라 대상이 많고 주기가 짧으면 병목이 생깁니다. 확인 주기를 늘리거나, 2.x에서 지원하는 외장 MariaDB 백엔드로 옮기는 것을 검토합니다.

ⅴ. 자기 자신은 못 지키는 사각지대: Uptime Kuma가 돌던 서버가 죽으면 아무도 알려 주지 않습니다. 외부에 아주 단순한 감시 하나(또는 데드맨 스위치 성격의 푸시 모니터)를 별도로 두어, 이 인스턴스 자체의 생존을 밖에서 지켜보게 합니다.

ⅵ. 3001 포트 노출 주의: 로그인 화면 뒤에는 감시 대상의 호스트명과 내부 포트가 모두 담긴 인프라 지도가 있습니다. 포트를 인터넷에 그대로 열지 말고, VPN이나 프록시 인증 뒤에 두는 것이 안전합니다.

Ⅶ. Uptime Kuma 자주 쓰는 명령·설정

명령 / 설정	설명
docker logs -f uptime-kuma	실행 로그 실시간 확인 (기동 오류 진단)
docker restart uptime-kuma	컨테이너 재시작
docker pull louislam/uptime-kuma:2	최신 2.x 이미지 내려받기(업데이트 준비)
docker volume inspect uptime-kuma	데이터 볼륨의 실제 저장 위치 확인
확인 주기(Heartbeat Interval)	감시 요청 간격. 기본 60초, 대상이 많으면 늘림
재시도(Retries)	장애로 확정하기 전 재확인 횟수. 오탐 완화

 업데이트는 새 이미지를 받은 뒤 컨테이너를 지우고 같은 볼륨으로 다시 만드는 순서입니다. 볼륨만 유지되면 설정과 기록은 그대로 남습니다.

[root@feccle] # docker pull louislam/uptime-kuma:2
[root@feccle] # docker stop uptime-kuma && docker rm uptime-kuma
[root@feccle] # docker run -d --restart=unless-stopped \
  -p 3001:3001 -v uptime-kuma:/app/data \
  --name uptime-kuma louislam/uptime-kuma:2

Ⅷ. Uptime Kuma 활용 방안

 소규모 팀이나 개인 서버에서 "우리 서비스가 지금 떠 있는가"를 빠르게 확인하고 장애 시 바로 통지받고 싶을 때 잘 맞습니다. 사내망 안쪽 장비의 포트 확인, 크론 작업의 생존 확인(푸시 모니터), 이용자용 상태 페이지 제공에도 유용합니다.

 대안 기술과 간단히 비교하면 다음과 같습니다.

도구	성격
Prometheus + Blackbox Exporter	메트릭 기반. 대규모·장기 지표와 세밀한 알림 규칙에 강함. 설정과 운영은 더 무거움
Nagios / Icinga	전통적 인프라 감시. 기능은 넓지만 초기 설정이 복잡함
UptimeRobot / Pingdom 등 SaaS	설치 불필요, 외부 관점 감시. 비용이 들고 내부망은 못 봄

 

 반대로 이럴 때는 다른 도구가 낫습니다. CPU, 메모리, 요청 지연 같은 지표를 오래 쌓아 분석하려면 Prometheus와 Grafana 조합이 맞습니다. 수천 개 대상을 여러 지역에서 고가용성으로 감시해야 한다면, 클러스터 기능이 없는 Uptime Kuma보다 분산 감시를 전제로 만든 도구가 낫습니다. 정리하면 Uptime Kuma는 가볍게 시작해 가용성 확인과 즉시 알림을 얻고 싶은 경우에 적합하고, 세밀한 지표 분석이나 대규모 분산 감시가 목적이라면 그에 맞는 도구를 함께 쓰는 편이 좋습니다.