设备指纹（yidun-device-fingerpint）
回答一个基础问题：这是不是同一台设备？ 答案是一个稳定 ID ——
sid。
目录名说明
源码目录是 yidun-device-fingerpint（历史拼写漏了 f），产品和注释中一律叫「设备指纹 / Device Fingerprint」。
1. 业务定位
客户端 SDK 采集数百维设备信息（系统、硬件、应用、网络、模拟器与改机特征），服务端据此：
- 为每台真实设备签发全局稳定的
sid； - 同一台物理设备多次上报时召回同一个 sid。
这两件事决定了风控能否做设备维度判定。sid 召回不一致的后果很直接：同一设备被识别成多台 → 放行黑产；不同设备被合并 → 误伤正常用户。
2. 部署形态
| 部署单元 | 说明 |
|---|---|
facade/upload-http | 上传接入，需外网（客户端 SDK 调用 /v1/ad/d 等） |
facade/query-http | 查询服务，服务端访问，无需外网 |
facade/innerapi | 内部服务接口 |
mq/storage | Kafka 异步消费持久化 |
scheduler | 统计与计费定时任务 |
console/backend | 管理后台 |
分层：upload-http → service/business（找回、风控、脚本校验）→ service/base（DAO/缓存/存储）→ mq/storage + scheduler。
3. 核心链路
sid 来源四类（SidFromEnum），可信度与优先级由检索规则决定：
| 来源 | 含义 |
|---|---|
NEID | 本地 neid 索引直接找回，最快 |
RULE | 字段匹配规则找回 |
ES | 向量相似度找回，适合改机场景 |
NEW | 新设备签发 |
4. 关键数据模型
| 对象 | 说明 |
|---|---|
RetrievalRule / 检索规则集 | 决定找回顺序与判定条件 |
VerificationRule | 验证脚本，异步校验上报真实性 |
DeviceVec | 平台设备向量抽象 |
| 设备黑名单 | DeviceIdBlack，按 sid 拦截 |
| SDK 配置 | 各端版本与能力开关 |
5. 存储与中间件
| 组件 | 存储内容 |
|---|---|
| MySQL | 配置、规则、产品、账户、计费 |
| HBase | 设备明细（宽表，写多读少） |
| Redis | 实时名单、计数、nonce 防重放 |
| Elasticsearch | 设备向量与 sid 索引（rule/neid/vector） |
| Kafka | 上报明细异步落库 |
| NOS | 大字段与附件 |
6. 加解密与协议
上传报文支持多版本协议：P1/P2/P3、WAES、RSA、AES、XOR，由 CryptoRouter 路由到对应实现（如 NisCryptoImplV200）。protobuf 定义集中在 AndroidFingerPrint.proto、EncryptMsg.proto。
改动协议意味着 SDK 与服务端必须同步发版，且要兼容存量 SDK 版本。
7. 设计模式与扩展点
| 扩展点 | 位置 | 说明 |
|---|---|---|
| 平台差异 | SDKType + DeviceVec | 新增端类型实现对应向量与解析 |
| 找回策略 | retrieve 包（neid/rule/vector 三路） | 调整找回顺序与阈值 |
| 加密协议 | CryptoRouter + NisCryptoImplV* | 新增协议版本 |
| 验证脚本 | AsyncScriptValidator | 异步真实性校验 |
8. 上下游依赖
| 方向 | 模块 | 说明 |
|---|---|---|
| 上游 | 各端 SDK | 上报加密设备数据 |
| 上游 | mplatform-strategy、intelligent-risk | 查询设备画像 |
| 下游 | mplatform-business | 产品与套餐、计费 |
| 下游 | checker-preprocess | 设备维度预处理配置 |
| 下游 | mplatform-clickhouse | 设备统计入仓 |
| 下游 | mplatform-event | 配置变更事件 |
9. 工程约束与变更红线
- 主流程只做解析/找回/风控/返回，明细落库全走 Kafka，禁止同步写存储。
- nonce 防重放必须生效，否则重放报文会污染设备数据。
- 检索规则索引不可随意删除：rule/neid/vector 索引缺失会直接降低找回率。
- 协议变更必须双向兼容：存量 SDK 仍在用旧版本。
- sid 一旦签发不可复用：错误合并设备是数据事故，无法简单回滚。
10. 关键代码索引
| 主题 | 路径 | 说明 |
|---|---|---|
| 上传入口 | yidun-device-fingerpint/facade/upload-http/src/main/java/.../controller/AndroidUploadController.java | 上报接口 |
| 主流程 | yidun-device-fingerpint/facade/upload-http/src/main/java/.../DeviceInboundServiceImpl.java | innerProcess 全流程 |
| sid 找回 | yidun-device-fingerpint/service/business/src/main/java/.../retrieve/ | neid/rule/vector 三路 |
| 检索规则 | yidun-device-fingerpint/service/business/src/main/java/.../retrievalrule/ | 规则加载与执行 |
| 加解密路由 | yidun-device-fingerpint/crypto/src/main/java/.../CryptoRouter.java | 多版本协议 |
| 异步落库 | yidun-device-fingerpint/mq/storage/src/main/java/.../DeviceDataRecordConsumer.java | Kafka 消费 |
| 查询服务 | yidun-device-fingerpint/facade/query-http/src/main/java/.../QueryDeviceController.java | 设备查询 |
11. 排查要点
| 现象 | 定位 | 结论 |
|---|---|---|
| 同一设备拿到不同 sid | 看 sid 来源与检索规则命中 | 多为 NEID 未命中、规则阈值过严、ES 索引缺失 |
| 不同设备被合并 | 看规则条件与向量阈值 | 规则过宽，需收紧 |
| 上报成功但查不到设备 | 看 Kafka 消费与 HBase 写入 | 异步落库堆积，与上传链路无关 |
| 上报大量解密失败 | 看协议版本与密钥配置 | SDK 版本与服务端协议不匹配 |
| 找回率下降 | 看索引健康与规则发布记录 | 索引重建或规则调整导致 |
排查顺序
设备问题先看 sid 来源分布，再看 检索规则，最后才看存储。多数「sid 不一致」根因在找回规则，而不是数据丢失。