Files
junhong_cmp_fiber/openspec/changes/add-carrier-gateway-rate-limit/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

8.7 KiB
Raw Blame History

Context

完整推导、生产数据与评审记录见 docs/engineering/轮询按运营商账户限流技术方案.md(第三部分第 4、6.2、7.1、7.4 节,第五部分第 3 节第 1 步)。本文只记录本 Change 的实现决策。

现状:

  • internal/gateway/client.go:141 executeWithRetry:一次方法调用最多 maxRetries + 1 次 HTTP 请求(默认 2 次重试),仅对超时、连接失败重试;每次尝试前后调用 AttemptObserver(stop_resume_audit.go、gateway_integration.go 已用于审计与集成日志)。
  • internal/gateway/flow_card.go:StopCard / StartCard 用默认重试;SetCardSpeedTier 已设 maxRetries = 0。
  • 业务错误只拼在错误字符串(client.go:274),集成日志 provider_code、provider_message 为空。
  • 轮询并发:internal/task/polling_base.go 的全局 + 任务类型计数(本 Change 不动,第 5 个 Change 下线)。
  • Asynq:pkg/queue/server.go 显式使用 asynq.DefaultRetryDelayFunc,未设 IsFailure;outbox:deliver 入队未设 MaxRetry(默认 25 次)。queue.concurrency 默认 10,轮询与 Outbox、导出、佣金共用。
  • Redis 单节点;自动化测试为 N/A,验证在维护者指定的测试环境进行。

Goals / Non-Goals

Goals:

  • 所有自动触发的卡网关调用受运营商账户限流约束,口径为每次实际 HTTP 请求。
  • 上线不造成整体变慢:先只统计,配好后整体拦截。
  • 限流不导致"流量用完停机"被推迟数小时或丢失。
  • 失败原因与调用量可见,停复机逐次可查。

Non-Goals:

  • 不改轮询调度、分片、并发计数(第 5 个 Change)。
  • 不改停复机业务规则与触发路径(第 4、6 个 Change);现有 stopCardWithRetry 的业务层 sleep 重试保留到第 6 个 Change。
  • 不做批量查询;不对后台人工点击、通道阈值、自动续费、手动刷新限流。

Decisions

  1. 限流在每次 HTTP 尝试前执行,而不是方法入口。方法入口只能扣一次,内部重试会漏计。实现为网关客户端的调用守卫 gateway.CallGuard(BeforeAttempt / AfterAttempt),在 executeWithRetry 每次尝试前、现有 AttemptObserver 之前调用;卡操作类型由 5 个卡方法写入 ctx。没有复用 ctx 里的 AttemptObserver,因为 ctx 只能放一个观察器,会与停复机、设备的审计观察器互相覆盖。限流拒绝发生在审计观察器之前,因此被拒绝的尝试不写集成日志。
  2. 滑动窗口 Lua(ZSET 毫秒时间戳),key gateway:qps:{cid}:{group};一次脚本同时校验账户组与全局组、普通操作与预留额度、high_waiting。备选令牌桶:突发更平滑但"本秒剩余"口径与后续分发器领取不一致,放弃。
  3. 默认限流、显式豁免:ctx 中只有豁免标记(带来源),没有"受限流"标记。备选"带标记才限流":新入口忘记打标记就漏网,与"不存在不限流的自动调用"冲突,放弃。
  4. 两种模式全局开关:polling.rate_limit_mode 放受控系统配置(tb_system_config,module = polling),不按账户覆盖(不灰度,见方案第三部分第 9 节)。API 与 Worker 各自用独立注册表读取同一份配置数据,进程内缓存 5 秒,后台修改数秒内生效。
    • 限流组与错误分类规则同样在进程内缓存 5 秒(GatewayRateLimitConfigTTL),后台保存后本进程立即失效、其他进程 5 秒内刷新;未另建 Redis 配置缓存。
    • 运营商账户口径为本系统 tb_carrier(卡上的 carrier_id),与网关客户端自身的 appId 无关:已知卡的调用方用 gateway.WithCarrier 传入,否则守卫按 ICCID 查本系统卡表并缓存 10 分钟;查不到时按账户 0(未知账户)单独计量。
    • Redis 故障时限流失败开放(放行并记日志),避免限流组件故障阻断全部网关调用。
  5. Asynq 内不等待:限流器提供"立即返回"与"等待至超时"两种模式,本 Change 只用立即返回。等待会占住共用的 10 个协程、饿死 Outbox 等业务。等待模式留给第 5 个 Change 的 NSQ 消费者。
  6. 限流错误不计失败:在 pkg/queue/server.go 设置 IsFailure(errors.Is(err, ErrRateLimited) 时返回 false)与 RetryDelayFunc(限流错误返回 rate_limited_retry_delay,其余回落 DefaultRetryDelayFunc)。只改服务配置与错误类型,各消费者业务代码不改。轮询 handler 另外自行短延迟 Requeue(它们是 MaxRetry(0))。累计推迟告警:任务载荷或 Redis 记首次限流时间,超过上限写告警。
  7. 停复机 maxRetries = 0:与 SetCardSpeedTier 同一做法(复制 Client 并置 0)。超时返回 CodeGatewayTimeout,现有调用方按失败或结果未知处理。
  8. 结构化错误:新增 GatewayError{Category, ProviderCode, ProviderMessage, Duration} 实现 error 并保留现有错误码(CodeGatewayError 等),调用方用 errors.As 取结构,既有 errors.Is/错误码判断不受影响。
  9. 错误分类:表 tb_gateway_error_classification + Redis 缓存;分类器按"适用操作 + 启用 + 优先级"匹配关键字(包含 / 前缀 / 正则)。初始数据按方案第 6.2 节表格写入迁移。
  10. 停复机记录表:PostgreSQL 声明式分区(PARTITION BY RANGE (created_at)),主键 (id, created_at),建 DEFAULT 分区;Worker 定时任务提前创建未来 N 个月分区(N 为系统参数)并按保留期删除过期分区。记录写入在业务事务之外,失败只记日志与计数。
  11. 审计替换:以"是否带限流豁免标记或由账户、个人客户、OpenAPI 发起"区分(legacyCommandLogging):
  • 系统自动停复机(系统任务发起、无豁免标记)只写停复机记录,不写 tb_audit_event 与集成日志;未调用上游的拒绝类审计保留。
  • 后台人工点击、通道阈值、自动续费,以及账户、个人客户、OpenAPI 发起的停复机保持原审计与集成日志并额外写记录。通道阈值与自动续费的可靠任务用集成日志标识做结果未知恢复,不能去掉。
  • 设备停复机(后台点击)在设备服务内同样写记录。
  • 普通轮询查询不再写集成日志(含有变化时的成功记录);同时是优先执行的轮次仍写,以满足优先轮询"返回集成交互日志标识"的现行要求。
  1. 分钟计数:key gateway:stat:{cid}:{op}:{yyyyMMddHHmm} Hash(按结果类别计数、耗时分桶),TTL 8 天,覆盖 observe 一周的评估需要。

  2. 观测序列遇限流:观测序列任务为 MaxRetry(0),现有逻辑在限流时记一次"被限流"并结束本次尝试(不归档、不报错),后续两次尝试与普通轮询兜底;本 Change 不做顺延重入队(需改序列幂等认领),观测序列在第 5 个 Change 下线。

  3. 业务层停复机重试:stopCardWithRetry / resumeCardWithRetry 遇限流立即返回,不再 sleep 重试、不写失败审计,由调用方既有重试或兜底路径处理。

Risks / Trade-offs

  • [默认 QPS 设得不合理] → 先 observe 至少一周,按 /polling-stats/carriers 数据为全部账户配置限流组后再整体 enforce;enforce 后异常可即时改回 observe。
  • [停复机不再内部重试,人工点击网络抖动直接失败] → 已接受;页面提示重试。
  • [移除系统自动停复机审计后,原审计查询看不到] → 停复机记录提供同等字段与查询;后台人工点击仍有统一审计。
  • [IsFailure 对全部 Asynq 任务生效] → 只对 ErrRateLimited 返回 false,其余错误行为不变;限流错误只由限流器产生。
  • [分区表维护任务失败] → DEFAULT 分区兜底插入不失败;监控分区创建结果。
  • [Redis 计数 key 量] → 账户 37 × 操作 5 × 分钟,8 天约 210 万个小 Hash;上线前按生产 Redis 余量评估,必要时改为 5 分钟粒度。

Migration Plan

  1. 测试环境:执行迁移(三张新表、tb_system_config 配置项与错误分类初始数据),部署 API 与 Worker,默认 observe。
  2. 按 tasks 第 9 节核对清单逐项验证,包括 enforce 下 Outbox 限流不计失败。
  3. 生产:维护者按生产运行说明手工执行迁移与发布,保持 observe 至少一周。
  4. 运营按统计为全部账户配置限流组,确认后改 enforce。
  5. 回退:改回 observe 即停止拦截;代码回退时新表保留不删。

Open Questions

  • 默认 QPS 初值:在测试环境与 observe 数据确认前,暂定为系统参数默认值,由维护者上线前填写。