Files
邹进 02a842f066
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 9m35s
fix: 网关限流系统配置 Key 改为三段式,修复注册失败
- 受控系统配置要求 Key 至少三段,原两段式 Key(如 polling.rate_limit_mode)注册被拒,后台不可见、限流器只能使用默认值
- Key 改为 polling.gateway.* 与 polling.stop_resume_record.*;新增迁移 000247 将已落库的旧 Key 改名并保留取值
- 后续提案中规划的开关同步改为三段式(polling.scheduler.mode、polling.stop_resume.queue_enabled)
2026-10-24 16:17:34 +09:00

7.1 KiB
Raw Blame History

ADDED Requirements

Requirement: 卡网关操作按运营商账户限流

系统 SHALL 对卡的 5 个网关操作(查流量、查状态、查实名、停机、复机)按目标卡所属运营商账户与操作类型找到所属限流组,并在每秒请求数达到该组 max_qps 时拒绝或延后本次请求。限流窗口 MUST 跨全部 API 与 Worker 进程共享。设备停复机拆分到卡后,每张卡 MUST 各自按其所属运营商账户查找限流组。未被任何启用的限流组覆盖的操作(含所在组已停用)MUST 按默认 QPS 限流,不得出现不限流的自动调用。配置了全局组时,请求 MUST 同时满足账户组与全局组才放行。

Scenario: 账户组 QPS 用满

  • GIVEN 运营商账户 A 的查询组 max_qps = 20,当前 1 秒窗口内已放行 20 次查询
  • WHEN 第 21 次查询 A 账户下卡的流量
  • THEN 系统在拦截模式下不发出该 HTTP 请求,返回"限流"结果

Scenario: 不同账户互不影响

  • GIVEN 账户 A 的查询组本秒已用满
  • WHEN 查询账户 B 下卡的状态
  • THEN 系统按账户 B 的限流组判断,不受账户 A 影响

Scenario: 限流组停用

  • WHEN 账户 A 的停复机组被停用后发起 A 账户下卡的停机
  • THEN 系统按默认 QPS 限流该次停机,不得不限流放行

Scenario: 全局组

  • GIVEN 配置了覆盖查询操作的全局组且其本秒已用满,账户 A 查询组仍有余量
  • WHEN 查询账户 A 下卡的流量
  • THEN 系统按全局组拒绝本次请求

Requirement: 按每次实际 HTTP 请求计量

系统 SHALL 在每次向网关发出 HTTP 请求之前各取一次限流名额,网关客户端一次方法调用内部的重试请求 MUST 各自计量。拿不到名额时,本次方法调用 MUST 结束且不再发起后续尝试。

Scenario: 查询内部重试

  • GIVEN 查流量第一次请求超时,网关客户端准备进行第二次尝试
  • WHEN 第二次尝试发出前
  • THEN 系统为第二次尝试再取一次名额,名额不足时不发出第二次请求并返回"限流"结果

Requirement: 默认限流与显式豁免

系统 SHALL 对卡的 5 个网关操作默认限流;只有后台人工点击的停复机、通道阈值、自动续费、手动刷新 4 个入口 MAY 携带豁免标记绕过限流,豁免调用 MUST 按豁免来源计数以便监控。未携带豁免标记的调用(含今后新增的入口)MUST 受限流约束。

Scenario: 新增自动入口未处理标记

  • WHEN 任一未声明豁免的入口调用停机
  • THEN 该调用受所属限流组约束

Scenario: 后台人工点击停机

  • WHEN 运营在后台对单卡点击停机
  • THEN 该调用不受限流约束,并计入"人工点击"豁免调用量

Requirement: 高优先级操作预留额度

当同一限流组内包含停机、复机与其他操作且配置了高优先级操作与 reserved_qps 时,系统 SHALL 让普通操作最多使用 max_qps − reserved_qps,高优先级操作可用满 max_qps;高优先级请求等待名额期间,普通操作 MUST 拿不到新名额。保存限流组时,系统 MUST 拒绝 reserved_qps ≥ max_qps、高优先级操作不属于本组操作、同一运营商账户下同一操作属于多个组的配置。

Scenario: 共享组内普通操作受预留约束

  • GIVEN 广电账户一个组含全部 5 个操作,max_qps = 10,停机与复机为高优先级,reserved_qps = 3
  • WHEN 本秒已放行 7 次查询后再发起查询
  • THEN 系统拒绝该查询;同一秒内的停机仍可放行至第 10 次

Scenario: 同一操作重复归组

  • WHEN 维护者为账户 A 新建组并包含已属于另一组的"查流量"
  • THEN 系统拒绝保存并提示该操作已属于其他组

Requirement: 只统计与拦截两种模式

系统 SHALL 按受控系统配置 polling.gateway.rate_limit_mode 全局决定限流模式:observe 时照常计数(实际 QPS、本应被拦截的次数)但不拦截、不等待;enforce 时按限流组拦截。默认值 MUST 为 observe。模式修改 MUST 即时生效,不需要重新部署。模式不得按运营商账户覆盖。

Scenario: 只统计模式下超出上限

  • GIVEN 模式为 observe,账户 A 查询组本秒已达上限
  • WHEN 再查询 A 账户下一张卡
  • THEN 系统照常发出请求,并把该次计入"本应被限流"次数

Scenario: 切换为拦截

  • WHEN 超级管理员把 polling.gateway.rate_limit_mode 改为 enforce
  • THEN 下一次请求起按限流组拦截,无需重启进程

Requirement: Asynq 任务内遇限流不等待且不计失败

在拦截模式下,系统 SHALL 让 Asynq 任务内发起的受限调用拿不到名额时立即返回"限流"错误,不在任务内等待名额。轮询任务遇限流 MUST 按 rate_limited_retry_delay 短延迟重新入队且不计为失败。其余 Asynq 任务(含 Outbox 消费者、观测序列)返回"限流"错误时,Asynq MUST 不将其计为失败、不增加重试计数,并按固定短延迟重试;其他错误的重试行为 MUST 不变。同一任务因限流累计推迟超过上限时,系统 MUST 写告警且任务继续重试。

Scenario: 流量用完停机遇限流

  • GIVEN 流量入账后的 Outbox 消费者判断需要停机,停复机组本秒已用满
  • WHEN 消费者调用停机拿不到名额
  • THEN 任务以"限流"错误结束,Asynq 不增加重试计数,几秒后重试,不会因连续限流推迟数小时或被归档

Scenario: 非限流错误

  • WHEN Outbox 消费者因数据库错误失败
  • THEN Asynq 按原有重试次数与递增间隔处理

Requirement: 停复机不使用网关内部重试

系统 SHALL 对停机、复机网关调用只发出一次 HTTP 请求,不使用网关客户端的内部重试,对全部停复机入口生效(含后台人工点击、通道阈值、自动续费)。超时或连接失败 MUST 按结果未知返回给调用方。

Scenario: 停机超时

  • WHEN 停机请求超时
  • THEN 系统不在同一次调用内再发停机请求,向调用方返回结果未知

Scenario: 后台人工点击停机网络抖动

  • WHEN 运营点击停机时连接失败
  • THEN 页面返回失败,由运营重新操作,系统不自动重试

Requirement: 限流组与限流参数可后台维护

系统 SHALL 提供限流组的列表(按运营商账户筛选,含全局组)、新建、详情、修改、启停、删除接口;修改类接口仅超级管理员可用并写统一审计。保存后 MUST 同步到共享缓存,下一次请求起生效。限流模式、限流短延迟、限流累计推迟告警上限等标量参数 SHALL 通过受控系统配置 module = polling 维护,列表 MUST 支持按 polling 模块筛选。

Scenario: 修改 QPS 即时生效

  • WHEN 超级管理员把账户 A 查询组 max_qps 从 20 改为 30
  • THEN 下一次请求起按 30 判断,无需重启

Scenario: 非超级管理员修改

  • WHEN 非超级管理员提交限流组修改
  • THEN 系统拒绝并保留原配置