故障排查（Troubleshooting）
上报失败、数据看不到、自托管实例异常——按本页「症状 → 原因 → 解决」自助定位。 平台级值班/SRE 排障见内部 on-call runbook ，本页面向 SDK 接入开发者 + 自托管运维。
先跑这一步：自托管实例用 argus-doctor 一键巡检；SDK 接入先核对下方「快速自查清单」。
快速自查清单
上报失败时，按顺序排查：
时钟
服务端要求上报请求的时间戳在 ±5 分钟（300 秒）窗口内。客户端/SDK 运行环境时钟漂移超过 5 分钟会被拒（invalid_timestamp）。用 NTP 同步系统时钟。
DSN
从 Console 项目设置复制完整 DSN，核对格式 argus://PUBLIC_KEY:SECRET_KEY@HOST/PROJECT_ID。确认 SECRET_KEY 未被改动，且从不出现在浏览器/客户端可见处（见 DSN & HMAC）。
网络可达
确认上报端点可达（Cloud 见 Console；本地默认 localhost:4318）。自托管确认 ingestion 服务在跑：docker ps | grep ingestion 或 kubectl get pod -l app=ingestion。
自托管巡检
argus-doctor # 人类可读巡检
argus-doctor --json # 供脚本消费SDK 上报错误码速查
ingestion 鉴权失败时返回结构化错误码。对照排查：
| HTTP | 错误码 | 原因 | 解决 |
|---|---|---|---|
| 400 | missing_header:X-Argus-DSN / missing_header:X-Argus-Timestamp | 缺必需请求头（SDK 初始化异常或版本过旧） | 升级 SDK；确认 DSN 字符串完整 |
| 401 | invalid_dsn | X-Argus-DSN 的 public key 与项目 DSN 不匹配 | 从 Console 重新复制 DSN，核对 public key |
| 401 | invalid_timestamp | 时间戳格式错，或超 ±5 分钟窗口（时钟漂移最常见） | NTP 同步时钟；确认 X-Argus-Timestamp 是 epoch 秒（不是毫秒） |
| 401 | invalid_signature | HMAC-SHA256 签名校验失败（secret key 错或请求被改） | 核对 secret key；勿在传输中改动 body |
| 403 | origin_not_allowed | Web SDK 域名白名单拒绝（即使 secret 泄露，未授权域名也无法伪造上报） | 在 Console 项目 Key 配置把该域名加入白名单；本地测试加 localhost |
| 413 | payload_too_large | 单次 batch 超过 16 MiB 上限（防内存炸弹） | 减小单次事件数 / 缩短 flush 间隔（SDK 会自动拆包重试） |
| 429 | quota_exceeded（带 Retry-After） | 当月事件配额用尽 | 见下方配额超限 |
最常见的坑：X-Argus-Timestamp 用了毫秒而非秒，或客户端时钟漂移 > 5 分钟 → 一律 invalid_timestamp。先查时钟。
配额超限 (429)
返回 429 quota_exceeded + Retry-After: <秒> 头表示当月事件配额用尽：
- 查用量：Console Dashboard → 当月 Usage（log / crash / apm / track / feedback / trace 全部计入）。
- 升级套餐：Pro / Team / Business 各有更高额度。
- 降用量：SDK 端降低采样率（详见各端 SDK 自保护配置）。
- 等重置：Free 档月底自动重置；
Retry-After指示下次可重试的秒数。
上报返回 200 但 Console 看不到数据
事件从 SDK 到可见要走 SDK → ingestion → ClickHouse → Console 四段，逐段排查：
| 环节 | 检查 | 常见断点 |
|---|---|---|
| ① SDK → ingestion | 上报 HTTP 状态、请求头、签名 | 401/403/413（见上）、429 配额（被静默丢弃前会返错误码，留意 SDK 内部日志） |
| ② ingestion | 服务可用 + 能写 ClickHouse | 自托管：argus-doctor 看 ingestion /readyz、ClickHouse 是否可达/磁盘满 |
| ③ ClickHouse | 事件是否落库 | 自托管可直查：SELECT count() FROM events_log WHERE project_id='你的项目' |
| ④ Console 查询 | 过滤条件 | project_id 不匹配（DSN 末尾与 Console 项目不一致）、查询时间范围设错、按 user_id 过滤但事件未携带该字段、channel 拼写错被跳过 |
最常见的「看不到」其实是 ④ 的过滤陷阱：上报用的 project_id 与你在 Console 看的项目不是同一个，或查询时间窗口没覆盖事件时间。
自托管部署故障
argus-doctor 输出解读
argus-doctor 巡检各微服务 /readyz + 基础设施（PostgreSQL / ClickHouse / Redis / MinIO）+ EE License + TLS 证书有效期，输出 [OK]/[WARN]/[FAIL] + 修复建议，退出码 0 健康 / 1 有致命问题。
| 检查项 | FAIL 常因 | 修复 |
|---|---|---|
微服务 /readyz | 依赖（PG/CH/Redis）不可达 | 看该服务日志；确认依赖容器启动 |
| PostgreSQL | 容器未起 / 密码错 / 网络 | 查 PG 日志；核对连接串 |
| ClickHouse | 容器未起 / 磁盘满 | df -h；清理过期数据（TTL）或扩容磁盘 |
| Redis / MinIO | 容器未起 | redis-cli ping / 查 MinIO 健康端点 |
| License (EE) | 过期 / 无效 / 时钟漂移 | 同步时钟；更新 License 文件 |
| TLS 证书 | 将过期（不足 7 天）/已过期 | 续期/轮换证书后重载网关 |
| 备份新鲜度 | cron 未执行 / 目标不可达 | 查 cron 与备份脚本日志（见 infra/deploy/README.md） |
聚合健康端点
监控系统可轮询 api-gateway 的聚合健康端点（汇总各服务 + 基础设施），非健康返回 503，适合做容器编排 liveness probe。详见自托管文档 。
FAQ
Q：时间戳为什么要用秒不是毫秒？ X-Argus-Timestamp 是 epoch 秒，服务端按 ±5 分钟窗口校验防重放。用毫秒会被判超窗口 → invalid_timestamp。
Q：secret key 能放前端吗？ 不能。端 SDK 的 secret 用于 HMAC 签名，必须只存在受控环境；Web 场景额外用域名白名单兜底（即使 secret 泄露，未授权域名也无法伪造上报）。
Q：怎么降低事件用量？ SDK 端调采样率 + 合理设置 flush 批量；崩溃等关键诊断事件优先级最高。
Q：离线/air-gapped 怎么部署？ 见自托管文档 的离线安装与 License 离线激活。
仍未解决？带上错误码 + argus-doctor --json 输出 + 复现步骤联系技术支持。