8.3 KiB

Raw Blame History

Plan: 設定驅動的多主機正式部署

Status: draft-for-review
Source: requirements.md, spec.md
Last updated: 2026-07-18
Implementation: not started; this plan does not authorize a live deployment

1. 交付策略

先建立設定 schema、preflight 與空 VM bootstrap，再碰正式服務。
先完成 WireGuard 與 Registry，確保後續 image 只需本機 build、遠端 pull。
資料層先行：Atlas connectivity、Redis persistence、MinIO persistence/bucket/backup。
將現有共同 release 拆成 frontend、backend、worker、crawler、ops images。
先單節點驗證，再做 frontend/backend rolling pool 與 Edge 動態 upstream。
first deploy、一般 deploy、config-only deploy、rollback 必須是不同明確路徑。
所有 live 操作前先在全新 Ubuntu 24.04 VM 的 staging inventory 演練。

2. 里程碑

M0 - 文件、設定契約與安全邊界

建立 deployment.yml.example 與 Vault schema。
定義 host role、覆寫規則、WireGuard 自動配號、image tag 與目錄契約。
實作 doctor/preflight，拒絕缺 IP、重複 IP、DNS 未指向、SSH/sudo 不可用與 unsupported OS。
定義正式環境防火牆矩陣、Atlas 固定出口與 TLS 前置條件。

完成定義：不連線部署即可驗證完整設定；錯誤訊息能指出欄位與 host。

M1 - 空 VM bootstrap

用 Ansible raw task 支援無 Python 的 Ubuntu 24.04。
安裝 Python、Docker/Compose、WireGuard、UFW、chrony、fail2ban、unattended-upgrades。
建立 /opt/haixun、/etc/haixun、/var/lib/haixun、服務帳號與權限。
設定 Docker log rotation、daemon 啟動、Registry trust/login hook。
防火牆先保留 SSH，再按 role 套規則。
bootstrap 可重跑，且不修改/清除 data volume。

完成定義：七種角色的空 VM 都可從只有 SSH/sudo 到 bootstrap ready；第二次執行為 no-op 或安全更新。

M2 - WireGuard、Registry 與本機 build pipeline

依 inventory 自動分配 WireGuard IP，建立 peer 並驗證連通。
配置固定出口節點供 Atlas 連線。
部署帶 TLS/auth/persistent volume 的自架 Registry。
Edge/Registry DNS 檢查與 Let's Encrypt 自動申請/續期。
新增 frontend/backend/worker/crawler/ops Dockerfile 與 Buildx build/push 指令。
image 使用 git SHA；保存上一個成功 tag 供 rollback。

完成定義：遠端 VM 不具備 source tree 也能 pull 並啟動測試 image；Registry 重啟後 image 仍存在。

M3 - Atlas、Redis、MinIO 與 first data initialization

production 移除本機 Mongo 假設，所有 runtime 讀取 Atlas URI。
Redis 獨立 Compose：auth、AOF、volume、health、backup/restore。
MinIO 獨立 Compose：volume、health、bucket/policy idempotent init、backup/restore。
ops image 提供 migration/init/seeder。
seeder 改為由 Vault 設定 admin email/display name/password，既有資料不覆寫。
將現有 backup、monitoring、reset 腳本從本機 Mongo 假設拆開；Atlas 備份交由 Atlas Backup/PITR。

完成定義：空 Atlas database 可按 migration -> init -> seed 建立；重跑不重複資料、不重設密碼；Redis/MinIO restart 後資料保留。

M4 - 應用角色拆分與無狀態修正

frontend image 只含 production static build。
backend image 含 gateway 與固定 extension ZIP path。
worker image 含 Go worker、Node profile scraper、相容 Chromium。
crawler sidecar 可設定 bind address、有 health endpoint，只走 private Docker network。
role-specific env/template 只下發所需 secret。
gateway readiness 補 Mongo + Redis；frontend 提供 build version；worker 啟動檢查 identity/connectivity。

完成定義：frontend/backend/worker 可分別 build、push、deploy、restart；刪除任一 app container 後可從 image/config 重建且無業務資料遺失。

M5 - 多節點、Edge 與一般部署

Edge 依 inventory 產生 frontend/backend upstream。
backend/frontend 採 serial: 1 rolling recreate，readiness 後才加入流量。
worker 支援指定 host 或整組新增/更新，worker ID 唯一。
config-only deploy 原子同步設定並只 recreate 指定角色。
status/logs/restart/rollback 以 role/host 過濾。
migration run_once 且先於 backend recreate；失敗立即停止。

完成定義：增加一個 IP 可加入新 worker；增加 frontend/backend IP 可健康註冊；部署期間其他健康節點持續服務。

M6 - First deploy orchestrator、備份與演練

make first-deploy 串接 M0-M5 checkpoint，但每一步仍可單獨重跑。
建立 Redis/MinIO/Registry restore runbook 與 Atlas restore 責任邊界。
提供首次部署報告：host、role、WG IP、image tag、health、TLS、backup 與單點警告。
在全新 staging VM 完成安裝、失敗續跑、config-only、加節點、rollback、重啟持久性與公網封鎖測試。
live deployment 必須由使用者另行確認，不因完成程式碼而自動執行。

完成定義：從設定檔與空 VM 到完整 staging 可用，不登入遠端手動安裝或改設定。

3. 預計檔案落點

apps/web/Dockerfile
apps/backend/Dockerfile.gateway
apps/backend/Dockerfile.worker
apps/backend/Dockerfile.ops
apps/backend/crawler/Dockerfile

deploy/prod/
  Makefile
  ansible.cfg
  deployment.yml.example
  secrets.vault.yml.example
  inventory/
  playbooks/
    bootstrap.yml
    first-deploy.yml
    deploy.yml
    database.yml
    status.yml
  roles/
    common/
    wireguard/
    registry/
    edge/
    frontend/
    backend/
    worker/
    redis/
    minio/
  templates/
  scripts/
    doctor.sh
    preflight.sh
    build.sh
    push.sh
    deploy.sh

現有單機 production scripts 在新流程驗收前不直接刪除；實作時先標示 legacy，確認沒有現役依賴後再決定移除，避免中斷既有環境。

4. 驗證矩陣

ID	驗證
DEP-01	空 Ubuntu 24.04 無 Python VM 可 bootstrap
DEP-02	bootstrap 重跑不清資料、不重建 secret
DEP-03	只填 SSH IP 即可自動配置 WireGuard IP
DEP-04	Registry TLS/auth/persistence 正常
DEP-05	應用 image 全由本機 build，遠端無 source/build
DEP-06	Atlas migration/init/seed 順序正確且可重跑
DEP-07	seed 不覆寫既有管理員密碼
DEP-08	Redis/MinIO restart 後資料保留
DEP-09	config-only deploy 不產生新 image且新設定生效
DEP-10	backend/frontend rolling deploy 保留健康服務
DEP-11	新增 worker IP 後只有新 host 被 bootstrap/deploy
DEP-12	新增 backend/frontend 後 Edge 只加入健康節點
DEP-13	migration 失敗時 backend 保持舊版
DEP-14	rollback 可切回上一個成功 image tag
DEP-15	公網無法直連 Redis/MinIO private API/backend/crawler
DEP-16	crawler sidecar 可用且 host 無公開 crawler port
DEP-17	Atlas 連線顯示固定出口 IP
DEP-18	備份與還原演練有可驗證結果

5. 風險與後續

風險	第一版處理
Redis/MinIO/Registry/Edge 單點	明示風險、持久化、備份、restore runbook；HA 後續里程碑
全 mesh 新增節點需更新 peers	由 Ansible inventory 統一生成並分批套用
Atlas 固定出口節點故障	第一版接受單點；文件化切換出口與 allowlist 流程
Outbox 全域 lock 限制 worker 擴縮	部署不誤稱 Outbox 已水平擴充；另立應用 task 改 due query/claim/concurrency
外部發文 at-least-once 重複	不在部署層假裝解決，保留既有 lease 風險並另案處理
seeder 目前寫死管理員資料	M3 先修成 Vault 可設定，再允許 first deploy seed
health 目前只檢查 Redis	M4 補 Mongo readiness，避免壞節點進 upstream
舊單機腳本仍可能在使用	新流程先並存並標 legacy，不自動刪除或改動現役服務

6. 實作前仍需填入的實際值

所有 VM SSH IP、user、port、private key。
Edge、Registry 網域與已完成的 DNS A/AAAA record。
Atlas SRV URI、database user 與固定出口 allowlist。
Registry、Redis、MinIO、JWT、加密、Crawler、Provider、SMTP 等 Vault secret。
初始管理員 email、display name、password。
各 VM CPU architecture、磁碟掛載與備份目的地。

上述值未備齊時可完成程式與 staging 測試，但不得執行正式 first deploy。

8.3 KiB Raw Blame History Unescape Escape