Files

OG T 15c7f6fcd3 docs(adr): 起草 ADR-054/055/056/057 — Phase 25 三方向架構決策

ADR-054: DIAGNOSE Privacy-First Routing (已批准)
  - _local_fallback_chain 設計決策
  - NEMOTRON privacy_level=local 首席架構師裁示
  - 全部 local 失敗 → REJECT + Telegram

ADR-055: Knowledge Auto-Harvesting (已批准)
  - AUTO_RUNBOOK DRAFT + ANTI_PATTERN PUBLISHED 設計理由
  - compute_hash() 碰撞風險說明
  - Fire-and-forget GC 防護強制規範

ADR-056: Config Drift Detection 四層架構 (已批准)
  - Detector→Analyzer→Interpreter→Remediator 職責邊界
  - AI 只做意圖分析不做修復決策
  - adopt() 暫停 + _recent_reports Phase 1 限制

ADR-057: adopt() Gitea PR API 實作路徑 (草案，待批准)
  - 解決 API Pod git add -A 安全風險
  - PR review 流程保障

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-04-05 00:24:50 +08:00

2.4 KiB

Raw Blame History

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，存在：

安全風險: git add -A 可能誤提交 Secret/ConfigMap 等敏感資料
多副本問題: 多個 API Pod 同時執行 git 操作會造成 conflict
認證問題: API Pod 需要持有 Gitea 認證，擴大攻擊面
Bypass 審核: 直接 push main 繞過 PR review 流程

決策（草案）

D1: adopt() 端點改用 Gitea PR API

流程：

用戶按下 adopt → API 呼叫 Gitea API 建立 PR → SRE review → merge

具體實作：

API 呼叫 POST /api/v1/repos/{owner}/{repo}/pulls（Gitea API）
PR title: chore: adopt drift — {namespace} {summary}
PR body: 包含漂移詳情、Nemotron 意圖分析、影響評估
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 實作	⏳ 待批准後

2.4 KiB Raw Blame History Unescape Escape