시놀로지 나스에 Uptime Kuma 설치하기 - 여러 서비스 상태를 한눈에 모니터링하는 법

인프라 관리의 핵심에는 문제가 생기기 전에 예방하는 것도 중요하지만, 그만큼 중요한 것이 문제가 발생했을 때 즉시 인지하는 것입니다. 특히 시놀로지 나스(Synology NAS)나 여러 서버를 운영하고 있다면, Uptime Kuma 같은 모니터링 도구는 거의 필수에 가깝습니다.

오늘은 저희가 실제 고객사의 장비를 관리할 때 애용하는 오픈소스 모니터링 도구, Uptime Kuma를 시놀로지 나스에 설치하는 방법을 공유합니다.

Uptime Kuma란? 시놀로지 나스에서 쓰는 이유
- 비즈니스 활용 사례: 고객사 나스 통합 관리
- 개인 개발자 활용 사례: '바이브 코딩' 시대의 필수품
시놀로지 나스에 Uptime Kuma 설치 방법 (도커)
마치며

Uptime Kuma란? 시놀로지 나스에서 쓰는 이유

사실 네트워크 상태를 체크하는 도구가 굉장히 많은 편입니다. 유료 솔루션도 많고, 무료도 많은데요, Uptime Kuma는 다음과 같은 장점이 있습니다.

직관적인 대시보드: 한눈에 들어오는 가동률(Uptime) 그래프와 응답 시간.
다양한 알림 지원: Slack, Telegram, Discord, 이메일 등 거의 모든 알림 수단에 연결 가능.
다양한 모니터링 대상: HTTP(s), TCP, Ping, DNS record, 도커 컨테이너(Docker Container) 등 지원.
가벼운 리소스: 시놀로지의 컨테이너 환경에서 매우 적은 리소스로 구동.
오픈소스: 소스가 투명하게 공개되어 있고, 많은 사용자들의 기여가 지속적으로 이루어짐.

현재는 2.x 버전대까지 개발이 진행되었으며, 기능적으로는 충분히 실사용이 가능한 수준입니다. 다만 오픈소스 특성상 메이저 버전 업데이트 시 일부 설정 변경이 필요할 수 있습니다.

비즈니스 활용 사례: 고객사 나스 통합 관리

저희는 고객사에 나스 구축 후 프리미엄 매니지먼트 유지보수 서비스 계약을 한 고객사에 대해서는 24시간 모니터링 및 보안 관제를 제공합니다.

하지만 나스 쪽에 설치해둔 모니터링 코드는 나스 자체가 죽은 경우(정전이나 네트워크 인프라 변경 등으로 연결이 안되는 상태) 저희가 확인할 수가 없습니다.

그래서 나스가 통신불능 상태가 되면 바로 알림을 받고 대응을 하기 위해서는 지속적인 모니터링 솔루션이 필요합니다만, 직접 ping이나 HTTP 상태 코드를 모니터링하는 툴을 만들지 않아도 Uptime Kuma 같은 툴을 사용하면 간단히 모니터링 및 알림 서비스를 만들 수가 있습니다.

개인 개발자 활용 사례: '바이브 코딩' 시대의 필수품

최근 Cursor나 ChatGPT 등 AI를 활용한 소위 '바이브 코딩'으로 1인 서비스를 런칭하는 분들이 많아졌습니다. 본인이 만든 서비스가 잘 돌아가고 있는지, API 서버가 죽지는 않았는지 주기적으로 확인을 해주는 게 좋습니다.

최초에 서비스를 서버에 올리고 실행할 때는 잘 되던 것이 언제부터인가 나도 모르는 사이 어떤 문제로 멈출 수도 있고, 또 메인 서비스는 잘 돌아가는데, API가 먹통이 되는 등 문제가 생길 여지는 많습니다.

이런 경우에 나스에 Uptime Kuma를 설치해두고 각종 서비스들을 모니터링하면 중단이 되더라도 바로 확인하고 조치가 가능합니다.

시놀로지 나스에 Uptime Kuma 설치 방법 (도커)

시놀로지는 도커 컴포즈(Docker Compose)를 지원하는 최신 패키지 컨테이너 매니저(Container Manager) 패키지를 제공합니다. 해당 패키지를 사용하여 설치해 보겠습니다.

먼저 컨테이너 매니저 패키지가 준비되어 있지 않다면, 컨테이너 매니저를 먼저 설치해 줍니다.

시놀로지 나스에서 컨테이너 매니저 설치 및 실행

기준:

Synology DSM 7.3

시놀로지 나스에 컨테이너 매니저를 설치하려면 먼저 패키지 센터 앱을 켜 주어야 합니다. 해당 앱의 검색창에 Container Manager를 키워드로 검색합니다.

결과로 Container Manager(Docker Inc. 개발, Synology Inc. 게시)가 나올텐데, 설치를 누른 후, 설치가 완료되어 열기 버튼이 활성화되면 눌러서 열어줍니다.

컨테이너 매니저를 처음 실행하면 좌측에 여러 메뉴 탭이 보이는데요, 주요 메뉴는 다음과 같습니다.

개요: 현재 실행중인 컨테이너들과 프로젝트 상태 요약
프로젝트: 도커 컴포즈 기반 앱 관리
컨테이너: 단일 도커 컨테이너 앱 관리
이미지: 각 도커 이미지 상태 및 업데이트 관리
레지스트리: 도커 허브(Docker Hub) 등 외부 이미지 저장소 검색
네트워크: 각 컨테이너나 프로젝트에서 사용하는 네트워크 설정
로그: 컨테이너 매니저의 동작 로그(이 앱의 GUI를 통한 활동만 기록합니다)

다른 메뉴는 사실 잘 만질 일이 없고, 프로젝트 메뉴가 아마 저희가 가장 많이 사용할 메뉴가 될 겁니다. 대부분의 셀프호스트 서비스들은 도커 컴포즈를 기반으로 배포되기 때문입니다.

원본 가이드에서 전체 내용 확인하기→

1. 프로젝트 생성 및 설치

먼저 컨테이너 매니저의 프로젝트 메뉴에서 [생성] 버튼을 누릅니다.

일반 설정

컨테이너 생성 창이 나타나면 프로젝트 이름은 원하는 이름으로 설정하고, 경로는 Uptime Kuma의 데이터가 저장될 독립 경로(가능하면 다른 앱이나 파일이 설치되지 않은 경로)를 새로 만들어서 지정해 줍니다.

원본은 docker-compose.yml 만들기를 선택해 줍니다. 그렇게 하면 텍스트를 직접 입력할 수 있는 필드가 나타나는데, 거기에 아래 코드를 붙여넣어 줍니다.

services:
  uptime-kuma:
    image: louislam/uptime-kuma:latest
    container_name: uptime-kuma
    restart: always
    ports:
      - "3001:3001"
    volumes:
      - ./data:/app/data
    environment:
      - TZ=Asia/Seoul  # 다른 국가라면 해당 타임존으로 수정

위 내용을 입력했다면 다음을 눌러 넘어갑니다.

웹 포털 설정

다음으로 웹 포털 설정 단계가 나타나는데, 여기에서는 Web Station을 통해 연결하지 않고 향후 역방향 프록시로 쉽게 접근이 가능하도록 하기 위해 아무 것도 선택하지 않고 다음을 눌러 넘어갑니다.

Uptime Kuma와 같은 도커 컴포즈 기반의 앱들의 경우 정적 웹서비스와 달리 Web Station에서 재부팅 시 제대로 상태를 잡아내기 어려운 버그가 있습니다.

요약

마지막으로 내가 설정한 값들의 요약 내용이 표로 나타납니다. 맞게 설정했는지 다시 확인합니다.

여기에서 우리는 Uptime Kuma의 경로로 설정한 루트 경로 아래의 /data 경로를 Uptime Kuma의 /app/data 폴더로 사용하기로 했습니다. 따라서 File Station을 열어 해당 경로에 들어간 후 data라는 이름의 폴더를 만들어 줍니다.

해당 과정을 마쳤다면 아래의 프로젝트가 생성되면 프로젝트 시작 을 체크하고 완료를 눌러 생성을 완료합니다.

이렇게 하면 터미널 빌드라는 창이 나타나고, 무엇인가 여러 가지를 다운로드하고 설치하는 화면이 나타납니다. Uptime Kuma의 원본 저장소에서 데이터를 가져오고 설치하는 과정이며, 시간이 조금 걸릴 수 있으니 기다려 줍니다.

  ..
  Container uptime-kuma Started
Exit Code: 0

마지막으로 위와 같이 나타나면 설치가 정상적으로 끝나고 실행까지 마무리된 것입니다.

2. 관리자 계정 설정

설치가 완료되면 나스의 3001번 포트를 통해 Uptime Kuma에 접속할 수 있게 됩니다. 예를 들어 내 나스의 내부 아이피 주소가 192.168.0.255라면, 웹브라우저의 주소창에 http://192.168.0.255:3001 을 입력하여 접속할 수 있습니다.

해당 페이지에 접속하면 Uptime Kuma의 언어와 초기 관리자 정보를 생성하게 됩니다. Language 항목은 한국어로 선택하시고, 이름 부분에 아이디를, 비밀번호를 두 번 입력해서 생성하기 버튼을 누릅니다.

3. 웹 개방

TIP

Uptime Kuma의 모든 기능(Push를 통한 HTTP 요청 등)을 사용하기 위해서는 이 앱을 외부에 개방하여 외부에서 요청을 받을 준비를 해야합니다.
단, 내 나스 쪽에서 수동적으로 서비스의 생존 여부를 확인하기만 한다면 3단계는 건너뛰고 바로 4단계를 진행하시면 됩니다.

Uptime Kuma를 웹에 개방하기 위해서는 시놀로지 DSM의 역방향 프록시 기능을 사용하면 간편합니다.

시놀로지 DSM에서 역방향 프록시 설정하기

기준:

Synology DSM 7.3

역방향 프록시를 설정하기 위해서는 먼저 DSM에 관리자 계정으로 접속한 다음, 제어판에 접속해야 합니다.

제어판의 메뉴를 클릭하면 로그인 포털이라는 메뉴가 보입니다.

로그인 포털 메뉴를 클릭한 뒤, 고급 탭으로 이동합니다.

그러면 역방향 프록시라는 항목과 버튼이 보일텐데, 이것을 눌러줍니다.

역방향 프록시 창의 [생성] 버튼을 누르면 새로운 역방향 프록시 규칙을 지정할 수 있게 됩니다.

일반 탭에는 다음과 같은 항목들이 있습니다.

구분	항목	설명
	역방향 프록시 이름	관리용 식별 이름 (외부에 노출되지 않습니다)
소스	프로토콜	HTTP(암호화 없음), HTTPS(암호화) 프로토콜 중 선택
소스	호스트 이름	외부에서 접속할 도메인 주소
소스	포트	외부에서 접속할 포트(HTTPS 기본 포트는 443)
소스	HSTS 활성화	HTTPS 강제 적용(보안을 위해 활성화)
대상	프로토콜	서비스에서 사용중인 프로토콜
대상	호스트 이름	서비스를 제공하는 주소(도메인 혹은 아이피, localhost 등)
대상	포트	해당 서비스가 실제로 사용하는 포트 번호

NOTE

여기에서 소스 호스트 이름으로 사용하는 도메인 주소는 A Record 값이 나스의 외부 IP 주소로 향해있거나, CNAME 값을 나스에 연결된 도메인으로 연결해 두어야 합니다.
[제어판] - [보안] - [인증서] 탭에 해당 도메인을 포함하는 인증서가 존재해야 하며, 인증서 페이지의 [설정] 버튼을 눌러 해당 서비스에 연결되는 인증서가 올바르게 설정되었는지 확인해야 합니다.

원본 가이드에서 전체 내용 확인하기→

해당 일반 탭의 내용은 아래와 같이 채워넣습니다.

항목	값
역방향 프록시 이름	`Uptime Kuma`와 같이 식별용 이름 입력
소스 프로토콜	`HTTPS`
소스 호스트 이름	Uptime Kuma를 연결하고자 하는 도메인 주소(예: `uptime-kuma.nasid.synology.me`)
소스 포트	외부에서 접속 가능한 포트 입력.
소스 HSTS 활성화	✅(안전한 연결을 위해 활성화를 권장)
대상 프로토콜	`HTTP`
대상 호스트 이름	`localhost`
대상 포트	`3001`(만약 .yml 파일 입력 시 다른 포트를 지정했다면 해당 포트를 입력합니다.)

다음으로는 사용자 지정 머리글 탭으로 이동하여 [생성] 버튼을 누른 뒤 [WebSocket]을 누릅니다. 그렇게 하면 자동으로 Upgrade와 Connection 항목이 생성될텐데, 이렇게 설정된 것을 확인하고 저장을 눌러 마칩니다.

4. 웹을 통한 접속 및 앱 설정

만약 3단계에서 역방향 프록시를 설정했다면 해당 설정한 도메인(예: uptime-kuma.nasid.synology.me)으로 접속하시고, 그러지 않았다면 2단계처럼 나스 아이피에 3001번 포트로 접속합니다. Uptime Kuma의 UI가 나타납니다.

역방향 프록시로 접속중이라면 우측 상단 로그인 프로필을 클릭하여 설정 메뉴를 열어줍니다. 여기에서 역방향 프록시 탭으로 이동한 후, HTTP 헤더 영역의 프록시 신뢰 항목을 확인으로 선택하고 저장을 누릅니다.

이제 실제 모니터링 대상을 추가해 보겠습니다. 이 프로젝트는 비교적 활발하게 개발이 이루어지고 있는 프로젝트라 UI가 종종 바뀔 수 있습니다.

좌측 상단의 [+ 새로운 모니터링 추가하기] 버튼을 눌러 새 모니터링 항목을 추가할 수 있습니다.

저는 테스트를 위해 네이버의 업타임을 체크하도록 설정해 보겠습니다. 아래 항목들을 입력합니다.

모니터링 종류: 대부분의 웹사이트 모니터링을 위해서는 HTTP(s)를 선택하면 됩니다.
이름: 해당 모니터링 항목을 식별하기 위한 이름으로, 저는 네이버를 입력하겠습니다.
URL: 모니터링할 주소입니다. 웹사이트의 경우 해당 웹사이트의 주소를 그대로 입력하면 됩니다. 제 경우 https://www.naver.com을 입력했습니다.
하트비트 주기: 해당 서비스의 생존 여부를 확인하는 시간 주기입니다. 기본값은 60으로, 60초마다 확인하도록 설정해 두면 됩니다.
알림 설정: 조건이 되면 알림을 받는 방법입니다. 클릭하면 처음 설정을 하게 될 텐데요, 텔레그램 알림을 추천합니다. 비용이 들지 않고 간단합니다. Botfather를 통해 만든 봇 토큰과 채팅 아이디를 입력하여 설정 가능합니다. 2버전대부터는 메시지 내용을 커스터마이징할 수 있습니다.

필요한 내용들을 채웠다면 최하단의 저장을 눌러 작업을 저장합니다.

이와 같은 방식으로 모니터링을 원하는 모든 서비스들을 추가합니다.

Uptime Kuma로 여러 서비스들의 온라인 상태를 확인하는 대시보드 화면

서비스들을 추가하면 위와 같이 일목요연하게 각 서비스의 활성 여부를 확인할 수 있습니다.

각 서비스를 클릭하면 업타임이 최근 24시간, 30일 간 몇%인지, 평균 응답 시간이 어떻게 되는지 등을 세부 페이지에서 확인할 수 있으며, HTTPS 방식의 연결일 경우 인증서 만료까지 얼마나 남았는지도 확인이 가능하여 인증서 갱신도 관리를 할 수 있습니다.

최초로 설정한 후에는 며칠 정도 각 서비스의 상태 추이를 보면서 이벤트 정보를 수집해 보는 게 좋습니다. 예를 들어 저희 같은 경우 일부 고객사에서 새벽에 몇 분 정도 서비스가 끊기는 경우가 있었는데, 그 시간이 거의 일정한 것으로 보아 네트워크 인프라의 주기적인 점검이 예상되어 실제 고객사의 PC에서 확인해 보니 공유기가 매일 새벽에 재시작되는 설정이 되어있었습니다. 이렇게 되면 나스가 먹통이 되지는 않지만 상태 체크를 위한 통신이 불가능해지므로 Down으로 잠시 인식될 수 있어, Uptime Kuma의 점검 예약 기능으로 해당 시간을 점검 시간으로 예약하여 알림에서 제외할 수 있었습니다.

마치며

Uptime Kuma는 시놀로지에 간단하게 설치할 수 있는 앱이지만 그 효용성은 굉장히 좋습니다. 이걸 한 번 설치해 두면 적어도 서버가 죽었는지 확인하는 노동은 완전히 사라지는 거죠.

혹시 설치나 설정 등의 과정에서 어려움이 있다면 아래 견적 요청을 통해 전문가의 도움을 받아보세요.