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 台北時間）執行：

```bash
# 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 已執行）:
```bash
kubectl rollout restart deployment/{name} -n {namespace}
```

若自動修復失敗，手動 SOP：
```bash
# 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 修復：
```bash
ssh 192.168.0.188 'docker restart minio'
# 或
ssh 192.168.0.188 'docker ps | grep minio'  # 先確認狀態
```

手動 SOP：
```bash
# 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，但必須先確認：

```bash
# 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）

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

```bash
# 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 分鐘：

```bash
# 確認高耗 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）

```bash
# 確認哪個憑證快到期
# 通常是 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

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

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

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

---

## 5. Kill Switch — 緊急凍結

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

```bash
# 方法 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**:
```bash
curl -X DELETE http://192.168.0.188:8000/api/v1/kill-switch \
  -H 'Authorization: Bearer {ADMIN_TOKEN}'
```

---

## 6. SLO 監控與應對

### SLO 儀表板

```bash
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

```bash
# 查看所有 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 主機）

```bash
# 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

```bash
# 系統健康
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](~/.claude/projects/-Users-ogt-awoooi/memory/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 台北時間建立*