116 lines
4.7 KiB
Markdown
116 lines
4.7 KiB
Markdown
# ADR-013: AIOps 自動修復閉環架構
|
||
|
||
**狀態**: Accepted
|
||
**日期**: 2026-04-19
|
||
**提案者**: Antigravity
|
||
|
||
---
|
||
|
||
## 背景與問題
|
||
|
||
EwoooC 系統已有 L1 Hermes 告警派發，但告警只能「通知」，無法「自癒」。
|
||
當 `psycopg2.OperationalError: could not translate host name "momo-postgres"` 這類明確的基礎設施問題發生時，仍需人工 SSH 登入修復，缺乏自動化閉環。
|
||
|
||
---
|
||
|
||
## 決策
|
||
|
||
建立三層 AIOps 閉環架構：
|
||
|
||
```
|
||
Exception → Incident(DB) → PlayBook 匹配 → Auto-Heal 執行 → HealLog(DB) → KM 沉澱(ai_insights) → Telegram 通知
|
||
```
|
||
|
||
### 新增元件
|
||
|
||
| 元件 | 類型 | 說明 |
|
||
|------|------|------|
|
||
| `database/autoheal_models.py` | Model | Incident / Playbook / HealLog 三張表 |
|
||
| `migrations/013_autoheal.sql` | Migration | 建表 + 種子 PlayBook 植入 |
|
||
| `services/auto_heal_service.py` | Service | 核心引擎（分類、匹配、執行、沉澱） |
|
||
| `database/manager.py` | 修改 | 加入 `_init_autoheal_tables()` |
|
||
| `scheduler.py` | 修改 | 三個核心任務植入 `handle_exception` |
|
||
| `utils/ssh_helper.py` | Helper | 共用 CLI `ssh` 執行層，供 AutoHeal / AiderHeal 使用 |
|
||
|
||
### PlayBook 動作類型
|
||
|
||
| action_type | 說明 |
|
||
|---|---|
|
||
| `DOCKER_RESTART` | 透過 SSH 跳板 restart 指定容器 |
|
||
| `SSH_CMD` | 執行白名單內的任意 SSH 指令 |
|
||
| `ALERT_ONLY` | 僅發 Telegram 告警，人工介入 |
|
||
| `WAIT_RETRY` | 紀錄後等待排程重試 |
|
||
|
||
### 安全設計
|
||
|
||
- SSH 指令白名單：2026-04-29 起僅允許明確列入 allowlist 的 read-only 診斷指令；高副作用容器操作需走受控 PlayBook 與保護清單
|
||
- `momo-db` / `momo-postgres` 永遠是 protected resource，不得被自動 restart / stop / recreate
|
||
- DB / DNS 類離線 playbook 若無法安全修復，降級為 `ALERT_ONLY` 或 `WAIT_RETRY`
|
||
- 冷卻機制：同 PlayBook 在 `cooldown_min` 內不重複觸發
|
||
- 升級機制：達到 `max_retries` 後 incident.status = `escalated` 並通知人工
|
||
|
||
### KM 沉澱格式
|
||
|
||
每次修復後寫入 `ai_insights`：
|
||
- `insight_type = "auto_heal_playbook"`
|
||
- 包含事件、症狀、行動、結果、教訓五要素
|
||
- 自動排入 `embedding_retry_queue` 完成 RAG 向量化
|
||
|
||
---
|
||
|
||
## 取捨
|
||
|
||
2026-05-13 實作修訂：現行程式碼已標準化到 `utils/ssh_helper.py`，以 CLI `ssh` + `ProxyJump` 參數組裝執行，AutoHeal 與 AiderHeal 共用同一層；因此 `paramiko` 不再是 runtime 依賴。若未來要重新引入 Paramiko，必須同時補回 helper 實作、requirements 與回歸測試。
|
||
|
||
---
|
||
|
||
## 結果
|
||
|
||
- P1/P2 等級的 DB_UNREACHABLE / DNS_FAIL 類問題可在 30 秒內完成自動修復
|
||
- 所有修復知識自動沉澱至 RAG KM，提升未來 AI 的判斷品質
|
||
- 覆蓋任務：`run_auto_import_task` / `run_icaim_analysis_task` / `run_weekly_strategy_task`
|
||
|
||
---
|
||
|
||
## 部署後記（2026-04-19 實測）
|
||
|
||
### 踩坑修正（共 5 個 hotfix commit）
|
||
|
||
| 問題 | 原因 | 修正 |
|
||
|---|---|---|
|
||
| `UndefinedTable: playbooks` | 建表順序 `[Incident, Playbook, HealLog]` FK 衝突 | 改為 `[Playbook, Incident, HealLog]` |
|
||
| `DetachedInstanceError` HealLog/Incident | `commit()` expire_on_commit 後 lazy-load 失敗 | `session.refresh(obj); session.expunge(obj)` |
|
||
| `TypeError: NoneType:.0f` | fallback HealLog 缺 `duration_ms` | except 分支補 `duration_ms=duration_ms` |
|
||
| compose=True 雙重呼叫 bug | `_execute_playbook` 先呼叫 compose，馬上覆寫為 docker restart | 刪除 use_compose 分支 |
|
||
| `No authentication methods available` | paramiko 找不到 SSH key | key 複製至 `/app/config/autoheal_id_ed25519`（rw mount），不需重建容器 |
|
||
|
||
### SSH 認證鏈設定
|
||
|
||
```
|
||
momo-scheduler → id_ed25519 → 110 (wooo) → tunnel → 188 (ollama) → docker restart
|
||
```
|
||
|
||
`ollama@188` 的 `id_ed25519.pub` 已加入 `authorized_keys`（第 11 行）。
|
||
|
||
### 實測結果
|
||
|
||
```
|
||
result=success duration=3110ms # DNS_FAIL → docker restart momo-db 成功
|
||
```
|
||
|
||
heal_log 在 restart momo-db 後因 DB 瞬斷無法寫入 DB（id=7~9 遺失）屬設計邊界，Telegram 通知仍正常推播。
|
||
|
||
### 2026-04-29 安全修訂
|
||
|
||
上述 `DNS_FAIL → docker restart momo-db` 屬早期實測紀錄，現在不再允許作為自動修復策略。最新規則：
|
||
|
||
- `momo-db` / `momo-postgres` 是資料層 protected resource。
|
||
- AutoHeal 寫 DB 失敗時不可讓自癒流程 crash，需保留 Telegram / log / fallback 記錄。
|
||
- `CODE_FIX`、resource action 與 ElephantAlpha orchestration 必須橋接 AutoHeal，不得直接執行危險副作用。
|
||
- raw `ai_insights` 寫入後必須 enqueue embedding，讓自癒知識進入 RAG。
|
||
|
||
### 新增 DB 表
|
||
|
||
- `migrations/014_telegram_users.sql` — EventRouter 推播對象（替代 .env 硬編碼）
|
||
- 種子：`telegram_id=-1003940688311, is_admin=true`
|