Uptime Kuma

Slack, Discord, Telegram을 포함한 90개 이상의 알림 서비스를 지원하는 HTTP, TCP, DNS, Docker 기반의 자체 호스팅 가동 시간 모니터링 도구입니다.

설치

Docker (권장)

# 영구 저장소를 포함하여 Uptime Kuma 실행
docker run -d \
  --restart=always \
  -p 3001:3001 \
  -v uptime-kuma:/app/data \
  --name uptime-kuma \
  louislam/uptime-kuma:2

# http://localhost:3001에서 접근

Docker — 로컬호스트만

# 로컬호스트에만 바인드 (외부 접근 없음)
docker run -d \
  --restart=always \
  -p 127.0.0.1:3001:3001 \
  -v uptime-kuma:/app/data \
  --name uptime-kuma \
  louislam/uptime-kuma:2

Docker Compose

# 공식 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

# http://localhost:3001에서 접근

Docker 컨테이너 모니터링 포함

# 컨테이너 상태 모니터링용 Docker 소켓 마운트
docker run -d \
  --restart=always \
  -p 3001:3001 \
  -v uptime-kuma:/app/data \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  --name uptime-kuma \
  louislam/uptime-kuma:2

Docker 없이 설치

# 요구 사항: Node.js 20.4+, Git

# 클론 및 설정
git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma
npm run setup

# 직접 시작
node server/server.js

# 또는 백그라운드 작동을 위해 PM2 사용
npm install -g pm2
pm2 start server/server.js --name uptime-kuma

기본 명령어

명령어	설명
`docker run -d -p 3001:3001 louislam/uptime-kuma:2`	Uptime Kuma 컨테이너 시작
`docker compose up -d`	Docker Compose로 시작
`docker compose down`	모든 서비스 중지
`docker compose logs -f`	컨테이너 로그 추적
`docker restart uptime-kuma`	컨테이너 재시작
`docker stop uptime-kuma`	컨테이너 중지
`docker start uptime-kuma`	중지된 컨테이너 시작
`node server/server.js`	Docker 없이 시작
`pm2 start server/server.js --name uptime-kuma`	PM2로 시작
`pm2 restart uptime-kuma`	PM2로 재시작
`pm2 stop uptime-kuma`	PM2로 중지
`pm2 logs uptime-kuma`	PM2 로그 보기

업데이트 명령어

Docker

# 최신 이미지 풀
docker pull louislam/uptime-kuma:2

# 현재 컨테이너 중지 및 제거
docker stop uptime-kuma
docker rm uptime-kuma

# 새 이미지로 재생성 (데이터는 볼륨에 유지)
docker run -d \
  --restart=always \
  -p 3001:3001 \
  -v uptime-kuma:/app/data \
  --name uptime-kuma \
  louislam/uptime-kuma:2

Docker Compose

# 풀 및 재생성
docker compose pull
docker compose up -d

Docker 없이

cd uptime-kuma
git fetch --all
git checkout 2.1.3 --force
npm install --production
npm run download-dist
pm2 restart uptime-kuma

모니터 유형

유형	설명
HTTP(S)	웹사이트 가용성 및 응답 시간 모니터링
HTTP(S) Keyword	응답 본문의 특정 텍스트 확인
HTTP(S) JSON Query	JSON 응답 값 검증
TCP Port	TCP 포트 개방 및 응답 여부 확인
Ping	호스트 가용성을 위한 ICMP ping
DNS	DNS 레코드 해석 모니터링
Docker Container	컨테이너 상태 모니터링
Steam Game Server	게임 서버 가용성 확인
MQTT	MQTT 브로커 연결성 모니터링
gRPC	gRPC 서비스 상태 모니터링
Radius	RADIUS 인증 서버 확인
GameDig	게임 서버 모니터링 (여러 프로토콜)
Push	하트비트 엔드포인트를 통한 수동 모니터링
Group	모니터의 논리적 그룹화

알림 서비스 (90개 이상)

채팅 및 메시징

서비스	설명
Slack	채널 웹훅 및 봇 알림
Discord	웹훅 기반 채널 알림
Telegram	봇 API 알림
Microsoft Teams	수신 웹훅 알림
Mattermost	자체 호스팅 채팅 통합
Rocket.Chat	웹훅 알림
Google Chat	공간 웹훅 알림
Matrix	분산형 채팅 알림

푸시 및 모바일

서비스	설명
Pushover	모바일 푸시 알림
Gotify	자체 호스팅 푸시 서버
ntfy	HTTP 기반 pub/sub 알림
Pushbullet	크로스 디바이스 푸시 알림
Signal	안전한 메시징 알림
LINE	LINE Notify 통합

사건 관리

서비스	설명
PagerDuty	사건 알림 및 온콜
Opsgenie	알림 관리 및 에스컬레이션
Squadcast	사건 관리
Splunk On-Call	VictorOps 알림 라우팅
Better Stack	가동 시간 및 사건 관리

이메일 및 웹훅

서비스	설명
SMTP Email	사용자 정의 이메일 알림
Webhook	사용자 정의 HTTP 엔드포인트 호출
Home Assistant	스마트 홈 자동화 트리거
Apprise	범용 알림 게이트웨이

환경 변수

변수	설명	기본값
`UPTIME_KUMA_PORT`	서버 포트	`3001`
`UPTIME_KUMA_HOST`	바인드 주소	`::`
`DATA_DIR`	데이터 저장소 디렉토리	`./data`
`TZ`	타임존	`UTC`
`UMASK`	파일 권한 마스크	`0000`
`NODE_EXTRA_CA_CERTS`	사용자 정의 CA 인증서 경로	—
`SSL_CERT`	SSL 인증서 경로	—
`SSL_KEY`	SSL 개인 키 경로	—

상태 페이지

기능	설명
Multiple Pages	다양한 서비스를 위한 별도 상태 페이지 생성
Custom Domains	상태 페이지를 사용자 정의 도메인에 매핑
Custom CSS	사용자 정의 CSS로 상태 페이지 스타일 지정
Incident Posts	상태 페이지에 표시되는 사건 보고서 생성
Maintenance	유지보수 창 예약
Monitor Groups	상태 페이지의 그룹으로 모니터 구성

Python API (자동화)

# Python API 클라이언트 설치
pip install uptime-kuma-api

API 사용 예

작업	설명
Add monitor	프로그래밍 방식으로 모니터 생성
Edit monitor	모니터 설정 업데이트
Delete monitor	모니터 제거
Pause/Resume	모니터 상태 전환
Get status	현재 모니터 상태 조회
Add notification	알림 공급자 설정
Get uptime	가동 시간 통계 조회

Docker Compose 설정

# compose.yaml
services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: always
    ports:
      - "3001:3001"
    volumes:
      - ./data:/app/data
      # 선택 사항: Docker 컨테이너 모니터링
      # - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - TZ=UTC

보안 설정

기능	설명
2FA	로그인용 이중 인증
Reverse Proxy	Nginx, Caddy 또는 Traefik 뒤에 배포
SSL/TLS	내장 SSL 또는 리버스 프록시 종료
Login Rate Limiting	브루트포스 공격 방지
API Keys	토큰 기반 API 접근

리버스 프록시 설정

Nginx

server {
    listen 443 ssl;
    server_name status.example.com;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

백업 및 복원

명령어	설명
`docker cp uptime-kuma:/app/data ./backup`	데이터 디렉토리 백업
`docker cp ./backup/. uptime-kuma:/app/data`	백업에서 복원
`docker volume inspect uptime-kuma`	볼륨 마운트 지점 찾기

문제 해결

문제	솔루션
UI 접근 불가	포트 바인딩 확인: `docker port uptime-kuma`
NFS 볼륨 오류	네트워크 파일 시스템이 아닌 로컬 디렉토리 사용
WebSocket 오류	WebSocket 업그레이드용 리버스 프록시 설정
컨테이너 시작 안 됨	로그 확인: `docker logs uptime-kuma`
데이터 유지 손실	`-v uptime-kuma:/app/data` 볼륨 사용 확인
Docker 모니터링 실패	docker.sock 마운트: `-v /var/run/docker.sock:/var/run/docker.sock:ro`

지원되는 플랫폼

플랫폼	상태
Linux (x64, ARM)	지원됨
Windows 10+ (x64)	지원됨
macOS	지원됨
Docker Desktop	지원됨
Kubernetes	Docker 이미지를 통함
FreeBSD/OpenBSD	지원되지 않음
Replit/Heroku	지원되지 않음

모범 사례

데이터 지속성을 위해 NFS가 아닌 Docker 볼륨 사용 (바인드 마운트 아님)
프로덕션 사용을 위해 SSL 종료를 통해 리버스 프록시 뒤에 배포하세요
첫 로그인 직후 관리자 계정에 2FA를 활성화하세요
외부 서비스의 모니터링 간격을 60초 이상으로 설정하세요
방화벽 뒤의 서비스를 위해 Push 모니터 유형을 사용하세요
중복성을 위해 최소 2개의 알림 채널을 설정하세요
내부 및 외부 대상을 위한 별도 상태 페이지를 생성하세요
데이터 디렉토리를 정기적으로 백업하세요 — 모든 설정이 포함됨
운영 센터와 일치하도록 TZ 환경 변수를 통해 타임존을 설정하세요