awoooi/docs/runbooks/RUNBOOK-PHASE-D-SENTRY-COMMENT.md

RunBook: Phase D — Sentry Comment 回寫啟動指南

類型: 操作型 RunBook
優先級: 🔴 P0（功能框架已建，只缺 Token 配置）
建立: 2026-03-29 12:35 (台北)
建立者: Antigravity
工時預估: 1.5–2 小時
前置條件: AWOOOI API 正常運行 (/api/v1/health 返回 200)

---

背景與現況

🔍 精確現況診斷

sentry_webhook.py 的 post_sentry_comment() 函式已實作完整邏輯：

sentry_webhook.py:251  → 呼叫 post_sentry_comment()
sentry_service.py:206  → post_issue_comment() 已實作 POST /api/0/issues/{id}/comments/
sentry_service.py:223  → 若 SENTRY_AUTH_TOKEN 為空，直接 return None 並 warning

唯一阻塞點：settings.SENTRY_AUTH_TOKEN 環境變數未設定，導致 comment 靜默跳過。

資料流確認

Sentry Issue 觸發
    ↓
/api/v1/webhooks/sentry/error  (sentry_webhook.py)
    ↓
analyze_and_comment() [Background Task]
    ↓
call_openclaw_analyzer()    → OpenClaw AI 分析
    ↓
create_sentry_approval()    → 建立 Approval ✅ 已運作
    ↓
send_sentry_telegram_alert()→ Telegram 通知 ✅ 已運作
    ↓
post_sentry_comment()       → ❌ SENTRY_AUTH_TOKEN 缺失，靜默跳過

---

Step 1: 取得 Sentry API Token

1.1 登入 Sentry 後台

瀏覽器開啟：http://192.168.0.110:9000
帳號：參見 docs/security/SECRETS_REFERENCE.md

1.2 建立 API Token

路徑：設定 → API → Auth Tokens → Create New Token

權限設定：
☑ project:read
☑ project:write
☑ issues:write    ← 必須勾選，否則無法回寫 comment
☑ event:read

Token 名稱建議：awoooi-openclaw-comment-writer

1.3 記錄 Token（請勿存入代碼庫！）

# 暫存到環境變數（本機測試用）
export SENTRY_AUTH_TOKEN="sentry_xxx..."

# 驗證 Token 有效性
curl -s http://192.168.0.110:9000/api/0/organizations/ \
  -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" | python3 -m json.tool | head -20
# 預期看到 organization 列表，無 401

---

Step 2: 注入 GitHub Secrets（CD 自動化）

2.1 加入 GitHub Repository Secrets

路徑：GitHub → owenhytsai/awoooi → Settings → Secrets → Actions

新增以下 Secrets：
名稱：SENTRY_AUTH_TOKEN
值：步驟 1.2 取得的 Token

2.2 更新 K8s Secret（手動注入生產環境）

# 在 192.168.0.120（K3s Master）執行
kubectl patch secret awoooi-secrets -n awoooi-prod \
  --patch="{\"data\":{\"SENTRY_AUTH_TOKEN\":\"$(echo -n 'YOUR_TOKEN' | base64)\"}}"

# 驗證
kubectl get secret awoooi-secrets -n awoooi-prod -o jsonpath='{.data.SENTRY_AUTH_TOKEN}' | base64 -d

2.3 更新 k8s/awoooi-prod/03-secrets.yaml（模板）

# k8s/awoooi-prod/03-secrets.yaml
# 新增以下欄位（使用 CD 自動注入，非硬編碼）
stringData:
  # ... 現有欄位 ...
  SENTRY_AUTH_TOKEN: "${SENTRY_AUTH_TOKEN}"  # CD 自動注入

---

Step 3: 更新 CD Workflow 自動注入

# .github/workflows/cd.yaml
# 在 "Inject K8s Secrets" 步驟中新增 SENTRY_AUTH_TOKEN

- name: Inject K8s Secrets
  run: |
    kubectl patch secret awoooi-secrets -n awoooi-prod \
      --patch="{\"data\":{
        \"OPENCLAW_TG_BOT_TOKEN\":\"$(echo -n '${{ secrets.OPENCLAW_TG_BOT_TOKEN }}' | base64)\",
        \"OPENCLAW_TG_CHAT_ID\":\"$(echo -n '${{ secrets.OPENCLAW_TG_CHAT_ID }}' | base64)\",
        \"SENTRY_AUTH_TOKEN\":\"$(echo -n '${{ secrets.SENTRY_AUTH_TOKEN }}' | base64)\"
      }}"

---

Step 4: 驗證 Sentry Comment 功能

4.1 本地單元測試（快速驗證）

cd /Users/ogt/awoooi
source .env

# 設定測試 Token
export SENTRY_AUTH_TOKEN="你的真實 Token"
export SENTRY_SELF_HOSTED_URL="http://192.168.0.110:9000"

# 用 Python 直接測試 SentryService
python3 -c "
import asyncio
import sys
sys.path.insert(0, 'apps/api/src')
from services.sentry_service import SentryService

async def test():
    svc = SentryService(
        base_url='http://192.168.0.110:9000',
        auth_token='$SENTRY_AUTH_TOKEN'
    )
    # 先列出 Issues 找一個真實 ID
    issues = await svc.list_issues(project='awoooi-api', limit=3)
    if issues:
        issue_id = issues[0]['id']
        print(f'找到 Issue: {issue_id}')
        result = await svc.post_issue_comment(
            issue_id=issue_id,
            text='🤖 **AWOOOI 測試** - Sentry Comment 回寫功能正常運作。'
        )
        print(f'Comment 結果: {result}')
    else:
        print('無 Issue 可測試')

asyncio.run(test())
"

4.2 E2E 端對端驗證（生產環境）

# 1. 在 Sentry 手動觸發一個測試 Issue
curl -X POST http://localhost:8000/api/v1/webhooks/sentry/error \
  -H "Content-Type: application/json" \
  -d '{
    "action": "triggered",
    "data": {
      "issue": {
        "id": "TEST-001",
        "title": "AWOOOI Comment 功能測試",
        "level": "error",
        "culprit": "test.py:1",
        "firstSeen": "2026-03-29T12:00:00Z",
        "count": 1,
        "project": {"slug": "awoooi-api"}
      },
      "event": {
        "message": "這是一個測試錯誤",
        "platform": "python"
      }
    }
  }'

# 預期回應
# {"status": "accepted", "issue_id": "TEST-001", "message": "Analysis scheduled"}

# 2. 等待 60 秒後（OpenClaw 分析需時）
sleep 60

# 3. 到 Sentry UI 的 Issue 中確認是否有 AI 分析 Comment
# http://192.168.0.110:9000/organizations/sentry/issues/TEST-001/

4.3 確認日誌

# 查看 API Pod 日誌
kubectl logs -n awoooi-prod \
  $(kubectl get pod -n awoooi-prod -l app=awoooi-api -o name | head -1) \
  --tail=50 | grep -i sentry_comment

# 預期看到
# sentry_comment_posted  issue_id=xxx  comment_id=12345

---

Step 5: 部署與驗收

# 觸發 CD
git add k8s/awoooi-prod/03-secrets.yaml .github/workflows/cd.yaml
git commit -m "feat(sentry): enable comment write-back via SENTRY_AUTH_TOKEN injection"
git push origin main

# 確認 CD 成功
gh run list --workflow=cd.yaml --limit 1

# 確認 Pod 有新 Token
kubectl exec -n awoooi-prod \
  $(kubectl get pod -n awoooi-prod -l app=awoooi-api -o name | head -1) \
  -- env | grep SENTRY_AUTH_TOKEN

---

驗收標準

項目	通過條件
K8s Secret 已注入	kubectl get secret 確認 SENTRY_AUTH_TOKEN 不為空
Token 有效	Sentry API /api/0/organizations/ 返回 200
Comment 回寫	Sentry Issue 中有「AI 錯誤分析」Comment
日誌正常	sentry_comment_posted 日誌出現，無 sentry_comment_failed
頻率統計	Comment 含「頻率統計」表格（24h 次數 > 1 時顯示）

---

常見問題排除

症狀	診斷指令	解法
sentry_comment_skipped 日誌	env | grep SENTRY_AUTH_TOKEN	Secret 未注入，重跑 Step 3
sentry_api_unauthorized	手動 curl Sentry API	Token 權限不足，重新建立
sentry_api_timeout	curl -v http://192.168.0.110:9000/	Sentry 服務本身異常
OpenClaw 分析失敗	curl http://192.168.0.188:8089/health	OpenClaw 服務需重啟