스마트 홈 네트워크 인프라 Uptime Kuma 모니터링 통합하는 깔끔한 방법

Uptime Kuma는 오픈소스 기반의 자체 호스팅 모니터링 도구입니다. HTTP, TCP, Ping, Docker 등 다양한 프로토콜을 지원하며, 아름답고 직관적인 UI와 빠른 반응속도를 갖추고 있어 개인 및 기업의 시스템 상태 모니터링에 적합합니다.

아래에 Uptime Kuma의 기본 활용 방법입니다.

개요 및 주요 특징

무엇을 위한 도구인가요?

• 서버/서비스의 가용성(UP/DOWN 상태)을 실시간 모니터링
• Slack, Telegram, Email 등 다양한 경고(알림) 채널 지원
• 다중 상태 페이지 생성 가능 (예: 고객용 상태 대시보드)

지원하는 모니터링 유형

타입	설명
HTTP(s)	웹사이트 응답 체크
TCP	포트 열림 여부 확인 (예: SSH, DB 등)
Ping	ICMP를 통한 가용성 확인
Docker	컨테이너 상태 확인
DNS Record	A, CNAME, MX 등 레코드 유효성 확인
Push	외부 시스템에서 상태 알림을 Push
Steam Game Server	게임 서버 상태 확인

설치 방법

Docker 사용 (가장 간단한 방법)

docker run -d --restart=always \
  -p 3001:3001 \
  -v uptime-kuma:/app/data \
  --name uptime-kuma \
  louislam/uptime-kuma:1

• 실행 후 브라우저에서 http://<서버IP>:3001 접속
• 최초 접속 시 관리자 계정 설정

Tip: 외부 노출 방지 시 127.0.0.1:3001:3001으로 바인딩

로컬 설치 (Non-Docker)

# 의존 패키지 설치 (Node.js 18+, npm 9 이상)
git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma
npm run setup

# PM2 백그라운드 실행 추천
npm install pm2 -g
pm2 start server/server.js --name uptime-kuma
pm2 save && pm2 startup

접속: http://localhost:3001

기본 설정 및 모니터 추가

최초 접속 시

1. 관리자 계정 생성
2. 기본 언어 및 테마 설정 (한국어 지원)

모니터 추가

1. 새 모니터 추가 클릭
2. 유형 선택: HTTP, Ping, TCP 등
3. 대상 입력: URL/IP/도메인
4. 인터벌 설정: 기본 20초
5. 알림 대상 지정 (Slack, Email 등)
6. 저장 및 모니터링 시작

알림 설정 방법 (Slack 예시)

1. Slack에서 Webhook URL 생성
   • Slack Incoming Webhooks 참고
2. Uptime Kuma > 설정 > Notification > Slack 추가
3. Webhook URL 입력 및 테스트
4. 성공 시 알림 연결 완료

다양한 알림 채널 지원

• Telegram
• Discord
• Gotify
• Pushover
• Email (SMTP)
• LINE, Rocket.Chat, Webhook 등 90개 이상

상태 페이지 만들기

내부용 상태 대시보드 제공

1. 상태 페이지 메뉴 → 새 상태 페이지
2. 이름, 공개여부, 표시할 모니터 선택
3. 서브도메인 연결 가능 (예: status.example.com)
4. 공개 링크 공유 가능

고급 기능 요약

기능	설명
Ping 그래프	RTT 시간 시각화
인증서 정보	HTTPS 인증서 만료일 표시
다국어 지원	50개 이상 언어
2FA	관리자 로그인 2단계 인증
프록시 지원	Proxy 환경 설정 가능
REST API	외부 자동화 연동 (제한적)
다중 관리자	유저 초대 기능은 없지만 로그인 공유 가능
백업/복원	설정 파일 백업 및 이관 가능 (/app/data 디렉터리)

업데이트 방법

도커 버전

docker pull louislam/uptime-kuma:1
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:1

Non-Docker

git pull
npm run setup
pm2 restart uptime-kuma

최신 업데이트 위키: How to Update

보안 체크리스트

항목	점검 포인트
인증 설정	반드시 관리자 계정에 2FA 설정
접근 제한	Reverse Proxy 구성 후 인증 헤더로 접근 제한
포트 노출	도커 포트 127.0.0.1로 바인딩 + 프록시 사용 권장
데이터 보호	/app/data 디렉터리 주기적 백업
SSL 인증	프록시에서 HTTPS 적용 (예: NGINX + Let's Encrypt)
알림 채널 보호	Webhook URL 외부 노출 주의
로그 모니터링	pm2 logs uptime-kuma로 주기적 점검

실전 활용 예시

1. 웹 서비스 가용성 모니터링

• HTTP 모니터 추가 (예: https://myservice.com)
• Slack 연동으로 다운시 실시간 알림

2. 내부 서버 포트 상태 체크

• TCP 모니터: IP + 포트 (예: 192.168.10.1:22)
• Ping 체크로 네트워크 단절 감지

3. Docker 컨테이너 상태 감시

• Docker 모니터 설정: 실행 여부 지속 확인
• 비정상 종료 시 관리자에게 알림

300x250

Uptime Kuma는 매우 직관적이고 유연한 설계를 통해 개인 블로그부터 기업 인프라까지 폭넓은 모니터링 활용이 가능한 도구입니다. 초기 설정만 완료하면 이후에는 UI 기반으로 손쉽게 모니터 추가와 알림 관리가 가능합니다.

Uptime Kuma x Home Assistant 통합

Uptime Kuma는 웹사이트, API, 서버 등 다양한 서비스의 상태(가동 시간 및 응답 시간)를 모니터링하는 오픈소스 도구이며, Home Assistant는 스마트 홈 자동화를 위한 강력한 오픈 플랫폼입니다.

이 통합의 목적은 다음과 같습니다.

• Home Assistant 내에서 Uptime Kuma가 모니터링 중인 서비스들의 상태를 센서 엔터티로 가져와 대시보드, 자동화 등에 활용
• 서버 상태에 따라 조명 색상 변경, 알림 전송, 자동 스크립트 실행 등 다양한 반응 구성 가능

준비사항

항목	내용
🔐 Uptime Kuma API Key	Uptime Kuma > Settings > API Keys → Add API Key 생성
🌐 Uptime Kuma URL	예: https://uptime.example.com (Home Assistant가 접근 가능해야 함)
🔧 Home Assistant 설치	최신 버전 운영 중인지 확인

1. My 버튼을 통한 자동 설정 (GUI)

1. Home Assistant에서 통합 시작
2. Uptime Kuma URL, API Key, SSL 인증서 검증 여부 입력
3. 완료 시 자동으로 센서 엔터티들이 생성됨

2. 수동 설정 (YAML 기반 구성 예시)

# configuration.yaml (예시 – 현재는 UI 설정 권장됨)
uptime_kuma:
  url: "https://uptime.example.com"
  api_key: "your_api_key_here"
  verify_ssl: true

💡 권장: UI 기반 통합 설정 사용 (YAML 수동 설정은 최신 버전에서는 deprecated 가능성 있음)

생성되는 센서 엔터티 종류

센서 이름	설명
sensor.<monitor_name>_status	현재 상태 (up, down, pending, maintenance)
sensor.<monitor_name>_response_time	마지막 체크에 걸린 응답 시간(ms)
sensor.<monitor_name>_cert_expiry	SSL 인증서 만료까지 남은 일수
sensor.<monitor_name>_type	모니터링 방식 (HTTP, TCP 등)
sensor.<monitor_name>_host	감시 대상 호스트명 또는 IP
sensor.<monitor_name>_port	감시 포트 번호 (해당 시)
sensor.<monitor_name>_url	감시 대상 URL (HTTP 기준)
update.uptime_kuma	Uptime Kuma 버전 상태 (최신 여부)

자동화 예시: 서비스 상태 기반 경고등

YAML 예시 – 서비스 다운 시 조명 빨간색으로 변경

alias: "Uptime Kuma 서비스 장애 경고"
description: "특정 서비스가 down일 때 조명 색상 변경"
trigger:
  - platform: state
    entity_id: sensor.api_server_status
    to: "down"
condition: []
action:
  - service: light.turn_on
    data:
      entity_id: light.warning_light
      color_name: "red"
      brightness: 255
mode: single

💬 응용 아이디어

• Ping이 실패하면 특정 방 조명 깜빡임
• 웹서버 down 시 Telegram으로 알림 발송
• 매일 아침 SSL 인증서 만료까지 일수가 15일 이하인 경우 알림

업데이트 주기 및 구조

항목	값
데이터 갱신 주기	기본 30초 마다 Uptime Kuma API 조회
인증 방식	API Key 기반 인증 (Bearer Header)
SSL 검증	설정에 따라 선택 가능 (verify_ssl)

알려진 제약 사항

• 모니터 이름 중복 불가: 동일한 이름의 모니터는 Home Assistant에서 하나만 표시됨
• 모니터 이름 변경 시: 새로운 엔터티가 생성되며 이전 엔터티는 수동 삭제 필요
• API 제한: 현재는 고유 ID 제공되지 않음 → 내부적으로 이름 기반 매칭

문제 해결

연결 실패 시 점검 항목

• Uptime Kuma 인스턴스에 Home Assistant가 접근 가능한지 (내부 네트워크 또는 도메인)
• API Key 정확 여부
• SSL 인증서 유효성 (자가 서명일 경우 verify_ssl: false 설정 필요)

디버깅 방법

1. logger: 설정에서 custom_components.uptime_kuma의 로그 레벨을 debug로 설정
2. 통합 재시작 후 로그 확인
3. Developer Tools > Diagnostics에서 상태 진단 정보 다운로드 가능

logger:
  default: info
  logs:
    custom_components.uptime_kuma: debug

Uptime Kuma + Home Assistant 통합은 단순한 가동 상태 확인을 넘어 홈 인프라 상태를 시각화, 자동화, 경고화 할 수 있는 강력한 조합입니다.

✔️ 네트워크/서버 다운 감지
✔️ SSL 인증서 만료 알림
✔️ 스마트홈 반응형 자동화

필요하시면 다음과 같은 확장 연동도 가능합니다.

• Prometheus / Grafana 시각화 연동
• Slack Webhook 알림 자동화
• n8n 연계 자동 티켓 생성 (TheHive, Jira 등)
• Docker Compose / Kubernetes 통합 운영