# 轮询入库异步化技术方案 - 日期: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:` 存在则直接 FIN。 2. 按 `kind` 调用现有 `ApplyTrafficObservation` / `ApplyNetworkObservation` / `ApplyCardObservation`,上下文超时 `polling.ingest.timeout`(默认 30s),从拿到消息开始计时。 3. 成功后:写 `ingest:done:`(TTL 48h);流量有变化时写 Redis 标记 `flow_evaluated:`(见 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:`(入库段写,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 条。