496c569d51
- RED_ZONES.md: Tier 3/2 紅區清單 - setup-hooks.sh: Git Hook 安裝腳本 - infrastructure docs: 部署拓撲更新 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
260 lines
7.4 KiB
Markdown
260 lines
7.4 KiB
Markdown
# AWOOOI 紅區治理手冊
|
||
|
||
> 代碼防區化治理 (Codebase Zoning) 與爆炸半徑鎖死 (Blast Radius Containment)
|
||
|
||
---
|
||
|
||
## 文件資訊
|
||
|
||
| 欄位 | 值 |
|
||
|------|-----|
|
||
| **版本** | v1.0 |
|
||
| **建立日期** | 2026-03-26 12:30 (台北) |
|
||
| **建立者** | Claude Code |
|
||
| **最後修改** | 2026-03-26 12:30 (台北) |
|
||
| **修改者** | Claude Code |
|
||
| **審查週期** | 每月第一個週一 |
|
||
|
||
### 變更紀錄
|
||
|
||
| 版本 | 日期 | 執行者 | 變更內容 |
|
||
|------|------|--------|----------|
|
||
| v1.0 | 2026-03-26 | Claude Code | 初始建立 - 紅區治理機制 |
|
||
|
||
---
|
||
|
||
## 紅區分級定義
|
||
|
||
| 等級 | 名稱 | 圖示 | 定義 | 變更後果 |
|
||
|------|------|------|------|----------|
|
||
| **Tier 3** | 核心大腦 | 🔴 | AI 決策、狀態機、Multi-Sig | 系統決策失靈 |
|
||
| **Tier 2** | 基礎設施 | 🟠 | DB Schema、K8s、CI/CD | 部署/資料異常 |
|
||
| **Tier 1** | 業務邏輯 | 🟢 | API 路由、UI 組件 | 功能異常 (可快速修復) |
|
||
|
||
---
|
||
|
||
## Tier 3 紅區清單 (8 個檔案)
|
||
|
||
### 1. 決策狀態機
|
||
```
|
||
檔案: apps/api/src/services/decision_manager.py
|
||
功能: OpenClaw AI 的決策核心，控制 PENDING→APPROVED→EXECUTED 狀態流轉
|
||
影響:
|
||
- AI 無法做出決策
|
||
- 審批流程卡死
|
||
- 所有待處理告警無法推進
|
||
```
|
||
|
||
### 2. 信任評分引擎
|
||
```
|
||
檔案: apps/api/src/services/trust_engine.py
|
||
功能: 計算操作的信任分數，決定是否需要 Multi-Sig 審批
|
||
影響:
|
||
- 危險操作被自動執行 (信任分數錯誤)
|
||
- 低風險操作被過度審批
|
||
- Multi-Sig 機制失效
|
||
```
|
||
|
||
### 3. 共識引擎
|
||
```
|
||
檔案: apps/api/src/services/consensus_engine.py
|
||
功能: Multi-Sig 多方簽核邏輯，確保關鍵操作需多人同意
|
||
影響:
|
||
- 單點簽核繞過安全機制
|
||
- 審批人數計算錯誤
|
||
- 共識達成判斷失靈
|
||
```
|
||
|
||
### 4. 事件處理引擎
|
||
```
|
||
檔案: apps/api/src/services/incident_engine.py
|
||
功能: 告警接收、分類、派發的核心引擎
|
||
影響:
|
||
- 告警無法被接收
|
||
- 事件分類錯誤
|
||
- Telegram 通知失敗
|
||
```
|
||
|
||
### 5. 分散式鎖服務
|
||
```
|
||
檔案: apps/api/src/services/multi_sig_redis.py
|
||
功能: Redis 分散式鎖，防止併發競爭
|
||
影響:
|
||
- 同一事件被多次處理
|
||
- 死鎖導致系統卡死
|
||
- 資料不一致
|
||
```
|
||
|
||
### 6. 安全攔截器
|
||
```
|
||
檔案: apps/api/src/services/security_interceptor.py
|
||
功能: 權限驗證、危險操作攔截
|
||
影響:
|
||
- 權限繞過漏洞
|
||
- 危險操作未被攔截
|
||
- 安全審計失效
|
||
```
|
||
|
||
### 7. 環境配置中心
|
||
```
|
||
檔案: apps/api/src/core/config.py
|
||
功能: 所有服務的連線配置 (Redis/PostgreSQL/Ollama/Telegram)
|
||
影響:
|
||
- 所有外部連線中斷
|
||
- 服務無法啟動
|
||
- 環境變數解析失敗
|
||
```
|
||
|
||
### 8. OTEL 監控核心
|
||
```
|
||
檔案: apps/api/src/core/telemetry.py
|
||
功能: OpenTelemetry 追蹤與指標收集
|
||
影響:
|
||
- SignOz 無法收到追蹤數據
|
||
- 系統可觀測性失明
|
||
- 問題排查極度困難
|
||
```
|
||
|
||
---
|
||
|
||
## Tier 2 橙區清單
|
||
|
||
### K8s 正式環境
|
||
```
|
||
目錄: k8s/awoooi-prod/*.yaml
|
||
功能: Kubernetes 正式環境部署檔案
|
||
影響: 正式環境部署失敗、NetworkPolicy 錯誤
|
||
```
|
||
|
||
### 資料庫 Schema
|
||
```
|
||
檔案: apps/api/src/db/models.py
|
||
功能: SQLAlchemy ORM 模型定義
|
||
影響: 資料庫結構不一致、Migration 衝突
|
||
```
|
||
|
||
### CI/CD Pipeline
|
||
```
|
||
目錄: .github/workflows/*.yml
|
||
功能: GitHub Actions 自動化流程
|
||
影響: 自動部署中斷、可能產生帳單費用
|
||
```
|
||
|
||
### Redis 連線池
|
||
```
|
||
檔案: apps/api/src/core/redis_client.py
|
||
功能: Redis 連線管理與 Stream 操作
|
||
影響: 快取服務中斷、Worker 無法接收任務
|
||
```
|
||
|
||
### Telegram 閘道
|
||
```
|
||
檔案: apps/api/src/services/telegram_gateway.py
|
||
功能: Telegram Bot 訊息收發
|
||
影響: 告警通知無法送達、審批按鈕失效
|
||
```
|
||
|
||
---
|
||
|
||
## 🏛️ 首席架構師審查流程
|
||
|
||
### 警告觸發時
|
||
|
||
當 Git commit 觸及紅區/橙區檔案時，pre-commit hook 會顯示警告，並**強制啟動首席架構師審查流程**：
|
||
|
||
```
|
||
╔══════════════════════════════════════════════════════════════╗
|
||
║ 🔴 TIER 3 紅區變更警告 ║
|
||
╚══════════════════════════════════════════════════════════════╝
|
||
|
||
[Tier 3 紅區] 決策狀態機
|
||
功能: OpenClaw AI 的決策核心
|
||
影響: ...
|
||
|
||
╔══════════════════════════════════════════════════════════════╗
|
||
║ 🏛️ 首席架構師審查必要 ║
|
||
╠══════════════════════════════════════════════════════════════╣
|
||
║ 1. 停止 commit，呼叫首席架構師介入 ║
|
||
║ 2. 首席架構師進行架構與代碼 Review ║
|
||
║ 3. 確認變更必要性、影響範圍、替代方案 ║
|
||
║ 4. 首席架構師簽核後，方可繼續 ║
|
||
╚══════════════════════════════════════════════════════════════╝
|
||
```
|
||
|
||
### 首席架構師審查檢查項
|
||
|
||
| 項目 | 說明 |
|
||
|------|------|
|
||
| **變更必要性** | 為什麼需要修改此核心檔案？有無其他方案？ |
|
||
| **影響範圍** | 此變更會影響哪些上下游模組？ |
|
||
| **風險評估** | 最壞情況是什麼？如何緩解？ |
|
||
| **回滾計畫** | 若出問題，如何快速回滾？ |
|
||
| **測試覆蓋** | 是否有足夠的測試保護此變更？ |
|
||
|
||
### 首席架構師簽核格式
|
||
|
||
```markdown
|
||
## 🏛️ 首席架構師審查簽核
|
||
|
||
**審查時間**: 2026-03-26 13:00 (台北)
|
||
**審查者**: 首席架構師 / Claude Code
|
||
|
||
### 變更摘要
|
||
- 檔案: decision_manager.py
|
||
- 原因: [說明]
|
||
|
||
### 審查結論
|
||
- [x] 變更必要性確認
|
||
- [x] 影響範圍可控
|
||
- [x] 回滾計畫完備
|
||
- [x] 測試覆蓋充足
|
||
|
||
### 簽核結果
|
||
✅ **批准** - 可繼續 commit
|
||
```
|
||
|
||
### Claude Code 看到警告後必須
|
||
|
||
1. **立即停止自動 commit**
|
||
2. **呼叫首席架構師介入**
|
||
3. **首席架構師進行審查**:
|
||
- 變更必要性
|
||
- 影響範圍評估
|
||
- 替代方案評估
|
||
- 回滾計畫
|
||
4. **首席架構師簽核後**才能繼續 commit
|
||
|
||
---
|
||
|
||
## 定期審查機制
|
||
|
||
### 審查週期
|
||
|
||
| 項目 | 週期 | 負責人 | 下次審查 |
|
||
|------|------|--------|----------|
|
||
| **紅區清單** | **每週一** | 首席架構師 | 2026-03-31 |
|
||
| **Hook 腳本** | **每月第一個週一** | 首席架構師 | 2026-04-06 |
|
||
| 違規統計 | 每週一 | Claude Code | 2026-03-31 |
|
||
|
||
### 審查檢查項
|
||
|
||
- [ ] 是否有新的核心模組需要加入紅區？
|
||
- [ ] 是否有紅區檔案已重構/移除？
|
||
- [ ] Hook 警告訊息是否仍然準確？
|
||
- [ ] 是否有誤報需要調整？
|
||
|
||
### 更新流程
|
||
|
||
1. 修改 `scripts/hooks/pre-commit` 中的 `TIER3_ZONES` 或 `TIER2_ZONES`
|
||
2. 執行 `bash scripts/setup-hooks.sh` 重新安裝
|
||
3. 更新本文件 `docs/RED_ZONES.md`
|
||
4. 更新 Memory: `feedback_red_zone_governance.md`
|
||
|
||
---
|
||
|
||
## 相關文件
|
||
|
||
- [HARD_RULES.md](HARD_RULES.md) - 絕對禁止規則
|
||
- [CLAUDE.md](../CLAUDE.md) - AI 開發憲法
|
||
- [scripts/hooks/pre-commit](../scripts/hooks/pre-commit) - Hook 腳本
|