109 lines
5.9 KiB
Markdown
109 lines
5.9 KiB
Markdown
# Requirements: 設定驅動的多主機正式部署
|
||
|
||
> Status: `draft-for-review`
|
||
> Slug: `haixun-deployment`
|
||
> Last updated: `2026-07-18`
|
||
> Implementation: not started
|
||
|
||
## 1. 一句話
|
||
|
||
營運者只需在本機設定檔填寫主機 IP、網域與加密機密，就能把全新的 Ubuntu 24.04 VM 初始化並部署成可分開更新、重啟與擴充的 frontend、backend、worker、Redis、MinIO、Registry 與 Edge 環境。
|
||
|
||
## 2. 目標
|
||
|
||
### R-01 設定檔是部署真相來源
|
||
|
||
- 非機密拓撲集中在 `deploy/prod/deployment.yml`。
|
||
- 機密集中在 Ansible Vault 加密的 `deploy/prod/secrets.vault.yml`。
|
||
- 遠端不得成為設定真相來源，不要求登入遠端手動編輯 env 或 YAML。
|
||
- 每台主機最低只需填可 SSH 的 IP；SSH user/port/key 可設全域預設並允許單機覆寫。
|
||
- WireGuard IP 預設自動分配，必要時才手動覆寫。
|
||
|
||
### R-02 空 VM 可自動初始化
|
||
|
||
- 支援全新 Ubuntu 24.04 LTS VM。
|
||
- 初始前提僅為：SSH 可達、指定使用者可 `sudo`、DNS 已按設定指向 Edge 與 Registry。
|
||
- bootstrap 必須安裝 Python、Docker Engine、Compose plugin、WireGuard、UFW、chrony、fail2ban 與安全更新工具。
|
||
- bootstrap 必須建立服務帳號、目錄、權限、Docker log rotation、TLS 與防火牆規則。
|
||
- bootstrap 必須可重複執行且不得刪除既有資料。
|
||
|
||
### R-03 元件可獨立部署
|
||
|
||
- frontend、backend、worker、Redis、MinIO、Registry、Edge 可個別 bootstrap、deploy、restart、status 與 rollback（資料層 rollback 另定義）。
|
||
- frontend、backend、worker 不得綁在同一 release artifact。
|
||
- 本機 build image 並 push 至自架 Registry；遠端不得執行 Go/npm build。
|
||
- 遠端在舊服務仍運作時先 pull image，再以 Compose recreate/restart。
|
||
- 設定變更可不 rebuild image，單獨同步並 recreate 指定角色。
|
||
|
||
### R-04 可從設定動態增加節點
|
||
|
||
- frontend、backend、worker host list 可有任意多台。
|
||
- 新增 worker 後不需流量註冊即可開始 claim job，且每台 worker ID 必須唯一。
|
||
- 新增 frontend/backend 後，自動重建 Edge upstream；健康檢查通過後才加入流量。
|
||
- 同一部署指令只處理設定中指定的角色或 host，其他節點不得被意外重啟。
|
||
|
||
### R-05 資料與狀態
|
||
|
||
- MongoDB 使用 Atlas，不再於 production Compose 自架 MongoDB。
|
||
- Redis 第一版為獨立單機、啟用密碼與 AOF，接受單點故障。
|
||
- MinIO 第一版為獨立單機與持久 volume，接受單點故障。
|
||
- frontend/backend/worker container 應可替換；媒體物件持久化於 MinIO，業務資料持久化於 MongoDB，cache/lock 位於 Redis。
|
||
- worker 的 Playwright、Node script 與 Chromium 必須封裝在 image；解密 session 暫存檔只可位於 ephemeral storage 並限制權限。
|
||
- gateway 使用的 extension ZIP 必須封裝在固定 image path，不能依賴開發者本機絕對路徑。
|
||
|
||
### R-06 MongoDB Atlas 初始資料庫流程
|
||
|
||
- first deploy 必須先驗證 Atlas DNS、TLS、帳密、database name 與來源 allowlist。
|
||
- 依序執行 forward migration、`cmd/init`、`cmd/seeder`。
|
||
- migration 失敗不得切換 backend。
|
||
- `cmd/init` 必須保持 idempotent，僅建立 operational indexes。
|
||
- seeder 的管理員 email、display name、password 必須由 Vault 設定。
|
||
- 重跑 seeder 不得覆寫既有管理員密碼；改密碼必須是獨立明確操作。
|
||
- 一般 deploy 可執行 migration，但不得每次自動 seed。
|
||
|
||
### R-07 網路與安全
|
||
|
||
- 主機間服務流量走 WireGuard，不直接暴露 Redis、MinIO、backend 或 crawler 到公網。
|
||
- Edge 僅公開網站需要的 `80/443`；Registry 只以 TLS 提供服務並要求認證。
|
||
- Edge 與 Registry 使用 DNS + Let's Encrypt，憑證自動續期。
|
||
- Atlas 只 allowlist 固定出口 IP；backend/worker 的 Atlas 流量必須符合此出口設計。
|
||
- frontend 與 API 使用同網域，Edge 將 `/api` 轉送 backend，將 `/haixun-assets` 轉送 MinIO。
|
||
- crawler 只能在 worker Docker private network 內被存取，不 publish host port。
|
||
- Vault 明文、生成的 env、Registry 密碼與私鑰不得提交 Git 或寫入 image。
|
||
|
||
### R-08 維運與防呆
|
||
|
||
- 提供 preflight、doctor、status、logs、restart、deploy-config 與 rollback 指令。
|
||
- 所有設定先寫暫存檔並驗證，再原子替換。
|
||
- backend/frontend 採健康節點逐台更新，不可一次停止所有副本。
|
||
- destructive reset/wipe 不得包含在一般 deploy，且必須有環境名稱與二次確認。
|
||
- Redis、MinIO 與 Registry 必須具備備份與還原文件；Atlas 備份使用 Atlas Backup/PITR。
|
||
- 單機 Redis、MinIO、Registry、Edge 的單點風險必須在 status 與文件中明示。
|
||
|
||
## 3. 不在第一版範圍
|
||
|
||
- Kubernetes。
|
||
- Docker Swarm。
|
||
- Redis Sentinel/Cluster。
|
||
- 分散式 MinIO。
|
||
- 多 Edge 高可用與自動 failover。
|
||
- 在遠端 VM 進行應用程式編譯。
|
||
- 自動建立 MongoDB Atlas project/cluster；第一版只連接已建立的 Atlas cluster。
|
||
- 自動修改 Atlas allowlist；固定出口 IP 先由營運者配置到 Atlas。
|
||
|
||
## 4. 已知限制
|
||
|
||
- 增加 worker 可提高一般 Mongo job 吞吐量，但目前 Outbox 仍被全域 Redis lock 序列化。
|
||
- Outbox 查詢目前最多掃描 500 筆且不適合作為大規模 worker pool 的最終方案。
|
||
- Redis、MinIO、Registry、Edge 第一版各一台時仍有單點故障。
|
||
- gateway 現有 health endpoint 只檢查 Redis；正式 rolling deployment 前需補足 Mongo readiness。
|
||
|
||
## 5. 驗收摘要
|
||
|
||
- 從全新 Ubuntu 24.04 VM 開始，除 DNS/Atlas/SSH 外不需登入遠端手動操作。
|
||
- 修改一份 host 設定加入 worker IP 後，可只部署新 worker。
|
||
- 修改設定但不 build，遠端 recreate 後能讀到新設定。
|
||
- backend/frontend 多節點更新期間至少保留一個健康節點。
|
||
- migration/init/seed 的順序、失敗停止與重跑安全性可驗證。
|
||
- 公網不能直連 Redis、MinIO private API、backend private port 或 crawler。
|