Uptime Kuma: 20초 주기 상태 점검과 90여 종 알림을 지원하는 오픈소스 셀프 호스팅 모니터링 도구
HTTP(s), TCP, Ping, Docker 컨테이너 상태를 20초 주기로 점검하고 Telegram·Discord·Slack 등 90개 이상의 채널로 알림을 보내는 오픈소스 셀프 호스팅 모니터링 대시보드 Uptime Kuma의 주요 기능과 설치 방법을 정리합니다.
Uptime Kuma는 개인 서버나 사내 인프라의 웹 서비스, 네트워크 포트, Docker 컨테이너가 정상 작동하는지 직접 구축한 서버에서 실시간으로 감시하는 오픈소스 셀프 호스팅(self-hosted, 외부 SaaS 대신 사용자 서버에 직접 설치해 운영하는 방식) 모니터링 도구입니다. GitHub 저장소 louislam/uptime-kuma는 MIT 라이선스로 공개되어 있으며, 기준 시점 93,613개의 스타를 기록하고 2026년 11월 12일 릴리스된 v2.5.11까지 꾸준히 유지보수되고 있습니다.

이미지 출처: louislam/uptime-kuma GitHub repository
웹사이트나 API 서버가 예고 없이 중단되었을 때 외부 유료 업타임 서비스에 의존하지 않고도 20초 단위의 빠른 장애 감지와 다중 상태 페이지(Status Page) 운영, 90종 이상의 메신저·이메일 알림 연동을 단일 웹 대시보드에서 처리할 수 있다는 점이 핵심입니다.
주요 모니터링 기능과 알림 연동 구조
Uptime Kuma는 단일 페이지 애플리케이션(SPA, 페이지 전체를 새로고침하지 않고 화면을 동적으로 갱신하는 웹 구조)과 WebSocket(서버와 브라우저 간 실시간 양방향 통신 규약) 기반의 대시보드를 제공해 점검 상태와 응답 지연 시간(Ping 차트)을 즉시 시각화합니다.
단순 웹 주소 접속 확인을 넘어 실제 운영 환경에서 자주 쓰이는 다양한 점검 방식을 폭넓게 다룹니다.
- 웹 및 API 프로토콜 점검: 일반 HTTP(s) 응답 코드 확인은 물론, 응답 본문에 특정 문구가 포함되었는지 검사하는 HTTP(s) Keyword, JSON 응답 데이터를 검증하는 HTTP(s) Json Query, 실시간 연결을 확인하는 Websocket 점검을 지원합니다.
- 네트워크 및 인프라 점검: 특정 포트의 열림 여부를 확인하는 TCP, 서버 생존 여부를 확인하는 Ping, 도메인 질의 응답을 살피는 DNS Record, 외부 작업이 주기적으로 신호를 보내는 Push 방식, Steam 게임 서버, 호스트 내 Docker 컨테이너 상태 감시까지 한곳에서 관리합니다.
- 상태 페이지와 보안 편의 기능: 용도나 서비스별로 여러 개의 공개·비공개 상태 페이지를 생성해 각각 별도 도메인에 연결할 수 있으며, SSL/TLS 인증서 정보 확인, 프록시(Proxy) 지원, 계정 보안을 위한 2단계 인증(2FA)과 다국어 인터페이스를 기본 포함합니다.
장애가 감지되었을 때 전달하는 알림 채널 역시 별도 플러그인 개발 없이 기본 내장되어 있습니다. Telegram, Discord, Slack, Gotify, Pushover, SMTP 기반 이메일 등 90개 이상의 알림 서비스를 지원하므로 팀이나 개인이 이미 쓰는 메신저로 곧바로 장애 경보를 받을 수 있습니다.
Docker 및 Node.js 환경별 설치 경로
저장소 공식 README에 안내된 배포 경로는 크게 Docker 컨테이너 방식과 Node.js 직접 실행 방식으로 나뉩니다. 기본 웹 인터페이스는 3001번 포트를 통해 열립니다.
가장 간단한 단일 명령어 실행 방식인 Docker Command는 다음과 같습니다.
docker run -d --restart=always -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:2
Docker Compose로 구성 파일을 관리하려면 전용 디렉터리를 만든 뒤 공식 저장소의 compose.yaml을 내려받아 백그라운드로 실행합니다.
mkdir uptime-kuma
cd uptime-kuma
curl -o compose.yaml https://raw.githubusercontent.com/louislam/uptime-kuma/master/compose.yaml
docker compose up -d
컨테이너를 쓰지 않는 환경에서는 Debian·Ubuntu·Fedora·ArchLinux 등 주요 리눅스 배포판과 Windows 10(x64) 이상, FreeBSD·OpenBSD·NetBSD 환경에서 Node.js 20.4 이상 버전과 Git을 준비해 직접 구동할 수 있습니다. 백그라운드 상시 실행에는 프로세스 관리자 PM2가 권장됩니다.
git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma
npm run setup
# 백그라운드 상시 실행(PM2 권장)
npm install pm2 -g && pm2 install pm2-logrotate
pm2 start server/server.js --name uptime-kuma
설치가 완료되면 브라우저에서 http://localhost:3001 또는 서버 IP의 3001번 포트로 접속해 초기 관리자 계정을 생성할 수 있습니다. 외부 직접 노출을 막고 리버스 프록시(Reverse Proxy, 앞단에서 외부 요청을 받아 내부 서버로 전달하는 중계 서버) 뒤에서만 운영하려면 포트 바인딩을 127.0.0.1:3001:3001로 제한하는 옵션이 안내되어 있습니다.
운영 전 반드시 확인할 제한사항과 주의점
실제 서버에 데이터를 영구 저장하고 안전하게 설치하려면 공식 문서에 명시된 두 가지 주의사항을 먼저 점검해야 합니다.
첫째, 데이터 볼륨 매핑 시 NFS(Network File System, 네트워크를 통해 원격 저장소를 로컬 디스크처럼 연결하는 파일 시스템)는 지원하지 않습니다. 컨테이너나 애플리케이션의 /app/data 경로를 외부 NFS 마운트에 연결하면 데이터베이스 손상이나 동작 오류가 발생할 수 있으므로 반드시 서버 내부의 로컬 디렉터리나 표준 도커 볼륨(Docker Volume)을 지정해야 합니다.
둘째, 검색 엔진에서 상위에 노출되는 uptimekuma.co 등 일부 도메인은 프로젝트 개발자가 운영하는 공식 사이트가 아닙니다. 공식 프로젝트 홈페이지는 [https://uptime.kuma.pet](https://uptime.kuma.pet)이며, 설치 명령어나 릴리스 파일을 확인할 때는 반드시 공식 GitHub 저장소(louislam/uptime-kuma)의 안내를 기준으로 삼아야 합니다. 또한 공식 데모 서버([https://demo.kuma.pet/start-demo](https://demo.kuma.pet/start-demo))는 10분 뒤 모든 데이터가 초기화되는 임시 체험 환경이므로 실제 설정 테스트 용도로만 활용하는 것이 알맞습니다.
출처
- GitHub 공식 저장소: louislam/uptime-kuma