awoooi/docs/operations/ON-CALL-HANDBOOK.md

AWOOOI On-Call 值班手冊（On-Call Handbook）

文件類型: 值班操作手冊
版本: v1.0
建立日期: 2026-04-14（台北時間）
建立者: Claude Sonnet 4.6（首席架構師）
適用對象: 統帥（首席）+ 未來 SRE 成員
相依文件: HUMAN-IN-THE-LOOP.md、SLO-SLI-DEFINITION.md、ALERT-TAXONOMY-CATALOG.md

---

0. 哲學：你是機長，AI 是副駕駛

AI 永遠可以被覆蓋，你永遠是最後決策者。

AWOOOI AIOps 系統設計為：

• 日常 P2/P3 告警 → AI 自動處理，你只需監控 Telegram 通知
• P0/P1 高風險告警 → AI 分析後送審，你做最終決定
• 系統失控時 → Kill Switch 一鍵凍結所有自動操作

值班的目標不是盯著告警，而是確保飛輪轉得順。

---

1. 值班前準備（Shift Start Checklist）

每天（建議 08:00 台北時間）執行：

# 1. 確認系統健康
curl -s http://192.168.0.188:8000/health | python3 -m json.tool

# 2. 確認 Alertmanager 正常
curl -s http://192.168.0.110:9093/api/v1/status

# 3. 確認昨日 SLO 數字
curl -s http://192.168.0.188:8000/api/v1/slo/dashboard

# 4. 確認 AI 模型可用
curl -s http://192.168.0.111:11434/api/tags | python3 -c "import json,sys; [print(m['name']) for m in json.load(sys.stdin)['models']]"

# 5. 看 Telegram #awoooi-alerts 頻道最近 12 小時的告警

每日晨報: AIOps 系統於 08:00 台北時間自動發送前 24 小時摘要至 Telegram

---

2. 告警分級處理矩陣

告警嚴重度 → 處理方式

嚴重度	P0 (CRITICAL)	P1 (HIGH)	P2 (MEDIUM)	P3 (LOW)
AI 處理	分析 + 送審	分析 + 送審	自動執行	自動執行
你的角色	必須審核	必須審核	監控結果	可忽略
SLA	15 分鐘內	30 分鐘內	無強制	無強制
若超時	自動升級通知	自動升級通知	自動重試	自動記錄

Telegram 卡片類型 → 你需要做什麼

卡片類型	外觀特徵	你的動作
TYPE-1 INFO	💚 INFO 開頭	無需動作，系統已自動記錄
TYPE-2 AUTO	⚡ AUTO REPAIR	觀察後續 RESULT 卡片即可
TYPE-3 REVIEW	🔴 NEEDS REVIEW + 按鈕	必須點擊 APPROVE 或 REJECT
TYPE-4 WAIT	⏸️ WAITING	人工評估後決定要不要手動修復
TYPE-8M SLO	📊 SLO ALERT	評估是否暫停自動修復

---

3. 高頻場景 SOP

3.1 Pod CrashLoopBackOff

Telegram 卡片: TYPE-2 或 TYPE-3（視 P 等級）

自動修復路徑（AI 已執行）:

kubectl rollout restart deployment/{name} -n {namespace}

若自動修復失敗，手動 SOP：

# 1. 查看 Pod 日誌
kubectl logs {pod-name} -n {namespace} --previous --tail=100

# 2. 確認 Pod 狀態
kubectl describe pod {pod-name} -n {namespace}

# 3. 手動重啟
kubectl rollout restart deployment/{name} -n {namespace}

# 4. 確認恢復
kubectl rollout status deployment/{name} -n {namespace}

---

3.2 MinIO 下線（或其他 188 主機上的 Docker 服務）

Telegram 卡片: TYPE-3（P1，需審核）

AI 建議的 SSH 修復：

ssh 192.168.0.188 'docker restart minio'
# 或
ssh 192.168.0.188 'docker ps | grep minio'  # 先確認狀態

手動 SOP：

# 1. 確認 188 主機可達
ping 192.168.0.188

# 2. SSH 進入主機
ssh 192.168.0.188

# 3. 確認容器狀態
docker ps -a | grep minio

# 4. 重啟容器
docker restart minio

# 5. 確認恢復
docker logs minio --tail=20
curl -s http://localhost:9000/minio/health/live

⚠️ 禁止: systemctl restart docker（會殺死 Gitea 等所有容器）

---

3.3 PostgreSQL 下線

Telegram 卡片: TYPE-3（CRITICAL，必須審核）

AI 會建議 kubectl rollout restart，但必須先確認：

# 1. 確認是服務問題還是 Pod 問題
kubectl get pods -n awoooi-prod | grep postgres

# 2. 若 Pod 崩潰 → 重啟
kubectl rollout restart deployment/postgresql -n awoooi-prod

# 3. 若 PVC 問題 → 不可自動處理，聯絡統帥
kubectl describe pvc postgres-pvc -n awoooi-prod

# 4. 確認 DB 可用
kubectl exec -n awoooi-prod deployment/postgresql -- psql -U postgres -c 'SELECT 1;'

資料風險提示: PostgreSQL 問題涉及持久化資料，kubectl delete pvc 被系統永久阻擋

---

3.4 告警鏈路斷裂（NoAlertsReceived2Hours）

這是最嚴重的情況：你看不到告警 = 系統失明

# 1. 確認 Alertmanager
curl http://192.168.0.110:9093/api/v1/status
curl http://192.168.0.110:9093/api/v1/alerts

# 2. 確認 AWOOOI API
curl http://192.168.0.188:8000/webhooks/test

# 3. 確認 Watchdog 心跳
# Watchdog 每分鐘送一個告警，若 2 小時沒收到 → 觸發此規則

# 4. 手動測試告警鏈路
curl -X POST http://192.168.0.110:9093/api/v1/alerts \
  -H 'Content-Type: application/json' \
  -d '[{"labels":{"alertname":"ManualTest","severity":"info"},"annotations":{"summary":"Manual test"}}]'

---

3.5 HostHighCpuLoad

Telegram 卡片: TYPE-1（INFO，系統自動記錄）

通常不需動作。若持續 > 30 分鐘：

# 確認高耗 CPU 程序
ssh 192.168.0.{110/120/121/188} 'top -bn1 | head -20'

# 若是 Ollama 模型推理（正常，等它結束）
ssh 192.168.0.188 'ps aux | grep ollama'

---

3.6 SSL 憑證到期告警

Telegram 卡片: TYPE-1（INFO）

# 確認哪個憑證快到期
# 通常是 Let's Encrypt 憑證需要 renew

# 若在 K8s 中由 cert-manager 管理
kubectl get certificates -A
kubectl describe certificate {cert-name} -n {namespace}

# 手動 renew（若 cert-manager 沒自動處理）
kubectl delete secret {tls-secret-name} -n {namespace}  # 觸發重新申請

---

4. 審核決策指南（APPROVE / REJECT）

在 Telegram 收到 TYPE-3 審核卡時：

應 APPROVE 的情況

• AI 信心度 > 0.80，且 kubectl 指令是 rollout restart / scale --replicas>0
• 你已確認症狀與 AI 診斷吻合
• 修復操作是可回滾的（rollout restart 可 rollout undo）
• 這是已知的重複故障，上次 Playbook 記錄過

應 REJECT 的情況

• AI 信心度 < 0.65（系統通常會標記 LOW CONFIDENCE）
• kubectl 指令包含不熟悉的資源名稱（可能是 LLM 幻覺）
• 時機不對（業務高峰期，即使必要也要評估）
• 你懷疑這是誤報

REJECT 後手動 SOP

# 1. 確認實際狀態
kubectl get pods -n {namespace}
kubectl logs {pod-name} -n {namespace} --tail=50

# 2. 若確認需要修復，手動執行
{manual command}

# 3. 在 Telegram 回覆告知已手動處理

---

5. Kill Switch — 緊急凍結

當你判斷 AI 系統行為異常（瘋狂重啟、錯誤修復），立即啟動：

# 方法 1：API Kill Switch（推薦）
curl -X POST http://192.168.0.188:8000/api/v1/kill-switch \
  -H 'Authorization: Bearer {ADMIN_TOKEN}' \
  -d '{"reason": "異常行為觀察到，手動凍結"}'

# 方法 2：直接修改 ConfigMap
kubectl set env deployment/awoooi-api AUTO_REPAIR_ENABLED=false -n awoooi-prod
kubectl rollout restart deployment/awoooi-api -n awoooi-prod

Kill Switch 效果: 所有 auto_repair 自動執行停止；TYPE-3 卡片不再自動批准；仍可手動操作

重新啟動 Kill Switch:

curl -X DELETE http://192.168.0.188:8000/api/v1/kill-switch \
  -H 'Authorization: Bearer {ADMIN_TOKEN}'

---

6. SLO 監控與應對

SLO 儀表板

curl -s http://192.168.0.188:8000/api/v1/slo/dashboard | python3 -m json.tool

SLO 閾值與應對

SLO	指標	目標	警戒線	緊急線	應對
SLO-1	自動修復成功率（7天）	≥ 80%	< 80%	< 50%	HITL-8：評估暫停自動修復
SLO-2	告警分析延遲 P95	< 20s	> 20s	> 30s	檢查 LLM / 切 Expert System
SLO-3	決策引擎可用性	≥ 95%	< 95%	< 80%	確認 Ollama + Gemini 狀態
SLO-4	未解決 P0/P1 逾時	0 件	> 0	> 2	立即介入

SLO-1 下降處理

若 SLO-1 < 80%：

1. 分析最近失敗的修復：SELECT * FROM approval_requests WHERE execution_success=false ORDER BY created_at DESC LIMIT 20;
2. 確認是新類型告警（知識庫沒有）還是已知告警修復失敗
3. 若是系統性問題 → 暫停自動修復，人工介入
4. 更新 docs/postmortems/ 記錄分析結果

---

7. 常用指令速查

Kubernetes

# 查看所有 Pod 狀態
kubectl get pods -n awoooi-prod

# 查看 Pod 日誌（最近 100 行）
kubectl logs {pod-name} -n awoooi-prod --tail=100

# 查看 Pod 日誌（上一個 Pod，崩潰後）
kubectl logs {pod-name} -n awoooi-prod --previous --tail=100

# 重啟 Deployment
kubectl rollout restart deployment/{name} -n awoooi-prod

# 查看 Deployment 狀態
kubectl rollout status deployment/{name} -n awoooi-prod

# 查看節點狀態
kubectl get nodes -o wide

# 查看所有資源
kubectl get all -n awoooi-prod

Docker（188 主機）

# SSH 進入 188
ssh 192.168.0.188

# 查看所有容器
docker ps -a

# 重啟特定容器
docker restart {container_name}

# 查看容器日誌
docker logs {container_name} --tail=100 -f

# 查看容器狀態
docker inspect {container_name} | python3 -m json.tool

AIOps API

# 系統健康
curl http://192.168.0.188:8000/health

# 最近 Incident 列表
curl http://192.168.0.188:8000/api/v1/incidents?limit=20

# SLO 儀表板
curl http://192.168.0.188:8000/api/v1/slo/dashboard

# 知識庫搜尋
curl "http://192.168.0.188:8000/api/v1/knowledge?q=minio+restart"

---

8. 主機快速參考

主機	IP	主要服務	SSH
主控節點	192.168.0.110	K3s Master, Prometheus, Alertmanager	ssh 192.168.0.110
工作節點-1	192.168.0.120	K3s Worker	ssh 192.168.0.120
工作節點-2	192.168.0.121	K3s Worker, Kali	ssh 192.168.0.121
AI 主機	192.168.0.188	Ollama, Harbor, Gitea, MinIO, AWOOOI	ssh 192.168.0.188

詳細 Port 分配 → reference_four_hosts.md

---

9. 升級聯絡矩陣

目前系統為統帥單人值班；未來擴展 SRE 團隊時使用

情況	聯絡對象	方式	優先度
P0 持續 > 15min	統帥	Telegram 直接訊息	立即
SLO-1 < 50%	統帥	Telegram #awoooi-alerts	15min 內
Kill Switch 啟動	統帥	Telegram 直接訊息	立即
疑似資安事件	統帥	電話	立即

---

10. 值班後交接（Shift End Checklist）

□ 所有 TYPE-3 卡片已處理（APPROVE/REJECT）
□ 未解決 Incident 已記錄在 LOGBOOK.md
□ SLO-1 在 80% 以上（若低於 80% 記錄原因）
□ 若觸發了 Kill Switch，已確認原因並重啟或記錄保持凍結的理由
□ 有意義的新故障 → 撰寫 Postmortem（使用 docs/templates/POSTMORTEM-TEMPLATE.md）
□ 更新 docs/LOGBOOK.md 今日條目

---

附錄 A：事件等級速查

等級	Severity	定義	典型案例
P0	CRITICAL	服務完全中斷，用戶無法使用	DB 下線、K8s 節點故障
P1	HIGH	核心功能受損，影響大多數用戶	MinIO 下線、OpenClaw 下線
P2	MEDIUM	部分功能受影響，有降級措施	Pod CrashLoop、SSL 到期
P3	LOW	輕微問題，無直接用戶影響	CPU 高負載、備份失敗

---

附錄 B：相關文件索引

文件	路徑	說明
HITL 規格書	docs/operations/HUMAN-IN-THE-LOOP.md	人工介入完整規格
SLO 定義	docs/slo/SLO-SLI-DEFINITION.md	SLO/SLI 量化定義
告警目錄	docs/reference/ALERT-TAXONOMY-CATALOG.md	告警分類完整列表
事後分析模板	docs/templates/POSTMORTEM-TEMPLATE.md	Postmortem 標準格式
AI 模型卡片	docs/ai/AI-MODEL-CARDS.md	各 AI 模型治理規格
服務端點	docs/reference/SERVICE-ENDPOINTS.md	所有服務 URL/Port
K3s 優化手冊	docs/runbooks/K3S-OPTIMIZATION-RUNBOOK.md	節點調優 SOP
飛輪鐵律	memory/feedback_auto_repair_flywheel_v2.md	ADR-068 五根因鐵律

---

本文件由 Claude Sonnet 4.6 於 2026-04-14 台北時間建立