> ## Documentation Index
> Fetch the complete documentation index at: https://docs.panguard.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker 部署

> 用 Docker 和 Docker Compose 跑 Panguard AI，容器化安全監控。

# Docker 部署

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

***

## 前置需求

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

***

## Docker 快速開始

<Steps>
  <Step title="拉 image">
    ```bash theme={null}
    docker pull panguard/panguard-ai:latest
    ```
  </Step>

  <Step title="跑容器">
    ```bash theme={null}
    docker run -d \
      --name panguard \
      -p 3000:3000 \
      -v panguard-data:/data \
      panguard/panguard-ai:latest
    ```
  </Step>

  <Step title="確認">
    ```bash theme={null}
    docker logs panguard
    ```
  </Step>
</Steps>

***

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

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

```yaml theme={null}
# 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 theme={null}
# 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 theme={null}
# 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 theme={null}
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 theme={null}
  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 theme={null}
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>