c6ec7a3b71
Some checks failed
CD Pipeline / workflow-shape (push) Successful in 0s
CD Pipeline / cancel-stale-cd (push) Has been skipped
CD Pipeline / build-and-deploy (push) Has been cancelled
CD Pipeline / post-deploy-checks (push) Has been cancelled
CD Pipeline / tests (push) Has been cancelled
43 lines
2.4 KiB
Markdown
43 lines
2.4 KiB
Markdown
# Public Maintenance Fallback Runbook
|
||
|
||
## 目標
|
||
|
||
主機或 VM 重啟時，public 網站不得直接露出空白 502。正式做法分兩層：
|
||
|
||
- L0 local edge：110 / 188 / 120 / 121 的 Nginx 仍可回應時，用 `ops/maintenance/maintenance.html` 攔截 `502` / `503` / `504`，顯示靜態維護頁。
|
||
- L1 external cloud/CDN：如果 99 / VMware / 家用路由 / 對外 IP 整段不可達，由外部雲端主機或 CDN health check 切到同一份靜態維護頁。
|
||
|
||
## 必要特性
|
||
|
||
- 維護頁不得讀取 `.env`、cookie、session、DB、K3s、Redis、NFS 或內部 API。
|
||
- 維護頁必須是靜態檔，能被 Nginx、Cloudflare Pages、S3/R2 static hosting、GCS static site 或任一低成本外部 VM 直接服務。
|
||
- L0 與 L1 使用同一份內容，避免使用者在不同故障層看到不同訊息。
|
||
- 502 fallback 只能處理 upstream failure；若整個 public edge unreachable，必須由 L1 接手。
|
||
|
||
## L0 受控套用
|
||
|
||
1. 將 `ops/maintenance/maintenance.html` 部署到 edge host 的 `/var/www/maintenance/maintenance.html`。
|
||
2. 在每個 public `server {}` 內 include `ops/maintenance/nginx-502-maintenance-snippet.conf` 的等價內容。
|
||
3. `nginx -t` 通過後才 reload Nginx。
|
||
4. 用壞 upstream staging vhost 或暫存 upstream 驗證 `X-AWOOOI-Fallback: local-maintenance`，不得用 production DB / app restart 當測試手段。
|
||
|
||
## L1 外部雲端/CDN 建議
|
||
|
||
優先順序：
|
||
|
||
1. Cloudflare / CDN health check + fallback origin：最快切換，對使用者體驗最好。
|
||
2. 低成本外部 VM：可控性高，能同時跑 blackbox probe；需要 VM patching 與監控。
|
||
3. Object storage static hosting：成本最低，適合維護頁；DNS/CDN health check 仍要另外配置。
|
||
|
||
L1 active 條件：
|
||
|
||
- `probe_success` 對主要 public routes 連續 2 分鐘失敗，或
|
||
- `awoooi_reboot_event_detected == 1` 且 `awoooi_reboot_auto_recovery_slo_ready == 0` 超過 10 分鐘，或
|
||
- 99 / 110 / 188 / 120 / 121 / 112 任一 P0 host down 且 public route 同時 502 / timeout。
|
||
|
||
## 驗證
|
||
|
||
- L0：對測試 vhost 讀回 `200` 或 `503` 的維護頁 HTML，且 header `X-AWOOOI-Fallback=local-maintenance` 存在。
|
||
- L1：從外部網路讀回靜態維護頁，且不經過 99 / 110 / 188 / 120 / 121 / 112。
|
||
- Recovery：主要 upstream 連續 2 分鐘健康後切回正式 origin；Telegram 發送 recovery 通知，並在 cold-start scorecard 留下 readback。
|