よくある障害のトラブルシューティング
目的: 統合時によくある障害に対して、症状-原因-修正を厳密に示すこと。
障害マトリクス
| 症状 | 想定原因 | 修正 |
|---|---|---|
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 エンドポイントがない | DB 統合が無効 | DATABASE_URL を設定してサービスを再起動し、query ルートを有効化する |
クイック診断
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 の認証なし、無効認証、有効認証の挙動を検証します。