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

231 lines
15 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 轮询入库异步化技术方案
- 日期: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 条。