Copy & Run

Uptime Kuma로 서비스 상태 감시하기: 도커 실행, 감시 대상 추가, 정상과 장애 확인

오픈소스 모니터링 도구 Uptime Kuma를 도커로 localhost에만 열어 띄우고, 감시 대상 두 개를 등록해 정상(UP)과 장애(DOWN)가 각각 기록되는 것을 확인합니다. 데이터가 도커 볼륨에 남는 방식도 함께 봅니다.

실습 노트 · 2026-10-28 발행 · 10분 · 2026-10 확인
실습 코드 내려받기: 전체 받기(zip)GitHubkuma_demo.py

사내 서비스가 죽었는데 사용자가 알려 주기 전까지 모르면 곤란합니다. Uptime Kuma는 주소를 주기적으로 호출해 응답 여부를 기록하고 알림을 보내는 오픈소스 도구입니다. 이 글에서는 Uptime Kuma를 도커로 띄우고 감시 대상을 두 개 등록해, 정상과 장애가 모두 기록되는지 확인합니다.

준비물

항목 확인한 값
Docker 29.5.3 (Windows 11)
이미지 louislam/uptime-kuma:1 (컨테이너 안 버전 1.23.17)

1. 실행

docker run -d --name osk-kuma -p 127.0.0.1:3901:3001 -v osk_kuma:/app/data louislam/uptime-kuma:1
  • 127.0.0.1:3901:3001: 이 PC 안에서만 접속되게 열었습니다. 주소 앞의 127.0.0.1을 빼면 같은 네트워크의 다른 PC에서도 접속됩니다.
  • -v osk_kuma:/app/data: 설정과 기록을 도커 볼륨에 저장합니다. 컨테이너를 지워도 볼륨이 남습니다.

약 25초 뒤 컨테이너 상태가 healthy가 되었고, http://127.0.0.1:3901/은 HTTP 302(초기 설정 화면으로 이동)를 돌려주었습니다.

docker ps 결과에서 osk-kuma 컨테이너가 healthy 상태이고 127.0.0.1의 3901번이 컨테이너 3001번에 연결된 것을 확인합니다.
docker ps 결과에서 osk-kuma 컨테이너가 healthy 상태이고 127.0.0.1의 3901번이 컨테이너 3001번에 연결된 것을 확인합니다.

이 단계의 파일 내려받기:kuma_demo.py

2. 관리자와 감시 대상 만들기

브라우저에서 계정을 만드는 것이 보통이지만, 이 글에서는 화면 대신 Uptime Kuma가 쓰는 소켓 API를 파이썬(python-socketio)으로 불러 같은 일을 했습니다. 그래서 화면 조작 과정은 확인하지 못했습니다.

  • 관리자 계정 만들기와 로그인이 모두 ok: True였습니다.
  • 감시 대상 1: 같은 PC의 다른 컨테이너 주소 http://host.docker.internal:3902/alive, 20초마다, HTTP 200번대면 정상.
  • 감시 대상 2: 아무것도 없는 http://host.docker.internal:3999/, 같은 조건.

host.docker.internal은 컨테이너 안에서 도커를 돌리는 PC를 가리키는 이름입니다.

이 단계의 파일 내려받기:kuma_demo.py

3. 결과

약 25초 뒤 받은 기록입니다(status 1은 UP, 0은 DOWN).

# 기대 출력(이 PC)
감시 대상 1: status 1, ping 13ms, 이후 10ms
감시 대상 2: status 0 (응답 시간 없음)

살아 있는 대상에는 UP과 응답 시간(10~13ms)이 기록되었고, 없는 포트는 DOWN으로 기록되었습니다. 대상 2가 DOWN인 이유는 연결이 안 되는 것이지 서비스가 느린 것이 아닙니다. 화면에서 이 둘을 구분해 읽으려면 응답 시간 항목이 비어 있는지 봅니다.

Uptime Kuma 대시보드에서 온라인 1, 오프라인 1로 집계되고, vaultwarden-alive는 100퍼센트에 초록 막대, wrong-port는 0퍼센트에 빨간 막대이며, 아래 표에 200 - OK와 connect ECONNREFUSED 메시지가 나란히 보이는 것을 확인합니다.
Uptime Kuma 대시보드에서 온라인 1, 오프라인 1로 집계되고, vaultwarden-alive는 100퍼센트에 초록 막대, wrong-port는 0퍼센트에 빨간 막대이며, 아래 표에 200 - OK와 connect ECONNREFUSED 메시지가 나란히 보이는 것을 확인합니다.

wrong-port 감시 대상의 상세 화면에서 주소 host.docker.internal:3999, 오프라인 표시, 응답 시간 N/A, 업타임 0퍼센트가 보이는 것을 확인합니다.
wrong-port 감시 대상의 상세 화면에서 주소 host.docker.internal:3999, 오프라인 표시, 응답 시간 N/A, 업타임 0퍼센트가 보이는 것을 확인합니다.

위 화면은 소켓 API로 만든 같은 구성을 다시 띄워 로그인한 상태로 캡처한 것입니다. 오프라인 사유로 ECONNREFUSED가 적혀, 서비스가 느린 것이 아니라 연결 자체가 거부됐다는 것을 구분할 수 있습니다.

4. 장애와 복구를 직접 만들어 보기

감시 도구는 장애가 났을 때 몇 초 만에 알아차리는지가 중요합니다. 감시 대상(nginx 컨테이너)을 일부러 멈췄다가 다시 시작해, DOWN과 UP이 기록되기까지 걸린 시간을 쟀습니다. 이번에는 host.docker.internal 대신 도커 네트워크(osk-net-kuma)를 만들어 두 컨테이너를 같은 네트워크에 넣고, 컨테이너 이름(osk-target)으로 감시했습니다. 감시 대상은 세 개입니다.

이름 종류 주소 정상일 때
정상 대상 HTTP http://osk-target/ UP, 응답 4~5ms
없는 포트 HTTP http://osk-target:3999/ DOWN, connect ECONNREFUSED
키워드 키워드 http://osk-target/에 Welcome to nginx가 있는지 UP, keyword is found

세 번째 종류인 키워드 감시는 응답 코드가 200이어도 화면에 엉뚱한 내용(오류 안내 등)이 나오면 DOWN으로 잡습니다. 서비스가 살아 있는지가 아니라 제대로 된 내용을 주는지를 보는 용도입니다.

감시 주기가 20초일 때 측정한 시간입니다(두 번 실행한 값).

단계 첫 실행 두 번째 실행
nginx 멈춤 → DOWN 기록 19초 25초
nginx 시작 → UP 기록 19초 20초

네 값 가운데 두 번째 실행의 DOWN 기록(25초)만 주기(20초)를 넘었습니다. DOWN이 기록되는 사유 문장은 실행마다 달랐습니다. 첫 실행에서는 getaddrinfo ENOTFOUND osk-target(멈춘 컨테이너의 이름을 못 찾음)이었고, 두 번째 실행에서는 timeout of 10000ms exceeded(10초 안에 응답 없음)였습니다. 같은 장애라도 도커가 이름을 풀어 주는 시점에 따라 사유가 달라지므로, 사유 문장 하나로 원인을 단정하지 않습니다. nginx를 멈춘 직후에는 감시 대상마다 확인 시각이 달라서, 어떤 대상은 아직 UP으로 보이기도 했습니다. 한 주기(20초)를 더 기다린 뒤 읽으면 세 개가 모두 DOWN이었습니다.

이 단계의 파일 내려받기:kuma_demo.py

5. 볼륨 백업과 복원

설정과 기록은 /app/data의 SQLite 파일(kuma.db)에 있습니다. 컨테이너를 멈춘 뒤 볼륨 내용을 다른 볼륨에 복사하고, 원래 컨테이너와 볼륨을 지운 다음 복사본으로 새 컨테이너를 띄웠습니다.

  • 복사된 파일: docker-tls, kuma.db, kuma.db-shm, kuma.db-wal, screenshots, upload
  • 복원한 컨테이너에서 같은 계정으로 로그인이 됐고, 감시 대상 세 개(없는 포트, 정상 대상, 키워드)가 그대로 있었습니다.

복사하기 전에 컨테이너를 멈춘 것은 SQLite가 쓰는 도중인 파일을 복사하면 깨질 수 있기 때문입니다. 아래 6절 표의 "백업" 행(볼륨을 주기적으로 복사한다)을 실제로 해 본 셈입니다. 다만 같은 PC 안에서 볼륨 사이로 복사한 것이어서, 다른 서버로 옮기는 경우는 확인하지 않았습니다.

이 단계의 파일 내려받기:kuma_demo.py

6. 운영 전에 정할 것

항목 내용
알림 슬랙, 이메일 등 알림 채널을 연결해야 장애를 바로 압니다. 이 글에서는 알림을 보내 보지 않았습니다
접속 범위 사내에 열 때는 HTTPS와 접근 제한을 먼저 정합니다
백업 볼륨 osk_kuma를 주기적으로 복사합니다
감시 주기 20초는 실험용입니다. 대상이 많으면 대상 서버 부하를 생각해 늘립니다

전체 코드

위 2~5단계를 한 번에 실행하는 파일입니다. 소켓 API로 계정과 감시 대상을 만드는 코드도 이 파일에 들어 있습니다. kuma_demo.py로 저장하고 pip install "python-socketio[client]" websocket-client를 한 뒤 python -X utf8 kuma_demo.py로 실행합니다. 이 PC에서는 약 4분이 걸렸습니다. 같은 이름의 컨테이너와 볼륨이 있으면 먼저 지우므로, 같은 이름의 다른 컨테이너가 있다면 이름을 바꾸고 실행합니다. 끝에서 만든 컨테이너, 네트워크, 볼륨을 모두 지웁니다. 비밀번호는 실습용 값이며 실제 계정에는 쓰지 않습니다.

kuma_demo.py 실행 결과에서 계정과 감시 대상 세 개가 만들어지고, 장애 중에 세 대상이 모두 DOWN이며, nginx 재시작 뒤 UP으로 돌아오고, 볼륨 복사본으로 새로 띄운 컨테이너에서 로그인과 감시 대상 세 개가 그대로 있는 것을 확인합니다.
kuma_demo.py 실행 결과에서 계정과 감시 대상 세 개가 만들어지고, 장애 중에 세 대상이 모두 DOWN이며, nginx 재시작 뒤 UP으로 돌아오고, 볼륨 복사본으로 새로 띄운 컨테이너에서 로그인과 감시 대상 세 개가 그대로 있는 것을 확인합니다.

"""Uptime Kuma 를 도커로 띄우고, 감시 대상 세 개를 만들어 정상 -> 장애 -> 복구를 기록하고, 볼륨 백업과 복원까지 확인한다.

준비: Docker, pip install "python-socketio[client]" websocket-client
주의: osk-kuma, osk-kuma-b, osk-target 컨테이너와 osk_kuma, osk_kuma_b 볼륨, osk-net-kuma 네트워크를 만들고 끝에서 모두 지운다.
      같은 이름이 이미 있으면 먼저 지운다. 127.0.0.1:3901 에만 연다.
실행: python -X utf8 kuma_demo.py   (약 4분)
"""
import subprocess
import time

import socketio

PORT = 3901
URL = f"http://127.0.0.1:{PORT}"
NET, TARGET, KUMA, VOL = "osk-net-kuma", "osk-target", "osk-kuma", "osk_kuma"
USER, PW = "admin", "Lab-Only-Pass-1"      # 실습용 값이다. 실제 계정에는 쓰지 않는다


def sh(*a, check=True):
    r = subprocess.run(a, capture_output=True, text=True)
    if check and r.returncode:
        raise RuntimeError(f"{a}: {r.stderr.strip()}")
    return r.stdout.strip()


def cleanup():
    for c in (KUMA, TARGET):
        sh("docker", "rm", "-f", c, check=False)
    sh("docker", "network", "rm", NET, check=False)
    sh("docker", "volume", "rm", VOL, "osk_kuma_b", check=False)


def wait_up():
    for _ in range(90):
        code = subprocess.run(["curl", "-s", "-o", "/dev/null", "-w", "%{http_code}", URL + "/"],
                              capture_output=True, text=True).stdout
        if code in ("200", "302"):
            return
        time.sleep(2)
    raise RuntimeError("Uptime Kuma 가 시작되지 않았다")


def connect():
    sio = socketio.Client()
    sio.beats = {}                                   # 감시 대상 번호 -> [(시각, 상태)]

    @sio.on("heartbeat")
    def _hb(b):
        sio.beats.setdefault(b["monitorID"], []).append((time.time(), b["status"], b.get("msg", ""), b.get("ping")))

    sio.connect(URL, transports=["websocket"])
    return sio


def call(sio, event, *args):
    box = {}
    sio.emit(event, args, callback=lambda r: box.update(r=r))
    for _ in range(100):
        if "r" in box:
            return box["r"]
        time.sleep(0.1)
    raise TimeoutError(event)


def monitor(name, url, **kw):
    m = {"type": "http", "name": name, "url": url, "method": "GET", "interval": 20, "retryInterval": 20,
         "resendInterval": 0, "maxretries": 0, "timeout": 10, "accepted_statuscodes": ["200-299"],
         "notificationIDList": {}, "ignoreTls": False, "upsideDown": False, "maxredirects": 10,
         "dns_resolve_type": "A", "dns_resolve_server": "1.1.1.1", "proxyId": None, "expiryNotification": False}
    m.update(kw)
    return m


def last(sio, mid):
    return sio.beats.get(mid, [(0, None, "", None)])[-1]


NAMES = {1: "정상 대상", 2: "없는 포트", 3: "키워드"}


def show(sio, title):
    print(f"-- {title}")
    for mid, name in NAMES.items():
        t, st, msg, ping = last(sio, mid)
        print(f"   {name:<8} status={st} ({'UP' if st == 1 else 'DOWN' if st == 0 else '기록 없음'}) ping={ping} msg={msg[:40]!r}")


cleanup()
print("## 1. 감시받을 nginx 와 Uptime Kuma 실행")
sh("docker", "network", "create", NET)
sh("docker", "run", "-d", "--name", TARGET, "--network", NET, "nginx:alpine")
sh("docker", "run", "-d", "--name", KUMA, "--network", NET, "-p", f"127.0.0.1:{PORT}:3001",
   "-v", f"{VOL}:/app/data", "louislam/uptime-kuma:1")
wait_up()
print("Uptime Kuma 응답 확인:", sh("docker", "inspect", "-f", "{{.State.Status}}", KUMA))

print("## 2. 관리자 계정과 감시 대상 세 개 만들기(소켓 API)")
sio = connect()
print("setup:", call(sio, "setup", USER, PW).get("ok"))
print("login:", call(sio, "login", {"username": USER, "password": PW, "token": ""}).get("ok"))
for name, url, extra in (("정상 대상", f"http://{TARGET}/", {}),
                         ("없는 포트", f"http://{TARGET}:3999/", {}),
                         ("키워드", f"http://{TARGET}/", {"type": "keyword", "keyword": "Welcome to nginx"})):
    r = call(sio, "add", monitor(name, url, **extra))
    print(f"add {name}: ok={r.get('ok')} id={r.get('monitorID')}")
time.sleep(45)
show(sio, "45초 뒤")

print("## 3. 장애 만들기: 감시 대상 nginx 를 멈춘다")
t0 = time.time()
sh("docker", "stop", TARGET)
detected = None
while time.time() - t0 < 90:
    if last(sio, 1)[1] == 0 and last(sio, 1)[0] > t0:
        detected = last(sio, 1)[0] - t0
        break
    time.sleep(1)
print(f"정상 대상이 DOWN 으로 기록되기까지 {detected:.0f}초 (감시 주기 20초)" if detected else "90초 안에 DOWN 이 기록되지 않음")
time.sleep(22)                                   # 감시 대상마다 확인 시각이 달라, 한 주기 더 기다린 뒤 읽는다
show(sio, "장애 중")

print("## 4. 복구: nginx 를 다시 시작한다")
t1 = time.time()
sh("docker", "start", TARGET)
back = None
while time.time() - t1 < 90:
    if last(sio, 1)[1] == 1 and last(sio, 1)[0] > t1:
        back = last(sio, 1)[0] - t1
        break
    time.sleep(1)
print(f"UP 으로 돌아오기까지 {back:.0f}초" if back else "90초 안에 UP 으로 돌아오지 않음")
sio.disconnect()

print("## 5. 볼륨 백업과 복원: 컨테이너와 볼륨을 지운 뒤 같은 데이터로 다시 띄운다")
sh("docker", "stop", KUMA)
sh("docker", "run", "--rm", "-v", f"{VOL}:/data", "-v", "osk_kuma_b:/bk", "alpine", "sh", "-c",
   "cp -a /data/. /bk/ && ls /bk | tr '\n' ' '")
print("복사한 파일:", sh("docker", "run", "--rm", "-v", "osk_kuma_b:/bk", "alpine", "ls", "/bk").replace("\n", " "))
sh("docker", "rm", "-f", KUMA)
sh("docker", "volume", "rm", VOL)
sh("docker", "run", "-d", "--name", KUMA, "--network", NET, "-p", f"127.0.0.1:{PORT}:3001",
   "-v", "osk_kuma_b:/app/data", "louislam/uptime-kuma:1")
wait_up()
sio = connect()
print("복원 뒤 login:", call(sio, "login", {"username": USER, "password": PW, "token": ""}).get("ok"))
time.sleep(5)
sio.disconnect()
sio2 = socketio.Client()
lists = {}
sio2.on("monitorList", lambda d: lists.update(d=d))
sio2.connect(URL, transports=["websocket"])
call(sio2, "login", {"username": USER, "password": PW, "token": ""})
time.sleep(4)
print("복원된 감시 대상:", sorted(m["name"] for m in lists.get("d", {}).values()))
sio2.disconnect()

print("## 6. 정리")
cleanup()
print("남은 osk 컨테이너:", len(sh("docker", "ps", "-a", "--filter", "name=osk-", "--format", "{{.Names}}").split()))
이 단계의 파일 내려받기:kuma_demo.py

자주 막히는 곳

증상 원인과 해결
장애 사유 문장이 실행마다 다릅니다 ENOTFOUND와 timeout처럼 같은 장애도 다르게 적힐 수 있습니다. 사유는 참고만 합니다
컨테이너 안에서 localhost로 감시하면 DOWN입니다 localhost는 컨테이너 자신입니다. host.docker.internal이나 같은 네트워크의 컨테이너 이름을 씁니다
포트가 이미 사용 중입니다 바깥쪽 포트 3901을 다른 번호로 바꿉니다
이미지 태그를 :2로 올려도 됩니까 이 글은 :1만 실행했습니다. 메이저 버전이 바뀌면 설정 방식이 다를 수 있어 확인하지 않았습니다

확인 범위

  • 해 본 것: 2026-10-28, Windows 11 · Docker 29.5.3 · Uptime Kuma 1.23.17에서 컨테이너 실행, 소켓 API로 계정과 감시 대상 두 개 생성, UP과 DOWN 기록 확인. 29일에 전체 스크립트(kuma_demo.py)를 두 번 실행해 감시 대상 세 개, 장애와 복구 시간, 볼륨 복사 뒤 복원을 확인했습니다.
  • 해 보지 않은 것: 웹 화면 조작, 알림 발송, 상태 페이지 공개, HTTPS 프록시, 다른 서버로의 이전, :2 이후 버전.
  • 읽을 때 주의: 응답 시간은 같은 PC 안의 호출이라 실제 네트워크 상황을 반영하지 않습니다.
이 단계의 파일 내려받기:kuma_demo.py

이 글은 스타트업·소규모 조직 보안 구축 로드맵의 한 단계입니다.

이 글의 다음 단계

이 내용을 팀 교육으로 진행하고 싶으신가요?

인원, 수준, 일정에 맞춰 실습 환경까지 준비해 진행합니다. 대상과 기간을 알려 주시면 구성을 제안해 드립니다.

교육 문의하기

교육 진행 순서와 자주 묻는 질문 보기

팀이나 교육 담당자에게 이 글 제안하기

메일로 보내실 수도 있습니다: fankh111@gmail.com

같은 카테고리의 글