---
title: 'Docker 部署'
description: '用 Docker 和 Docker Compose 跑 Panguard AI，容器化安全監控。'
icon: 'docker'
---

# Docker 部署

Panguard 提供 Docker image 和 Compose config，方便容器化部署。這篇涵蓋單容器、完整堆疊 Compose、正式環境強化。

---

## 前置需求

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

---

## Docker 快速開始

<Steps>
  <Step title="拉 image">```bash docker pull panguard/panguard-ai:latest ```</Step>
  <Step title="跑容器">
    ```bash docker run -d \ --name panguard \ -p 3000:3000 \ -v panguard-data:/data \
    panguard/panguard-ai:latest ```
  </Step>
  <Step title="確認">```bash docker logs panguard ```</Step>
</Steps>

---

## Docker Compose：基本（API + Ollama）

這個 config 跑 Panguard API server 搭配本地 Ollama，零成本做 Layer 2 AI 分析。

```yaml
# 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:
```

```bash
# build 並啟動
docker compose up -d

# 拉 Ollama model（只有第一次需要）
docker exec panguard-ollama ollama pull llama3

# 看日誌
docker compose logs -f panguard
```

---

## Docker Compose：完整堆疊（Guard + Ollama + Threat Cloud）

跑完整 Panguard 平台，含 Guard 防護和本地 AI。

```yaml
# docker-compose.full.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
    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:
  panguard-data:
  ollama-models:

networks:
  panguard-net:
    driver: bridge
```

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

---

## Port 參考

| Port    | 服務        | 協定 | 備註                  |
| ------- | ----------- | ---- | --------------------- |
| `3000`  | API Server  | HTTP | 主要入口              |
| `11434` | Ollama      | HTTP | 本地 AI 推論          |
| `2222`  | SSH 蜜罐    | TCP  | 預設 SSH 蜜罐 port    |
| `8080`  | HTTP 蜜罐   | TCP  | 預設 HTTP 蜜罐 port   |
| `2121`  | FTP 蜜罐    | TCP  | 預設 FTP 蜜罐 port    |
| `4450`  | SMB 蜜罐    | TCP  | 預設 SMB 蜜罐 port    |
| `3307`  | MySQL 蜜罐  | TCP  | 預設 MySQL 蜜罐 port  |
| `3390`  | RDP 蜜罐    | TCP  | 預設 RDP 蜜罐 port    |
| `2323`  | Telnet 蜜罐 | TCP  | 預設 Telnet 蜜罐 port |

---

## 環境變數

### Guard Agent

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

### API Server

| 變數            | 預設值 | 說明            |
| --------------- | ------ | --------------- |
| `PANGUARD_PORT` | `3000` | API server port |

<Warning>
正式環境的 Compose 檔不要把密鑰寫在 `environment` 裡。改用權限受限的 `env_file`：

```yaml
env_file:
  - /etc/panguard/guard.env # chmod 600
```

</Warning>

---

## 正式環境強化

### Docker Image 安全

正式環境 image 包含：

- **多階段 build** -- build 依賴不會進最終 image
- **非 root 使用者** -- 以 `panguard`（UID 1001）跑
- **tini** -- 正確的 PID 1 信號處理和 zombie process 回收
- **最小套件** -- 最終 image 只有 `tini` 和 `curl`

### 需要的 Capabilities

Guard 回應動作在 Docker 裡要授予這些 capabilities：

```yaml
cap_add:
  - NET_ADMIN # 透過 iptables 封鎖 IP
  - KILL # 砍惡意 process
  - SYS_PTRACE # 記憶體掃描
```

### 檢查清單

- [ ] 設 `NODE_ENV=production`（開啟 HSTS、關閉萬用 CORS）
- [ ] 產生強力密鑰（`openssl rand -hex 32`）
- [ ] 用 TLS 終止（前面放 nginx/Caddy 反向代理）
- [ ] 限制 Manager port 的網路存取
- [ ] 密鑰用 env file 掛載，不要用行內環境變數
- [ ] 用 named volume 做持久化
- [ ] 設好容器日誌輪替

---

## 日誌位置（容器內）

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

### 日誌輪替

ReportAgent 自動處理日誌輪替：

| 設定           | 預設值 |
| -------------- | ------ |
| 最大檔案大小   | 50 MB  |
| 最大輪替檔案數 | 10     |
| 保留期間       | 90 天  |

---

## 備份策略

<Tip>
定期備份這些關鍵檔案：

- **基線資料**（`/data/baseline.json`）-- 丟了要重跑學習模式
- **Threat Cloud 資料庫** -- 定期備份 SQLite
- **Config** -- config 和環境檔存進版本控制或密鑰管理服務
  </Tip>

---

## 相關文件

<CardGroup cols={2}>
  <Card title="系統服務" icon="gear" href="/guides/system-service">
    不用 Docker，把 Guard 裝成原生 systemd/launchd 服務。
  </Card>
  <Card title="多端點部署" icon="server" href="/guides/multi-endpoint">
    把 Guard agent 連線到集中式 Manager。
  </Card>
  <Card title="Threat Cloud" icon="cloud" href="/guides/threat-cloud-deployment">
    在 Guard 機群旁邊部署 Threat Cloud。
  </Card>
  <Card title="架構" icon="sitemap" href="/concepts/architecture">
    平台的完整技術架構。
  </Card>
</CardGroup>
