Praetor 部署與安全規格 v0.1

狀態：設計稿

這份文件定義 Praetor 的部署模式、容器拓樸、網路安全邊界、資料持久化、備份還原、secrets 管理，以及如何在 不把 Codex / Claude Code 再裝進 Docker 的前提下，讓 Praetor 使用宿主機已登入的 coding executors。

1. 設計目標

Praetor 的部署層要同時滿足：

1. 一鍵部署容易

2. 本機模式安全且可直接使用

3. 遠端模式有清楚的網路與登入邊界

4. 重要資料可持久化、可備份、可還原

5. subscription executor mode 可使用宿主機既有工具

6. 不把高風險能力直接暴露到 Docker 內部或公網

2. 支援的部署模式

Praetor 應官方支援三種模式：

| 模式 | 適用場景 | 預設暴露面 | 推薦程度 |

|---|---|---|---|

| Local-only | 個人電腦、單機、自用 | 127.0.0.1:3000 | 最高 |

| Remote private | VPS / NAS / home server，限本人或內網 | 443 經反向代理 | 高 |

| Remote public | 對外公開網域 | 443 經反向代理 | 進階 |

2.1 Local-only

這是 Praetor v1 的預設模式。

特性：

2.2 Remote private

特性：

2.3 Remote public

特性：

2.4 v1 正式支援矩陣

Praetor v1 建議把支援範圍直接寫死：

| Deployment mode | API mode | Local model mode | Subscription executor mode |

|---|---|---|---|

| Local-only | 正式支援 | 正式支援 | 正式支援 |

| Remote private | 正式支援 | 條件支援 | 條件支援 |

| Remote public | 正式支援 | 進階支援 | 不列為正式支援 |

說明：

2.5 官方安裝路線

Quick Start

目標：

建議：

Bring Your Own Subscription

目標：

建議：

3. 容器拓樸

Praetor 建議至少拆成三個容器服務：

生產模式再加：

可選：

重要的是：

3.1 推薦拓樸

Browser / Mobile / Telegram
        ↓
      proxy (prod only)
        ↓
        web
        ↓
        api
        ↓
      worker
        ↓
workspace / config / data
        ↓
host executor bridge (outside Docker)
        ↓
Codex / Claude Code on host

4. 資料持久化與目錄策略

Praetor 的重要資料不應放在容器可寫層。

應至少拆成三類：

4.1 workspace/

用途：

建議：

4.2 config/

用途：

建議：

4.3 data/

用途：

建議：

5. 網路安全邊界

Praetor 的網路安全原則很簡單：

只有入口服務可以對外，其他服務全部留在 Docker 內部網路。

5.1 Local-only 模式

建議：

5.2 Remote 模式

建議：

5.3 絕對不應做的事

6. 認證、登入與 session

6.1 Local-only

Local-only 可支援較輕的 owner 體驗，但仍建議至少保留：

建議流程：

6.2 Remote private / public

必須有：

建議：

7. Secrets 管理

7.1 Local dev / prototype

可以接受：

但要清楚標示：

7.2 生產模式

建議：

敏感項目至少包含：

7.3 基本規則

8. 備份與還原

Praetor 要備份的是「狀態」，不是容器本身。

8.1 必備份項目

8.2 不需要重點備份的項目

8.3 建議策略

8.4 還原順序

1. 還原 config/

2. 還原 workspace/

3. 還原 data/

4. 重新啟動 compose

5. 執行 integrity check

6. 檢查 mission resume / executor connectivity / approvals

9. 更新與回滾策略

建議：

Praetor 不應假設：

因此：

10. Subscription Executor Mode 的正式設計

這一節專門處理你現在最在意的問題：

Praetor 要如何使用已安裝在宿主機上的 Codex 或 Claude Code，而不是在 Docker 裡再裝一次。

10.1 設計結論

不要把宿主機二進位直接 mount 進容器。

也不要要求使用者在 Docker 裡重裝一次 Codex / Claude Code。

推薦方案是：

host executor bridge

也就是：

10.2 為什麼不用「直接在容器裡呼叫 host binary」

因為這樣通常會帶來：

也會讓部署文件變得極難 support。

10.3 正確抽象：Host Executor Bridge

推薦新增一個宿主機常駐進程：

它不屬於 Docker stack。

它的責任只有：

它不是通用 shell API。

10.4 Bridge 的最小職責

必須提供：

10.5 Bridge 的安全規則

必須：

不應：

10.5.1 非互動執行原則

bridge 的責任不是把 CLI 的互動提示直接傳給瀏覽器。

它應：

標準化事件至少要包含：

10.6 路徑映射

Docker 內部與宿主機的 workspace 路徑可能不同。

因此 Praetor 要顯式保存：

path_mapping:
  container_workspace_root: /app/workspace
  host_workspace_root: /absolute/path/to/workspace

worker 在容器內生成任務規格時，使用 container path。

bridge 接到任務時，先把 container path 轉成 host path，再在宿主機上啟動 executor。

10.7 執行流程

標準流程建議如下：

1. owner 在 Web / Mobile / Telegram 提出任務

2. Praetor / worker 生成 mission 和 task spec

3. worker 將 task spec 寫入 workspace/.praetor/runs/...

4. worker 呼叫 host executor bridge

5. bridge 驗證 token、workspace root、executor type

6. bridge 在宿主機上用已登入的 codex 或 claude 執行

7. executor 在 host workspace 內讀寫檔案

8. bridge 將執行結果、事件、exit code 回傳給 worker

9. worker 更新 mission state、activity log、review queue

10.8 這樣做的好處

10.9 這樣做的代價

10.10 部署建議

最適合 subscription executor mode 的是：

對 Remote public：

11. 不同 executor 模式的推薦

| 模式 | 適合什麼部署 | 優點 | 風險 |

|---|---|---|---|

| API mode | local / remote / public | 穩定、易於服務化 | 有 API 成本 |

| Local model mode | local / private | 隱私較好 | 品質與資源要求不穩 |

| Subscription executor mode | local / private | 可用既有訂閱、體驗最貼近個人使用 | 需要 host bridge 與登入維護 |

12. 推薦預設

Praetor v1 建議預設：

13. 外部參考