Uptime Kuma: 90종 이상의 알림과 가동 상태를 추적하는 셀프 호스팅 모니터링 도구
HTTP(s), TCP, Ping, Docker 컨테이너 상태를 20초 주기로 점검하고 Telegram·Slack 등 90개 이상의 채널로 장애를 전달하는 오픈소스 모니터링 도구 Uptime Kuma의 핵심 기능과 구축 방법을 살펴봅니다.
웹 서비스나 내부 인프라를 안정적으로 운영하려면 서버가 지금 정상 작동하는지 실시간으로 확인하는 모니터링 환경이 반드시 필요합니다. 외부 상용 SaaS 도구는 호스트 수가 늘어날 때마다 비용 부담이 커지고 사내 폐쇄망에 위치한 장비를 감시하기 어렵다는 제약이 따릅니다. 오픈소스 프로젝트인 Uptime Kuma는 외부 클라우드 의존 없이 사용자가 직접 보유한 서버에 설치해 서비스 가동 상태를 관리할 수 있는 셀프 호스팅(Self-hosted) 모니터링 도구입니다.

이미지 출처: louislam/uptime-kuma GitHub repository
Uptime Kuma는 웹 인터페이스를 통해 모니터링 대상을 손쉽게 등록하고 네트워크 장애나 서비스 중단이 일어났을 때 즉각 경보를 발송하도록 설계되었습니다. GitHub에서 9만 3천 개 이상의 스타(Star)를 모으며 활발하게 관리되고 있으며, 최근 2026년 11월 12일 버전 2.5.11 릴리스를 공개하며 기능을 보완했습니다. 상용 가동 시간 모니터링 서비스인 Uptime Robot의 대안으로 출발해 깔끔한 반응형 대시보드와 유연한 알림 연동 기능으로 개인 홈랩부터 기업 개발팀까지 폭넓게 활용되고 있습니다.
다양한 점검 프로토콜과 20초 간격의 모니터링 구조
Uptime Kuma의 가장 큰 장점은 모니터링할 수 있는 프로토콜과 검증 방식이 폭넓다는 점입니다. 일반적인 웹사이트 접속 여부를 확인하는 HTTP(s) 호출뿐만 아니라 네트워크 계층과 애플리케이션 환경에 맞춘 세부 점검을 모두 지원합니다.
- 웹 및 API 검증: 단순 응답 코드 확인을 넘어 HTTP(s) Keyword 기능을 통해 특정 문자열이 페이지에 포함되어 있는지 검사하거나, HTTP(s) Json Query 방식으로 REST API의 반환값을 분석해 서비스 정상 여부를 판별합니다.
- 네트워크 계층 점검: 원격 포트 연결을 시험하는 TCP 포트 감시, 네트워크 도달성을 확인하는 핑(Ping) 테스트, 도메인 주소 변환이 올바른지 검증하는 DNS Record 조회를 지원합니다.
- 컨테이너 및 양방향 통신: 실시간 통신 상태를 점검하는 웹소켓(WebSocket) 감시와 더불어 호스트에서 구동 중인 도커(Docker) 컨테이너의 실행 상태를 직접 추적할 수 있습니다.
- 하트비트 푸시(Push): 주기적으로 실행되는 백업 작업이나 배치 스크립트가 Uptime Kuma로 성공 신호를 전송하게 만들어, 정해진 시간 안에 신호가 오지 않으면 장애로 간주하는 역방향 모니터링도 가능합니다.
이러한 모든 검사는 최소 20초 주기(Interval)로 설정할 수 있어 장애 발생 순간을 빠르게 감지합니다. 웹 UI 화면에는 가동 시간 비율과 실시간 응답 지연 시간 차트(Ping Chart), SSL/TLS 인증서 만료 잔여 기간이 일목요연하게 표시되어 인프라 엔지니어가 전체 상태를 한눈에 파악할 수 있습니다.
90개 이상의 알림 채널 지원과 공개 상태 페이지
서버 장애를 감지한 뒤 운영자에게 알림을 제때 보내지 못하면 모니터링 도구의 역할을 다할 수 없습니다. Uptime Kuma는 텔레그램(Telegram), 디스코드(Discord), 슬랙(Slack), 고티파이(Gotify), 푸시오버(Pushover), 표준 이메일(SMTP)을 포함해 90종 이상의 외부 알림 서비스를 기본 탑재하고 있습니다.
별도의 복잡한 스크립트를 작성하지 않고도 웹 설정 화면에서 웹훅(Webhook) 주소나 봇 토큰을 입력하면 즉시 경보 채널이 연결됩니다. 이를 통해 주간 업무 시간에는 슬랙 채널로 상태를 공유하고, 심야 긴급 장애는 텔레그램이나 푸시 앱으로 발송하는 식의 알림 정책 구성이 가능합니다.
또한 엔드유저나 고객에게 서비스 가동 현황을 투명하게 안내할 수 있는 '상태 페이지(Status Page)' 생성 기능을 제공합니다. 관리자 화면과 분리된 읽기 전용 상태 페이지를 여러 개 만들 수 있으며, 각 페이지를 특정 도메인에 연결하거나 테마 색상을 맞춤 지정할 수 있습니다. 관리자 화면 접근에는 이중 인증(2FA, Two-Factor Authentication)과 프록시(Proxy) 경유를 지원해 외부 노출 환경에서도 보안을 유지할 수 있습니다.
배포 방식과 운영 환경에서 주의할 점
Uptime Kuma는 단일 실행 파일 수준으로 가볍게 패키징되어 있어 도커(Docker) 컨테이너 환경이나 Node.js 런타임 환경에서 모두 간편하게 구동할 수 있습니다. 가장 널리 권장되는 배포 방식은 Docker Compose를 이용한 방법입니다.
mkdir uptime-kuma
cd uptime-kuma
curl -o compose.yaml https://raw.githubusercontent.com/louislam/uptime-kuma/master/compose.yaml
docker compose up -d
도커 단일 명령어로 즉시 컨테이너를 올릴 수도 있습니다. 포트 매핑을 통해 기본 웹 포트인 3001번으로 접속할 수 있습니다.
docker run -d --restart=always -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:2
도커를 사용하지 않는 환경이라면 Node.js 20.4 이상 버전과 Git이 설치된 Linux, Windows 10/Server, BSD 환경에서 저장소를 복제한 뒤 프로세스 관리 도구인 pm2를 활용해 백그라운드 서비스로 등록할 수 있습니다.
git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma
npm run setup
npm install pm2 -g && pm2 install pm2-logrotate
pm2 start server/server.js --name uptime-kuma
구축 시 반드시 확인해야 할 주의 사항도 있습니다. Uptime Kuma는 데이터베이스 파일의 동시성 및 I/O 특성상 NFS(Network File System)와 같은 네트워크 기반 파일 시스템 마운트를 공식적으로 지원하지 않습니다. 도커 볼륨을 매핑할 때는 반드시 로컬 디스크 디렉터리나 호스트 내부 볼륨을 지정해야 데이터 손상이나 비정상 종료를 예방할 수 있습니다. 아울러 검색 포털 상단에 노출되는 일부 비공식 웹사이트(예: uptimekuma.co)는 공식 프로젝트 팀이 운영하는 사이트가 아니므로, 소프트웨어 설치와 문서 확인은 공식 GitHub 저장소(louislam/uptime-kuma)를 기준으로 진행해야 안전합니다.
출처
- GitHub 저장소: louislam/uptime-kuma
- 공식 홈페이지: uptime.kuma.pet
- 최신 릴리스 내역: v2.5.11 Release