diff --git a/docs/adr/ADR-054-diagnose-privacy-first-routing.md b/docs/adr/ADR-054-diagnose-privacy-first-routing.md new file mode 100644 index 00000000..a8c83252 --- /dev/null +++ b/docs/adr/ADR-054-diagnose-privacy-first-routing.md @@ -0,0 +1,96 @@ +# ADR-054: DIAGNOSE Privacy-First Routing(本地隱私邊界) + +> **狀態**: ✅ 已批准 +> **日期**: 2026-04-04 +> **決策者**: 統帥 + 首席架構師 +> **首席架構師評分**: 技術背書 +> **關聯 ADR**: ADR-052 (AI Provider Registry) +> **實作**: Phase 25 P0 — commit 3455044, a562db4 + +--- + +## 背景 + +### 問題陳述 + +`DIAGNOSE` 任務類型(根本原因分析、服務診斷)會接收到包含機密基礎設施資訊的 Incident 資料(Pod 名稱、錯誤堆疊、服務拓撲)。在 ADR-052 的 AI Provider Registry 架構下,DIAGNOSE 原本沿用 `_fallback_chain`,可能將機密資料傳送至雲端 Provider(Gemini、Claude)。 + +### 驅動因素 + +1. **零信任原則**: 機密基礎設施資料不應離開內網 +2. **合規要求**: 避免系統診斷資料上傳至第三方雲端 +3. **能力需求**: 診斷任務需要高推理能力,不能只用 Ollama + +--- + +## 決策 + +### D1: 建立 `_local_fallback_chain` + +```python +# ai_router.py +self._local_fallback_chain: list[tuple[AIProviderEnum, str]] = [ + (AIProviderEnum.NEMOTRON, self._nemotron_default), # NIM 188,主力 + (AIProviderEnum.OLLAMA, self._ollama_summary), # Ollama 188,備援 +] +``` + +DIAGNOSE 任務強制使用此鏈,不允許降級至任何 `privacy_level="cloud"` 的 Provider。 + +### D2: NEMOTRON Provider 的 privacy_level 裁定 + +**首席架構師裁示 (2026-04-04)**: +- NEMOTRON Provider 對應 NVIDIA NIM 部署在 **192.168.0.188**(內網 GPU 主機) +- 非 NVIDIA 官方雲端 API(api.nvidia.com) +- 屬於 local infra,`privacy_level = "local"`,可納入 DIAGNOSE 隱私邊界 + +```python +# nemotron.py +@property +def privacy_level(self) -> str: + return "local" # NIM 部署在 192.168.0.188(內網 GPU) +``` + +### D3: 全部 Local Provider 不可用時 → REJECT + Telegram + +```python +# 全部 local provider 失敗或不可用時 +await tg.send_text("⚠️ DIAGNOSE 本地 Provider 不可用,需要人工介入") +return AIResult(success=False, reason="REJECT_PRIVACY_BOUNDARY") +``` + +不降級至雲端。必要時通知人工介入。 + +### D4: route_sync() 同步版本同樣適用隱私邊界 + +`route_sync()` 補齊相同的 DIAGNOSE → `_local_fallback_chain` 判斷,確保同步路徑不繞過隱私邊界。 + +--- + +## 後果 + +### 正面影響 + +- DIAGNOSE 資料的隱私保護有制度性保障 +- 失敗時告警人工介入,不靜默降級至雲端 +- NIM 188 具備足夠診斷能力(Nemotron-4 340B 量化版) + +### 負面影響 / 風險 + +- 若 NIM 188 離線且 Ollama 超時,DIAGNOSE 功能暫時中斷 +- 需要維護 NIM 188 的高可用性 + +### 未決事項 + +- NIM 188 是否需要 Startup Probe(K0.5,待維護窗口) +- 若未來引入第三個 local provider,`_local_fallback_chain` 需更新 + +--- + +## 替代方案 + +| 方案 | 理由未採用 | +|------|-----------| +| 允許 DIAGNOSE 降級至 Gemini | 違反零信任原則 | +| 只用 Ollama 做 DIAGNOSE | 能力不足,診斷品質差 | +| 所有任務類型一律 local-only | 過於保守,影響正常業務功能 | diff --git a/docs/adr/ADR-055-knowledge-auto-harvesting.md b/docs/adr/ADR-055-knowledge-auto-harvesting.md new file mode 100644 index 00000000..45284bd1 --- /dev/null +++ b/docs/adr/ADR-055-knowledge-auto-harvesting.md @@ -0,0 +1,121 @@ +# ADR-055: Knowledge Auto-Harvesting(AUTO_RUNBOOK + ANTI_PATTERN) + +> **狀態**: ✅ 已批准 +> **日期**: 2026-04-04 +> **決策者**: 統帥 + 首席架構師 +> **首席架構師評分**: 技術背書 +> **關聯 ADR**: ADR-052 (AI Provider Registry), ADR-043 (Knowledge Base) +> **實作**: Phase 25 P1 — commit 3455044 + +--- + +## 背景 + +### 問題陳述 + +AutoRepair 執行修復後,成功/失敗的知識停留在系統日誌中,無法被後續決策利用。特別是: + +1. **成功修復** → 修復步驟應被收錄為可參考的 Runbook +2. **失敗修復** → 失敗模式應被記錄以防止重複嘗試相同方法 + +Knowledge Base 存在但靠人工填寫,形成知識孤島。 + +--- + +## 決策 + +### D1: AUTO_RUNBOOK — 成功修復自動產生草稿 Runbook + +```python +# auto_repair_service.py — execute_auto_repair() 成功後 +task = asyncio.create_task(gen.generate_runbook(incident, playbook, result)) +self._pending_tasks.add(task) +task.add_done_callback(self._pending_tasks.discard) +``` + +- EntryType: `AUTO_RUNBOOK` +- EntryStatus: `DRAFT`(需要人工審核後才升為 APPROVED) +- Nemotron 生成內容,失敗時有最小化 fallback + +**理由**: 自動生成的 Runbook 品質未經驗證,保持 DRAFT 讓 SRE 審核,避免錯誤知識被自動採納。 + +### D2: ANTI_PATTERN — 失敗修復直接發布防災記錄 + +```python +# auto_repair_service.py — execute_auto_repair() 失敗後 +task = asyncio.create_task( + gen.generate_anti_pattern(incident, playbook, fail_result, symptoms_hash) +) +self._pending_tasks.add(task) +task.add_done_callback(self._pending_tasks.discard) +``` + +- EntryType: `ANTI_PATTERN` +- EntryStatus: `PUBLISHED`(直接發布,無需人工審核) +- 理由:失敗記錄的目的是「防止重蹈覆轍」,早一秒發布早一秒保護 + +### D3: SymptomPattern.compute_hash() — O(1) 防災閘門 + +```python +def compute_hash(self) -> str: + key = ( + "|".join(sorted(self.alert_names)) + "||" + + "|".join(sorted(self.affected_services)) + "||" + + json.dumps(self.label_patterns, sort_keys=True) + ) + return hashlib.sha256(key.encode()).hexdigest()[:16] +``` + +- 16 字元 hex = 2^64 碰撞空間,工程實踐上足夠 +- 碰撞發生最壞結果:某次修復被誤攔截,需人工重試——可接受 + +### D4: evaluate_auto_repair() 加入 ANTI_PATTERN 閘門 + +```python +# 症狀提取後、Playbook 匹配前 +symptoms_hash = symptoms.compute_hash() +anti_patterns = await get_knowledge_service().check_anti_pattern(symptoms_hash, days=7) +if anti_patterns: + return AutoRepairDecision( + can_auto_repair=False, + reason=f"過去 7 天有失敗案例: {anti_patterns[0].title}", + blocked_by="ANTI_PATTERN", + ) +``` + +閘門位置:診斷症狀後、開始執行前,屬於預防性攔截。 + +### D5: Fire-and-Forget 必須有 GC 防護 + +所有 `asyncio.create_task()` 必須: +1. 持有引用至 `self._pending_tasks` +2. 在 `done_callback` 中從集合移除 + +```python +task = asyncio.create_task(coro) +self._pending_tasks.add(task) +task.add_done_callback(self._pending_tasks.discard) +``` + +成功分支與失敗分支必須對稱實作,不得有遺漏。 + +--- + +## 後果 + +### 正面影響 + +- Knowledge Base 自動積累修復經驗,形成正向循環 +- 失敗模式即時保護,防止重複損耗 +- SRE 工作聚焦於審核而非撰寫 + +### 負面影響 / 風險 + +- Nemotron 生成的 Runbook 品質參差,需 SRE 審核成本 +- ANTI_PATTERN 直接發布,若症狀 hash 碰撞可能誤攔正常修復 + +### 未決事項(Backlog) + +- I2: `nvidia.chat()` system prompt 格式是否符合 NIM message format 規範 +- M1: ANTI_PATTERN 是否需要 Telegram 確認視窗(human-in-the-loop 選項) +- M2: symptoms_hash 16 字元截斷的碰撞監控機制 diff --git a/docs/adr/ADR-056-config-drift-detection.md b/docs/adr/ADR-056-config-drift-detection.md new file mode 100644 index 00000000..a5bcb130 --- /dev/null +++ b/docs/adr/ADR-056-config-drift-detection.md @@ -0,0 +1,123 @@ +# ADR-056: Config Drift Detection — GitOps 守門員架構 + +> **狀態**: ✅ 已批准 +> **日期**: 2026-04-04 +> **決策者**: 統帥 + 首席架構師 +> **首席架構師評分**: 技術背書 +> **關聯 ADR**: ADR-052, ADR-057 (adopt() Gitea PR API) +> **實作**: Phase 25 P2 — commit 3455044 + +--- + +## 背景 + +### 問題陳述 + +K8s 叢集實際狀態可能因以下原因與 Git YAML 產生漂移: + +1. 緊急 Hotfix 直接 kubectl 操作而未提交 Git +2. 人為誤操作(kubectl edit / kubectl set image) +3. CI/CD 部分失敗導致 Rollout 中斷 + +目前無系統性機制偵測此類漂移,也無法自動修復。 + +--- + +## 決策 + +### D1: 四層架構(Detector → Analyzer → Interpreter → Remediator) + +``` +GitStateReader ─┐ + ├─→ DriftDetector.scan() → raw DriftReport +K8sStateReader ─┘ + ↓ + DriftAnalyzer.classify() → HIGH/MEDIUM/INFO + ↓ + NemotronDriftInterpreter.analyze() → intent + explanation + ↓ + DriftRemediator.rollback() / adopt() +``` + +**職責邊界**: +- Detector: 事實比對(Git vs K8s),不做判斷 +- Analyzer: 分級(白名單過濾、嚴重度分類) +- Interpreter: AI 意圖分析,**只輸出意圖判斷,不輸出修復指令** +- Remediator: 確定性修復執行,不使用 AI 決定修復策略 + +### D2: AI 只做意圖分析,確定性程式碼做修復 + +NemotronDriftInterpreter 分析漂移意圖(emergency_hotfix / human_error / automated_change / unknown),為人工決策提供參考。 + +修復由確定性程式碼執行(`kubectl apply` / `git push`),不允許 AI 生成 kubectl 指令。 + +**理由**: AI 生成的修復指令無法保證正確性,對 K8s 叢集的破壞難以回滾。 + +### D3: rollback() 使用 kubectl apply(覆蓋回 Git 狀態) + +```python +cmd = ["kubectl", "apply", "-f", target, "-n", namespace, "--dry-run=none"] +``` + +- `resource_key` 參數支援精細範圍(按 Kind/Name 匹配 YAML 檔) +- 失敗時只通知,不重試(避免重複操作) + +### D4: adopt() 端點暫停開放(見 ADR-057) + +API Pod 內執行 `git add -A` 有安全風險: + +1. API Pod 通常無 Git 認證(SSH key / token) +2. `git add -A` 可能誤提交敏感檔案 +3. 多副本部署下 git 操作不安全 + +暫回傳 501,ADR-057 完成後改由 Gitea PR API 實作。 + +### D5: CronJob 每小時自動掃描 + +```yaml +schedule: "0 * * * *" +concurrencyPolicy: Forbid # 防並發 +activeDeadlineSeconds: 300 # 5 分鐘超時 +backoffLimit: 0 # 失敗不重試 +``` + +### D6: 漂移報告暫存(in-process dict,Phase 1) + +```python +_recent_reports: dict[str, DriftReport] = {} # 最多 50 筆,FIFO +``` + +此為 Phase 1 設計,多副本部署下不一致。 + +**升級路徑**: Phase 2 遷移至 `drift_reports` DB 表(migration phase9 已就緒)。 + +--- + +## 後果 + +### 正面影響 + +- 漂移偵測自動化,每小時一次無需人工 +- 四層架構職責清晰,各層可獨立替換 +- AI 只做分析不做決策,保持確定性修復 + +### 負面影響 / 風險 + +- `_recent_reports` 多副本不一致(Phase 1 已知限制) +- adopt() 功能暫停,承認漂移需要手動 git 操作 + +### 未決事項 + +- C3: `_recent_reports` 遷移至 DB(見 Phase 2 計畫) +- I4: `_is_allowlisted` / `_is_critical` field_path 比對邏輯需整合測試覆蓋 +- ADR-057: adopt() Gitea PR API 實作 + +--- + +## 替代方案 + +| 方案 | 理由未採用 | +|------|-----------| +| AI 生成 kubectl patch 指令執行修復 | AI 生成指令不可控,破壞難以回滾 | +| 只記錄漂移不修復 | 缺少閉環,漂移長期積累 | +| GitOps operator (Flux/ArgoCD) 完全接管 | 引入外部依賴,與現有架構整合成本高 | diff --git a/docs/adr/ADR-057-adopt-gitea-pr-api.md b/docs/adr/ADR-057-adopt-gitea-pr-api.md new file mode 100644 index 00000000..09726248 --- /dev/null +++ b/docs/adr/ADR-057-adopt-gitea-pr-api.md @@ -0,0 +1,82 @@ +# ADR-057: Drift Adopt 端點 — Gitea PR API 實作路徑 + +> **狀態**: 📝 草案(待統帥批准後實作) +> **日期**: 2026-04-04 +> **決策者**: 統帥 + 首席架構師 +> **關聯 ADR**: ADR-056 (Config Drift Detection) +> **觸發原因**: 首席架構師 C2 裁示 — API Pod 內執行 git add -A 有安全漏洞 + +--- + +## 背景 + +### 問題陳述 + +ADR-056 中 `adopt()` 端點的設計目標:將 K8s 實際狀態的合法漂移反向寫回 Git(使 Git 承認此次變更)。 + +原始實作使用 `_git_push()` 在 API Pod 內執行 `git add -A && git commit && git push gitea main`,存在: + +1. **安全風險**: `git add -A` 可能誤提交 Secret/ConfigMap 等敏感資料 +2. **多副本問題**: 多個 API Pod 同時執行 git 操作會造成 conflict +3. **認證問題**: API Pod 需要持有 Gitea 認證,擴大攻擊面 +4. **Bypass 審核**: 直接 push main 繞過 PR review 流程 + +--- + +## 決策(草案) + +### D1: adopt() 端點改用 Gitea PR API + +流程: +``` +用戶按下 adopt → API 呼叫 Gitea API 建立 PR → SRE review → merge +``` + +具體實作: +1. API 呼叫 `POST /api/v1/repos/{owner}/{repo}/pulls`(Gitea API) +2. PR title: `chore: adopt drift — {namespace} {summary}` +3. PR body: 包含漂移詳情、Nemotron 意圖分析、影響評估 +4. PR 建立後推送 Telegram 通知 SRE review + +### D2: 分支命名規範 + +``` +drift/adopt-{report_id[:8]}-{timestamp} +``` + +API 建立 branch 並 commit 對應 YAML 變更,再開 PR。 + +### D3: API Pod 認證方式 + +使用 Gitea API Token(現有 `GITEA_API_TOKEN` secret),只需 PR 建立權限,不需要 push main 權限。 + +--- + +## 實作前置條件 + +- [ ] 統帥批准此 ADR +- [ ] 確認 `GITEA_API_TOKEN` 已在 K8s Secret 中(現有 secret 確認) +- [ ] 確認 Gitea API `/repos/wooo/awoooi/pulls` 端點可用 +- [ ] 設計 YAML diff 的精確生成邏輯(只改漂移的欄位) + +--- + +## 替代方案 + +| 方案 | 理由未採用 | +|------|-----------| +| 繼續 git push main(原實作) | 安全風險 + 多副本問題 | +| 完全移除 adopt() | 失去 GitOps 閉環能力 | +| 透過 Webhook 觸發 Gitea CI | 複雜度高,與現有 CD 流程耦合 | + +--- + +## 狀態追蹤 + +| 項目 | 狀態 | +|------|------| +| 首席架構師 C2 裁示(暫停 git push) | ✅ 2026-04-04 | +| adopt() 端點回傳 501 | ✅ 2026-04-04 | +| ADR-057 起草 | ✅ 2026-04-05 | +| 統帥批准 ADR-057 | ⏳ 待決 | +| Gitea PR API 實作 | ⏳ 待批准後 |