Skip to main content

​
Docker 部署

Panguard 提供 Docker 映像檔與 Compose 設定，用於容器化部署。本指南涵蓋單容器設定、完整堆疊 Compose 部署與正式環境強化。

​
前置條件

需求版本
Docker>= 24.0
Docker Compose>= 2.20

​
使用 Docker 快速開始

1

拉取映像檔

docker pull panguard/panguard-ai:latest
2

運行容器

docker run -d \
  --name panguard \
  -p 3000:3000 \
  -v panguard-data:/data \
  panguard/panguard-ai:latest
3

驗證

docker logs panguard

​
Docker Compose：基本設定（API + Ollama）

此設定運行 Panguard API 伺服器搭配本地 Ollama 執行個體，零成本進行 Layer 2 AI 分析。 
# docker-compose.yml
services:
  panguard:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: panguard
    restart: unless-stopped
    ports:
      - '3000:3000'
    volumes:
      - panguard-data:/data
      - ./config:/app/config:ro
    environment:
      - PANGUARD_DATA_DIR=/data
      - PANGUARD_PORT=3000
      - OLLAMA_ENDPOINT=http://ollama:11434
    depends_on:
      ollama:
        condition: service_healthy

  ollama:
    image: ollama/ollama:latest
    container_name: panguard-ollama
    restart: unless-stopped
    ports:
      - '11434:11434'
    volumes:
      - ollama-models:/root/.ollama
    healthcheck:
      test: ['CMD', 'curl', '-f', 'http://localhost:11434/api/tags']
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 30s

volumes:
  panguard-data:
  ollama-models:

# 建置並啟動
docker compose up -d

# 拉取 Ollama 模型（僅首次）
docker exec panguard-ollama ollama pull llama3

# 查看日誌
docker compose logs -f panguard

​
Docker Compose：完整堆疊（Auth + Manager + Guard + Ollama）

此設定運行完整的 Panguard 平台，包含身份驗證、機群管理與本地 AI。 
# docker-compose.full.yml
services:
  panguard-auth:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: panguard-auth
    restart: unless-stopped
    ports:
      - '3000:3000'
    volumes:
      - auth-data:/data
      - ./config:/app/config:ro
    environment:
      - PANGUARD_DATA_DIR=/data
      - PANGUARD_PORT=3000
      - JWT_SECRET=your-secret-key-here
      - GOOGLE_CLIENT_ID=your-google-client-id
      - GOOGLE_CLIENT_SECRET=your-google-client-secret
      - MANAGER_URL=http://panguard-manager:8443
      - MANAGER_AUTH_TOKEN=your-manager-token
      - OLLAMA_ENDPOINT=http://ollama:11434
    depends_on:
      panguard-manager:
        condition: service_started
      ollama:
        condition: service_healthy
    networks:
      - panguard-net

  panguard-manager:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: panguard-manager
    command: ["node", "dist/cli/index.js", "manager", "--port", "8443"]
    restart: unless-stopped
    ports:
      - '8443:8443'
    environment:
      - MANAGER_PORT=8443
      - MANAGER_AUTH_TOKEN=your-manager-token
      - MANAGER_MAX_AGENTS=500
      - CORS_ALLOWED_ORIGINS=http://localhost:3000
    networks:
      - panguard-net

  ollama:
    image: ollama/ollama:latest
    container_name: panguard-ollama
    restart: unless-stopped
    ports:
      - '11434:11434'
    volumes:
      - ollama-models:/root/.ollama
    networks:
      - panguard-net
    healthcheck:
      test: ['CMD', 'curl', '-f', 'http://localhost:11434/api/tags']
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 30s

volumes:
  auth-data:
  ollama-models:

networks:
  panguard-net:
    driver: bridge

docker compose -f docker-compose.full.yml up -d

​
連接埠參考

連接埠服務協定備註
3000API 伺服器（Auth + Web）HTTP主要入口點
8443Manager 伺服器HTTP代理程式註冊、心跳、SSE
11434OllamaHTTP本地 AI 推論
2222Trap：SSH 蜜罐TCP預設 SSH trap 連接埠
8080Trap：HTTP 蜜罐TCP預設 HTTP trap 連接埠
2121Trap：FTP 蜜罐TCP預設 FTP trap 連接埠
4450Trap：SMB 蜜罐TCP預設 SMB trap 連接埠
3307Trap：MySQL 蜜罐TCP預設 MySQL trap 連接埠
3390Trap：RDP 蜜罐TCP預設 RDP trap 連接埠
2323Trap：Telnet 蜜罐TCP預設 Telnet trap 連接埠

​
環境變數

​
Guard 代理程式

變數預設值說明
PANGUARD_DATA_DIR./data基線、日誌、規則的資料目錄
PANGUARD_MODElearningGuard 模式：learning 或 protection
OLLAMA_ENDPOINThttp://localhost:11434Ollama API 端點
ANTHROPIC_API_KEY（無）雲端 AI 用 Claude API 金鑰
OPENAI_API_KEY（無）雲端 AI 用 OpenAI API 金鑰
ABUSEIPDB_KEY（無）威脅情報用 AbuseIPDB API 金鑰

​
Auth 伺服器

變數預設值說明
PANGUARD_PORT3000API 伺服器連接埠
JWT_SECRET（無）JWT 簽名密鑰（正式環境必要）
GOOGLE_CLIENT_ID（無）Google OAuth 用戶端 ID
GOOGLE_CLIENT_SECRET（無）Google OAuth 用戶端密鑰

​
Manager

變數預設值說明
MANAGER_PORT8443Manager HTTP 伺服器連接埠
MANAGER_AUTH_TOKEN（無）API 驗證用 Bearer token
MANAGER_MAX_AGENTS500最大已註冊代理程式數
正式環境的 Compose 檔案中切勿透過 environment 金鑰傳遞密鑰。改用受限權限的 env_file：
env_file:
  - /etc/panguard/guard.env  # chmod 600

​
正式環境強化

​
Docker 映像檔安全

正式環境 Docker 映像檔包含：
  • 多階段建置 — 建置依賴不在最終映像檔中
  • 非 root 使用者 — 以 panguard（UID 1001）執行
  • tini — 正確的 PID 1 信號處理與殭屍行程回收
  • 最小套件 — 最終映像檔僅包含 tini 與 curl

​
所需權限

Guard 回應動作在 Docker 中運作需授予以下權限： 
cap_add:
  - NET_ADMIN    # Block IPs via iptables
  - KILL         # Terminate malicious processes
  - SYS_PTRACE   # Memory scanning

​
檢查清單

  • 設定 NODE_ENV=production（啟用 HSTS、停用萬用 CORS）
  • 產生強力密鑰（openssl rand -hex 32）
  • 使用 TLS 終止（前方放置 nginx/Caddy 反向代理）
  • 限制 Manager 連接埠的網路存取
  • 將密鑰掛載為環境檔案，而非行內環境變數
  • 使用命名磁碟區進行持久化資料
  • 設定容器日誌輪替

​
日誌位置（容器內）

元件路徑格式
Guard 事件/data/events.jsonlJSONL
Guard 動作/data/action-manifest.jsonlJSONL
Guard 基線/data/baseline.jsonJSON
應用程式日誌stdout/stderr結構化 JSON

​
日誌輪替

ReportAgent 自動處理日誌輪替：
設定預設值
最大檔案大小50 MB
最大輪替檔案數10
保留期間90 天

​
備份策略

定期備份以下關鍵檔案：
  • 基線資料（/data/baseline.json）— 遺失需重新執行學習模式
  • Auth 資料庫（auth.db）— 每日備份，使用 sqlite3 auth.db ".backup backup.db"
  • Threat Cloud 資料庫 — 依排程備份 SQLite 資料庫
  • 設定 — 將設定與環境檔案儲存於版本控制或密鑰管理器中

​
相關內容

系統服務

將 Guard 安裝為原生 systemd/launchd 服務，而非使用 Docker。

多端點設定

將 Guard 代理程式連線至集中式 Manager。

Threat Cloud

在 Guard 機群旁部署 Threat Cloud。

架構

平台的完整技術架構。