awoooi/docs/runbooks/HOST-188-HYGIENE-MAINTENANCE-RUNBOOK.md

# 188 Host Hygiene 維護窗口 Runbook

> 版本：2026-06-26.v2
> 適用範圍：`192.168.0.188` host PostgreSQL `14/main`、`awoooi-startup.service`、certbot / ACME renewal hygiene。
> 狀態：`HOST_188_HYGIENE_GREEN`

---

## 1. 目的

188 目前的產品服務、public routes 與 host hygiene 均已收斂為 green。這份 runbook 將「服務恢復」、「host hygiene」、「DR escrow」與「Wazuh registry」分開，避免把 route `200`、container healthy、`pg_isready`、exporter green 或 `reset-failed` 誤判成其他層級也完成。

本文件記錄 2026-06-26 已完成的 188 host hygiene 修復與後續操作邊界。它不是 DR escrow 完成證明，也不是 Wazuh / SOC runtime action 授權。未取得 owner、rollback owner、maintenance window、backup / restore evidence 與 post-check plan 前，仍不得執行資料層 break-glass、restore、未批准 renew、或其他主機寫入。

---

## 2. 最新只讀證據

2026-06-26 12:02-12:13 Asia/Taipei live evidence：

| 層級 | 證據 | 判定 |
|------|------|------|
| Host systemd | `systemctl is-system-running` 為 `running`，failed units `0 loaded units listed` | host hygiene green |
| 產品容器 | MOMO、VibeWork、2026FIFA、ClawBot、MinIO、exporters、MOMO DB 等容器 healthy / up | 產品服務 green |
| PostgreSQL runtime | `k3s-postgres-recovery` container 為 `Running=true`、`NetworkMode=host`、restart policy `unless-stopped`，`pg_isready -h localhost -p 5432` accepting connections | production DB runtime green |
| Host PostgreSQL unit | `postgresql@14-main.service` reset 後 `Result=success / inactive`；`pg_lsclusters` 仍可能因 recovery container PID model 顯示 host cluster down | 不再作為 service blocker；由 runtime-ready 判斷 |
| Startup unit | `/usr/local/bin/awoooi-startup.sh` 已改為 `postgres_runtime_ready()`，接受 active host unit 或 `k3s-postgres-recovery` host-network runtime；不再自動執行 `pg_resetwal` | fail-closed 修復完成 |
| Nginx / ACME route | `sentry.wooo.work`、`gitea.wooo.work`、`langfuse.wooo.work`、`signoz.wooo.work` HTTP-01 self-test token 均由 `/var/www/html` 正確回應 | challenge route green |
| certbot timers | duplicate apt `certbot.timer` 已停用；snap `snap.certbot.renew.timer` enabled / active / waiting；`certbot.service` 與 `snap.certbot.renew.service` `Result=success / inactive` | renewal runner hygiene green |
| public cert | shared `sentry.wooo.work` certificate valid until `2026-07-09 16:03:40 UTC` | 尚未宣稱已 renew；等待 snap timer / ACME window |

---

## 3. GO / NO-GO

| Gate | GO 條件 | NO-GO 條件 |
|------|---------|------------|
| 服務層 | MOMO / VibeWork / 2026FIFA / SignOz / public routes 可用 | 產品 route 或 DB 容器同時故障時，先走 incident triage |
| PostgreSQL | DB owner 確認 host `14/main` 是否仍為 authoritative source | 無法確認用途就不得 reset / disable / restore |
| Backup | 有可追溯 backup ref、restore target isolation、rollback owner | 沒有 backup / restore evidence 就不得 `pg_resetwal` 或 restore |
| certbot | DNS / ACME / public gateway owner response accepted，rate-limit 冷卻期明確 | ACME route 未確認、仍被 rate-limit、或缺 rollback owner |
| 維護窗口 | owner、窗口、post-check、operator notification 完整 | 只有「服務看起來綠」或「想清 failed units」 |

---

## 4. PostgreSQL `14/main` 決策樹

1. **先判定用途**
   - 是否仍被任何 production service 使用。
   - 是否只是舊的 host cluster，產品 DB 已由 containerized PostgreSQL 接管。
   - 是否仍承載 K3s Kine、MOMO、monitoring、legacy app 或 operator tooling。

2. **若確認 host cluster 已廢棄**
   - 準備 owner disposition：廢棄原因、affected scope、最後 backup / dump ref、保留期限。
   - 維護窗口內才可停用 unit 或調整 startup script 的 host PG dependency。
   - 停用後仍需 post-check：public routes、MOMO health、SignOz、exporters、backup-status、cold-start。

3. **若確認 host cluster 仍需要保留**
   - 先建立隔離 restore target，不直接覆蓋 production data directory。
   - 先比對 backup / WAL / data directory metadata。
   - 只有 DB owner 明確接受資料風險與 rollback plan 後，才可進入 break-glass 修復。

4. **禁止預設路徑**
   - 不得直接 `pg_resetwal`。
   - 不得直接 `rm -rf /var/lib/postgresql/14/main`。
   - 不得直接 `systemctl reset-failed` 假綠。
   - 不得把 container `momo-db` healthy 當成 host `14/main` healthy。

---

## 5. certbot / ACME 決策樹

1. **先停止誤判**
   - `certbot.service` failed 目前代表 renewal 未成功，不代表現有憑證立即失效。
   - `sentry.wooo.work` cert 仍有效到 `2026-07-09 16:03:40 UTC`。

2. **先做 owner evidence**
   - domain / SAN / shared certificate coverage ref。
   - ACME challenge route owner。
   - renewal owner。
   - rollback owner。
   - validation plan。

3. **維護窗口內才可做**
   - `nginx -t`。
   - ACME challenge route smoke。
   - certbot dry-run 或 renew。
   - Nginx reload。

4. **禁止事項**
   - rate-limit 期間反覆 renew。
   - 未確認 challenge route 就 renew。
   - 同時保留 apt certbot timer 與 snap certbot timer 的重複失敗狀態。
   - 貼出 private key、ACME account key、DNS credential、未脫敏 certbot log。

---

## 6. 維護窗口最小步驟

此段只定義順序；不代表目前已批准執行。

### Phase 0：一鍵只讀 preflight

在 repo 工作站先執行只讀 checklist；它不會 restart、reload、renew、reset-failed、restore、`pg_resetwal` 或寫入遠端狀態。

```bash
SSH_BATCH_MODE=yes bash scripts/reboot-recovery/188-host-hygiene-maintenance-checklist.sh --no-color
```

目前預期結果是：

```text
SERVICE_GREEN=1
HOST_HYGIENE_BLOCKED=0
RUNTIME_ACTION_AUTHORIZED=0
Result: HOST_188_HYGIENE_GREEN.
```

### Phase A：維護前只讀快照

```bash
systemctl --failed --no-pager
pg_lsclusters
systemctl status postgresql@14-main.service --no-pager
systemctl status certbot.service snap.certbot.renew.service --no-pager
docker ps --format '{{.Names}}\t{{.Status}}\t{{.Ports}}'
/backup/scripts/backup-status.sh --no-notify
/home/wooo/scripts/full-stack-cold-start-check.sh --monitor-read-only --no-color --watch --interval 1 --max-attempts 1
```

### Phase B：owner 決策

| 決策 | 必填 evidence |
|------|---------------|
| host PostgreSQL 廢棄 | owner disposition、affected services、last backup ref、retention owner |
| host PostgreSQL restore | source backup ref、isolated restore target、checksum / row-count plan、rollback owner |
| certbot route 修復 | certificate coverage ref、ACME owner、challenge route plan、post-renew validation |

### Phase C：受控修復

只在 maintenance window 內由 operator 執行；此文件不提供自動 apply。

### Phase D：post-check

```bash
systemctl --failed --no-pager
pg_lsclusters
curl -fsS https://mo.wooo.work/health
curl -fsS https://stock.wooo.work/api/v1/system/freshness
curl -fsS https://awoooi.wooo.work/api/v1/health
/backup/scripts/backup-status.sh --no-notify --no-refresh
/home/wooo/scripts/full-stack-cold-start-check.sh --monitor-read-only --no-color --watch --interval 1 --max-attempts 1
```

成功標準：

- 產品 routes 仍綠。
- backup core 仍 `core_blockers=0`。
- cold-start 維持 `WARN=0 BLOCKED=0`。
- 若 owner 決定 host PG 廢棄，systemd failed unit 必須以 owner disposition 收斂，不可只是 reset-failed。
- 若 owner 決定 host PG 修復，必須有 restore / data integrity evidence。
- 若 certbot 修復，必須有 cert notAfter、ACME route、Nginx config test 與 reload evidence。

---

## 7. 目前完成度

| Lane | 完成度 | 說明 |
|------|-------:|------|
| 服務恢復 | `100%` | routes、containers、cold-start、backup core 已 green |
| 188 host hygiene repair | `100%` | startup fail-closed、PostgreSQL runtime-ready 判斷、systemd failed units、ACME route 與 certbot timer hygiene 已收斂 |
| PostgreSQL runtime source-of-truth | `100%` | production DB runtime 以 `k3s-postgres-recovery` host-network container + `pg_isready` 判斷，不用 host `pg_lsclusters` 假紅 |
| certbot / ACME route hygiene | `95%` | HTTP-01 route 與 timer split 已修；正式 renew 成功仍等待 snap timer / ACME window |
| DR escrow | `BLOCKED` | `escrow_missing=5`，不可用 188 host green 替代 |
| Wazuh registry | `BLOCKED` | manager registry accepted `0`，不可用 route `200` 或 transport count 替代 |

---

## 8. 不得宣稱

- 不得宣稱 DR complete；credential escrow evidence 仍缺 `5`。
- 不得宣稱 Wazuh registry recovered；manager registry accepted 仍為 `0`。
- 不得宣稱 certbot certificate 已完成正式 renew；目前完成的是 HTTP-01 route / timer hygiene / failed units 清除。
- 不得把 `reset-failed` 單獨當成修復完成；本次完成是因 startup source、Nginx ACME route、timer split 與 postcheck 同時收斂。
- 不得宣稱這份文件批准任何新的 runtime action。