现场使用的设备走运营商 4G,大多在 NAT 之后,没有公网入口 —— 服务器无法反向连接设备。一份「需要被忽略的自用标识清单」(自家机型的编号与 MAC 地址)要同步到所有设备,只能由设备主动来拉。
版本计数器
方案的核心是一个只增不减的版本号:
- 设备每次发送数据时携带自己持有的清单版本
wl; - 服务端在 ingest 响应里回带当前版本
wl_version; - 设备发现两者不一致,主动
GET /api/v1/whitelist拉全量。
服务器永不主动连设备 —— 现场设备多在 4G NAT 之后,连不过去,也不该连。版本只增不减,设备凭数字大小判断新旧,不需要做时间戳对齐,设备时钟不准也不会误判。
拉取接口的鉴权与数据发送用同一把 X-API-Key,不引入第二套身份体系;同时按设备 ID 限流,防止固件异常时疯狂重拉。
容量闸门:拒绝,不截断
清单不是无限长的。设备端超过 128 条时,服务端直接返回 400 拒绝同步,绝不静默截断。
静默丢条目比拉取失败更危险:设备以为拿到了完整清单,实际少了几条,本该被忽略的自用机型就混进了结果里。宁可拉取失败把问题暴露出来,不能假装成功。
版本 0 的语义
设备侧版本 0 = 从未同步过。此状态下不做过滤,全部显示 —— 没见过清单的设备宁可多显示,不可漏显示。