fix: 网关限流系统配置 Key 改为三段式,修复注册失败
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 9m35s

- 受控系统配置要求 Key 至少三段,原两段式 Key(如 polling.rate_limit_mode)注册被拒,后台不可见、限流器只能使用默认值
- Key 改为 polling.gateway.* 与 polling.stop_resume_record.*;新增迁移 000247 将已落库的旧 Key 改名并保留取值
- 后续提案中规划的开关同步改为三段式(polling.scheduler.mode、polling.stop_resume.queue_enabled)
This commit is contained in:
邹进
2026-10-24 16:17:34 +09:00
parent 9b0930db9f
commit 02a842f066
16 changed files with 70 additions and 34 deletions

View File

@@ -31,7 +31,7 @@
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 秒,后台修改数秒内生效。
4. **两种模式全局开关**:`polling.gateway.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 故障时限流失败开放(放行并记日志),避免限流组件故障阻断全部网关调用。

View File

@@ -7,7 +7,7 @@
- 新增网关限流器:按"运营商账户 → 限流组 → 操作"对卡的 5 个网关操作(查流量、查状态、查实名、停机、复机)做每秒请求数限制,滑动窗口,跨 Worker 共享;**按每次实际 HTTP 尝试计量**(挂在 `AttemptObserver.BeforeAttempt`),网关内部重试同样计入。
- 默认限流、显式豁免:只有后台人工点击停复机、通道阈值、自动续费、手动刷新 4 个入口打豁免标记,其余卡操作一律受限。
- 限流组配置(新表 `tb_carrier_rate_limit_group`):组内操作、`max_qps`、高优先级操作与预留额度、可选全局组;未覆盖或组已停用的操作按默认 QPS,不存在不限流的自动调用。
- 两种模式:受控系统配置 `polling.rate_limit_mode`,`observe`(只统计、不拦截,默认)与 `enforce`(拦截),全局生效、不按账户覆盖。上线先 `observe` 采集至少一周,配好全部账户限流组后整体切到 `enforce`。
- 两种模式:受控系统配置 `polling.gateway.rate_limit_mode`,`observe`(只统计、不拦截,默认)与 `enforce`(拦截),全局生效、不按账户覆盖。上线先 `observe` 采集至少一周,配好全部账户限流组后整体切到 `enforce`。
- 拦截时在 Asynq 任务内**不等待**:拿不到名额立即返回"限流"错误;轮询任务短延迟重入队且不计失败;Asynq 服务配置 `IsFailure` 对"限流"错误返回 false、`RetryDelayFunc` 返回固定短延迟,Outbox 消费者与观测序列因此不会因限流消耗重试次数、推迟数小时或归档。
- **BREAKING** `StopCard` / `StartCard` 不再使用网关内部重试(`maxRetries = 0`),对全部停复机入口生效(含后台人工点击):避免超时后几百毫秒内对同一张卡连发 2~3 次撞上游单卡频率限制。
- 网关返回结构化错误(错误类别、网关业务码与信息、耗时),不再只拼在错误字符串里。

View File

@@ -59,7 +59,7 @@
### Requirement: 只统计与拦截两种模式
系统 SHALL 按受控系统配置 `polling.rate_limit_mode` 全局决定限流模式:`observe` 时照常计数(实际 QPS、本应被拦截的次数)但不拦截、不等待;`enforce` 时按限流组拦截。默认值 MUST 为 `observe`。模式修改 MUST 即时生效,不需要重新部署。模式不得按运营商账户覆盖。
系统 SHALL 按受控系统配置 `polling.gateway.rate_limit_mode` 全局决定限流模式:`observe` 时照常计数(实际 QPS、本应被拦截的次数)但不拦截、不等待;`enforce` 时按限流组拦截。默认值 MUST 为 `observe`。模式修改 MUST 即时生效,不需要重新部署。模式不得按运营商账户覆盖。
#### Scenario: 只统计模式下超出上限
- **GIVEN** 模式为 `observe`,账户 A 查询组本秒已达上限
@@ -67,7 +67,7 @@
- **THEN** 系统照常发出请求,并把该次计入"本应被限流"次数
#### Scenario: 切换为拦截
- **WHEN** 超级管理员把 `polling.rate_limit_mode` 改为 `enforce`
- **WHEN** 超级管理员把 `polling.gateway.rate_limit_mode` 改为 `enforce`
- **THEN** 下一次请求起按限流组拦截,无需重启进程
### Requirement: Asynq 任务内遇限流不等待且不计失败

View File

@@ -3,7 +3,7 @@
- [x] 1.1 新增成对迁移:建 `tb_carrier_rate_limit_group`(`carrier_id` 可空表示全局组、`group_code`、`group_name`、`max_qps`、`operations`、`high_priority_operations`、`reserved_qps`、`status`、审计字段);down 删表。
- [x] 1.2 新增成对迁移:建 `tb_gateway_error_classification`(关键字、匹配方式、类别、适用操作、优先级、启用状态),写入方案第 6.2 节的初始规则;down 删表。
- [x] 1.3 新增成对迁移:建分区表 `tb_card_stop_resume_record`(按 `created_at` 月分区,主键 `(id, created_at)`,DEFAULT 分区,当前月起若干个月分区,索引 `(card_id, created_at)`、`(carrier_id, created_at)`、`(result, created_at)`);down 删表。
- [x] 1.4 新增成对迁移:`tb_system_config` 插入 `module = polling` 配置项(`polling.rate_limit_mode` 默认 `observe`、`rate_limited_retry_delay`、限流累计推迟告警上限、默认 QPS、停复机记录保留月数与提前建分区月数);down 删除这些键。
- [x] 1.4 新增成对迁移:`tb_system_config` 插入 `module = polling` 配置项(`polling.gateway.rate_limit_mode` 默认 `observe`、`rate_limited_retry_delay`、限流累计推迟告警上限、默认 QPS、停复机记录保留月数与提前建分区月数);down 删除这些键。
- [x] 1.5 新增对应 model 与 Store;`internal/infrastructure/systemconfig` 注册上述键(类型、取值范围、枚举),`SystemConfigListRequest.Module` 枚举增加 `polling`;为 JSON 类型注册项增加结构校验接缝。
## 2. 网关结构化错误与停复机不重试