BFE AI 限流 Redis 键回退机制深度解析:未配置 redis_key 时按规则名生成计数器键(SC07 TC-03)
BFE AI 限流 Redis 键回退机制深度解析:未配置 redis_key 时按规则名生成计数器键(SC07 TC-03)
本篇技术指南围绕 BFE(百度开源七层负载均衡)mod_ai_rate_limit 模块的 Redis 限流计数器键生成逻辑展开,重点解析集成测试场景 SC07 的 TC-03 用例:当限流规则未显式配置 redis_key 时,BFE 如何回退到"基于规则名"生成 Redis key 以实现向后兼容。读完本文,你将掌握 redis_key 与规则名的优先级关系、Redis key 的完整拼接规则(含 policyId 前缀)、RPM/TPM 计数器持久化的底层原理,以及如何在真实 BFE 进程 + 嵌入式 Redis 环境中复现"第一次 200、第二次 429"的完整验证流程。
一、背景:mod_ai_rate_limit 的 Redis 计数器与键的稳定性
mod_ai_rate_limit 是 BFE AI 网关体系中的限流模块,负责对 AI 请求按策略(Policy)维度执行 RPM(每分钟请求数)、TPM(每分钟 Token 数)与并发数(Concurrency)三类限流。限流计数器的状态持久化在 Redis 中,因此 Redis 键的生成规则直接决定了计数器在规则重命名、模型变更之后是否保持连续。
从源码结构看,限流模块的数据链路是:产品规则(Config)→ 策略(RateLimitPolicies)→ 限流器集合(policyLimiterSet),其中每个 RPM/TPM 限流器在构造时都会绑定一个 Redis key:
- mod_ai_rate_limit.go 中的
executeCheckLimitPolicy依次执行并发、RPM、TPM 检查,任一检查不通过即触发策略动作; - policy_limiter.go 中的
newPolicyLimiterSet通过buildRpmRedisKey/buildTpmRedisKey为每个规则计算 Redis key,再据此创建QPMLimiter/TPMLimiter。
SC07 场景的全部测试目标即围绕这一设计展开:
- 显式配置
redis_key时,BFE 使用该 key 读写 Redis 计数器; - 规则名变更但
redis_key不变时,RPM 计数器保持连续(TC-01); - 规则模型变更但
redis_key不变时,RPM 计数器保持连续(TC-02); - 未配置
redis_key时,BFE 回退到基于规则名生成 Redis key,保持向后兼容(TC-03,本文主题)。
二、Redis key 生成优先级:显式 redis_key 优先,缺失时回退规则名
限流规则的 JSON 字段在 data_load.go 中定义,RPM 与 TPM 规则均包含可选的 redis_key 字段:
{
"name": "rpmabc1",
"window_minutes": 1,
"max_requests": 100,
"burst": 1,
"models": ["gpt-4"],
"redis_key": "RL_RPM_rlp-0001_0"
}
key 的最终确定逻辑实现在 policy_limiter.go 中,优先级清晰可循:
func buildRpmRedisKey(policyId string, rule *RPMRuleConf) string {
if rule.RedisKey != "" {
if strings.HasPrefix(rule.RedisKey, "default_bfe_") {
return rule.RedisKey
}
return buildRedisKey(policyId, rule.RedisKey)
}
return buildRedisKey(policyId, fmt.Sprintf("rpm_%s", buildRpmInstId(rule)))
}
判定顺序为:
redis_key为空(未配置):回退到规则名(详见第三节);redis_key非空且以default_bfe_开头:视为新格式,控制面已下发完整 Redis key,直接原样使用,不再拼接前缀;redis_key非空但不以default_bfe_开头:视为旧格式,控制面只下发 suffix,需要拼接default_bfe_{policyId}_前缀,最终形如default_bfe_rlp-0001_RL_RPM_rlp-0001_0。
TPM 的 buildTpmRedisKey 逻辑与 RPM 完全对称(TPM 回退分支使用 tpm_ 前缀)。这种"双格式兼容"设计从源码注释可以推断:新格式允许控制面直接下发完整键名以彻底掌控计数器归属,旧格式则保留早期版本的拼接习惯,避免升级后计数器全部失效。
三、回退路径源码剖析:default_bfe_{policyId}rpm{ruleName}
当 redis_key 缺失时,回退键由两个函数协作生成,位于 policy_limiter.go:
func buildRedisKey(policyId string, suffix string) string {
return fmt.Sprintf("%s_%s_%s", "default_bfe", policyId, suffix)
}
func buildRpmInstId(rule *RPMRuleConf) string {
if rule.Name != "" {
return rule.Name
}
return fmt.Sprintf("rpm_%d_%d_%d", rule.TimeWindow, rule.MaxRequests, rule.Burst)
}
- 策略(policy)维度是 key 的第一层隔离:所有回退键都带
default_bfe_{policyId}前缀,不同策略即使规则名相同也不会互相串扰; - 规则名是第二层隔离:规则配置了
name时,直接用规则名作为 suffix,RPM 最终键为default_bfe_{policyId}_rpm_{ruleName},TPM 为default_bfe_{policyId}_tpm_{ruleName}; - 规则名缺失时的兜底:若连
name也未配置(配置校验其实强制要求 name 非空,见RPMRuleConfFile.Check()的 "Please set name"),则退化使用规则参数摘要(如rpm_60_100_1)作为 suffix,保证键仍唯一。
这一点被单测 policy_limiter_test.go 直接锁定:
| 测试函数 | 输入 | 期望结果 |
|---|---|---|
TestBuildRedisKey |
buildRedisKey("policy1", "suffix") |
default_bfe_policy1_suffix |
TestBuildRpmRedisKeyFallbackToName |
规则 Name="abc",无 RedisKey |
default_bfe_policy1_rpm_abc |
TestBuildTpmRedisKeyFallbackToName |
规则 Name="abc",无 RedisKey |
default_bfe_policy1_tpm_abc |
TestBuildRpmInstIdWithoutName |
规则无 Name,TimeWindow=120, MaxRequests=100, Burst=10 |
rpm_120_100_10 |
也就是说,在 TC-03 用例中(策略 policyID = "rlp-0001"、规则名 name-based-rule),BFE 实际写入 Redis 的 RPM 计数器键为 default_bfe_rlp-0001_rpm_name-based-rule——这是可从源码直接推导的确定性结论。
四、TC-03 测试用例全流程解读
4.1 用例目标与运行模式
TC-03 的定位是向后兼容性验证:早期版本未引入 redis_key 字段时,计数器完全依赖规则名组织,本用例确保升级到支持 redis_key 的版本后,存量配置(未配置 redis_key)的限流行为不发生任何变化。
运行模式为单组件模式:仅启动真实 bfe 进程与嵌入式 Redis(由测试框架提供),不涉及 ai-gateway-api 与 conf-agent。
4.2 前置条件与配置构造
前置条件(与测试代码 sc07_ai_rate_limit_redis_key_test.go 一一对应):
- 已编译
bfe可执行文件; - 嵌入式 Redis 已启动(
common/redis_server.go提供内存 Redis 服务); - mock 后端
cluster_ratelimit已启动,返回 200; - 临时 BFE 配置已生成并加载,
ai_rate_limit.data由测试代码通过rateLimitPolicy("name-based-rule", "gpt-4", "")动态生成。
cluster_ratelimit.AIConf(定义在运行时生成的 cluster_conf/cluster_conf.data):
{
"AIConf": {
"Type": 0,
"Keys": [
{"Name": "ratelimit-key", "Key": "sk-ratelimit-key", "Weight": 100}
]
}
}
限流规则 RPM(redis_key 显式为 "",即不配置):
| 字段 | 值 |
|---|---|
Name |
name-based-rule |
Models |
["gpt-4"] |
RedisKey |
""(未配置) |
MaxRequests |
1 |
WindowMinutes |
1 |
Burst |
1 |
4.3 BFE 请求与预期结果
向 BFE 发送 2 次 POST 请求(Host ratelimit.example.org,Path /v1/chat/completions,Authorization: Bearer ak_ratelimit,Body {"model":"gpt-4"}):
| 步骤 | 预期响应 | 说明 |
|---|---|---|
| 1 | 200 | 首次请求,RPM 计数从 0 → 1,未超阈值,转发至 mock 后端 |
| 2 | 429 | 第二次请求,RPM 计数达到 MaxRequests=1,命中限流,返回 RPM_LIMIT_EXCEEDED |
附加断言:cluster_ratelimit mock backend 仅被命中 1 次。
4.4 底层行为链
从 mod_ai_rate_limit.go 的 checkRPM 实现可以看出,每次请求对匹配模型的所有 RPM 限流器调用 item.limiter.Check(1, agent)——这是一个基于 Redis 的原子计数操作(由 bfe_util/limit_rate 的 RedisLRAgent 驱动)。当检查返回不允许时,executePolicyAction 依据产品规则的 hit_action(本例为 FINISH)构造 AI 错误响应:错误码 RPM_LIMIT_EXCEEDED、HTTP 状态 429(映射关系见 error_code.go),并将请求 ErrCode 置为 ErrAiRateLimit 后直接结束(不转发后端)。这正是"第二次请求 429、后端只被命中 1 次"的完整来源。
五、复现 TC-03 所需的完整配置参考
5.1 mod_ai_rate_limit.conf
模块配置在 mod_ai_rate_limit.conf 中给出,IsRejectOnRedisError = true 表示 Redis 故障时直接拒绝请求(也可改为 false 放行):
[basic]
ProductRulePath = ../conf/mod_ai_rate_limit/ai_rate_limit.data
IsRejectOnRedisError = true
[redis]
# bns addr
bns = BFE.poc-redis-wx
# timeout in ms
connectTimeout = 20
readTimeout = 20
writeTimeout = 20
# max idle connections
maxIdle = 20
[log]
OpenDebug = false
配置校验逻辑在 conf_load.go:ProductRulePath 必填、Redis.Bns 必须通过 CheckRedisConf、ConnectTimeout/ReadTimeout/WriteTimeout 均需大于 0。
5.2 ai_rate_limit.data
完整的产品限流数据文件见 ai_rate_limit.data,其中 Config 定义产品级命中动作(FINISH),RateLimitPolicies 定义策略及其 TPM/RPM/并发规则,ApikeyRateLimitPolicyBindings 将 API Key 绑定到策略。TC-03 对应的最小化策略片段如下(省略 redis_key 字段即触发回退):
{
"Config": {
"ai_product": [
{
"cond": "default_t()",
"hit_action": {"cmd": "FINISH", "params": []}
}
]
},
"RateLimitPolicies": {
"rlp-0001": {
"name": "ratelimitX",
"enabled": true,
"rules": {
"rpm": [
{
"name": "name-based-rule",
"window_minutes": 1,
"max_requests": 1,
"burst": 1,
"models": ["gpt-4"]
}
]
}
}
},
"ApikeyRateLimitPolicyBindings": {
"ak_ratelimit": ["rlp-0001"]
},
"Version": "1.0"
}
数据加载时 data_load.go 会执行严格校验:window_minutes 必须在 [1, 360] 区间、RPM 规则 name 必填、burst < 1 时自动修正为 1、每个策略至少配置 tpm/rpm/max_concurrency 之一、同类型规则名不得重复。
5.3 路由与主配置
SC07 场景涉及的其余配置文件(均可在 tests/integration/implementation/scenario-SC07-ai-rate-limit-redis-key/testdata 下找到模板):
- bfe.conf:
EnableAiGateway = true,加载mod_ai_token_auth、mod_ai_route、mod_ai_rate_limit三个模块; mod_ai_route/ai_route.data:apikey 级路由,ak_ratelimit命中apikey_ak_ratelimit路由表,其规则ratelimit-default(default_t()条件)将请求定向到cluster_ratelimit,无 fallback;mod_ai_token_auth/token_rule.data:为ak_ratelimit绑定unlimited_plan配额,确保 TC-03 的 429 只可能来自限流而非配额扣减(SC07 不依赖 SC03 的 RMB 配额逻辑);server_data_conf/host_rule.data:声明ai_product产品线对应的 Host(ratelimit.example.org);cluster_conf/gslb.data:cluster_ratelimit的 GSLB 权重配置。
5.4 执行与清理
用例通过集成测试框架运行:common/bfe_config_builder.go 根据 RateLimitPolicyData 动态生成 ai_rate_limit.data 与 cluster_conf,common/process_env.go 负责编译并启动真实 bfe 进程。测试结束后需依次停止 bfe 进程、mock 后端与嵌入式 Redis,并删除临时配置目录(测试代码通过 testEnv.Close() 统一完成清理)。
六、向后兼容的工程意义
TC-03 验证的回退机制看似简单,实则是限流系统演进中的关键兼容性设计:
- 存量配置零迁移:早期仅按规则名组织计数器的部署,升级后不需要为每条规则补写
redis_key,限流状态无缝衔接; - 策略级隔离兜底:
default_bfe_{policyId}前缀保证了即使规则名相同,不同策略的计数器也不会互相污染;同一策略内 RPM 与 TPM 通过rpm_/tpm_后缀区分,互不影响; - 与显式配置的清晰分界:一旦控制面希望让计数器"跟随业务标识而非规则名"(例如规则改名、模型变更时保持计数连续),只需下发
redis_key即可覆盖回退逻辑——这正是 SC07 中 TC-01、TC-02 与 TC-03 共同构成的完整键策略谱系:显式 key 掌控连续性,缺失 key 保兼容。
七、延伸阅读与验证入口
- 场景总览:tests/integration/测试设计文档/scenario-SC07-AI限流Redis键/场景说明.md
- 本用例设计:tests/integration/测试设计文档/scenario-SC07-AI限流Redis键/TC-03-未配置redis_key时按规则名回退.md
- 集成测试实现:sc07_ai_rate_limit_redis_key_test.go
- key 生成源码:policy_limiter.go
- key 生成单测:policy_limiter_test.go
- 限流模块入口:mod_ai_rate_limit.go
- 配置加载与校验:conf_load.go、data_load.go
如需深入验证,可运行 go test ./bfe_modules/mod_ai_rate_limit/... 执行 key 生成的单元测试,或在 tests/integration 目录下运行 SC07 集成测试,观察 default_bfe_rlp-0001_rpm_name-based-rule 键在 Redis 中的计数变化。