> ## 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.

# 多端點部署

> 部署 Panguard Manager，跨多台機器進行機群安全管理。

# 多端點部署

分散式部署中，多台機器上的 Guard agent 向一台集中式 Manager 回報。Manager 提供機群全域可見性、跨 agent 威脅關聯、集中式策略派發。

***

## 架構

```
[Machine A: Manager]                [Machine B: Guard Agent]
+-------------------+               +---------------------+
| Manager Server    |<-- heartbeat --| GuardEngine         |
| :8443             |<-- events   --| (learning/protection)|
|                   |-- policy   -->|                     |
+-------------------+               +---------------------+
        ^
        |                            [Machine C: Guard Agent]
        |                            +---------------------+
        +<-- heartbeat/events -------| GuardEngine         |
        +--- policy ---------------->|                     |
                                     +---------------------+
```

***

## 部署 Manager

<Steps>
  <Step title="產生認證 Token">
    建立 Manager 和 Agent 之間通訊用的 token：

    ```bash theme={null}
    export MANAGER_TOKEN=$(openssl rand -hex 32)
    echo $MANAGER_TOKEN
    ```

    <Warning>
      這個 token 要安全保存。每個 Guard agent 註冊都需要它。
    </Warning>
  </Step>

  <Step title="啟動 Manager">
    ```bash theme={null}
    panguard manager --port 8443 --auth-token "$MANAGER_TOKEN"
    ```

    Manager 接受 Guard agent 連線，提供：

    * **Agent 登錄** -- 最多追蹤 500 個已註冊 agent
    * **威脅彙總** -- 透過來源 IP、惡意軟體 hash、攻擊模式做跨 agent 關聯
    * **策略引擎** -- 集中派發規則和 config
    * **SSE 串流** -- 給管理儀表板的即時事件串流
  </Step>

  <Step title="確認 Manager 在跑">
    ```bash theme={null}
    curl -H "Authorization: Bearer $MANAGER_TOKEN" \
      http://localhost:8443/api/overview
    ```
  </Step>
</Steps>

***

## 部署 Guard Agent

在每台端點機器上：

<Steps>
  <Step title="安裝 Panguard">
    ```bash theme={null}
    npm install -g panguard
    ```
  </Step>

  <Step title="啟動 Guard 並連線 Manager">
    ```bash theme={null}
    panguard guard start \
      --manager-url "http://manager-host:8443" \
      --manager-token "your-secure-token" \
      --data-dir /var/panguard-guard
    ```

    Agent 會：

    1. 啟動時向 Manager 註冊
    2. 每 30 秒送心跳
    3. 偵測到威脅即時回報
    4. 每 5 分鐘拉取策略更新
  </Step>
</Steps>

***

## Agent 生命週期

| 階段       | 端點                               | 間隔               | 說明                               |
| -------- | -------------------------------- | ---------------- | -------------------------------- |
| **註冊**   | `POST /api/agents/register`      | 一次（啟動時）          | Agent 送主機名稱、OS、版本；收到唯一 `agentId` |
| **心跳**   | `POST /api/agents/:id/heartbeat` | 每 30 秒           | CPU/記憶體用量、已處理事件數、模式、uptime       |
| **威脅回報** | `POST /api/agents/:id/events`    | 即時               | 偵測到的威脅立刻送出                       |
| **策略拉取** | `GET /api/policy/agent/:id`      | 每 5 分鐘           | Agent 檢查有沒有新策略                   |
| **失效偵測** | --                               | 每 30 秒（server 端） | 90 秒沒心跳的 agent 標記為失效             |
| **取消註冊** | `DELETE /api/agents/:id`         | 手動               | 從機群移除 agent                      |

***

## 跨 Agent 威脅關聯

Manager 的威脅彙總即時關聯所有 agent 的威脅：

* **來源 IP 關聯** -- 多個端點看到同一個攻擊者 IP，觸發升級
* **惡意軟體 hash 關聯** -- 跨 agent 出現相同指紋，代表有進行中的攻擊活動
* **攻擊模式關聯** -- 5 分鐘窗口內出現相關 MITRE ATT\&CK 模式

<Info>
  跨 agent 關聯用 5 分鐘滑動窗口，資料保留 24 小時。跨 3 個以上 agent 的威脅自動升級為 CRITICAL。
</Info>

***

## 策略派發

策略引擎讓你集中控制所有 Guard agent：

```bash theme={null}
# 設定全域策略
curl -X POST -H "Authorization: Bearer $MANAGER_TOKEN" \
  -H "Content-Type: application/json" \
  http://manager-host:8443/api/policy \
  -d '{
    "autoRespondThreshold": 85,
    "ipBlocklist": ["203.0.113.0/24"],
    "alertChannels": ["slack"]
  }'
```

策略變更會在下一個 5 分鐘拉取週期內同步到所有 agent。

***

## 即時監控

### SSE 事件串流

即時串流所有 agent 的事件：

```bash theme={null}
curl -N -H "Authorization: Bearer $MANAGER_TOKEN" \
  http://manager-host:8443/api/events/stream
```

### 機群概覽

```bash theme={null}
curl -H "Authorization: Bearer $MANAGER_TOKEN" \
  http://manager-host:8443/api/overview
```

***

## Manager 設定

### 環境變數

| 變數                              | 預設值        | 說明                    |
| ------------------------------- | ---------- | --------------------- |
| `MANAGER_PORT`                  | `8443`     | HTTP server port      |
| `MANAGER_AUTH_TOKEN`            | （無）        | API 認證用的 Bearer token |
| `MANAGER_MAX_AGENTS`            | `500`      | 最大 agent 註冊數          |
| `MANAGER_HEARTBEAT_TIMEOUT_MS`  | `90000`    | 心跳逾時（超過就標失效）          |
| `MANAGER_HEARTBEAT_INTERVAL_MS` | `30000`    | 失效檢查間隔                |
| `MANAGER_CORRELATION_WINDOW_MS` | `300000`   | 跨 agent 威脅關聯窗口（5 分鐘）  |
| `MANAGER_THREAT_RETENTION_MS`   | `86400000` | 威脅資料保留時間（24 小時）       |
| `CORS_ALLOWED_ORIGINS`          | （無）        | 逗號分隔的允許 CORS origin   |

### 可選 SQLite 持久化

大規模部署可以開 SQLite 做持久儲存：

```bash theme={null}
panguard manager --port 8443 --auth-token "$MANAGER_TOKEN" --db /var/panguard-manager/data.db
```

***

## 正式環境部署

<Tip>
  正式環境建議把 Manager 裝成 systemd 服務，前面擋 TLS
  反向代理。詳見[系統服務指南](/guides/system-service)和 [Docker
  部署指南](/guides/docker-deployment)。
</Tip>

### 安全檢查清單

* [ ] 產生強力 token（`openssl rand -hex 32`）
* [ ] 用 TLS 終止（nginx/Caddy 反向代理）
* [ ] Manager port（8443）只允許 Guard agent 網段存取
* [ ] 用非 root 系統使用者跑
* [ ] 設 `NODE_ENV=production` 開啟強化模式
* [ ] 密鑰存在 `chmod 600` 的環境檔裡

***

## 相關文件

<CardGroup cols={2}>
  <Card title="架構" icon="sitemap" href="/concepts/architecture">
    Manager-Agent 系統的完整技術架構。
  </Card>

  <Card title="系統服務" icon="gear" href="/guides/system-service">
    把 Manager 和 Guard 裝成 systemd/launchd 服務。
  </Card>

  <Card title="Docker 部署" icon="docker" href="/guides/docker-deployment">
    用 Docker Compose 跑完整堆疊。
  </Card>

  <Card title="Threat Cloud" icon="cloud" href="/guides/threat-cloud-deployment">
    跨機群的集中式威脅情報。
  </Card>
</CardGroup>