직접 구성해보니 모니터링에서 가장 크게 체감한 부분은 “서비스가 죽었다”는 사실보다 언제부터 상태가 흔들렸는지였습니다. 홈서버는 하루 종일 들여다보는 장비가 아니다 보니, 장애를 늦게 발견하면 원인을 거슬러 올라가는 데 더 많은 시간이 걸립니다.
Rocky Linux 9.x에서 Uptime Kuma 올리기
Rocky Linux 9.x 서버에 Docker와 Compose v2가 이미 설치되어 있다는 전제로 구성했습니다. Uptime Kuma는 별도 데이터베이스 없이 컨테이너 하나로 시작할 수 있어 홈서버 모니터링용으로 부담이 적었습니다.
저는 설정 파일과 데이터를 분리하기 위해 /opt/uptime-kuma 아래에 Compose 파일과 볼륨 디렉터리를 두었습니다. 핵심은 컨테이너가 재시작되더라도 모니터링 이력과 알림 설정이 사라지지 않도록 볼륨 경로를 고정하는 것입니다.
실행은 Compose v2 기준으로 아래처럼 하면 됩니다.
컨테이너가 올라온 뒤에는 브라우저에서 http://서버IP:3001로 접속해 관리자 계정을 만들면 됩니다. 내부망에서만 사용할 계획이라면 공유기 포트포워딩은 열지 않는 편이 낫습니다.
재시작 정책과 볼륨을 먼저 챙긴 이유
Uptime Kuma는 모니터링 도구라서 다른 서비스보다 더 꾸준히 살아 있어야 합니다. 그래서 restart: unless-stopped를 넣어 Docker 데몬 재시작이나 서버 재부팅 이후에도 자동으로 올라오게 했습니다.
always를 쓰는 경우도 있지만, 제가 쓰는 홈서버에서는 관리자가 명시적으로 컨테이너를 내렸다면 그 상태를 유지하는 쪽이 더 자연스러웠습니다. 그래서 unless-stopped 정책이 운영 방식에 더 잘 맞았습니다.
| 항목 | 장점 | 단점 |
|---|---|---|
restart: unless-stopped |
서버 재부팅 후 자동 복구되고, 사용자가 직접 내린 상태는 유지됩니다. 홈서버 운영에 가장 무난한 선택입니다. | 장애 테스트 중 컨테이너를 내려둔 사실을 잊으면 계속 꺼진 상태로 남을 수 있습니다. |
restart: always |
Docker가 살아나는 순간 컨테이너도 다시 올라옵니다. | 의도적으로 중지한 컨테이너도 다시 살아날 수 있어 점검 중에는 불편할 수 있습니다. |
| 재시작 정책 없음 | 동작이 단순하고 예측하기 쉽습니다. | 서버 재부팅 후 모니터링이 꺼진 채 방치될 가능성이 큽니다. |
볼륨은 ./data:/app/data처럼 잡아두면 /opt/uptime-kuma/data에 설정과 이력이 남습니다. 나중에 서버를 옮기거나 백업할 때도 이 디렉터리만 챙기면 복구가 비교적 간단합니다.
서비스별로 다른 방식으로 감시하기
홈서버에 여러 컨테이너를 올려두면 서비스마다 확인 방식이 조금씩 달라집니다. HTTP만 확인하면 놓치는 부분이 있고, Ping만 보면 애플리케이션이 실제로 응답하는지 알기 어렵습니다.
MinIO처럼 포트 응답이 중요한 서비스는 TCP와 HTTP를 나눠서 보는 편이 좋았습니다. Immich는 웹 화면이나 API 응답 여부를 보는 쪽이 실용적이고, Open WebUI는 로그인 화면이 뜨는지만 확인해도 초기 장애 감지에는 충분했습니다.
| 서비스 | 확인 방식 | 한계 |
|---|---|---|
| MinIO | TCP 9000, 콘솔 HTTP 응답을 나눠 보면 스토리지 접근 문제를 빨리 알 수 있습니다. | 인증이 필요한 API까지 깊게 확인하려면 별도 엔드포인트 설계가 필요합니다. |
| Immich | HTTP 상태 확인으로 웹 서비스 장애를 감지하기 좋습니다. | 백그라운드 작업 큐나 DB 상태까지는 기본 HTTP 체크만으로 부족할 수 있습니다. |
| Open WebUI | 웹 UI 응답 여부를 간단히 확인할 수 있어 운영 부담이 적습니다. | 모델 서버나 백엔드 연결 문제는 별도 체크가 필요할 수 있습니다. |
Uptime Kuma에서 모니터를 추가할 때는 서비스 성격에 맞춰 이렇게 나눴습니다.
HTTP 체크는 상태 코드가 200번대로 돌아오는지 보는 방식이라 가장 직관적입니다. TCP는 서비스 포트가 열려 있는지 확인하는 데 좋고, Ping은 서버 자체가 네트워크에서 보이는지 확인하는 용도로 두면 됩니다.
Discord Webhook으로 알림 보내기
알림은 Telegram도 많이 쓰지만, 저는 홈서버 알림을 한 채널에 모아두기 쉬운 Discord Webhook 방식으로 설정했습니다. 이미 개인 서버나 운영 채널을 쓰고 있다면 별도 봇을 만들지 않아도 되는 점이 편합니다.
Discord에서 채널 설정으로 들어가 Webhook을 만들고 URL을 복사합니다. 그다음 Uptime Kuma의 Settings > Notifications에서 Discord를 선택한 뒤 Webhook URL을 붙여 넣으면 됩니다.
설정 후에는 바로 저장하고 끝내지 말고 Test 버튼으로 실제 알림이 오는지 확인해야 합니다. 이 단계에서 알림이 오지 않으면 장애 상황에서도 조용할 수밖에 없습니다. 채널 권한, Webhook URL 오타, 방화벽 설정을 먼저 확인하는 편이 좋습니다.
알림 문구는 길게 만들 필요가 없었습니다. 서비스명, 상태, 발생 시각 정도만 있어도 휴대폰에서 보고 바로 판단할 수 있습니다.
내부망 전용과 Cloudflare Tunnel 비교
Uptime Kuma를 꼭 외부에 공개할 필요는 없습니다. 집 안이나 VPN 안에서만 확인한다면 내부 IP로 접근하는 구성이 가장 단순합니다. 외부에서도 상태를 보고 싶다면 Cloudflare Tunnel 뒤에 두는 방식도 선택할 수 있습니다.
| 구성 | 장점 | 단점 |
|---|---|---|
| 내부망 전용 | 외부 노출이 거의 없고 구성이 단순합니다. 홈서버 기본값으로 두기 좋습니다. | 밖에서는 VPN 없이 접속하기 어렵습니다. |
| Cloudflare Tunnel | 포트포워딩 없이 외부 접속 주소를 만들 수 있습니다. | 계정, 터널, 접근 정책을 추가로 관리해야 합니다. 설정이 느슨하면 모니터링 화면이 노출될 수 있습니다. |
내부망 전용이면 Compose의 포트 바인딩을 조금 더 제한할 수 있습니다.
이렇게 하면 해당 내부 IP에서만 포트를 열도록 구성할 수 있습니다. 다만 서버 네트워크 환경에 따라 IP가 바뀌면 접속이 안 될 수 있으니, 홈서버에는 고정 IP를 주는 편이 관리하기 쉽습니다.
Cloudflare Tunnel 뒤에 둘 경우에는 Uptime Kuma 자체 로그인만 믿기보다 Cloudflare Access 같은 접근 제어를 함께 두는 쪽이 낫습니다. 모니터링 화면에는 서비스 주소와 장애 이력이 들어가기 때문에 생각보다 민감한 정보가 많습니다.
이력으로 장애 시작 시점 찾기
Uptime Kuma를 며칠만 켜둬도 의외로 패턴이 보입니다. 특정 시간대에 Immich가 잠깐 느려지거나, MinIO 콘솔만 간헐적으로 끊기는 식입니다.
이럴 때 “지금 죽었나?”보다 언제부터 불안정했나를 보는 게 더 중요했습니다. 로그를 뒤져볼 기준 시간이 생기기 때문입니다. 예를 들어 새벽 2시부터 HTTP 체크가 흔들렸다면, 그 시간대의 백업 작업, 컨테이너 업데이트, 스토리지 I/O를 같이 보면 됩니다.
모니터링 간격은 너무 촘촘하게 잡지 않았습니다. 개인 홈서버 기준으로는 30초에서 60초 정도면 충분했습니다. 외부 서비스처럼 SLA를 따지는 환경이 아니라면, 감지 속도보다 알림 피로도를 줄이는 쪽이 오래 갑니다.
Uptime Kuma 자체 장애에 대비하기
모니터링 도구도 결국 하나의 컨테이너입니다. 그래서 Uptime Kuma만 믿고 끝내기보다는 최소한의 백업과 점검 루틴을 만들어두는 게 좋았습니다.
/opt/uptime-kuma/data디렉터리 주기 백업- Compose 파일을 별도 Git 저장소나 NAS에 보관
- 서버 재부팅 후
docker compose ps로 상태 확인 - Discord 테스트 알림을 한 달에 한 번 정도 직접 실행
- Uptime Kuma 컨테이너 로그 확인
백업은 거창하게 시작하지 않아도 됩니다. 중요한 건 설정과 이력을 잃지 않는 것입니다. 특히 알림 설정을 다시 만드는 일이 은근히 번거로워서, 데이터 디렉터리 백업은 처음 구성할 때 같이 잡아두는 편이 낫습니다.
홈서버 모니터링은 장애를 없애는 도구라기보다 장애를 늦게 발견하는 시간을 줄이는 장치에 가깝습니다. Uptime Kuma를 붙여두니 서비스별 상태를 한 화면에서 볼 수 있었고, 무엇보다 장애가 시작된 시점을 남길 수 있어 운영할 때 꽤 쓸모가 있었습니다.
답글 남기기