이 포스트는 블로그 주인장이 흥미롭다고 생각하는 주제를 AI 모델을 통해 작성을 요청한 아티클입니다.

서버나 웹 서비스를 운영하다 보면 시스템이 정상적으로 작동하고 있는지 지속적으로 확인해야 할 필요가 있습니다. Uptime Kuma는 이러한 모니터링 작업을 간편하게 수행할 수 있도록 도와주는 자체 호스팅 방식의 오픈소스 모니터링 도구입니다. GitHub에서 77,900개 이상의 스타를 받았으며, Docker Hub에서 1억 2,700만 회 이상 다운로드될 만큼 검증된 프로젝트입니다.

프로젝트 개요

Uptime Kuma는 Louis Lam이 개발한 모니터링 솔루션으로, “쿠마(クマ/熊)”라는 이름은 일본어로 ‘곰’을 의미합니다. 작은 곰이 여러분의 웹사이트를 지켜본다는 콘셉트를 담고 있습니다.¹

이 프로젝트의 핵심 특징은 자체 호스팅 방식이라는 점입니다. 외부 서비스에 의존하지 않고 자신의 서버에서 직접 실행하기 때문에, 민감한 인프라 정보를 외부에 노출하지 않으면서도 체계적인 모니터링 환경을 구축할 수 있습니다.

주요 모니터링 기능

Uptime Kuma는 다양한 프로토콜과 서비스 유형에 대한 모니터링을 지원합니다.

1. 지원하는 모니터링 유형

HTTP(S) 모니터링이 가장 기본적인 기능으로, 웹사이트나 API 엔드포인트의 상태를 확인할 수 있습니다. 단순히 응답 코드만 확인하는 것이 아니라, 특정 키워드가 페이지에 포함되어 있는지 검증하거나 JSON 응답의 특정 필드 값을 확인하는 것도 가능합니다.

TCP 포트 모니터링을 통해서는 데이터베이스나 SSH 서버 같은 네트워크 서비스의 가용성을 점검할 수 있습니다. Ping 모니터링으로는 IP 주소나 도메인의 네트워크 연결 상태를 확인할 수 있으며, DNS 레코드 모니터링으로는 도메인 설정이 올바른지 검증할 수 있습니다.

특이한 점은 Docker 컨테이너와 Steam 게임 서버까지 모니터링할 수 있다는 것입니다. 컨테이너 기반 인프라를 운영하는 환경에서 특히 유용한 기능입니다.

2. 체크 주기와 성능

기본적으로 20초 간격으로 상태를 확인하지만, 필요에 따라 이 간격을 조정할 수 있습니다. 짧은 체크 주기 덕분에 장애 발생 시 신속하게 감지할 수 있습니다.

Uptime Kuma는 단일 서버에서 수백 개의 모니터를 동시에 관리할 수 있도록 설계되었지만, 대규모 분산 환경에서는 확장성에 제약이 있을 수 있습니다.

알림 시스템

Telegram을 통한 알림 예시

Uptime Kuma의 가장 강력한 기능 중 하나는 광범위한 알림 서비스 지원입니다. 90개 이상의 알림 채널을 지원하며, 주요 서비스로는 다음과 같은 것들이 있습니다.

• 메시징 플랫폼: Telegram, Discord, Slack, Microsoft Teams
• 이메일: SMTP를 통한 일반 이메일, SendGrid
• 푸시 알림: Pushover, Pushbullet
• 협업 도구: Splunk, PagerDuty
• SMS: Twilio
• 기타: Webhook, Gotify, Signal 등

각 모니터마다 별도의 알림 설정을 구성할 수 있어, 중요한 프로덕션 서버는 즉각적인 알림을 받고 개발 환경은 알림을 최소화하는 식의 유연한 운영이 가능합니다.

상태 페이지 기능

공개 상태 페이지 예시

Uptime Kuma는 모니터링 결과를 공개적으로 보여줄 수 있는 상태 페이지(Status Page) 기능을 제공합니다. 이는 고객이나 팀원에게 서비스 상태를 투명하게 공유할 수 있는 중요한 도구입니다.

다음과 같은 특징이 있습니다.

• 다중 상태 페이지 생성: 서비스별로 별도의 상태 페이지를 만들 수 있습니다
• 도메인 매핑: 커스텀 도메인을 연결하여 브랜드에 맞게 운영할 수 있습니다
• 다국어 지원: 여러 언어로 상태 페이지를 제공할 수 있습니다
• 실시간 업데이트: WebSocket을 통해 페이지가 자동으로 갱신됩니다

상태 페이지에는 현재 상태뿐만 아니라 과거 가동률 통계와 예정된 유지보수 일정도 표시할 수 있습니다.

기술 스택 및 아키텍처

Uptime Kuma는 현대적인 웹 기술 스택을 기반으로 구축되었습니다.

프론트엔드는 Vue 3, Vite.js, Bootstrap 5로 구성되어 있으며, 반응형 디자인과 다크 모드를 지원합니다. 사용자 인터페이스가 직관적이고 빠르게 작동하는 것이 특징입니다.

백엔드는 Node.js 기반으로 작성되었으며, JavaScript와 TypeScript가 혼용되어 있습니다. WebSocket을 활용한 실시간 통신 덕분에 별도의 새로고침 없이도 모니터링 상태가 즉시 업데이트됩니다.

데이터 저장소로는 SQLite를 사용하여 별도의 데이터베이스 서버 없이도 작동할 수 있습니다. 이는 설정과 관리를 크게 단순화합니다.

Node.js 20.4 이상이 필요하며, Docker를 사용하지 않는 경우 PM2를 통한 프로세스 관리가 권장됩니다.

설치 및 배포 방법

라이트 모드 인터페이스

Uptime Kuma는 여러 방법으로 설치할 수 있지만, Docker를 사용한 배포가 가장 권장됩니다.

Docker Compose를 이용한 설치

가장 간편한 방법은 Docker Compose를 사용하는 것입니다.

version: '3.8'
services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    volumes:
      - uptime-kuma:/app/data
    ports:
      - "3001:3001"
    restart: always

volumes:
  uptime-kuma:

이 설정을 docker-compose.yml 파일로 저장한 후 docker-compose up -d 명령으로 실행하면, http://localhost:3001에서 Uptime Kuma에 접속할 수 있습니다.

Docker 명령어를 통한 설치

Docker Compose를 사용하지 않는다면 다음과 같이 직접 실행할 수도 있습니다.

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

Docker 없이 설치

Docker를 사용하지 않는 환경이라면 직접 설치도 가능합니다. Node.js 20.4 이상과 Git, 그리고 PM2가 필요합니다.

git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma
npm run setup
npm install pm2 -g
pm2 start server/server.js --name uptime-kuma

프로덕션 환경에서는 반드시 역방향 프록시(Nginx, Caddy 등)를 앞단에 두고 HTTPS를 설정하는 것이 권장됩니다.

보안 및 인증

Uptime Kuma는 다중 사용자 환경을 지원하며, 각 사용자는 독립적인 계정을 가질 수 있습니다. 2단계 인증(2FA)을 지원하여 계정 보안을 강화할 수 있습니다.

API 키 관리 기능도 제공하여, 외부 시스템에서 안전하게 Uptime Kuma와 통신할 수 있습니다. 다만 RESTful API가 완전히 갖춰져 있지는 않아, 자동화에는 일부 제약이 있을 수 있습니다.

추가 기능들

설정 페이지 인터페이스

기본적인 모니터링 기능 외에도 다양한 부가 기능이 있습니다.

Ping 차트는 응답 시간의 변화를 시각적으로 확인할 수 있게 해줍니다. 네트워크 지연이나 성능 저하를 조기에 파악하는 데 유용합니다.

SSL/TLS 인증서 정보 표시 기능은 인증서 만료일을 추적하여, 갱신 시기를 놓치지 않도록 도와줍니다.

프록시 지원을 통해 방화벽 뒤에 있는 서비스도 모니터링할 수 있으며, Prometheus 메트릭 내보내기를 통해 기존 모니터링 스택과 통합할 수도 있습니다.

유지보수 일정 기능은 예정된 다운타임을 미리 등록하여, 이 기간 동안에는 알림을 보내지 않도록 설정할 수 있습니다.

배지 생성 기능으로 GitHub README나 다른 웹페이지에 실시간 상태 배지를 삽입할 수 있습니다.

Uptime Kuma의 한계와 대안

Uptime Kuma는 강력한 도구지만, 모든 상황에 완벽한 것은 아닙니다.

확장성 측면에서는 단일 서버 기반이기 때문에 수천 개 이상의 엔드포인트를 모니터링하는 대규모 환경에서는 성능 제약이 있을 수 있습니다. 이런 경우에는 Prometheus나 Grafana 같은 엔터프라이즈급 솔루션을 고려해야 합니다.

RESTful API가 완전하지 않아 Infrastructure as Code 방식의 설정 관리가 어려울 수 있습니다. 파일 기반 설정 지원도 제한적입니다.

커뮤니티 중심의 프로젝트이기 때문에 공식적인 상업 지원은 없습니다. 다만 GitHub Issues와 Reddit 커뮤니티(r/UptimeKuma)를 통해 활발한 커뮤니티 지원은 받을 수 있습니다.

대안으로는 Gatus, OneUptime, Checkmate 같은 오픈소스 프로젝트나, UptimeRobot, Better Stack Uptime 같은 호스팅 서비스가 있습니다. 각각 장단점이 있으므로 용도에 맞게 선택하면 됩니다.²

Cloudflare Tunnel 및 역방향 프록시 설정

Uptime Kuma를 인터넷에 노출하려면 안전한 방법이 필요합니다. Cloudflare Tunnel을 사용하면 포트 포워딩 없이도 서비스를 공개할 수 있으며, Nginx나 Caddy 같은 역방향 프록시를 통해 HTTPS를 적용하고 추가적인 보안 계층을 구성할 수 있습니다.³

역방향 프록시를 사용하는 경우 WebSocket 연결이 제대로 작동하도록 설정을 조정해야 합니다. Uptime Kuma 문서의 역방향 프록시 섹션에서 각 프록시 소프트웨어별 설정 예시를 확인할 수 있습니다.

블로그 주인장의 의견

개인적으로 홈 서버와 소규모 프로젝트들을 운영하고 있는데, Uptime Kuma는 정말 유용한 도구입니다. 특히 Docker 컨테이너 모니터링 기능은 컨테이너 기반 인프라를 관리하는 입장에서 매우 편리합니다.

설치도 간단하고 UI도 직관적이어서, 복잡한 엔터프라이즈 모니터링 솔루션에 비해 진입 장벽이 낮습니다. Telegram이나 Discord 같은 메신저로 바로 알림을 받을 수 있어서, 장애가 발생했을 때 빠르게 대응할 수 있습니다.

다만 앞서 언급했듯이 대규모 환경에서는 한계가 있을 수 있으니, 개인 서버나 중소 규모 인프라에 적합한 솔루션이라고 생각합니다. 저도 이제 개인 서버 인프라에 본격적으로 적용해볼 계획입니다.

마치며

Uptime Kuma는 자체 호스팅 방식의 모니터링 도구를 찾는 개발자와 시스템 관리자에게 훌륭한 선택지입니다. 77,900개 이상의 GitHub 스타와 1억 회 이상의 Docker 다운로드는 그 유용성을 입증합니다.

설정이 간단하고 다양한 모니터링 유형을 지원하며, 90개 이상의 알림 서비스와 통합할 수 있다는 점이 큰 장점입니다. 또한 MIT 라이선스로 배포되어 상업적 용도로도 자유롭게 사용할 수 있습니다.

소규모부터 중규모 인프라를 운영하면서 외부 서비스에 의존하지 않고 모니터링 시스템을 구축하고 싶다면, Uptime Kuma를 시도해볼 가치가 충분합니다. 공식 데모 사이트에서 직접 체험해보고 자신의 환경에 적합한지 판단해보시기 바랍니다.

1. Uptime Kuma GitHub Wiki 홈페이지 ↩︎

2. Better Stack Community Uptime Kuma Alternatives 가이드 ↩︎

3. Uptime Kuma Wiki Reverse Proxy 설정 가이드 ↩︎