feat: 轮询观测入库异步化,调网关与入库分离,采集记录经消息攒批写入
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 16m2s
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 16m2s
- 轮询步骤异步模式下只调网关并发布 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>
This commit is contained in:
230
docs/2026-11-06-轮询入库异步化技术方案.md
Normal file
230
docs/2026-11-06-轮询入库异步化技术方案.md
Normal file
@@ -0,0 +1,230 @@
|
||||
# 轮询入库异步化技术方案
|
||||
|
||||
- 日期: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 条。
|
||||
Reference in New Issue
Block a user