docs: Sprint 5.1 資料安全護欄 — ADR-062/063 + 方案規範驗證
- ADR-062: Data Safety Guardrails (服務分級/Pre-flight/MultiSig) - ADR-063: Service Registry IaC 設計規範 - Sprint 5.1 方案文件: 規範驗證通過，P1-P5 問題修正 - P1: Playbook 存 Redis（非 SQL），M-001 改為 Pydantic model 修改 - P2: velero_client.py 命名維持（與 signoz_client 慣例一致） - P3: docker-health-monitor 狀態釐清 - P4/P5: DI setter + Deployment Verification 補充 - LOGBOOK: 當前焦點更新為 Sprint 5.1 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
OG T
@@ -6,7 +6,7 @@
|
||||
|
||||
---
|
||||
|
||||
## 📍 當前狀態 (2026-04-08 全面監控+操作記錄完成)
|
||||
## 📍 當前狀態 (2026-04-08 Sprint 5.1 規劃完成)
|
||||
|
||||
| 項目 | 狀態 | 說明 |
|
||||
|------|------|------|
|
||||
@@ -16,16 +16,31 @@
|
||||
| alert_operation_log 溯源 | ✅ | Phase 11, 654 筆歷史回填 (f20121a) |
|
||||
| ADR-060 全面監控規劃 | ✅ | 已批准 |
|
||||
| ADR-061 Event Sourcing | ✅ | 已實施 |
|
||||
| Plan A docker-health-monitor.sh | ⏳ 待實作 | 腳本設計完成，待部署 |
|
||||
| Plan B Exporters (PG/Redis/Nginx) | ⏳ 待部署 | docker-compose.exporters.yaml 已有框架 |
|
||||
| Plan C Blackbox 外部網站 | ⏳ | 4 個外部網站待加入 |
|
||||
| ADR-062 Data Safety Guardrails | ✅ | 規劃批准，待實作 |
|
||||
| ADR-063 Service Registry IaC | ✅ | 規劃批准，待實作 |
|
||||
| Sprint 5.1 方案文件 | ✅ | 規範驗證通過，待統帥下令 |
|
||||
| docker-health-monitor.sh | ⏳ Sprint 5.1 L4 | 需改為純感知層（移除 docker restart） |
|
||||
| Plan B Exporters (PG/Redis/Nginx) | ⏳ Sprint 5.2 | docker-compose.exporters.yaml 已有框架 |
|
||||
| Plan C Blackbox 外部網站 | ⏳ Sprint 5.2 | 4 個外部網站待加入 |
|
||||
|
||||
**下一步**: 實作 Plan A docker-health-monitor.sh → 部署 Plan B Exporters
|
||||
**當前焦點**: Sprint 5.1 資料安全護欄（待統帥下令執行 Layer 0~7）
|
||||
**下一步**: 統帥確認 C1-C5 前置條件 → 開始 Layer 0
|
||||
|
||||
---
|
||||
|
||||
## 📊 里程碑總覽 (壓縮版)
|
||||
|
||||
### 2026-04-08 — Sprint 5.1 資料安全護欄規劃完成
|
||||
|
||||
- 11 項首席架構師決策（Q1-Q11）完成
|
||||
- 服務分級（BLOCK/CRITICAL_HITL/STANDARD_HITL/AUTO）確立
|
||||
- Pre-flight 備份檢查機制設計完成
|
||||
- MultiSig 雙簽機制設計完成
|
||||
- ADR-062 Data Safety Guardrails 批准
|
||||
- ADR-063 Service Registry IaC 批准
|
||||
- 完整實施方案 + 規範驗證通過（P1-P5 問題修正）
|
||||
- 關鍵發現：Playbook 存於 Redis（非 PostgreSQL），修正 M-001 方向
|
||||
|
||||
### 2026-04-08 — 全面監控+操作溯源架構
|
||||
|
||||
- 自動修復移除所有 gate：直接執行（統帥指令）
|
||||
|
||||
98
docs/adr/ADR-062-data-safety-guardrails.md
Normal file
98
docs/adr/ADR-062-data-safety-guardrails.md
Normal file
@@ -0,0 +1,98 @@
|
||||
# ADR-062 — 資料安全護欄 (Data Safety Guardrails)
|
||||
|
||||
> **狀態**: 已批准 (首席架構師裁示 2026-04-08)
|
||||
> **撰寫**: Claude Sonnet 4.6 / 2026-04-08 Asia/Taipei
|
||||
> **相關**: ADR-061 (Alert Operation Log), ADR-058 (SSH Host Repair), ADR-039 (CI/CD)
|
||||
|
||||
---
|
||||
|
||||
## 背景
|
||||
|
||||
Sprint 5.1 啟動前，AWOOOI 的自動修復機制已「移除所有 gate」（2026-04-08 統帥指令），所有 APPROVED Playbook 均可直接執行。此設計在無狀態服務上運作良好，但對**有狀態服務（Stateful Services）**存在資料遺失風險：
|
||||
|
||||
- PostgreSQL 重啟 → WAL 截斷、事務回滾
|
||||
- Redis 重啟 → in-memory 資料遺失、冪等鎖消失
|
||||
- ClickHouse 重啟 → 列欄檔案損壞
|
||||
|
||||
同時，系統缺乏「AI 動作可追查」機制：OpenClaw 的 LLM 推理過程與 alert_operation_log 斷層。
|
||||
|
||||
---
|
||||
|
||||
## 決策
|
||||
|
||||
### D1 — 服務分級（Q1）
|
||||
|
||||
建立四級 Stateful 分類，儲存於 `ops/config/service-registry.yaml`（IaC，版控）：
|
||||
|
||||
| 等級 | 定義 | 服務 |
|
||||
|------|------|------|
|
||||
| `BLOCK` | 系統禁止，僅告警 | PostgreSQL (所有實例), ClickHouse |
|
||||
| `CRITICAL_HITL` | MultiSig 2票才執行 | Redis, Gitea, Harbor, MinIO |
|
||||
| `STANDARD_HITL` | 1票審核，特殊 restart 命令 | Prometheus, Grafana, Alertmanager |
|
||||
| `AUTO` | 自動執行 | Nginx, 所有 K3s Pod, Ollama 等 |
|
||||
|
||||
### D2 — Pre-flight 備份檢查（Q2）
|
||||
|
||||
針對 `CRITICAL_HITL` 且 `requires_pre_backup=True` 的服務，執行前檢查：
|
||||
- Velero 最近 Completed 備份 < 4 小時 → 放行
|
||||
- 過期 → **Abort + 觸發緊急備份（非同步）+ 通知人工**（非直接執行）
|
||||
- CPU/IO 高負載類告警 → 禁止觸發備份（Q4，防止雪上加霜）
|
||||
|
||||
### D3 — MultiSig 雙簽（Q3）
|
||||
|
||||
`CRITICAL_HITL` 服務需要 2 票 Telegram 授權才執行，延續 Sprint 3 的 MultiSig 基礎設施。Sprint 5.1 先以同一 user 兩次點擊驗證狀態機，後續 Sprint 擴充多帳號。
|
||||
|
||||
### D4 — Prometheus auto_repair flag 優先級（Q9）
|
||||
|
||||
- `auto_repair: "false"` → 強制 HITL，AI 無法覆寫
|
||||
- `auto_repair: "true"` → 進入 AI + Guardrail 評估，Guardrail 有最終否決權
|
||||
|
||||
### D5 — Langfuse trace_id 寫入 alert_operation_log（Q10）
|
||||
|
||||
OpenClaw 分析完成後，`langfuse_trace_id` 必須寫入 `alert_operation_log.context`，實現 AI 動作全程可追查。
|
||||
|
||||
### D6 — AlertManager 不抑制（Q11）
|
||||
|
||||
Guardrail 阻擋時，不呼叫 AlertManager silence API。靠 AWOOOI Redis TTL 去重（10 分鐘），AlertManager 持續 firing 保持監控可見性。
|
||||
|
||||
---
|
||||
|
||||
## 新增 event_type（共 8 個）
|
||||
|
||||
```
|
||||
GUARDRAIL_BLOCKED # Stateful 服務被阻擋
|
||||
PRE_FLIGHT_PASSED # Pre-flight 備份檢查通過
|
||||
PRE_FLIGHT_FAILED # Pre-flight 失敗（備份過期）
|
||||
BACKUP_TRIGGERED # 緊急備份已觸發
|
||||
BACKUP_COMPLETED # 緊急備份完成
|
||||
BACKUP_FAILED # 緊急備份失敗
|
||||
APPROVAL_ESCALATED # 升級為 CRITICAL_APPROVAL（需 2 票）
|
||||
CHANGE_APPLIED # 手動變更已記錄
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 新增模組
|
||||
|
||||
| 模組 | 路徑 | 職責 |
|
||||
|------|------|------|
|
||||
| ServiceRegistryClient | `services/service_registry.py` | 讀取 YAML，查詢服務分級 |
|
||||
| VeleroClient | `services/velero_client.py` | kubectl 查詢備份狀態，觸發緊急備份 |
|
||||
| PreflightService | `services/preflight_service.py` | Pre-flight 備份檢查邏輯 |
|
||||
|
||||
所有模組遵循 leWOOOgo 積木化規範：Service 層，有 `get_xxx()` + `set_xxx()` singleton 模式。
|
||||
|
||||
---
|
||||
|
||||
## 後果
|
||||
|
||||
- 所有有狀態服務的自動修復操作，由「預設允許」改為「預設拒絕，明確授權才執行」
|
||||
- AI 每一個修復決策都有 Langfuse trace_id 可追查
|
||||
- Prometheus alert rule 的 `auto_repair` flag 成為有效的安全底線
|
||||
- 系統複雜度增加，但「資料安全」優先於「修復速度」
|
||||
|
||||
---
|
||||
|
||||
## 實施計畫
|
||||
|
||||
見 `docs/superpowers/plans/2026-04-08-sprint5-data-safety-guardrails.md`（Layer 0~7 完整步驟）
|
||||
92
docs/adr/ADR-063-service-registry-iac.md
Normal file
92
docs/adr/ADR-063-service-registry-iac.md
Normal file
@@ -0,0 +1,92 @@
|
||||
# ADR-063 — Service Registry IaC 設計規範
|
||||
|
||||
> **狀態**: 已批准 (首席架構師裁示 2026-04-08)
|
||||
> **撰寫**: Claude Sonnet 4.6 / 2026-04-08 Asia/Taipei
|
||||
> **相關**: ADR-062 (Data Safety Guardrails)
|
||||
|
||||
---
|
||||
|
||||
## 背景
|
||||
|
||||
ADR-062 決定使用靜態 YAML 儲存服務的 Stateful 分級（Q6 決策：IaC）。需要規範此 YAML 的設計原則、修改流程、以及與程式碼的整合方式。
|
||||
|
||||
---
|
||||
|
||||
## 設計原則
|
||||
|
||||
**Infrastructure as Code**：服務的 Stateful 屬性是架構本質，不允許在 Web UI 上隨意修改。所有變更必須透過 Git PR + 統帥審核。
|
||||
|
||||
---
|
||||
|
||||
## 檔案位置
|
||||
|
||||
```
|
||||
ops/config/service-registry.yaml
|
||||
```
|
||||
|
||||
此路徑在 `service_registry.py` 中以相對於 repo root 的方式計算：
|
||||
```python
|
||||
Path(__file__).parents[5] / "ops" / "config" / "service-registry.yaml"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## YAML 結構規範
|
||||
|
||||
```yaml
|
||||
services:
|
||||
- name: <service_name> # 唯一識別，對應 container name / k8s service name
|
||||
display_name: <顯示名稱>
|
||||
host: <IP 或 "k3s">
|
||||
stateful_level: BLOCK | CRITICAL_HITL | STANDARD_HITL | AUTO
|
||||
reason: <說明為何此分級> # 必填，記錄決策依據
|
||||
alert_only: true # 僅 BLOCK 使用
|
||||
requires_pre_backup: false # CRITICAL_HITL 使用
|
||||
restart_command: "docker start" # 特殊重啟命令（如 Prometheus/Grafana）
|
||||
containers: ["container-name"] # docker container 名稱（可多個）
|
||||
|
||||
backup_policies:
|
||||
velero_max_age_hours: 4
|
||||
emergency_backup_timeout: 600
|
||||
block_backup_on_high_io: true
|
||||
io_threshold_percent: 80
|
||||
|
||||
multisig:
|
||||
critical_required_votes: 2
|
||||
standard_required_votes: 1
|
||||
vote_expiry_minutes: 30
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 分級決策標準
|
||||
|
||||
| 分級 | 標準 |
|
||||
|------|------|
|
||||
| `BLOCK` | 有 PostgreSQL WAL / ClickHouse 列欄資料 / 重啟必然造成資料遺失或損壞 |
|
||||
| `CRITICAL_HITL` | 有 Volume 掛載 / 重啟可能中斷活躍寫入 / AWOOOI 核心依賴 |
|
||||
| `STANDARD_HITL` | 有 WAL 或狀態但可安全 `docker start`（非 restart）/ 監控基礎設施 |
|
||||
| `AUTO` | 無狀態 / K3s Pod（有 PDB 保護）/ 重啟只影響短暫可用性 |
|
||||
|
||||
---
|
||||
|
||||
## 維護流程
|
||||
|
||||
1. 新增服務 → PR to `ops/config/service-registry.yaml`
|
||||
2. PR 描述必須說明：服務名稱、分級、理由
|
||||
3. 統帥審核後 merge
|
||||
4. ServiceRegistryClient 下次載入時自動生效（singleton 有 lazy load）
|
||||
|
||||
---
|
||||
|
||||
## 失敗行為（Fail-Safe）
|
||||
|
||||
ServiceRegistryClient 讀取失敗時 **fallback AUTO**（不阻擋告警流程），並記錄 ERROR log。此設計確保 Service Registry 本身的故障不會導致整個告警鏈路中斷。
|
||||
|
||||
---
|
||||
|
||||
## 未來擴充
|
||||
|
||||
- 服務依賴關係（dependency edges）→ Sprint 5 拓撲圖使用
|
||||
- 備份策略客製化（每個服務獨立設定）
|
||||
- 動態覆寫（緊急情況時可 kubectl configmap 注入）
|
||||
1320
docs/superpowers/plans/2026-04-08-sprint5-data-safety-guardrails.md
Normal file
1320
docs/superpowers/plans/2026-04-08-sprint5-data-safety-guardrails.md
Normal file
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user