Files
junhong_cmp_fiber/openspec/changes/add-carrier-gateway-rate-limit/design.md
邹进 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

74 lines
8.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## 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.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 故障时限流失败开放(放行并记日志),避免限流组件故障阻断全部网关调用。
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 发起的停复机保持原审计与集成日志并额外写记录。通道阈值与自动续费的可靠任务用集成日志标识做结果未知恢复,不能去掉。
- 设备停复机(后台点击)在设备服务内同样写记录。
- 普通轮询查询不再写集成日志(含有变化时的成功记录);同时是优先执行的轮次仍写,以满足优先轮询"返回集成交互日志标识"的现行要求。
12. **分钟计数**:key `gateway:stat:{cid}:{op}:{yyyyMMddHHmm}` Hash(按结果类别计数、耗时分桶),TTL 8 天,覆盖 `observe` 一周的评估需要。
13. **观测序列遇限流**:观测序列任务为 `MaxRetry(0)`,现有逻辑在限流时记一次"被限流"并结束本次尝试(不归档、不报错),后续两次尝试与普通轮询兜底;本 Change 不做顺延重入队(需改序列幂等认领),观测序列在第 5 个 Change 下线。
14. **业务层停复机重试**:`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` 数据确认前,暂定为系统参数默认值,由维护者上线前填写。