가이드

작성자 Matt Connor 2026-07-15 · 업데이트됨 2026-08-27

Uptime Kuma Docker 설치 및 서버 모니터링 구축 방법

Q: Telegram이나 이메일로 알림을 받으려면 어떻게 해야 합니까?

Settings의 Notifications 메뉴에서 채널을 추가한 뒤, 각 모니터에 연결하십시오. Telegram의 경우 @BotFather을 통해 봇을 생성하고 https://api.telegram.org/bot /getUpdates에서 chat.id을 확인하십시오. 이메일의 경우 SSL에는 465을 사용하고, 제공업체가 2단계 인증을 요구하면 앱 비밀번호를 사용하여 STARTTLS용 587를 설정하십시오. 알림을 신뢰하기 전에 Test 버튼을 눌러 메시지가 정상적으로 도착하는지 확인하십시오.

Q: Uptime Kuma로 cron 작업이나 백업 스크립트를 모니터링할 수 있습니까?

네, Push 모니터를 사용하면 가능합니다. Uptime Kuma가 제공하는 URL을 스크립트 끝에 curl하면 작업이 성공했을 때만 신호가 발생합니다. 작업이 실패하거나 서버가 다운되면 하트비트가 전달되지 않으며, 설정한 시간이 지나면 알림이 발송됩니다. 외부 체크 방식으로는 스크립트 내부를 확인할 수 없으므로, 예약된 작업의 실제 실행 여부를 확인하는 가장 확실한 방법입니다.

Docker를 활용해 Uptime Kuma를 설치하고 웹사이트와 포트 상태를 감시하는 방법을 설명합니다. 모니터링 도구를 대상 서버와 분리하여 운영해야 하는 이유와 알림 설정 등 실무적인 구축 가이드를 확인하여 안정적인 서버 운영 환경을 구성해 보시기 바랍니다.

구축할 내용

외부에서 다른 서버와 웹사이트를 감시하다가 응답이 멈추는 즉시 이메일, Telegram, Discord 또는 웹훅으로 알림을 보내는 소형 컨테이너 하나를 구축합니다. Uptime Kuma는 SQLite 파일을 사용하는 단일 Node 프로세스로, 256-512 MB의 RAM만으로도 원활하게 실행됩니다. 실시간 대시보드, 기록 그래프, 공개 상태 페이지 기능을 제공합니다. 설치는 10줄 내외의 Compose 파일로 완료됩니다. 실제로 중요한 것은 어디에서 실행하는지와 테스트를 통해 알림이 실제로 발송되는지 확인했는지 여부입니다. 알림 도달 여부를 검증하지 않은 모니터링은 아예 없는 것보다 위험합니다. 아무것도 감시하지 않으면서 보호받고 있다는 착각을 주기 때문입니다.

모니터링 도구는 장애 영향권 밖에서 실행하십시오

이 결정 하나가 전체 시스템의 성패를 좌우하므로 가장 먼저 고려해야 합니다. Uptime Kuma를 모니터링 대상과 동일한 서버에서 실행하지 마십시오. 모니터링 도구가 감시 대상 서버와 같은 곳에 있다면, 서버가 다운되거나 메모리가 고갈되는 등 정작 중요한 장애 상황에서 모니터링 도구까지 함께 죽어버려 아무런 알림도 받을 수 없습니다. 모니터링 도구가 죽어서 발생하는 침묵은 "모든 것이 정상"이라는 상태와 구분할 수 없기 때문입니다. 서버가 살아있더라도 더 미묘한 함정이 있습니다. localhost을 모니터링하는 도구가 워크로드와 CPU 자원을 공유하면, 부하가 급증할 때 모니터링 체크 자체가 타임아웃되어 대상을 down 상태로 오판하게 됩니다. 실제 사용자는 서비스를 정상적으로 이용하고 있는데도 거짓 경보가 발생하는 것입니다.

따라서 Uptime Kuma는 모니터링 대상과는 다른 VPS에서 실행하십시오. 가급적 다른 제공업체나 다른 지역(region)의 서버를 사용하는 것이 좋습니다. 사용자가 접속하는 방식 그대로, 즉 공용 인터넷을 통해 호스트 이름으로 서비스에 접근하도록 구성하십시오. 저렴한 인스턴스 하나면 충분하며, 작은 모니터링 VPS 한 대로 모든 서버를 감시할 수 있습니다. 이러한 물리적 분리는 무거운 애플리케이션을 호스팅할 때 특히 중요합니다. 예를 들어 PhotoPrism이나 Immich 사진 라이브러리 같은 서비스는 새로운 데이터를 가져와 인덱싱하는 동안 몇 시간씩 CPU를 점유할 수 있는데, 같은 하드웨어를 공유하는 모니터링 도구는 서비스가 단지 바쁜 상태일 뿐인데도 장애가 발생했다고 오인할 수 있습니다. Uptime Kuma 자체의 장애를 감지하려면, 다른 곳에서 cron을 이용해 push heartbeat를 보내도록 설정하십시오.

사전 요구 사항 및 사이징

Docker Engine과 Compose v2 플러그인이 설치된 최신 Ubuntu 24.04 VPS가 필요합니다. 이때 docker.io 배포판 패키지는 버전이 뒤처지므로 반드시 Docker 공식 apt 저장소에서 설치하십시오.
256 MB RAM으로도 소수의 모니터를 운영할 수 있습니다. 수십 개의 모니터와 리버스 프록시를 함께 운영하려면 512 MB에서 1 GB 정도가 적당하며, 점검 사이의 CPU 사용량은 거의 유휴 상태입니다.
TLS와 공개 상태 페이지를 사용하려면 도메인과 DNS A 레코드가 필요합니다(예: VPS를 가리키는 status.example.com). 비공개 인스턴스라면 DNS 없이 VPN이나 SSH 터널을 사용할 수 있습니다.
알림을 보낼 외부 네트워크 연결이 필요합니다. 메일 제공업체로의 SMTP 연결이나 Telegram 및 Discord로의 HTTPS 연결이 이에 해당합니다.

Compose 파일

이 내용을 /srv/uptime-kuma/compose.yaml에 저장합니다.

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - kuma-data:/app/data

volumes:
  kuma-data:

서비스를 실행하고 첫 부팅 과정을 확인합니다.

sudo mkdir -p /srv/uptime-kuma
# save the file above as /srv/uptime-kuma/compose.yaml, then:
cd /srv/uptime-kuma && sudo docker compose up -d
sudo docker compose logs -f uptime-kuma

정상적으로 시작되면 Listening on 3001 로그가 출력되고 조용해집니다. 이 파일에는 의도적으로 설정된 세 가지 사항이 있습니다.

3001:3001이 아닌 127.0.0.1:3001:3001을 사용합니다. Docker는 ufw가 패킷을 검사하기 전에 DNAT 규칙을 평가하여 포트를 노출합니다. 따라서 단순히 3001:3001로 설정하면 방화벽 설정과 관계없이 대시보드가 공개 인터넷에 노출됩니다. 루프백(loopback)에 바인딩하면 리버스 프록시만 외부로 노출되므로 안전합니다. 프록시를 거치지 않고 접근해야 한다면 자체 호스팅 WireGuard VPN을 통해 3001로 연결할 수 있습니다.

/app/data에 명명된 볼륨(named volume)을 사용합니다. Uptime Kuma가 기억하는 모든 데이터, 즉 SQLite 데이터베이스, 모니터링 설정, 알림 설정, 상태 페이지 로고 등이 이곳에 저장됩니다. 이 데이터를 잃어버리면 관리자 화면이 초기화되므로, 반드시 백업해야 할 유일한 항목입니다.

이미지는 메이저 태그인 :2로 고정합니다. 이는 현재 안정적인 버전 라인입니다. 복사하기 전에 Docker Hub에서 최신 메이저 버전을 확인하십시오. 프로젝트에서 사용을 권장하지 않는 latest와 같은 유동적인 태그는 절대 추적하지 마십시오. 이 이미지의 메이저 버전 업데이트는 데이터베이스 마이그레이션을 동반하며, 이는 일상적인 pull 과정에서 우연히 발생해서는 안 되고 의도적으로 수행해야 합니다.

주의 사항: /app/data은 POSIX 파일 잠금을 지원하는 파일 시스템에 위치해야 합니다. 로컬 Docker 볼륨은 괜찮지만, NFS를 사용하면 SQLite 데이터베이스가 손상되어 SQLITE_BUSY 및 database disk image is malformed 오류가 발생하므로 네트워크 공유 드라이브는 절대 사용하지 마십시오.

첫 실행: 관리자 계정 생성

프록시를 통해 https://status.example.com으로 인스턴스에 접속하거나, SSH 터널을 이용하십시오. ssh -L 3001:127.0.0.1:3001 user@your-vps을 실행한 뒤 http://localhost:3001을 엽니다. 첫 페이지는 관리자 사용자 이름과 비밀번호를 설정하는 양식이며, 기본 로그인 정보는 없습니다. 대시보드는 모니터링 대상의 내부 주소와 토큰을 모두 확인할 수 있으므로, 실제 비밀번호를 설정하십시오. 비밀번호를 잊어버린 경우 브라우저가 아닌 호스트에서 재설정해야 합니다.

sudo docker compose exec uptime-kuma npm run reset-password

알림 채널을 먼저 추가하고 테스트하십시오

모니터를 추가하기 전에 알림 설정을 먼저 완료하십시오. 그래야 모니터를 생성할 때마다 채널을 연결할 수 있습니다. Settings 메뉴에서 Notifications, Setup Notification 순으로 이동하십시오. 각 채널의 Test 버튼을 눌러 메시지가 정상적으로 도착하는지 확인하십시오. 테스트하지 않은 알림은 설정이 조용히 실패하는 두 번째로 흔한 원인입니다.

Email (SMTP). 호스트, 포트, 암호화 방식, 사용자 이름, 비밀번호, 발신자(From) 및 수신자(To) 주소를 입력하십시오. 정상 작동하는 조합은 두 가지입니다. "Secure"를 TLS/SSL로 설정한 465, 또는 STARTTLS를 사용하는 587입니다. Gmail이나 2단계 인증을 사용하는 대부분의 공급자를 이용할 때는 반드시 app password를 생성해야 합니다. 일반 계정 비밀번호를 사용하면 Error: Invalid login: 535-5.7.8 Username and Password not accepted 오류가 발생합니다.

Telegram. @BotFather에게 메시지를 보내고 /newbot 명령을 전송한 뒤, 봇 토큰을 복사하십시오. 채팅 ID를 확인하려면 새로 만든 봇에게 메시지를 한 번 보낸 다음, https://api.telegram.org/bot<token>/getUpdates를 열어 JSON 데이터에서 chat.id 값을 읽으십시오. 한 번도 메시지를 보내지 않은 봇은 getUpdates 정보가 비어 있어 알림을 보낼 곳이 없습니다.

Discord. 채널에서 Edit Channel, Integrations, Webhooks, New Webhook 순으로 이동하여 URL을 복사한 뒤, Discord 알림 설정에 붙여넣으십시오.

Generic webhook. Slack 수신 웹훅, 사용자 지정 엔드포인트, 홈 자동화 훅 등 다른 서비스를 이용하려면 Webhook 유형을 선택하십시오. 이 유형은 사용자가 제공한 URL로 JSON 페이로드를 POST 방식으로 전송합니다. 번들로 포함된 Apprise 통합 기능을 사용하면 목록에 있는 90여 개의 다른 서비스 대부분을 지원할 수 있습니다. 장애 알림과 휴대폰 사이에 제3자가 개입하는 것을 원치 않는다면 내장된 ntfy 유형을 선택하고 직접 운영하는 ntfy 서버를 지정하십시오. 이 방식을 사용하면 사용자가 처음부터 끝까지 제어하는 채널을 통해 휴대폰으로 푸시 알림을 받을 수 있습니다.

모니터 추가하기 (한 번에 한 유형씩)

Add New Monitor를 클릭하고 유형을 선택한 뒤, Friendly Name, Check Interval(60초가 적당합니다), Retries("down"으로 간주하기 전 연속 실패 횟수; 패킷 하나 유실로 알림이 가지 않도록 2 또는 3으로 설정), 그리고 발생시킬 알림을 설정합니다. 주로 사용할 유형은 다음과 같습니다.

HTTP(s). 전체 URL을 입력합니다. 상태 코드가 허용 범위(기본값 200-299; 301 또는 401이 정상인 경우 Accepted Status Codes에서 범위를 넓히십시오)에 포함되면 "up"으로 간주합니다. 웹사이트와 API를 점검하는 기본 도구입니다.
HTTP(s) - Keyword. 동일한 요청을 수행하지만, 응답 본문에 특정 문자열이 포함되어야(또는 Invert를 선택한 경우 포함되지 않아야) "up"으로 간주합니다. 이는 사이트가 200 OK를 반환하면서도 "Error establishing a database connection"이라는 문구를 출력하는 상황을 잡아냅니다. 일반 HTTP 체크는 이를 정상으로 판단하기 때문입니다. 또한 브라우저 프론트엔드가 별도의 백엔드와 통신하는 경우에도 적합합니다. 예를 들어 Jellyfin 위에 얹은 Halcyon 비디오 스토어 스킨의 경우, 뒤에 있는 미디어 서버에 접근할 수 없어도 페이지 셸은 200을 정상적으로 반환합니다.
TCP Port. HTTP가 아닌 서비스(22번 포트의 SSH, 5432번 포트의 Postgres, 25번 포트의 SMTP 서버, 게임 서버 등)를 대상으로 호스트와 포트에 직접 TCP 연결을 시도합니다.
Ping. ICMP echo를 사용하여 도달 가능성과 지연 시간을 확인합니다. 하지만 많은 네트워크와 클라우드 방화벽이 ICMP를 차단하므로, Ping 모니터가 빨간색으로 표시된다면 "호스트 다운"일 수도 있고 "제공자가 Ping을 차단"한 것일 수도 있습니다. TCP 모니터로 다시 확인하십시오.
DNS. 지정한 리졸버를 통해 레코드(A, AAAA, MX, TXT 등)를 조회하고 응답을 검증합니다. 도메인 등록 기관이나 DNS 장애를 조기에 발견할 수 있습니다.
Push. 외부에서 내부를 확인하는 방식의 모니터이며, 다음 섹션에서 다룹니다.

푸시(하트비트) 모니터를 사용한 크론 작업 모니터링

위에서 설명한 모든 모니터는 외부에서 서비스 내부로 접근합니다. 푸시 모니터는 반대로 작동합니다. Uptime Kuma가 대기하고 있으면, 작업이 완료되었을 때 서비스가 Uptime Kuma에 "작업을 완료했다"고 신호를 보냅니다. 백업이나 크론 작업을 감시하는 가장 확실한 방법입니다. HTTP 체크는 URL 응답 여부만 알 수 있지만, 작업 완료 여부는 해당 작업만이 알 수 있기 때문입니다.

Push 유형의 모니터를 생성하십시오. Uptime Kuma가 다음과 같은 고유 URL을 생성합니다.

https://status.example.com/api/push/j8Xa2Kd9Qe?status=up&msg=OK&ping=

Heartbeat Interval을 작업 실행 주기보다 약간 더 길게 설정하십시오. 그런 다음, 스크립트의 마지막에 성공 시에만 실행되도록 아래 한 줄을 추가하십시오.

#!/usr/bin/env bash
set -euo pipefail
# ... your backup or job runs here; set -e aborts on any failure ...
curl -fsS --retry 3 "https://status.example.com/api/push/j8Xa2Kd9Qe?status=up&msg=backup+ok&ping="

작업이 실패하면 set -e이 curl 명령 이전에 중단됩니다. 서버가 다운된 경우에도 스크립트는 실행되지 않습니다. 어느 경우든 하트비트 신호가 멈추게 되며, 설정한 간격과 재시도 횟수를 초과하면 Uptime Kuma는 모니터 상태를 down으로 변경하고 알림을 보냅니다. 푸시 토큰은 비밀로 취급하십시오. 토큰을 가진 사람은 누구나 정상적인 신호를 위조할 수 있습니다.

공개 상태 페이지 구축

상태 페이지는 고객에게 노출되는 화면으로, 대시보드를 공개하지 않으면서 서비스의 가동 여부와 최근 이력을 보여줍니다. Status Pages에서 New Status Page로 이동하여 이름과 슬러그(/status/main와 같은 공개 경로)를 지정합니다. 원하는 모니터를 "Websites"나 "APIs"와 같은 그룹으로 드래그하여 추가하고, 로고와 간단한 설명을 입력한 뒤 저장합니다. 또한 페이지를 별도의 도메인에 연결하여 status.example.com에서 직접 서비스하도록 설정할 수도 있습니다.

두 가지 주의 사항이 있습니다. 첫째, 상태 페이지는 서비스의 존재 여부와 가동 상태를 드러내므로 공개해도 괜찮은 모니터만 추가해야 합니다. 둘째, 대시보드는 로그인 뒤에 숨겨져 있지만, 상태 페이지는 의도적으로 공개되어 있으며 별도의 인증이 필요하지 않습니다.

리버스 프록시와 TLS를 적용하고 WebSocket을 고려하십시오

공개 인스턴스를 운영하려면 루프백에 바인딩된 컨테이너 앞단에 리버스 프록시를 배치하여 TLS와 호스트 이름을 설정하십시오. 많은 사용자가 실수하는 세부 사항은 다음과 같습니다. Uptime Kuma의 UI는 실시간 Socket.IO 애플리케이션이므로 프록시가 WebSocket 연결을 업그레이드해야 합니다. 이 설정을 누락하면 페이지는 로드되지만 연결되지 않습니다. 대시보드는 "Connecting..." 상태로 멈춰 있고, 실시간 하트비트는 업데이트되지 않으며, 브라우저 콘솔에는 WebSocket connection to 'wss://.../socket.io/...' failed가 표시됩니다.

nginx와 certbot을 설치한 다음 루프백 포트로 프록시하는 vhost를 작성하십시오. 우선 포트 80에서 설정하고 나중에 certbot으로 TLS를 추가하십시오. 챌린지, 갱신 타이머 및 실패 모드는 certbot과 nginx를 이용한 Let's Encrypt 인증서 발급에서 다룹니다.

sudo apt install -y nginx certbot python3-certbot-nginx

이 내용을 /etc/nginx/sites-available/status.example.com로 저장하십시오. 두 개의 WebSocket 관련 줄이 핵심입니다.

server {
    listen 80;
    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;
        proxy_read_timeout 3600s;
    }
}

사이트를 활성화하고 설정을 테스트한 뒤, certbot이 해당 블록을 다시 작성하여 443 포트에서 수신하도록 하고 인증서를 적용하며 HTTP를 HTTPS로 리다이렉트하게 하십시오.

sudo ln -s /etc/nginx/sites-available/status.example.com /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d status.example.com

Upgrade 및 Connection "upgrade" 쌍이 전체 설정의 핵심이며, proxy_read_timeout 3600s은 nginx가 장시간 유지되는 소켓을 강제로 끊지 않도록 방지합니다. certbot은 이 두 설정을 생성된 443 블록에 복사합니다. 이미 하나의 프록시 뒤에서 여러 컨테이너를 운영 중이라면, Traefik을 통한 라우팅 및 자동 TLS 설정을 사용하여 컨테이너 레이블만으로 동일한 작업을 수행할 수 있으며, 이 방식은 기본적으로 WebSocket 업그레이드를 전달합니다.

vhost 전체에 basic-auth를 적용하지 마십시오. 공개 상태 페이지와 /api/push 엔드포인트까지 차단되기 때문입니다. Uptime Kuma의 내장 로그인 기능을 유지하고, 인터넷에 노출된 경우 반복적인 로그인 실패를 감시하는 fail2ban을 추가하십시오. 대시보드를 공개할 필요가 없다면 프록시를 제거하고 VPN을 통해 접속하는 것이 좋습니다.

올바른 TLS 인증서 만료 모니터링

HTTP(s) 모니터를 사용하면 TLS 인증서가 만료되기 전에 경고를 받을 수 있습니다. Certificate Expiry Notification 항목을 체크하면 Uptime Kuma가 설정된 일수만큼 앞서 알림을 보냅니다. 이때 흔히 발생하는 두 가지 실수가 모니터링 결과를 왜곡합니다. 반드시 IP가 아닌 호스트네임으로 모니터링해야 합니다. SNI 없이 요청을 보내면 서버의 기본 인증서만 확인하게 되어 Hostname/IP does not match certificate's altnames 오류가 발생하기 때문입니다. 또한 만료 경고를 받으려는 모니터에서 Ignore TLS/SSL Error 옵션을 체크하지 마십시오. 이 옵션은 자체 서명된 내부 호스트(unable to verify the first certificate, DEPTH_ZERO_SELF_SIGNED_CERT)를 위한 것이지만, 이를 활성화하면 Uptime Kuma가 만료 여부를 포함한 인증서 검증 자체를 수행하지 않게 됩니다.

백업: 단일 디렉터리

모든 데이터가 /app/data에 저장되므로, 컨테이너를 중지한 상태에서 해당 볼륨을 복사하면 SQLite 파일의 일관성을 유지한 채 백업할 수 있습니다.

cd /srv/uptime-kuma
sudo docker compose stop
sudo docker run --rm \
  -v uptime-kuma_kuma-data:/data \
  -v /var/backups/kuma:/backup \
  alpine tar czf /backup/kuma-$(date -u +%Y%m%dT%H%M%SZ).tgz -C /data .
sudo docker compose start

Compose는 프로젝트 디렉터리 이름을 접두사로 붙이므로, 먼저 docker volume ls | grep kuma를 사용하여 볼륨의 실제 이름을 확인하십시오. 그 후 tarball을 서버 외부로 복사하십시오. 동일한 VPS에 저장된 백업은 진정한 의미의 백업이 아닌 단순 복사본에 불과합니다. 복구 과정은 이와 반대입니다. 스택을 중지하고, 비어 있는 /app/data 볼륨에 압축을 푼 뒤, 다시 시작하십시오.

업그레이드

업그레이드는 이미지 풀(pull) 방식으로 진행합니다:

cd /srv/uptime-kuma
sudo docker compose pull
sudo docker compose up -d

새 컨테이너는 첫 시작 시 데이터베이스 마이그레이션을 자동으로 수행합니다. 이때 docker compose logs -f을 모니터링하십시오. 이미지를 풀(pull)하기 전에 위에서 설명한 백업을 반드시 수행하고, 메이저 태그 범위 내에서 업그레이드하십시오. :1에서 :2로 이동하는 것은 단방향 마이그레이션이므로, 반드시 먼저 백업을 수행하고 릴리스 노트를 확인해야 합니다.

실패 유형 및 표시되는 메시지

localhost를 가리키는 모니터의 잘못된 "다운" 상태. 모니터가 timeout of 48000ms exceeded 또는 connect ETIMEDOUT 메시지와 함께 빨간색으로 표시되지만, 노트북에서는 서비스가 정상 응답합니다. Uptime Kuma가 실행 중인 동일한 호스트를 대상으로 설정했다면, 대상 서비스가 아닌 CPU나 메모리 급증으로 인해 체크가 지연된 것입니다. 모니터를 별도의 VPS로 옮기고 공용 호스트 이름을 대상으로 설정하십시오.

connect ECONNREFUSED 127.0.0.1:443 (또는 기타 포트). 해당 포트에서 수신 대기 중인 서비스가 없습니다. 서비스가 중단되었거나, 컨테이너 내부에서 localhost를 모니터링하고 있을 가능성이 있습니다. 컨테이너 내부에서 127.0.0.1은 서버가 아닌 컨테이너 자신을 의미합니다. 루프백 주소가 아닌 공용 호스트 이름을 모니터링하십시오.

이메일 테스트 시 Invalid login: 535-5.7.8 Username and Password not accepted. SMTP 자격 증명이 잘못되었거나, 서비스 제공업체가 계정 비밀번호 대신 앱 전용 비밀번호를 요구하는 경우입니다. 앱 비밀번호를 생성하여 입력하십시오.

이메일 테스트 시 connect ETIMEDOUT 또는 queryA ETIMEDOUT <host>. 포트 번호가 잘못되었거나 서비스 제공업체가 아웃바운드 SMTP를 차단하는 경우입니다. 465 또는 587이 Secure/STARTTLS 설정과 일치하는지 확인하고, 호스트에서 nc -vz smtp.example.com 587 명령을 사용하여 테스트하십시오. 많은 제공업체가 아웃바운드 25 포트를 차단하며, 일부는 요청하기 전까지 제출용 포트를 차단하기도 합니다.

이메일 테스트 시 self signed certificate 또는 unable to verify the first certificate. SMTP 서버가 Node에서 신뢰하지 않는 인증서를 제시하는 경우입니다. 임시방편으로 해결하지 말고 메일 서버의 인증서를 수정하십시오.

대시보드가 "Connecting..." 상태에서 멈추고 콘솔에 WebSocket connection ... failed이 표시됨. 리버스 프록시가 WebSocket 업그레이드를 처리하지 못하는 경우입니다. nginx에 Upgrade 및 Connection "upgrade" 헤더를 추가하거나, Traefik 또는 Caddy와 같이 기본적으로 해당 헤더를 전달하는 프록시를 사용하십시오. HTML은 일반적인 HTTP GET 요청이므로 로드되지만, 실시간 소켓 연결은 업그레이드가 필요합니다.

인증서 만료 모니터가 경고하지 않거나 잘못된 경고를 보냄. Ignore TLS/SSL Error 옵션이 체크되어 인증서 확인 기능이 비활성화되었거나, IP 주소를 대상으로 설정하여 SNI 누락으로 인해 잘못된 인증서를 읽고 Hostname/IP does not match certificate's altnames 오류가 발생하는 경우입니다. 옵션 체크를 해제하고 호스트 이름으로 모니터링하십시오.

로그에 SQLITE_BUSY 또는 database disk image is malformed 표시. /app/data 볼륨이 적절한 파일 잠금을 지원하지 않는 파일 시스템(주로 NFS)에 위치한 경우입니다. 로컬 Docker 볼륨으로 이동한 뒤 백업에서 복구하십시오.

FAQ

업타임 모니터는 어디에서 실행해야 합니까?

모니터링 대상 서버와는 다른 서버, 가급적 다른 제공업체나 다른 지역의 서버에서 실행해야 합니다. 사용자가 접근하는 방식과 동일하게 공용 인터넷을 통해 호스트 이름으로 대상에 접근하십시오. 모니터가 대상과 같은 서버에서 실행되면 서버가 중단될 때 모니터도 함께 중단됩니다. 또한 호스트에 부하가 걸리면 정상적인 서비스도 '다운'된 것으로 오판할 수 있습니다. 별도의 작은 VPS를 사용하면 이러한 문제를 모두 방지할 수 있습니다.

Telegram이나 이메일로 알림을 받으려면 어떻게 해야 합니까?

Settings의 Notifications 메뉴에서 채널을 추가한 뒤, 각 모니터에 연결하십시오. Telegram의 경우 @BotFather을 통해 봇을 생성하고 https://api.telegram.org/bot<token>/getUpdates에서 chat.id을 확인하십시오. 이메일의 경우 SSL에는 465을 사용하고, 제공업체가 2단계 인증을 요구하면 앱 비밀번호를 사용하여 STARTTLS용 587를 설정하십시오. 알림을 신뢰하기 전에 Test 버튼을 눌러 메시지가 정상적으로 도착하는지 확인하십시오.

Uptime Kuma로 cron 작업이나 백업 스크립트를 모니터링할 수 있습니까?

네, Push 모니터를 사용하면 가능합니다. Uptime Kuma가 제공하는 URL을 스크립트 끝에 curl하면 작업이 성공했을 때만 신호가 발생합니다. 작업이 실패하거나 서버가 다운되면 하트비트가 전달되지 않으며, 설정한 시간이 지나면 알림이 발송됩니다. 외부 체크 방식으로는 스크립트 내부를 확인할 수 없으므로, 예약된 작업의 실제 실행 여부를 확인하는 가장 확실한 방법입니다.

Uptime Kuma와 Zabbix 중 무엇을 사용해야 합니까?

Uptime Kuma는 "외부에서 보았을 때 서비스가 정상인가, 알림이 제대로 발송되었는가"라는 질문에 10분 내로 답을 주며, 리소스를 거의 사용하지 않고 상태 페이지 기능도 제공합니다. CPU, 메모리, 디스크 추세나 전체 인프라의 임계값과 같은 상세 지표는 수집하지 않습니다. 그러한 용도로는 전체 Zabbix 모니터링 서버와 같은 에이전트 기반의 무거운 도구가 필요하며, 많은 사용자가 두 도구를 함께 운영합니다. 무엇을 운영할지 아직 결정하지 못했다면 2026년 셀프 호스팅 추천 목록에서 모니터링의 맥락을 확인해 보십시오.

#uptime-kuma#monitoring #docker #self-hosting#status-page