README.ko.md

March 30, 2026 · View on GitHub

DockProbe

Docker 컨테이너 모니터링 대시보드 — 이상 탐지 & 텔레그램 알림
컨테이너 하나. 명령어 하나. 완벽한 가시성.

Docker Pulls Image Size

DockProbe란?

DockProbe는 단일 컨테이너로 실행되는 셀프호스팅 Docker 모니터링 대시보드입니다. 모든 컨테이너와 호스트 머신의 CPU, 메모리, 네트워크, 디스크 메트릭을 실시간으로 수집하여 깔끔한 다크 테마 웹 UI에 표시합니다.

GPU 인식 호스트 모니터링은 CPU 사용률, 호스트 메모리, 디스크 부족, 로드 평균과 함께 NVIDIA GPU 온도와 사용률을 실시간 차트로 추적합니다. ML 워크로드나 GPU 집약적 컨테이너를 운영한다면, DockProbe는 별도의 GPU 모니터링 도구 없이 완전한 가시성을 제공합니다.

문제가 발생하면 DockProbe가 자동으로 감지합니다. 6가지 이상 탐지 규칙이 CPU 폭주, 메모리 초과, 온도 경고, 디스크 부족, 예기치 않은 재시작, 네트워크 급증을 감시합니다. 각 알림에는 바로 실행 가능한 명령어가 포함된 권장 조치가 제공되어, 무엇이 잘못되었는지뿐만 아니라 정확히 어떻게 대응해야 하는지 알 수 있습니다. 알림은 텔레그램으로 즉시 전송되어 사용자가 알아차리기 전에 대응할 수 있습니다.

내장 보안 스캐너가 5분마다 16가지 자동 점검을 수행하여 컨테이너 설정 오류, 네트워크 노출, 호스트 보안 강화 상태를 확인합니다.

컨테이너마다 에이전트를 설치할 필요 없고, 외부 데이터베이스도 없고, 복잡한 설정도 없습니다. Docker 소켓을 마운트하고 명령어 하나만 실행하면 https://localhost:9090에서 Docker 환경 전체를 한눈에 볼 수 있습니다. 외부에서 접속하고 싶다면? Cloudflare Tunnel을 기본 지원하여 포트포워딩 없이 안전한 HTTPS 접속이 가능합니다.

빠른 시작

git clone https://github.com/deep-on/dockprobe.git && cd dockprobe && bash install.sh

끝. 대화형 설치가 인증, 텔레그램 알림, HTTPS를 자동 설정합니다. https://localhost:9090에 접속하세요.

필요 조건: Docker (Compose v2), Git, OpenSSL

Docker Hub에서 바로 실행

git clone도 빌드도 필요 없습니다 — pull하고 바로 실행:

# 1. Compose 파일과 환경변수 템플릿 다운로드
curl -fsSL https://raw.githubusercontent.com/deep-on/dockprobe/main/docker-compose.hub.yaml -o docker-compose.yaml
curl -fsSL https://raw.githubusercontent.com/deep-on/dockprobe/main/.env.example -o .env

# 2. .env 파일에 자격증명 입력
vi .env

# 3. (선택) 자체 서명 SSL 인증서 생성
mkdir -p certs && openssl req -x509 -newkey rsa:4096 -nodes \
  -keyout certs/key.pem -out certs/cert.pem \
  -days 825 -subj "/CN=dockprobe"

# 4. 실행
docker compose up -d

Docker Hub에서 사용 가능: deeponinc/dockprobe — Multi-arch (amd64 + arm64)

대시보드 미리보기

DockProbe 대시보드

주요 기능

카테고리	내용
실시간 대시보드	다크 테마 웹 UI, 10초 자동 갱신, 정렬 가능한 테이블, Chart.js 차트
컨테이너 모니터링	CPU %, 메모리 %, 네트워크 I/O, 블록 I/O, 재시작 횟수
호스트 모니터링	CPU/GPU 온도 및 사용률, 메모리 사용량, 디스크 사용량, 로드 평균
이상 탐지	6가지 규칙 + 권장 조치 안내 — CPU 폭주, 메모리 초과, 고온, 디스크 부족, 재시작, 네트워크 스파이크
텔레그램 알림	즉시 알림 + 알림 유형별 30분 쿨다운
보안	Basic Auth, 레이트 리밋 (5회 실패 시 60초 차단), HTTPS
보안 스캐너	16가지 자동 점검 (컨테이너/호스트/네트워크), 5분 주기 스캔, 심각도 배지
세션 관리	접속자 추적, 최대 접속 수 제한, 실시간 IP 표시
비밀번호 관리	대시보드 UI에서 사용자명/비밀번호 변경
설정 UI	대시보드에서 최대 접속 수 실시간 변경
접속 방식	자체 서명 SSL (기본) 또는 Cloudflare Tunnel (포트포워딩 불필요)
경량	Python 패키지 4개, 단일 HTML 파일, SQLite 7일 보관

대시보드 구성

섹션	내용
세션 바	로그인 사용자, IP, 활성 접속 수 / 최대 제한
호스트 카드	CPU 온도, GPU 온도, CPU/GPU %, 호스트 메모리, 디스크 %, 로드 평균
컨테이너 테이블	CPU/메모리/네트워크 기준 정렬, 이상 시 빨간색 표시
차트 (5개)	컨테이너 CPU·메모리 추이, 호스트 CPU/GPU %, 호스트 온도·로드
Docker 디스크	이미지, 빌드 캐시, 볼륨, 컨테이너 RW 레이어
알림 이력	최근 24시간 타임스탬프 포함

이상 탐지 규칙

규칙	조건	동작
컨테이너 CPU	>80% 3회 연속 (30초)	텔레그램 + 대시보드 빨간색
컨테이너 메모리	>90% (limit 대비)	즉시 알림
호스트 CPU 온도	>85°C	즉시 알림
호스트 디스크	>90% 사용	즉시 알림
컨테이너 재시작	restart_count 증가	즉시 알림
네트워크 스파이크	RX 10배 급증 + 100MB 이상	즉시 알림

모든 임계값은 환경변수로 조정 가능합니다.

각 이상 탐지에는 구체적인 명령어가 포함된 실행 가능한 권장 조치가 제공됩니다:

이상 유형	권장 조치 예시
CPU 폭주	`docker stats <name>` · `docker restart <name>` · `docker update --cpus=2 <name>`
메모리 초과	`docker stats <name>` · `docker update --memory=2g <name>`
재시작 반복	`docker logs --tail 50 <name>` · `docker inspect <name>`
네트워크 급증	`docker logs --tail 50 <name>` · DDoS 또는 예기치 않은 트래픽 확인
고온	팬/냉각 시스템 점검 · `sensors -u`로 상세 확인
디스크 부족	`docker system prune -f` · `docker builder prune -f` · `docker volume prune`

보안 스캐너

DockProbe는 5분마다 16가지 보안 점검을 자동 실행하고, 심각도 배지와 함께 전용 대시보드 섹션에 결과를 표시합니다.

카테고리	점검 항목
컨테이너 (9)	특권 모드, root 실행, 위험한 capability, Docker 소켓 마운트, 민감 경로 마운트, 읽기 전용 rootfs, AppArmor/Seccomp 비활성화, 환경변수 내 시크릿, 메모리/CPU 제한 미설정
네트워크 (3)	호스트 네트워크 모드, 과도한 포트 노출, SSH 포트 (22) 노출
호스트 (4)	Docker 데몬 보안 옵션, 커널 ASLR, IP 포워딩, Linux Security Module 상태

심각도 수준:

🔴 심각 — 즉각 조치 필요 (예: 특권 모드, 쓰기 가능한 Docker 소켓)
🟡 경고 — 보안 개선 권장
🔵 정보 — 참고용 발견 사항
🟣 사용 불가 — 환경 제약으로 점검 불가; 활성화 방법 안내

호스트 수준 점검에는 볼륨 마운트가 필요합니다 (/proc:/host_proc:ro, /sys:/host_sys:ro). 마운트되지 않은 경우 해당 점검은 설정 안내와 함께 사용 불가로 표시됩니다.

아키텍처

┌──────────────────────────────────────────────┐
│  DockProbe Container                         │
│                                              │
│  FastAPI + uvicorn (port 9090)               │
│  ├── collectors/                             │
│  │   ├── containers.py  (aiodocker)          │
│  │   ├── host.py        (/proc, /sys, GPU)   │
│  │   └── images.py      (system df)          │
│  ├── alerting/                               │
│  │   ├── detector.py    (6 규칙 + 조치)      │
│  │   └── telegram.py    (httpx)              │
│  ├── security/                               │
│  │   └── scanner.py     (16 checks)          │
│  ├── storage/                                │
│  │   └── db.py          (SQLite WAL)         │
│  └── static/                                 │
│      └── index.html     (Chart.js)           │
│                                              │
│  마운트 볼륨:                                 │
│    docker.sock (ro), /sys (ro), /proc (ro),  │
│    nvidia-smi (ro), SQLite named volume      │
└──────────────────────────────────────────────┘

의존성 (4개만):

fastapi — 웹 프레임워크
uvicorn — ASGI 서버
aiodocker — 비동기 Docker API 클라이언트
httpx — 비동기 HTTP 클라이언트 (텔레그램 API)

설정

.env 파일로 모든 설정을 관리합니다:

# 인증 (필수)
AUTH_USER=admin
AUTH_PASS=your-password

# 텔레그램 알림 (선택)
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_CHAT_ID=your-chat-id

# 임계값 (선택, 기본값 표시)
CPU_THRESHOLD=80
MEM_THRESHOLD=90

# 최대 접속 수 (선택, 0 = 무제한)
MAX_CONNECTIONS=3

# Cloudflare Tunnel (선택)
CF_TUNNEL_TOKEN=your-tunnel-token

접속 방식

방법 1: 로컬 네트워크 (자체 서명 SSL) — 기본

bash install.sh   # 옵션 1 선택

https://localhost:9090 또는 https://<서버IP>:9090으로 접속

같은 네트워크의 다른 기기에서 접속하려면 서버의 LAN IP를 사용합니다 (예: https://192.168.1.100:9090). 필요 시:

방화벽에서 포트 허용: sudo ufw allow 9090/tcp
브라우저에서 자체 서명 인증서 경고 수락

브라우저 경고가 뜨는 이유? DockProbe는 설치 시 생성된 자체 서명 SSL 인증서를 사용합니다. 공인 인증기관(CA)이 발급한 인증서가 아니기 때문에 브라우저가 "연결이 비공개로 설정되어 있지 않습니다" 경고를 표시합니다. 정상적인 동작이며 보안 문제가 아닙니다 — "고급" → "사이트로 이동"을 클릭하면 접속됩니다. 이 경고를 없애려면 정식 TLS 인증서를 자동 제공하는 Cloudflare Tunnel (방법 3)을 사용하세요.

방법 2: 포트포워딩으로 원격 접속

Cloudflare 없이 외부에서 접속하려면:

공유기에서 9090 포트를 서버의 LAN IP로 포워딩
https://<공인IP>:9090으로 접속
공인 IP가 바뀌면 DDNS 서비스 (No-IP, DuckDNS 등) 사용

참고: 포트가 직접 노출됩니다. Basic Auth + HTTPS가 기본 활성화되어 있지만, 보안을 위해 Cloudflare Tunnel (방법 3)을 권장합니다.

방법 3: Cloudflare Tunnel (원격 접속 추천)

포트포워딩 불필요, 방화벽 변경 불필요, 정식 TLS 인증서 — 어디서든 가장 쉽고 안전하게 접속하는 방법입니다.

bash install.sh   # 옵션 2 선택, 터널 토큰 입력

설정 단계:

Cloudflare Zero Trust에서 무료 계정 생성
Networks > Tunnels > Create a tunnel 이동
터널 이름 지정 (예: dockprobe) 후 터널 토큰 복사
bash install.sh 실행 후 Cloudflare Tunnel 옵션 선택
토큰 입력
Cloudflare 대시보드에서 Public Hostname을 http://localhost:9090으로 설정
https://your-domain.com으로 정식 TLS 인증서와 함께 접속

API 엔드포인트

엔드포인트	메서드	설명
`/`	GET	대시보드 HTML
`/api/current`	GET	최신 스냅샷 (컨테이너 + 호스트 + 이미지 + 이상탐지)
`/api/history/{name}?hours=1`	GET	컨테이너 시계열 데이터
`/api/history/host?hours=1`	GET	호스트 시계열 데이터
`/api/alerts?hours=24`	GET	알림 이력
`/api/session`	GET	현재 사용자, IP, 활성 접속 수
`/api/settings`	GET/POST	런타임 설정 (max_connections)
`/api/change-password`	POST	사용자명/비밀번호 변경
`/api/health`	GET	헬스체크 (인증 불필요)

보안

DockProbe는 다중 보호 레이어를 갖춘 안전한 셀프호스팅을 위해 설계되었습니다:

인증 및 접근 제어

Basic Auth — 모든 엔드포인트 인증 필수 (/api/health 제외)
PBKDF2-SHA256 비밀번호 해싱 — 랜덤 솔트 적용 (600k 반복)
레이트 리밋 — 로그인 5회 실패 시 IP별 60초 차단
최소 8자 비밀번호 요구
접속 수 제한 — 최대 동시 접속자 설정 가능

네트워크 및 전송

HTTPS — 자체 서명 RSA-4096 (기본) 또는 Cloudflare Tunnel
CORS — 교차 출처 요청 명시적 차단
CSRF 보호 — POST 엔드포인트에 X-Requested-With 헤더 필수
HTTP 폴백 경고 — 평문 모드 시 시작 시 경고 표시 (터널 전용)

컨테이너 보안 강화

비루트 실행 — 컨테이너가 appuser로 실행, root 아님
읽기 전용 마운트 — Docker 소켓, /sys, /proc 모두 read-only
경로 탐색 방지 — 정적 파일 서빙 시 경로 검증
제어 기능 없음 — 모니터링 전용, 컨테이너 조작 불가
OpenAPI/Swagger 비활성화 — 프로덕션에서 API 문서 엔드포인트 비활성화

프록시 인식 레이트 리밋

X-Forwarded-For는 TRUSTED_PROXIES 환경변수에 등록된 IP에서만 신뢰
직접 연결 시 항상 실제 클라이언트 IP 사용

수동 설치

설치 스크립트 대신 직접 설정하려면:

git clone https://github.com/deep-on/dockprobe.git
cd dockprobe

# .env 설정
cp .env.example .env
vi .env

# SSL 인증서 생성 (선택)
mkdir -p certs
openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout certs/key.pem -out certs/cert.pem \
  -days 365 -subj "/CN=dockprobe"

# 시작
docker compose up -d --build

라이선스

Apache License 2.0 — LICENSE 참조

귀속 조건: 수정 및 재배포 시 DeepOn 로고와 "Powered by DeepOn Inc." 문구를 UI에 유지해야 합니다.

DeepOn Inc.에서 만들었습니다.