- 轮询步骤异步模式下只调网关并发布 card.ingest 入库消息,入库消费者固定并发 30、按采集 ID 去重、可重试错误不限次数退避重投 - 采集记录经 card.collection 攒批写入,失败整批重投,新增 (observation_id, observed_at) 唯一索引 - 网络、实名观测增加乱序保护;轮询读查询走缓存,套餐状态查询各自计时且失败不缓存 - 入库积压告警与反压;系统配置 polling.ingest.mode 默认 sync 可回退;测试环境 nsqd 消息全部落盘 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
15 KiB
轮询入库异步化技术方案
- 日期:2026-11-06
- 分支:
Iteration/8-11(只部署测试环境,不涉及生产配置与重启) - 关联:
add-carrier-polling-scheduler(按运营商账户调度)、add-card-traffic-queue-and-observed-deduction(采集队列与按观测扣减)、refactor-audit-log-persistence(采集记录分表)
1. 背景
1.1 测试环境现状(2026-11-06 上午,只读统计)
| 指标 | 数值 |
|---|---|
worker 报 context deadline exceeded 的 SQL |
每分钟 90–220 次,平均约 130 次,即每小时约 8,000 次,部署审计改造前已存在 |
| 慢查询告警(> 500ms) | 每小时约 13.8 万条,占 worker 日志行数 53% |
按主键查单行 tb_iot_card |
经常 0.7–2.4 秒 |
| worker 日志量 | 每小时约 26 万行,18 分钟写满一个 100MB 文件,40 个备份只能留约 12 小时 |
| 数据库连接 | worker 连接池 MAX_OPEN_CONNS=60,测试库上 61 个连接,基本占满;有一次 30 个会话同时等锁 |
| 采集记录丢失 | 写采集成功表/失败表 3 秒超时,约每 16 分钟丢 60 条 |
1.2 原因:消费并发没有总量限制
NSQ 只限制了每个运营商账户的并发(保护网关),没有限制全部账户加起来的并发(保护数据库):
| 来源 | 规则 | 理论上限 | 实测 |
|---|---|---|---|
卡轮询 polling.card.<账户> |
每账户 20(default_card_max_in_flight,tb_carrier_polling_param 无记录) |
41 × 20 = 820 | 约 310 |
停复机 polling.stop_resume.<账户> |
每账户 10 | 41 × 10 = 410 | 约 22 |
设备评估 polling.device_eval |
10 | 10 | 10 |
| 异步任务队列 | JUNHONG_QUEUE_CONCURRENCY=50 |
50 | — |
| 合计 | 约 1,290 | 约 380 |
worker.polling_total_max_concurrency: 100 只传给旧分片轮询(cmd/worker/main.go:371),按账户调度的 NSQ 消费者不受它约束。
每个轮询步骤在同一个任务里先调网关、再同步写库,所有写库都在步骤超时内完成。三百多个任务抢 60 个连接,等连接的时间计入超时,数据库稍有抖动就成批超时。
1.3 超时分布(按调用栈,约 16 分钟样本)
| 占比 | 位置 | 说明 |
|---|---|---|
| 约 40% | 配置匹配查套餐状态(TierResolver.Prefill,internal/polling/config_manager.go:191,共用 3 秒) |
绑定设备的卡连查 3 次;失败后把"未知"结果写进缓存 |
| 约 20% | writeTrafficFailureAudit |
沿用已超时的上下文再查卡,属连带报错 |
| 约 20% | 写采集成功表、失败表(collectionRecordTimeout = 3s) |
记录直接丢失 |
| 其余 | 流量观测事务、网络状态观测、实名缓存失效等 |
2. 目标与原则
- 调上游与入库分开控制:调网关按账户并发(保持现有每账户上限),入库单独发消息、由单独的消费者处理。
- 数据库并发有总上限:入库消费者的并发是一个固定、可配置的数,与账户数量无关;加账户不会挤爆数据库。
- 消费慢一点没关系:消息在 NSQ 里排队,入库按数据库承受的速度处理;不丢、不重复算。
- 轮询步骤只做"调网关 + 发消息":调网关前必要的读查询走缓存,尽量不碰数据库。
- 可切回:保留同步入库路径,用系统配置一键切换,异常时可回退。
- 范围:只在
Iteration/8-11上实现,只部署测试环境。
3. 现状链路(一次流量步骤)
NSQ 卡任务 ──► 步骤(15s 超时)
├─ 读:优先轮询项 FindActive(tb_polling_priority_item)
├─ 读:卡(先清缓存再查库 tb_iot_card)
├─ 读:轮询范围校验(tb_carrier、tb_device、tb_device_sim_binding)
├─ 调网关 QueryFlow
├─ 写:ApplyTrafficObservation
│ ├─ Redis 采集队列 Push
│ ├─ 事务:锁卡行、查有效套餐、写日快照、更新卡、写流量事件 outbox、通道阈值评估、审计
│ └─ 写采集成功表/失败表(3s)
├─ 写:对接日志、优先项完成
└─ 返回 TriggeredEvaluation(决定是否跳过本轮套餐步骤)
网络状态步骤(ApplyNetworkObservation)、实名步骤(ApplyCardObservation)结构相同;套餐步骤不调网关,只读写库。
4. 技术设计
4.1 两段式
采集段(按账户并发,现有 NSQ 卡任务) 入库段(固定小并发)
┌────────────────────────────────┐ ┌──────────────────────────────┐
│ 读缓存 → 调网关 → 发入库消息 │──NSQ──► │ card.ingest 消费者(并发 N) │
│ 网关失败 → 发采集失败消息 │ │ Apply*Observation(事务) │
└────────────────────────────────┘ │ → 发采集记录消息 │
└──────────────┬───────────────┘
│NSQ
┌──────────────▼───────────────┐
│ card.collection 消费者 │
│ 攒批写成功表/失败表 │
└──────────────────────────────┘
- 采集段:现有卡任务消费者,并发规则不变(每账户
card_max_in_flight)。步骤拿到网关结果后发一条入库消息就结束,步骤结果只反映"网关是否成功"。 - 入库段:新 topic
card.ingest,单独消费者,max_in_flight=polling.ingest.concurrency(默认 30)。 - 采集记录:新 topic
card.collection,单独的批量消费者(见 4.5)。
4.2 入库消息
topic card.ingest,JSON:
| 字段 | 说明 |
|---|---|
kind |
traffic / network / realname |
card_id、carrier_id、iccid |
卡标识 |
observation_id |
现有 attempt.IntegrationID,幂等键 |
observed_at |
网关返回时刻(不是入库时刻) |
source、scene、correlation_id |
现有观测元数据 |
payload |
流量:reading_mb、reading_result、reset_day;网络:status、extend、imei;实名:verified |
raw、failure |
网关原始数据(截断规则同采集记录) |
priority_item_id |
本轮认领的优先轮询项,入库成功后由入库段完成 |
published_at |
发出时刻,用于积压与延迟统计 |
4.3 入库消费者
处理一条消息:
- 幂等检查:Redis
ingest:done:<observation_id>存在则直接 FIN。 - 按
kind调用现有ApplyTrafficObservation/ApplyNetworkObservation/ApplyCardObservation,上下文超时polling.ingest.timeout(默认 30s),从拿到消息开始计时。 - 成功后:写
ingest:done:<observation_id>(TTL 48h);流量有变化时写 Redis 标记flow_evaluated:<card_id>(见 4.6)。- 本轮认领了优先轮询项的观测不走消息,仍在卡任务内同步入库,优先项完成与对接日志沿用原逻辑。
- 网络观测命中风险停机或已销户时,卡任务按网关结果直接停止该卡轮询,入库段写库时关闭轮询开关。
- 失败:
- 数据库超时、连接错误等可重试错误:NSQ 延迟重投,退避 5s、15s、30s、1m、2m,之后每 5 分钟一次,不设次数上限、不丢弃(入库消费者的 NSQ
max_attempts设为 0);第 10 次起每次重投记 ERROR,带observation_id、卡号与错误,便于排查。 - 业务性错误(卡不存在、数据校验失败):不重投,记 WARN 后 FIN。
- 本期不做死信表。长时间重试的消息会体现在积压量与最老消息等待时间上(见 4.7)。
- 数据库超时、连接错误等可重试错误:NSQ 延迟重投,退避 5s、15s、30s、1m、2m,之后每 5 分钟一次,不设次数上限、不丢弃(入库消费者的 NSQ
4.4 顺序与幂等
NSQ 不保证顺序,也可能重投。逐项说明现有逻辑能否承受:
| 风险 | 处理 |
|---|---|
| 同一张卡两条流量消息乱序 | 采集队列按 observed_at 插入,"新点在队尾才写"——旧消息后到时不在队尾,不写快照,只记采集记录。现有规则已覆盖 |
| 同一张卡两条消息并发处理 | 事务内 FOR UPDATE 锁卡行,串行执行 |
| 同一条消息重投 | ① ingest:done 键挡掉已成功的;② 事务提交后、写键前崩溃:日快照取当日最大值、增量按"本月最大 − 已结算"计算,重放得到 0 增量;流量事件 outbox ID 由 observation_id 生成,重复写入被唯一键挡掉;③ 采集队列 Push 同一个点需改为按 observed_at 去重(Lua 内判断) |
| 网络/实名状态乱序 | 现有 ApplyNetworkObservation、ApplyCardObservation 需确认按 observed_at 比较"更新的才生效";没有的补上 |
| 采集记录重复 | 成功表/失败表按 (observation_id, observed_at) 建唯一索引(含分区键),批量写用 ON CONFLICT DO NOTHING |
4.5 采集记录批量写
- 入库段写完事务后,把采集成功记录发到
card.collection;采集段网关失败、无读数时直接把失败记录发到card.collection,不经过入库段。 card.collection消费者max_in_flight= 500,攒满polling.collection.batch_size(默认 200)或等满 1 秒就批量写一次(多行 INSERT),成功后统一 FIN,失败统一重投。- 写库并发固定 1–2 个连接。按测试环境每小时约 2.1 万条计算,每秒约 6 条,一次批量写即可。
- 现有 3 秒超时和"写失败只记日志"的逻辑删除,不再丢记录。
4.6 采集段剩余读查询
步骤里调网关前的读查询不能异步,改为走缓存:
| 读查询 | 现状 | 改为 |
|---|---|---|
| 卡信息 | 每步先清缓存再查库 | 读 Redis 卡缓存;入库段写完后失效缓存 |
优先轮询项 FindActive |
每步每类型查一次库 | Redis 维护"有活动优先项的卡"集合,不在集合里不查库 |
| 运营商实名开关、重置日 | 每步查库 | 进程内缓存 1 分钟 |
| 设备轮询开关、绑定关系 | 每步查库 | 并入卡缓存 |
| 套餐状态(配置匹配) | 3 次查询共用 3 秒,失败缓存"未知" | 每次查询各自计时;失败不写缓存,下次重查 |
套餐步骤跳过逻辑:现在根据同一任务里流量步骤的 TriggeredEvaluation 跳过。异步后改为读 Redis 标记 flow_evaluated:<card_id>(入库段写,TTL = 套餐检查间隔)。
4.7 积压与反压
- 监控:每分钟读 nsqd
/stats,记录card.ingest、card.collection的积压量和最老消息等待时间,写应用日志。 - 告警:积压超过
polling.ingest.alert_depth(默认 200,000)或等待超过 10 分钟,记 ERROR(接现有告警通道)。 - 反压:积压超过
polling.ingest.pause_depth(默认 500,000,须大于告警阈值)时,调度器暂停发新的卡任务;降到一半以下恢复。账户限流状态不受影响。
4.8 NSQ 持久化
nsqd 当前参数 --mem-queue-size=10000:消息先放内存,nsqd 意外退出会丢掉内存里的部分。
- 测试环境改为
--mem-queue-size=0:所有消息直接落盘(./nsq-data已挂载),按现有量级(每秒几十条)性能没有影响。 - 卡任务 topic 也会一起落盘,对现有调度无行为变化。
- 磁盘占用:入库消息带网关原始数据,单条约 2KB;积压到反压阈值 50 万条约 1GB,测试服务器剩余 32G,足够。
4.9 不改的同步路径
以下入口量小、需要立即返回结果,保持同步入库:后台人工刷新、运营商回调(移动/联通/电信实名)、激活前结算、观测序列(series runner)。
4.10 配置项
| 配置 | 默认 | 说明 |
|---|---|---|
polling.ingest.mode |
sync |
sync 为现在的同步入库;部署确认无误后切 async |
polling.ingest.concurrency |
30 | 入库消费者并发 |
polling.ingest.timeout |
30s | 单条入库超时 |
polling.collection.batch_size |
200 | 采集记录批量大小 |
polling.ingest.alert_depth / pause_depth |
200,000 / 500,000 | 告警与反压阈值 |
mode 与阈值放系统配置(改了几秒内生效),并发放启动配置。启动时检查:入库并发 + 采集记录写并发(2)不超过 MAX_OPEN_CONNS − 20(给采集段读查询、异步任务队列与其他查询留出至少 20 个连接),超过记 ERROR。测试环境 MAX_OPEN_CONNS=60:入库 30 + 采集记录 2 = 32 ≤ 40,满足。
4.11 发布失败兜底
采集段发消息失败(nsqd 不可用)时,降级为当前的同步入库,并记 WARN;不因 nsqd 故障丢观测。
5. 影响与代价
- 入库延迟:正常几秒;积压时更长。卡流量、状态在后台的刷新会比现在晚几秒。
- 停复机判断:超量停机、通道阈值停机依赖入库结果,跟着入库段触发,晚几秒。
- 优先轮询(加急):完成时间从"网关返回"推迟到"入库成功"。
- 同一张卡的数据库写入从"一个任务内"变成"跨两个消费者",排查时按
observation_id串联日志。
6. 分支与范围
- 基于
Iteration/8-11,只部署测试环境;不写生产配置、不涉及生产重启。 - 依赖
add-carrier-polling-scheduler、add-card-traffic-queue-and-observed-deduction的现有实现,不改它们的业务规则。
7. 实施步骤
- 采集队列 Push 按
observed_at去重;网络/实名观测补"更新的才生效"判断(如缺)。 - 采集记录唯一索引迁移;
card.collection批量消费者;采集段失败记录改发消息。 card.ingest消息、入库消费者、幂等键、不限次数的退避重试。- 三个轮询步骤改为发消息;优先项完成、对接日志、
StopPolling、flow_evaluated移到入库段;发布失败降级。 - 采集段读查询走缓存;套餐状态查询各自计时、失败不缓存。
- 积压监控、告警、反压;启动并发检查。
- 系统配置与回退开关;测试环境 nsqd 改
--mem-queue-size=0。
8. 测试与验证(测试环境)
| 验证项 | 通过标准 |
|---|---|
| SQL 超时 | context deadline exceeded 从每小时约 8,000 次降到个位数 |
| 慢查询 | 每小时告警数明显下降,worker 日志留存能达到 14 天目标的量级 |
| 采集记录完整 | 每小时:入库消息数 = 成功表 + 失败表新增行数(按 observation_id 对账) |
| 计量正确 | 抽样卡日快照、套餐扣减与同步模式结果一致;重投、乱序不重复扣减 |
| 积压 | card.ingest 等待时间常态 < 30 秒 |
| 回退 | polling.ingest.mode=sync 后恢复现有行为 |
| 降级 | 停掉 nsqd 时采集段改为同步入库,不丢观测 |
9. 已定事项(2026-11-06)
- 入库消费者默认并发 30。
- 测试环境 nsqd 改为
--mem-queue-size=0,所有消息直接落盘。 - 本期不做死信:可重试错误不限次数退避重试,不丢弃;业务性错误记 WARN 后丢弃。
- 积压告警阈值 200,000 条;反压(暂停派发新卡任务)阈值 500,000 条。