Files
junhong_cmp_fiber/docs/2026-11-06-轮询入库异步化技术方案.md
邹进 1214181e78
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 16m2s
feat: 轮询观测入库异步化,调网关与入库分离,采集记录经消息攒批写入
- 轮询步骤异步模式下只调网关并发布 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>
2026-11-06 16:33:29 +09:00

15 KiB
Raw Permalink Blame History

轮询入库异步化技术方案

  • 日期: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. 目标与原则

  1. 调上游与入库分开控制:调网关按账户并发(保持现有每账户上限),入库单独发消息、由单独的消费者处理。
  2. 数据库并发有总上限:入库消费者的并发是一个固定、可配置的数,与账户数量无关;加账户不会挤爆数据库。
  3. 消费慢一点没关系:消息在 NSQ 里排队,入库按数据库承受的速度处理;不丢、不重复算。
  4. 轮询步骤只做"调网关 + 发消息":调网关前必要的读查询走缓存,尽量不碰数据库。
  5. 可切回:保留同步入库路径,用系统配置一键切换,异常时可回退。
  6. 范围:只在 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 入库消费者

处理一条消息:

  1. 幂等检查:Redis ingest:done:<observation_id> 存在则直接 FIN。
  2. 按 kind 调用现有 ApplyTrafficObservation / ApplyNetworkObservation / ApplyCardObservation,上下文超时 polling.ingest.timeout(默认 30s),从拿到消息开始计时。
  3. 成功后:写 ingest:done:<observation_id>(TTL 48h);流量有变化时写 Redis 标记 flow_evaluated:<card_id>(见 4.6)。
    • 本轮认领了优先轮询项的观测不走消息,仍在卡任务内同步入库,优先项完成与对接日志沿用原逻辑。
    • 网络观测命中风险停机或已销户时,卡任务按网关结果直接停止该卡轮询,入库段写库时关闭轮询开关。
  4. 失败:
    • 数据库超时、连接错误等可重试错误:NSQ 延迟重投,退避 5s、15s、30s、1m、2m,之后每 5 分钟一次,不设次数上限、不丢弃(入库消费者的 NSQ max_attempts 设为 0);第 10 次起每次重投记 ERROR,带 observation_id、卡号与错误,便于排查。
    • 业务性错误(卡不存在、数据校验失败):不重投,记 WARN 后 FIN。
    • 本期不做死信表。长时间重试的消息会体现在积压量与最老消息等待时间上(见 4.7)。

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. 实施步骤

  1. 采集队列 Push 按 observed_at 去重;网络/实名观测补"更新的才生效"判断(如缺)。
  2. 采集记录唯一索引迁移;card.collection 批量消费者;采集段失败记录改发消息。
  3. card.ingest 消息、入库消费者、幂等键、不限次数的退避重试。
  4. 三个轮询步骤改为发消息;优先项完成、对接日志、StopPolling、flow_evaluated 移到入库段;发布失败降级。
  5. 采集段读查询走缓存;套餐状态查询各自计时、失败不缓存。
  6. 积压监控、告警、反压;启动并发检查。
  7. 系统配置与回退开关;测试环境 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)

  1. 入库消费者默认并发 30。
  2. 测试环境 nsqd 改为 --mem-queue-size=0,所有消息直接落盘。
  3. 本期不做死信:可重试错误不限次数退避重试,不丢弃;业务性错误记 WARN 后丢弃。
  4. 积压告警阈值 200,000 条;反压(暂停派发新卡任务)阈值 500,000 条。