VPS에 Uptime Kuma 설치하기: 웹사이트 및 서버 모니터링 구축

2026. 8. 30.읽는 데 13분

Tropic

VPS에 Uptime Kuma 설치하기: 웹사이트 및 서버 모니터링 구축

Uptime Kuma: VPS에 자체 웹사이트 모니터링 구축하기

웹사이트가 고장 난 상태에서도 200 OK를 계속 반환할 수 있습니다. 백업 작업도 눈에 띄는 오류 없이 중단될 수 있습니다. Uptime Kuma는 두 상황을 모두 감지합니다. 웹사이트, API, 포트, 백그라운드 작업을 점검하고 문제가 발생하면 알림을 보냅니다.

이 글에서는 모니터링을 어디에 배치해야 하는지, 어떤 VPS가 필요한지, Uptime Kuma 2를 설치하고 HTTPS, Telegram, 상태 페이지를 설정하는 방법을 살펴봅니다.

7단계로 설치하는 Uptime Kuma

모니터링 대상 프로젝트와 분리된 소형 VPS를 준비합니다.
monitor.example.com 같은 서브도메인을 VPS로 연결합니다.
Docker를 설치하고 Uptime Kuma 2를 실행합니다.
내부 포트 3001의 외부 접근을 차단하고 HTTPS를 연결합니다.
HTTP, DNS, TCP 또는 Push 모니터를 만듭니다.
Telegram과 필요한 경우 상태 페이지를 설정합니다.
업데이트와 데이터 디렉터리의 외부 백업을 구성합니다.

Uptime Kuma란 무엇인가

Uptime Kuma는 무료 오픈 소스 자체 호스팅 도구입니다. 대시보드와 점검 기록은 사용자의 서버에 저장됩니다.

HTTP(S), TCP 포트, ping, DNS, WebSocket, 응답 내 텍스트와 JSON, Push 신호, Docker 컨테이너를 점검할 수 있습니다. 최소 점검 간격은 20초입니다. 수십 가지 알림 채널, 2FA, 응답 지연 그래프, TLS 인증서 모니터링, 여러 상태 페이지도 지원합니다.

`200 OK` 뒤에 숨은 장애를 찾는 방법

일반적인 HTTP 점검은 응답 코드만 확인합니다. 하지만 웹 서버가 빈 페이지나 애플리케이션 오류 화면을 표시하면서도 성공 상태를 반환할 수 있습니다.

더 정확하게 점검하려면 다음 기능을 사용합니다.

Keyword — 사이트 이름이나 “사용자 대시보드”처럼 표시되어야 하는 문구를 찾습니다;
JSON Query — API 응답의 값을 확인합니다. 예: status: healthy.

이렇게 하면 단순히 포트에 접속할 수 있는지만 확인하는 것이 아니라, 애플리케이션이 정상 작동한다는 최소한의 징후까지 검증할 수 있습니다.

백업과 cron 작업을 위한 Push 모니터

Push 모니터는 서비스를 직접 주기적으로 조회하지 않고, 서비스가 정기적으로 보내는 신호를 기다립니다. 백업 스크립트나 cron 작업은 성공적으로 완료된 뒤 고유 URL을 호출합니다. 신호가 제시간에 도착하지 않으면 Uptime Kuma가 장애를 알립니다.

이를 통해 “사이트는 작동하지만 일일 백업이 며칠째 생성되지 않는” 조용한 문제를 발견할 수 있습니다.

Uptime Kuma가 대체하지 못하는 것

Uptime Kuma는 주로 가용성과 응답 시간을 감시합니다. CPU, RAM, 디스크, 로그, 컨테이너 메트릭은 Prometheus, Netdata, Zabbix 또는 다른 모니터링 시스템으로 보완해야 합니다. Kuma는 외부에서 문제를 발견하고, 메트릭은 원인을 찾는 데 도움을 줍니다.

모니터링을 별도 VPS에 두어야 하는 이유

Uptime Kuma를 웹사이트와 같은 서버에 설치하면 VPS, 네트워크 또는 데이터센터 장애가 발생할 때 프로젝트와 모니터링이 동시에 중단될 수 있습니다. 그러면 알림도 전송되지 않을 수 있습니다.

대시보드는 별도 VPS에 배치하고, 중요한 프로젝트라면 다른 지역이나 다른 제공업체를 선택합니다. Kuma 자체를 외부 서비스로 점검하는 것도 유용합니다. 모니터링 시스템도 누군가가 감시해야 합니다.

Uptime Kuma 서버 요구 사항

프로젝트는 CPU와 RAM에 대한 엄격한 공식 최소 사양을 지정하지 않습니다. 소규모 설치에 실용적인 시작 구성은 다음과 같습니다.

1 vCPU;
1 GB RAM;
10 GB SSD;
Ubuntu 24.04 LTS;
IPv4;
HTTPS용 도메인 또는 서브도메인.

이 구성은 일반적으로 수십 개의 간단한 점검에 충분합니다. 수백 개의 모니터, 장기간 기록 보관 또는 브라우저 기반 점검이 필요하다면 2 GB RAM 이상을 선택하는 것이 좋습니다.

VPS에 Uptime Kuma를 설치하는 방법

이 예시에서는 Ubuntu 24.04와 서브도메인 monitor.example.com을 사용합니다.

1. DNS와 방화벽 설정

VPS의 IPv4 주소를 가리키는 DNS A 레코드를 만듭니다. SSH로 접속한 뒤 필요한 포트를 엽니다.

ssh root@SERVER_IP
apt update && apt upgrade -y

ufw allow OpenSSH
ufw allow 80/tcp
ufw allow 443/tcp
ufw --force enable

새 연결을 확인하기 전까지 현재 SSH 세션을 닫지 마세요.

2. Docker와 Docker Compose 설치

apt install -y ca-certificates curl
install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

apt update
apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

docker compose version

3. Uptime Kuma 2 실행

mkdir -p /opt/uptime-kuma
cd /opt/uptime-kuma

cat > compose.yaml <<'EOF'
services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - ./data:/app/data
EOF

docker compose up -d
docker compose ps

:2 태그를 사용하세요. latest는 여전히 오래된 v1 브랜치를 가리킵니다. /app/data 디렉터리는 로컬 디스크나 일반 Docker volume에 저장해야 합니다. NFS처럼 파일 잠금을 올바르게 지원하지 않는 스토리지는 데이터베이스를 손상시킬 수 있습니다.

포트 3001은 127.0.0.1에서만 접근할 수 있습니다. 외부에는 HTTPS가 적용된 리버스 프록시를 통해 대시보드를 공개합니다.

4. Caddy로 HTTPS 연결

apt install -y caddy

cat > /etc/caddy/Caddyfile <<'EOF'
monitor.example.com {
    reverse_proxy 127.0.0.1:3001
}
EOF

caddy validate --config /etc/caddy/Caddyfile
systemctl reload caddy

DNS가 VPS를 가리키면 Caddy가 TLS 인증서를 자동으로 요청하고 WebSocket을 프록시합니다. 대시보드는 도메인이나 서브도메인의 루트에 배치해야 합니다. example.com/kuma 같은 주소는 지원되지 않습니다.

5. 관리자 계정 생성

https://monitor.example.com을 열고 길고 고유한 비밀번호로 계정을 만든 다음 이중 인증을 활성화합니다.

첫 번째 모니터를 추가하는 방법

Add New Monitor를 클릭하고 HTTP(s)를 선택합니다.

이름과 전체 URL을 입력합니다.
예를 들어 60초로 점검 간격을 설정합니다.
일시적인 네트워크 장애에 대비해 재시도를 두 번 추가합니다.
알림 채널을 선택합니다.
모니터를 저장하고 성공한 요청이 표시되는지 확인합니다.

메인 사이트에는 HTTP와 Keyword 점검이 유용하고, API에는 상태 확인 엔드포인트와 JSON Query를 사용할 수 있습니다. 모니터링만을 위해 데이터베이스나 관리 포트를 인터넷에 공개하지 마세요. 신뢰할 수 있는 네트워크나 VPN을 사용하세요.

백업용 Push 모니터 예시

Push 유형의 모니터를 만든 뒤 고유 URL을 스크립트 끝에 추가합니다.

backup-command && \
  curl -fsS "https://monitor.example.com/api/push/SECRET_TOKEN?status=up&msg=backup-ok"

요청은 백업이 성공한 뒤에만 실행됩니다. Push 토큰은 비밀번호처럼 보관하세요. URL을 아는 사람은 거짓 성공 신호를 보낼 수 있습니다.

Telegram 연결 방법

@BotFather를 통해 봇을 만들고 봇에게 메시지를 보낸 다음 Settings → Notifications → Telegram을 엽니다. Bot Token과 Chat ID를 입력하고 Test를 누른 뒤 알림 채널을 모니터에 연결합니다. 중요한 서비스에는 이메일 같은 두 번째 채널을 추가하세요.

상태 페이지를 만드는 방법

Status Pages에서는 모니터를 그룹화하고 현재 상태와 가동 기록을 표시하며 도메인을 연결하고 Maintenance를 통해 예정된 작업을 알릴 수 있습니다. 내부 IP와 기술적인 URL은 공개하지 마세요. 고객에게는 “웹사이트”, “API”, “사용자 대시보드”, “결제” 같은 구성 요소만 보여주면 충분합니다.

업데이트와 백업

대규모 업데이트 전에는 컨테이너를 중지하고 데이터 디렉터리를 저장합니다.

cd /opt/uptime-kuma
docker compose down

tar -czf /root/uptime-kuma-$(date +%F).tar.gz \
  data compose.yaml

docker compose up -d

압축 파일을 다른 장치나 외부 스토리지로 옮기세요. 같은 VPS에 있는 복사본은 서버 삭제나 디스크 장애로부터 보호하지 못합니다.

일반 업데이트는 다음과 같이 진행합니다.

cd /opt/uptime-kuma
docker compose pull
docker compose up -d --force-recreate

실행 후 docker compose ps, 대시보드, 테스트 알림을 확인합니다.

Uptime Kuma용 VPS 선택 방법

소규모 설치에는 1 vCPU와 1 GB RAM을 갖춘 Linux VPS면 충분합니다. 성능보다 독립성이 더 중요합니다. 메인 프로젝트가 접속 불가능한 상황에서도 모니터는 계속 작동해야 합니다.

모니터링 대상 서비스가 다른 플랫폼이나 독립 노드에 있다면 Uptime Kuma를 tropic.host의 VPS에 배치할 수 있습니다. Ubuntu, Docker, 고정 IP를 이용하면 대시보드를 빠르게 실행할 수 있고, 점검 수가 늘어나면 리소스를 확장할 수 있습니다.

프로덕션 환경이 이미 같은 인프라에 있다면 다른 노드를 선택하거나 외부 예비 모니터를 추가하세요. 장애 지점을 분리하는 것이 CPU 코어 하나를 더 추가하는 것보다 유용합니다.

자주 발생하는 실수

실수	문제가 되는 이유	더 나은 방법
모니터링을 프로젝트와 같은 곳에 설치함	공통 장애가 발생하면 서비스와 알림이 모두 사라짐	별도 VPS나 다른 지역 사용
포트 `3001`을 외부에 공개함	리버스 프록시와 HTTPS 없이 대시보드에 접근할 수 있음	포트를 `127.0.0.1`에 바인딩
`200` 코드만 확인함	애플리케이션 오류가 성공처럼 보일 수 있음	Keyword 또는 JSON Query 추가
`latest` 태그를 사용함	오래된 v1 브랜치를 가리킴	`louislam/uptime-kuma:2` 사용
백업을 같은 VPS에 저장함	서버와 함께 백업도 사라짐	`data` 디렉터리를 외부로 복사

요약

Uptime Kuma는 소형 VPS를 웹사이트, API, DNS, 포트, 인증서, 백그라운드 작업을 위한 자체 모니터링 센터로 바꿔 줍니다. Keyword는 깨진 페이지를 찾고, JSON Query는 잘못된 API 응답을 감지하며, Push는 중단된 백업이나 cron 작업을 알려 줍니다.

신뢰할 수 있는 구성을 위해 모니터링을 프로덕션과 분리하고 포트 3001을 닫으며 HTTPS, 2FA, 두 개의 알림 채널을 설정하세요. 이후 데이터 디렉터리를 외부에 백업하고 Uptime Kuma 자체도 독립적으로 점검하세요.

FAQ

Uptime Kuma는 무료인가요?

네. MIT 라이선스로 배포되는 오픈 소스 프로젝트입니다. 인프라, 도메인, 외부 백업 비용만 필요합니다.

Uptime Kuma에는 RAM이 얼마나 필요한가요?

소규모 설치는 1 GB RAM으로 시작하는 것이 적절합니다. 수백 개의 점검, 장기간 기록 또는 Browser Engine을 사용하려면 2 GB 이상을 할당하세요.

Docker 없이 Uptime Kuma를 설치할 수 있나요?

네. Node.js와 PM2를 이용해 설치할 수 있습니다. 하지만 VPS에서는 Docker Compose가 일반적으로 업데이트, 이전, 복구하기 더 쉽습니다.

도메인 없이 Uptime Kuma를 사용할 수 있나요?

기술적으로는 IP 주소나 SSH 터널을 통해 사용할 수 있습니다. 인터넷에서 계속 접속하려면 서브도메인과 HTTPS를 사용하는 편이 더 안전합니다.

Uptime Kuma에서 CPU, RAM, 디스크 사용량을 볼 수 있나요?

완전한 서버 메트릭 시스템처럼 제공되지는 않습니다. 서버 리소스를 모니터링하려면 Prometheus, Netdata, Zabbix 또는 다른 전문 도구를 함께 사용하세요.

블로그로 돌아가기