问题排查手册
排查的核心不是「读代码」，而是先把问题归位到某一层，再用最短路径证伪。本篇给出五类高频故障的定位路径。
0. 通用分层定位法
任何线上问题，先按这个顺序排除：
记住四层的顺序：网关 → 检测服务 → 策略 → checker。反向跳层排查（直接看规则）是最常见的时间浪费。
1. 现象：请求被拒绝 / 返回鉴权失败
| 检查项 | 位置 | 结论 |
|---|---|---|
| 签名是否有效 | 网关 PlatformSignService 校验逻辑 | 签名错误或时间戳超窗 → 客户端时钟/签名算法问题 |
| 令牌是否有效 | 网关 JwtExtPlugin | 令牌过期或已注销 → 重新签发 |
| URL 是否有功能权限 | 网关 FunctionPermissionCache | 权限缓存未刷新 → 查权限中心事件下发 |
| 路由是否存在 | ShenYu selector/rule 配置 | 规则未注册 → 检查服务是否成功注册元数据 |
判据
网关层拒绝的特征是「请求根本没进业务日志」。如果业务日志里有请求但结果异常，问题一定在网关之后。
2. 现象：规则命中但客户没被处置
按可能性从高到低：
- 规则是预上线状态：只产生试命中，不参与处置。查规则状态是否为
PRE_ONLINE。 - 命中的是试运行结果：响应组装只取正式命中（
hitFormalRules），试命中（hitTrailRules）仅在明细中可见。 - 策略集未包含该规则集：规则属于 A 规则集，但策略引用的是 B。查策略集的过程配置。
- 处置动作是异步的：加名单、点水任务、信用评分经 Kafka 异步执行，回包不含动作结果。查动作消费是否堆积。
- 客户侧未执行处置：回包给了动作，但客户端/服务端没有落地执行。
排查动作是否真的执行，看 Kafka 消费链路：规则命中 → 动作消息 → RuleActionConsumer → 名单库/点水服务。
3. 现象：误拦截 / 命中率异常升高
| 可能原因 | 定位方法 |
|---|---|
| 名单被批量误加 | 查名单来源分布：RULE_HIT（规则自动加）、OPEN_API_ADD（客户接口加）、人工导入；重点看规则自动加的名单项 |
| 规则条件被改 | 查规则操作日志（策略中心记录）与规则快照 |
| 预处理字段值错乱 | 查 trace 中 prepro.* 的实际取值与类型 |
| 指标口径变化 | 查指标窗口与过滤条件是否被修改，比对同期值 |
| 设备指纹找回错误 | 查 sid 来源：NEID / RULE / ES / NEW，找回策略命中异常会导致设备被错误合并 |
处理顺序：先止血再定位。止血手段是锁定规则或下线名单匹配器，而不是回滚整个策略集。
4. 现象：响应变慢 / 超时
各层的典型耗时特征：
| 层 | 特征 | 常见原因 |
|---|---|---|
| 网关 | 首包时间整体抬升 | 鉴权缓存失效导致回源、限流组件触发 |
| 检测服务 | P99 抖动但均值正常 | 单个 handler 链环节阻塞、线程池打满 |
| 策略执行 | 部分请求超时 | 单个策略集超时不降级、并发任务过多 |
| checker | 单次调用耗时高 | 预处理脚本执行慢（Groovy 超时 300ms）、名单缓存未命中、指标走异步 |
| 存储 | 回包后延迟 | Kafka 堆积、ES/HBase 写入变慢 |
关键判断：判定链路是同步的，落库链路是异步的。如果只有明细延迟而回包正常，问题在存储侧，不要动判定逻辑。
5. 现象：配置改了不生效
这是最高频的问题，统一按三步查：
分模块的具体检查点：
| 配置类型 | 生效路径 | 检查点 |
|---|---|---|
| 规则/规则集 | 管理端写库 → 缓存模块生成可执行模型 → 执行端每 120s 刷新 | 缓存服务是否生成新版本 |
| 名单 | 写库 → outbox 事件 → 增量同步任务写 Redis 分片 | generation 是否切换 |
| 指标 | 写库 → 本地缓存按 modify_time 增量刷新 | 缓存版本号 |
| 预处理 | 写库 → 本地缓存刷新 | 执行侧是否读到新配置 |
| 元数据字段 | 元数据中心 → 事件中台 → 各服务 meta-client 缓存 | 下游缓存最后同步时间 |
| 权限 | 控制台写库 → 事件中台 → 网关权限缓存 | 权限缓存是否更新 |
6. 现象：数据对不上（看板/报表）
| 差异表现 | 可能原因 |
|---|---|
| 明细有、看板无 | 入仓链路（Kafka → ClickHouse dwd）堆积或失败 |
| 看板有、明细无 | 看板走预聚合表 ads_*_view_all，与明细表口径不同 |
| 两边都少 | 上游根本没投递明细消息（判定被短路） |
| 时间维度错位 | 时区/窗口边界问题，注意统计口径是自然日还是滑动窗口 |
排查顺序：上游是否投递 → Kafka 是否有堆积 → 消费者是否写入成功 → 查询用的是哪张表。口径问题优先怀疑表的选择，而不是数据丢了。
7. 排查工具一览
| 想确认的事 | 看哪里 |
|---|---|
| 请求是否到达 | 网关访问日志、检测服务入口日志 |
| 走了哪些环节 | 链路 trace（检测上下文 resultStatus 与各 handler 标记） |
| 判定结果明细 | 检测明细（ES/ClickHouse）与命中记录 topic |
| 配置变更历史 | 各中台操作日志（@OperationLog 埋点） |
| 缓存是否最新 | 各服务缓存最后刷新时间、事件拉取游标 |
| 服务健康 | 各应用健康检查接口、QOS 端点 |
排查红线
线上排查时不要直接改数据库或手动清缓存。名单缓存有 generation 切换机制、规则缓存有版本校验，手工干预会破坏一致性，正确做法是走管理接口或等待对账任务。