常見故障排除
目的：為常見整合失敗提供嚴格的「症狀-原因-修復」指引。
故障矩陣
| 症狀 | 可能原因 | 修復 |
|---|---|---|
POST /query 回傳 401（Missing bearer token） | 缺少 Authorization 標頭 | 從 auth 啟動流程送出 Authorization: Bearer <token> |
POST /query 回傳 401（Invalid token） | JWT 過期/無效，或 issuer/audience 不符 | 重新啟動權杖並確認 auth 設定（AUTH_ISSUER、AUTH_AUDIENCE、JWKS URL） |
POST /query 回傳 400（start_ts must be <= end_ts） | 請求本文時間範圍無效 | 確保 start_ts 小於或等於 end_ts |
POST /log 回傳 400/驗證錯誤 | 請求本文不是有效 JSON 物件 | 一律送出 JSON 本文（最少 {}） |
私有頻道寫入回傳 401 | 對受保護頻道未提供權杖 | 送出有效擁有者 Bearer 權杖 |
私有頻道讀寫回傳 404 | 帳戶與頻道擁有者不一致 | 使用 JWT acc 聲明相符的權杖 |
WebSocket 私有升級回傳 401 | 升級請求權杖缺失或無效 | 升級期間加入有效 Authorization 標頭 |
WebSocket 私有升級回傳 404 | 權杖 acc 與頻道擁有者不一致 | 改用擁有者帳戶權杖重新連線 |
POST /query 回傳空的 files | 範圍內無上傳檔案或篩選條件過窄 | 放寬範圍/篩選條件，並確認 uploader/compression worker 正在執行 |
OpenAPI 缺少 /query 端點 | 資料庫整合未啟用 | 設定 DATABASE_URL 並重啟服務以啟用查詢路由 |
快速診斷
JSONLOG_BASE_URL="http://localhost:3002"
curl -sS "${JSONLOG_BASE_URL}/health"
curl -sS "${JSONLOG_BASE_URL}/stats"
curl -sS "${JSONLOG_BASE_URL}/openapi.json" | jq '.paths | keys'腳本化 Auth 排查
cd jsonlog
set -a && source .env && set +a
npm run test:auth:smoke此 smoke 流程會驗證 /query 在無驗證、無效驗證與有效驗證下的行為。