Files
junhong_cmp_fiber/openspec/changes/add-carrier-polling-scheduler/design.md
邹进 42e881576d
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 9m33s
feat: 卡网关按运营商账户限流并记录停复机调用
- 新增网关限流:按本系统运营商账户(卡 carrier_id)→ 限流组 → 操作限制每秒请求数,每次 HTTP 尝试计量,默认限流、仅后台人工点击/通道阈值/自动续费/手动刷新豁免;支持只统计与拦截两种模式,默认只统计
- Asynq 遇限流不计失败、固定短延迟重试;轮询任务与停复机业务重试遇限流短延迟重排
- 停机、复机不再使用网关内部重试,只发一次请求
- 网关返回结构化错误;新增上游错误分类规则表与测试接口
- 新增按月分区的停复机记录表:系统自动停复机只写记录,不再写统一审计与集成日志;普通轮询查询不再写集成日志
- 新增限流组、错误分类、停复机记录、按账户调用统计与枚举后台接口
- 迁移 000243~000246;同步 OpenSpec 提案(含后续 6 个 change)与技术方案、工程约束
2026-10-24 15:06:41 +09:00

5.6 KiB
Raw Blame History

Context

完整设计见 docs/engineering/轮询按运营商账户限流技术方案.md 第三部分第 15.1、7.27.6、8、9、14 节。本文记录实现决策。

现状:internal/polling/scheduler.go 每秒对 16 个分片 × 5 类型 Lua 出队后逐条 Enqueue 到 Asynq(MaxRetry(0)、无 TaskID);按 ZCARD 背压(50 万);polling_base.go 全局 + 类型并发令牌;优先提示 List polling:priority:{taskType} 与手动触发 List;OnCardStatusChanged 重新入队全部类型;业务事件经 Outbox AppendSeriesRequested 创建"立即、3 分钟、5 分钟"观测序列,读入口经 BestEffortSeriesDispatcher(C 端资产详情、后台资产实时状态、C 端与后台实名链接;OpenAPI 不触发)。Redis 单节点;仓库无 NSQ 依赖;自动化测试为 N/A。生产 98,430 张卡、89,962 张开启轮询、37 个运营商账户。

Goals / Non-Goals

Goals: 按账户隔离、不丢卡、同卡串行、去重;业务事件检查合并且受限流;整体切换可回退。

Non-Goals: 停复机指令队列与设备维度判断(第 6 个 Change,本 Change 中套餐步骤与 Outbox 消费者仍按现有方式同步停复机);批量查询;手动刷新行为。

Decisions

  1. Redis 结构(前缀新,不与旧 key 冲突):
    • 账户:polling:carrier:{cid}:priority|queue(ZSET,member=card_id)、:running(ZSET,member=token,score=到期,仅计数)、:dispatch_lock。stop_resume、sr_running 在第 6 个 Change 使用,本 Change 预留领取顺序。
    • 卡:polling:card:{id}:due(Hash:各类型到期、优先标记、连续失败、首次失败、最近错误、最近成功时间)、:claim(值=token)、:exec(值=token+实例)。
  2. Lua 脚本:领取(清理过期 running → 计算上限 → 优先/普通按占比 → 预计调用数对比剩余 QPS → SET claim NX PX → 推后 score → 写 running)、续期(校验 token → PEXPIRE claim/exec → 推后 score 与 running)、收尾(校验 token → 删 claim/exec → 移出 running → 写 due → 按优先标记选队列设 score)、请求检查(设 due[type]=now、冷却判断、放入 priority 或打标记)。全部单节点 Lua,不跨 slot 问题。
  3. NSQ 而非 Asynq(已定保留 NSQ):每账户独立 topic polling.card.{cid},channel worker;消费者 max_in_flight 按账户参数;msg_timeout 大于续期间隔,执行中 Touch;租约 > msg_timeout × 允许重投次数。动态订阅随运营商账户与配置刷新。
  4. 执行权 key:NSQ 在消费者假死时会重投同一 token,仅核对 claim 无法区分;SET exec token+实例 NX PX 续期间隔×2 抢不到即 FIN。
  5. 步骤函数:原 4 个 handler 拆为 step(ctx, StepInput{Card, Result}) (nextDue, err);Result 预留批量查询与推送结果。套餐步骤本轮流量已触发评估时可跳过(配置)。沿用 polling_priority_claim.go 的优先项认领与收尾。卡流量同步锁保留与手动刷新互斥。
  6. 限流等待模式:NSQ 消费者使用第 1 个 Change 限流器的"等待至超时"模式(不占 Asynq 协程),等待超过单步超时返回限流超时,按短延迟重排不计失败。
  7. 请求检查取代观测序列:5 处 AppendSeriesRequested 与 3 处读入口分发改为调用"请求检查(卡、类型、场景)";场景表 tb_polling_check_scene 预置 scene 行(订单支付、套餐激活、停复机成功、设备操作、自动续费购包、C 端资产详情、后台资产实时状态、实名链接),读入口默认配置冷却。观测序列中与卡检查无关的部分(设备信息同步 query_device_info)保持不变。
  8. 失败告警:tb_polling_failure_alert 部分唯一索引(卡、检查类型、未关闭),告警写入走异步、失败只记日志;通知走现有 alert_service.go。停复机方向的告警在第 6 个 Change 接入同一张表。
  9. 整体切换:polling.scheduler_mode 放受控系统配置;切换由 Worker 监听配置变更执行:停旧调度 → 初始化新结构(按批读库,进度复用 /polling-stats/init-progress)→ 开启分发。回退对称。旧 handler 执行前检查模式。
  10. 监控:队列与执行数读 Redis;QPS、耗时读第 1 个 Change 的分钟计数;告警读告警表。

Risks / Trade-offs

  • [不灰度,新调度出问题影响全部 9 万张卡] → 测试环境按生产规模压测(造卡或回放生产卡 ID),覆盖 tasks 第 11 节全部场景;上线首日重点监控,异常用 scheduler_mode 回退。
  • [初始化 10 万张卡耗时] → 测试环境实测并写入上线步骤;初始化期间不领取,切换窗口内轮询暂停。
  • [新增 NSQ 组件] → nsqd 与 nsqlookupd 部署、监控与告警纳入运维;NSQ 消息丢失由租约到期兜底。
  • [Redis 内存增加] → 每卡一个 due Hash(约 10 字段),上线前按生产卡量估算并确认 maxmemory 与淘汰策略不淘汰轮询 key。
  • [读入口冷却期内页面数据不新] → 已接受;页面照常展示数据库数据。

Migration Plan

  1. 测试环境部署 nsqd + nsqlookupd;执行迁移(三张新表、系统配置项、并发配置表注释)。
  2. 部署 API 与 Worker,scheduler_mode = legacy;运营配置账户调度参数与场景。
  3. 切 carrier,按 tasks 第 11 节核对;演练回退与再次切换。
  4. 生产:维护者部署 NSQ、执行迁移与发布,选择低峰期切 carrier,首日监控。
  5. 稳定运行后另行删除旧分片 key 与旧调度代码。