Beszel Docker 설치 가이드: 경량 서버 모니터링의 새로운 표준 ⋆ Blog * JackerLab

개요

Beszel은 Docker 통계, 히스토리 데이터, 알림 기능을 갖춘 경량 서버 모니터링 플랫폼입니다. Prometheus + Grafana 스택의 복잡함 없이, 몇 분 만에 서버와 컨테이너를 모니터링할 수 있습니다. Go로 작성되어 매우 가볍고, Hub-Agent 아키텍처로 여러 서버를 중앙에서 관리합니다.

항목	내용
GitHub	https://github.com/henrygd/beszel
공식 사이트	https://beszel.dev
Docker Hub	https://hub.docker.com/r/henrygd/beszel
라이선스	MIT
개발 언어	Go
최신 버전	0.18.x (2025년 기준)

Beszel이란?

Beszel은 2024년에 등장해 빠르게 인기를 얻은 셀프호스팅 서버 모니터링 도구입니다. “간단하고 가벼운 서버 모니터링”을 목표로, 복잡한 설정 없이 즉시 사용할 수 있도록 설계되었습니다.

핵심 철학

"Simple, lightweight server monitoring"
- 설정 최소화
- 리소스 효율성
- Docker 네이티브 지원
- 즉시 사용 가능

아키텍처

Beszel은 두 가지 컴포넌트로 구성됩니다:

컴포넌트	역할	설명
Hub	중앙 서버	웹 대시보드, 데이터 저장, 알림 관리
Agent	모니터링 에이전트	각 서버에서 실행, 메트릭 수집 및 전송

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Server 1   │     │  Server 2   │     │  Server 3   │
│   (Agent)   │     │   (Agent)   │     │   (Agent)   │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │
       └───────────────────┼───────────────────┘
                           │ SSH (암호화)
                           ▼
                    ┌─────────────┐
                    │    Hub      │
                    │ (Dashboard) │
                    └─────────────┘

주요 기능

시스템 모니터링

메트릭	설명
CPU	호스트 및 컨테이너별 사용량
메모리	RAM, Swap, ZFS ARC 포함
디스크	사용량, I/O (다중 파티션 지원)
네트워크	호스트 및 컨테이너 대역폭
로드	Load Average
온도	시스템 센서
GPU	Nvidia, AMD, Intel 지원
배터리	노트북 배터리 잔량
S.M.A.R.T.	디스크 건강 상태

Docker/Podman 모니터링

기능	설명
컨테이너 목록	실행 중인 모든 컨테이너
개별 통계	컨테이너별 CPU/메모리/네트워크
히스토리	시간별 사용량 그래프
상태 추적	컨테이너 시작/중지 감지

알림 시스템

서비스	지원
Discord	✅
Slack	✅
Telegram	✅
Ntfy	✅
Gotify	✅
Pushover	✅
Webhook (Generic)	✅
Email (SMTP)	✅
Matrix	✅
Mattermost	✅

알림 트리거 조건:

CPU 사용량 임계치
메모리 사용량 임계치
디스크 사용량 임계치
대역폭 임계치
온도 임계치
로드 평균 임계치
시스템 오프라인

추가 기능

기능	설명
다중 사용자	사용자별 시스템 관리
OAuth/OIDC	Google, GitHub 등 SSO
자동 백업	S3 호환 스토리지 지원
REST API	외부 연동 가능
다크 모드	UI 테마 지원

경쟁 도구 비교

기능	Beszel	Uptime Kuma	Netdata	Prometheus+Grafana
설치 난이도	매우 쉬움	쉬움	쉬움	어려움
리소스 사용	매우 낮음	낮음	중간	높음
Docker 통계	✅ 개별	❌	✅	✅ 설정 필요
히스토리 데이터	✅	❌	✅	✅
다중 서버	✅	✅	✅	✅
알림	✅	✅	✅	✅
업타임 체크	❌	✅	❌	✅
GPU 모니터링	✅	❌	✅	✅ 설정 필요

선택 가이드

상황	추천
서버 + Docker 모니터링	Beszel
웹사이트 업타임 체크	Uptime Kuma
실시간 상세 분석	Netdata
대규모 인프라	Prometheus + Grafana
가장 간단한 설치	Beszel

시스템 요구 사항

Hub (중앙 서버)

항목	최소	권장
CPU	1 Core	2 Core
RAM	64MB	128MB
저장소	50MB + 데이터	1GB+

Agent (모니터링 대상)

항목	요구 사항
CPU	최소
RAM	~20MB
저장소	~10MB

Docker 설치

방법 1: Hub만 설치 (기본)

# docker-compose.yml
services:
  beszel:
    image: henrygd/beszel:latest
    container_name: beszel
    restart: unless-stopped
    ports:
      - "8090:8090"
    environment:
      - APP_URL=http://localhost:8090
    volumes:
      - ./beszel_data:/beszel_data

실행:

mkdir -p ~/beszel && cd ~/beszel

# docker-compose.yml 생성 후
docker compose up -d

# 로그 확인
docker compose logs -f beszel

접속: http://localhost:8090

방법 2: Hub + 로컬 Agent (같은 서버)

Hub와 Agent를 같은 서버에서 실행하는 경우:

# docker-compose.yml
services:
  beszel:
    image: henrygd/beszel:latest
    container_name: beszel
    restart: unless-stopped
    ports:
      - "8090:8090"
    environment:
      - APP_URL=http://localhost:8090
    volumes:
      - ./beszel_data:/beszel_data
      - ./beszel_socket:/beszel_socket

  beszel-agent:
    image: henrygd/beszel-agent:latest
    container_name: beszel-agent
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./beszel_socket:/beszel_socket
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - LISTEN=/beszel_socket/beszel.sock
      - KEY=  # Hub에서 생성된 공개키 입력

방법 3: 원격 Agent (다른 서버)

Hub 서버 (docker-compose.yml):

services:
  beszel:
    image: henrygd/beszel:latest
    container_name: beszel
    restart: unless-stopped
    ports:
      - "8090:8090"
    environment:
      - APP_URL=https://beszel.example.com
    volumes:
      - ./beszel_data:/beszel_data

Agent 서버 (docker-compose.yml):

services:
  beszel-agent:
    image: henrygd/beszel-agent:latest
    container_name: beszel-agent
    restart: unless-stopped
    network_mode: host
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - LISTEN=45876
      - KEY=ssh-ed25519 AAAA...  # Hub에서 복사한 공개키

Agent 서버에서 포트 열기:

sudo ufw allow 45876/tcp

방법 4: 다중 디스크 모니터링

services:
  beszel-agent:
    image: henrygd/beszel-agent:latest
    container_name: beszel-agent
    restart: unless-stopped
    network_mode: host
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      # 추가 디스크 마운트
      - /mnt/data/.beszel:/extra-filesystems/data:ro
      - /mnt/backup/.beszel:/extra-filesystems/backup:ro
    environment:
      - LISTEN=45876
      - KEY=ssh-ed25519 AAAA...

방법 5: GPU 모니터링 (Nvidia)

services:
  beszel-agent:
    image: henrygd/beszel-agent:latest
    container_name: beszel-agent
    restart: unless-stopped
    network_mode: host
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - LISTEN=45876
      - KEY=ssh-ed25519 AAAA...
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

방법 6: Traefik 연동

services:
  beszel:
    image: henrygd/beszel:latest
    container_name: beszel
    restart: unless-stopped
    environment:
      - APP_URL=https://beszel.example.com
    volumes:
      - ./beszel_data:/beszel_data
    networks:
      - traefik_network
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.beszel.rule=Host(`beszel.example.com`)"
      - "traefik.http.routers.beszel.entrypoints=websecure"
      - "traefik.http.routers.beszel.tls.certresolver=letsencrypt"
      - "traefik.http.services.beszel.loadbalancer.server.port=8090"

networks:
  traefik_network:
    external: true

방법 7: Docker Socket Proxy (보안 강화)

Docker 소켓 직접 마운트 대신 프록시 사용:

services:
  beszel-agent:
    image: henrygd/beszel-agent:latest
    container_name: beszel-agent
    restart: unless-stopped
    network_mode: host
    environment:
      - LISTEN=45876
      - KEY=ssh-ed25519 AAAA...
      - DOCKER_HOST=tcp://socket-proxy:2375
    depends_on:
      - socket-proxy

  socket-proxy:
    image: lscr.io/linuxserver/socket-proxy:latest
    container_name: socket-proxy
    restart: unless-stopped
    environment:
      - CONTAINERS=1  # 컨테이너 정보만 허용
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "127.0.0.1:2375:2375"

환경 변수

Hub 환경 변수

변수	기본값	설명
`APP_URL`	–	웹 UI URL (리버스 프록시 시 필수)
`USER_EMAIL`	–	첫 번째 사용자 이메일
`USER_PASSWORD`	–	첫 번째 사용자 비밀번호
`DISABLE_PASSWORD_AUTH`	false	비밀번호 로그인 비활성화 (OAuth 전용)
`MFA_OTP`	false	이메일 OTP 활성화
`SHARE_ALL_SYSTEMS`	false	모든 사용자에게 시스템 공유
`CONTAINER_DETAILS`	true	컨테이너 상세 정보 허용
`CSP`	–	Content-Security-Policy 헤더

Agent 환경 변수

변수	기본값	설명
`KEY`	–	Hub의 공개 SSH 키 (필수)
`LISTEN`	45876	포트 또는 소켓 경로
`DOCKER_HOST`	–	Docker 소켓 경로 오버라이드
`FILESYSTEM`	–	루트 디스크 지정
`EXTRA_FILESYSTEMS`	–	추가 디스크 (바이너리 설치 시)
`SENSORS`	–	온도 센서 화이트/블랙리스트
`NICS`	–	네트워크 인터페이스 필터
`EXCLUDE_CONTAINERS`	–	제외할 컨테이너 패턴
`LOG_LEVEL`	info	로그 레벨
`MEM_CALC`	–	메모리 계산 방식 (htop)
`SKIP_GPU`	false	GPU 모니터링 비활성화

컨테이너 제외 예시

environment:
  # 특정 컨테이너 제외
  - EXCLUDE_CONTAINERS=test-web,test-api
  # 패턴으로 제외
  - EXCLUDE_CONTAINERS=test-*,*-staging

네트워크 인터페이스 필터

environment:
  # 화이트리스트 (eth*만 모니터링)
  - NICS=eth*
  # 블랙리스트 (docker* 제외)
  - NICS=-docker*,veth*

초기 설정

1) Hub 접속 및 관리자 생성

URL: http://localhost:8090

첫 접속 시 관리자 계정을 생성합니다.

2) 시스템 추가

대시보드에서 Add System 클릭
시스템 이름과 호스트 정보 입력
Copy docker compose 클릭하여 Agent 설정 복사
Agent 서버에서 docker-compose.yml 생성 및 실행
Hub에서 Add System 버튼 클릭하여 완료

3) 알림 설정

Settings → Notifications:

알림 URL 추가 (예: Discord, Telegram)
테스트 알림 전송
시스템별 알림 임계치 설정

알림 URL 예시:

# Discord
discord://token@webhookid

# Telegram
telegram://token@telegram?chats=@channel

# Ntfy
ntfy://ntfy.sh/mytopic

# Gotify
gotify://gotify.example.com/token

# Slack
slack://token-a/token-b/token-c

# Generic Webhook
generic://example.com/webhook?template=json

알림 설정 상세

Discord 알림

Discord 채널 설정 → Webhooks → 새 Webhook 생성
Webhook URL 복사: https://discord.com/api/webhooks/123456789/abcdef...
Beszel 형식으로 변환: discord://abcdef...@123456789

Telegram 알림

@BotFather에서 봇 생성, 토큰 받기
채팅 ID 확인
URL 형식: telegram://BOT_TOKEN@telegram?chats=CHAT_ID

Ntfy 알림

ntfy://ntfy.sh/your-topic
# 또는 셀프호스팅
ntfy://ntfy.example.com/your-topic

알림 임계치 설정

시스템 테이블에서 벨 아이콘 클릭:

메트릭	예시 임계치
CPU	80% (10분 평균)
메모리	90%
디스크	85%
온도	80°C

OAuth/OIDC 설정

Google OAuth

Google Cloud Console에서 OAuth 2.0 클라이언트 생성
Redirect URI: https://beszel.example.com/api/oauth2-redirect
Hub 설정:

environment:
  - APP_URL=https://beszel.example.com

Settings → Auth providers → Google 에서 Client ID/Secret 입력

GitHub OAuth

GitHub Settings → Developer settings → OAuth Apps
Callback URL: https://beszel.example.com/api/oauth2-redirect
Hub에서 Client ID/Secret 설정

백업 및 복원

자동 백업 (S3)

Settings → Backups:

S3 호환 스토리지 정보 입력
백업 주기 설정 (예: 매일)
보관 기간 설정

수동 백업

# 데이터 디렉토리 백업
tar czf beszel-backup-$(date +%Y%m%d).tar.gz beszel_data/

# 복원
tar xzf beszel-backup-20250129.tar.gz

업데이트

cd ~/beszel

# 최신 이미지 다운로드
docker compose pull

# 재시작
docker compose up -d

트러블슈팅

Agent 연결 실패

1) 포트 확인:

# Agent 서버에서
sudo ufw status
sudo ufw allow 45876/tcp

2) 키 확인:

# KEY가 정확히 복사되었는지 확인
environment:
  - KEY=ssh-ed25519 AAAA...

3) 네트워크 모드:

# network_mode: host 필수 (Agent)
network_mode: host

Docker 통계 안 보임

1) 소켓 마운트 확인:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock:ro

2) 권한 확인:

# Docker 그룹에 사용자 추가
sudo usermod -aG docker $USER

디스크가 안 보임

Docker 볼륨으로 추가 디스크 마운트:

volumes:
  - /mnt/data/.beszel:/extra-filesystems/data:ro

메모리 계산이 다름

# htop 방식으로 변경
environment:
  - MEM_CALC=htop

로그 확인

# Hub 로그
docker logs beszel -f

# Agent 로그
docker logs beszel-agent -f

# 디버그 모드
environment:
  - LOG_LEVEL=debug

보안

기본 보안 설정

강력한 비밀번호 사용
HTTPS 필수 (리버스 프록시)
OAuth 활성화 권장

Docker Socket 보안

# 읽기 전용 마운트
volumes:
  - /var/run/docker.sock:/var/run/docker.sock:ro

# 또는 Socket Proxy 사용
environment:
  - DOCKER_HOST=tcp://socket-proxy:2375

방화벽 설정

# Agent 포트는 Hub에서만 접근 가능하도록
sudo ufw allow from HUB_IP to any port 45876

비밀번호 로그인 비활성화 (OAuth 전용)

environment:
  - DISABLE_PASSWORD_AUTH=true

REST API 사용

Beszel은 PocketBase 기반으로 REST API를 제공합니다.

인증:

# 토큰 발급
curl -X POST https://beszel.example.com/api/collections/users/auth-with-password \
  -H "Content-Type: application/json" \
  -d '{"identity":"user@example.com","password":"password"}'

시스템 목록:

curl https://beszel.example.com/api/collections/systems/records \
  -H "Authorization: Bearer TOKEN"

사용 사례

1. 홈랩 모니터링

여러 서버/NAS 중앙 관리
Docker 컨테이너 리소스 추적
디스크 공간 알림

2. 소규모 팀 인프라

개발/스테이징/프로덕션 서버 모니터링
팀원별 접근 권한 관리
Slack/Discord 알림

3. VPS 모니터링

여러 VPS 중앙 대시보드
대역폭 사용량 추적
비용 최적화를 위한 리소스 분석

마무리

Beszel은 복잡한 설정 없이 서버와 Docker 컨테이너를 모니터링할 수 있는 경량 도구입니다. Prometheus + Grafana의 강력함이 필요 없는 소규모 환경에서 최적의 선택이며, 몇 분 만에 설치하고 바로 사용할 수 있습니다.

핵심 장점

장점	설명
초경량	Hub ~64MB, Agent ~20MB
간편한 설치	Docker Compose 한 줄로 시작
Docker 네이티브	컨테이너별 상세 통계
다양한 알림	20+ 알림 서비스 지원
다중 서버	Hub-Agent 아키텍처
OAuth 지원	Google, GitHub 등 SSO

이런 분께 추천

복잡한 모니터링 스택이 부담스러운 분
Docker 컨테이너 리소스를 추적하고 싶은 분
여러 서버를 중앙에서 관리하고 싶은 분
가벼운 리소스 사용을 원하는 분
빠른 설치와 즉시 사용을 원하는 분

개요