182 lines
8.3 KiB
Markdown
182 lines
8.3 KiB
Markdown
# 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. 交付策略
|
||
|
||
1. 先建立設定 schema、preflight 與空 VM bootstrap，再碰正式服務。
|
||
2. 先完成 WireGuard 與 Registry，確保後續 image 只需本機 build、遠端 pull。
|
||
3. 資料層先行：Atlas connectivity、Redis persistence、MinIO persistence/bucket/backup。
|
||
4. 將現有共同 release 拆成 frontend、backend、worker、crawler、ops images。
|
||
5. 先單節點驗證，再做 frontend/backend rolling pool 與 Edge 動態 upstream。
|
||
6. first deploy、一般 deploy、config-only deploy、rollback 必須是不同明確路徑。
|
||
7. 所有 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. 預計檔案落點
|
||
|
||
```text
|
||
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。
|