常见故障排查
目的：为常见集成失败提供严格的“症状-原因-修复”指导。
故障矩阵
| 症状 | 可能原因 | 修复 |
|---|---|---|
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 在无认证、无效认证和有效认证下的行为。