BFE AI 限流 Redis 键稳定性验证:规则重命名后 RPM 计数器保持连续的实现原理与测试设计(SC07 TC-01)
BFE AI 限流 Redis 键稳定性验证:规则重命名后 RPM 计数器保持连续的实现原理与测试设计(SC07 TC-01)
本篇技术指南围绕 BFE(现代七层负载均衡器)中 mod_ai_rate_limit 模块的 AI 限流 Redis 键(redis_key)设计 展开,聚焦于 SC07 场景的第一个集成测试用例 TC-01「规则重命名后 RPM 计数器保持连续」。读者将掌握 redis_key 的三种生成分支、RPM 滑动窗口计数的 Lua 原子实现、限流判定在 BFE 过滤器链中的完整调用路径,以及如何通过「重启 BFE + 改名」的集成测试验证计数器在规则重命名后不重置,为限流规则的命名治理与平滑演进提供可复用的设计依据与测试范式。
一、用例概览:TC-01 在 SC07 中的定位
| 项目 | 内容 |
|---|---|
| 用例编号与名称 | TC-01 规则重命名后 RPM 计数器保持连续 |
| 所属场景 | SC07 AI 限流 Redis 键(见 场景说明) |
| 版本声明 | bfe:当前源码版本 |
SC07 场景要回答的核心问题是:mod_ai_rate_limit 按规则维度对 AI 请求做 RPM/TPM 限流,限流计数器持久化在 Redis 中,Redis 键的生成规则直接决定计数器在规则重命名、模型变更后的连续性。TC-01 正是该场景的第一个验证点:当限流规则显式配置 redis_key 时,redis_key 的优先级高于规则名(rule name),规则重命名不会导致计数器重置。同场景的 TC-02「模型变更后 RPM 计数器保持连续」与 TC-03「未配置 redis_key 时按规则名回退」分别覆盖模型维度与向后兼容路径,见 TC-02、TC-03。
二、测试目的与运行模式
测试目的:验证 redis_key 优先级高于规则名,规则重命名不会导致计数器重置。
运行模式:单组件模式 —— 仅启动真实 bfe 进程与嵌入式 Redis,不涉及 ai-gateway-api 与 conf-agent。这一模式把验证范围收敛在 BFE 自身的数据面行为上:限流判定、Redis 读写、429 响应构造全部由单个 bfe 进程完成,便于精确定位「计数器连续性问题」是否由键生成逻辑引起。
三、前置条件与配置构造
3.1 前置条件
- 已编译
bfe可执行文件; - 嵌入式 Redis 已启动;
- mock 后端
cluster_ratelimit已启动,返回 200; - 临时 BFE 配置已生成并加载,包含
mod_ai_rate_limit规则:- 规则名:
old-rule - 模型:
gpt-4 redis_key:RL_RPM_rlp-0001_0MaxRequests: 1WindowMinutes: 1Burst: 1
- 规则名:
ai_route.data中apikey_ak_ratelimit命中ratelimit-default,target 为cluster_ratelimit;ak_ratelimit已绑定限流策略rlp-0001。
3.2 cluster_ratelimit 的 AIConf
{
"AIConf": {
"Type": 0,
"Keys": [
{"Name": "ratelimit-key", "Key": "sk-ratelimit-key", "Weight": 100}
]
}
}
AIConf.Keys 定义该 cluster 的 API-Key 轮换表,Weight: 100 表示该 key 被 100% 命中,保证测试期间请求始终使用同一组凭据,不引入 key 轮换带来的变量。
3.3 限流规则 RPM 配置
{
"Name": "old-rule",
"Models": ["gpt-4"],
"RedisKey": "RL_RPM_rlp-0001_0",
"MaxRequests": 1,
"WindowMinutes": 1,
"Burst": 1
}
MaxRequests: 1 + WindowMinutes: 1 + Burst: 1 的含义是:1 分钟时间窗口内最多放行 1 个请求。因此窗口内第一个请求通过(200),第二个请求必然触发 RPM 限流(429)——这是本用例能精确观察到「计数器是否连续」的前提。
3.4 涉及的配置文件(SC07 全场景)
| 文件 | 说明 |
|---|---|
bfe.conf |
启用 EnableAiGateway,加载 mod_ai_route、mod_ai_token_auth、mod_ai_rate_limit |
mod_ai_route/mod_ai_route.conf |
指定 ai_route.data 路径 |
mod_ai_route/ai_route.data |
定义 apikey 级路由规则,命中 cluster_ratelimit |
mod_ai_token_auth/mod_ai_token_auth.conf |
指定 token 规则路径 |
mod_ai_rate_limit/mod_ai_rate_limit.conf |
指定限流规则路径 |
server_data_conf/host_rule.data |
声明 ai_product 产品线对应的 Host |
server_data_conf/route_rule.data |
默认路由 |
cluster_conf/gslb.data |
GSLB 权重配置 |
cluster_conf/cluster_table.data |
运行时根据 mock 后端地址动态生成 |
cluster_conf/cluster_conf.data |
运行时根据 mock 后端动态生成,包含 cluster_ratelimit 的 AIConf |
说明:
ai_rate_limit.data由测试代码在运行时根据rateLimitPolicy()动态生成,便于控制规则名、模型与redis_key(场景说明原文)。其 JSON 结构为Config(产品线级命中条件与动作)、RateLimitPolicies(策略 ID → 策略定义)、ApikeyRateLimitPolicyBindings(API-Key → 策略 ID 列表)、Version,字段解析见 data_load.go 与示例 ai_rate_limit.data。
四、BFE 请求步骤(完整执行序列)
发送 3 次 POST 请求:
| 步骤 | Host | Path | Authorization | Body | 说明 |
|---|---|---|---|---|---|
| 1 | ratelimit.example.org |
/v1/chat/completions |
Bearer ak_ratelimit |
{"model":"gpt-4"} |
窗口内第一个请求,放行 |
| 2 | ratelimit.example.org |
/v1/chat/completions |
Bearer ak_ratelimit |
{"model":"gpt-4"} |
同一窗口内第二个请求,触发 RPM 限流 |
3(重启 BFE 后,规则名改为 new-rule) |
ratelimit.example.org |
/v1/chat/completions |
Bearer ak_ratelimit |
{"model":"gpt-4"} |
规则改名但 redis_key 不变,应仍被限流 |
其中集成测试实现中实际发送请求的构造方式(Host、Authorization: Bearer、Content-Type: application/json)可对照 sc07_ai_rate_limit_redis_key_test.go。
五、预期结果与验证点
- 三次请求分别返回 200、429、429;
cluster_ratelimitmock backend 被命中 1 次。
对预期结果的解读:
- 第 1 次 200 且 backend 命中 1 次:请求通过限流并被真实转发到 mock 后端;
- 第 2 次 429 且 backend 不再命中:RPM 计数在 Redis 中生效,请求在限流层被拦截;
- 第 3 次(改名 + 重启后)仍为 429:这是本用例的黄金断言 —— 即使 BFE 进程重启、规则名从
old-rule改为new-rule,只要redis_key保持不变,Redis 中的计数器(ZSET 中的时间戳成员)仍然存在,窗口内的额度已被第 1 次请求耗尽,因此第 3 次请求同样被拒。这直接证明了「redis_key优先级高于规则名」。
六、源码级原理:redis_key 如何决定计数器身份
TC-01 之所以成立,根源在 policy_limiter.go 中 Redis 键的生成逻辑。RPM 限流器实例在 newPolicyLimiterSet 中创建,键由 buildRpmRedisKey 决定:
func buildRpmRedisKey(policyId string, rule *RPMRuleConf) string {
if rule.RedisKey != "" {
// 新格式:控制面直接下发完整 Redis Key(以 default_bfe_ 开头)。
// 旧格式:控制面下发 suffix,需要拼接前缀。
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以default_bfe_开头(新格式),视为控制面下发的完整键,直接使用; - 后缀拼接:
redis_key非空但不带前缀(旧格式),作为后缀拼接为default_bfe_{policyId}_{suffix}(buildRedisKey 为fmt.Sprintf("%s_%s_%s", "default_bfe", policyId, suffix))。本用例中的RL_RPM_rlp-0001_0属于此分支,实际落库键为default_bfe_rlp-0001_RL_RPM_rlp-0001_0; - 按规则名回退:
redis_key为空时,回退为default_bfe_{policyId}_rpm_{rpmInstId},其中 buildRpmInstId 优先取rule.Name,为空时退化为rpm_{TimeWindow}_{MaxRequests}_{Burst}组合串。
这正是 TC-01 与 TC-03 的分水岭:
- TC-01 中规则名
old-rule→new-rule发生变化,但分支 2 的键只依赖policyId与redis_key,与规则名无关,因此计数器身份不变、不会重置; - TC-03 中未配置
redis_key时走分支 3,键内嵌规则名,一旦改名计数器身份即改变 —— 这正是 SC07 场景要验证的向后兼容回退行为(旧版本没有redis_key字段时按规则名建键)。
需要强调的是,buildRpmRedisKey 的入参 policyId(策略 ID)是另一个「稳定身份」维度:本用例中 redis_key 命名为 RL_RPM_rlp-0001_0,显式携带了策略 ID 语义,进一步保证策略级计数器的可辨识性。
七、源码级原理:RPM 滑动窗口计数与请求处理链路
7.1 限流判定在过滤器链中的位置
mod_ai_rate_limit 在 Init 中注册了两个过滤器回调:
HandleAfterAITargetModel→ targetModelCheckHandler:在目标模型解析完成后执行限流检查(按目标模型而非客户端原始模型匹配,见issue #1387相关注释);HandleRequestFinish→limitRequestFinishHandler:请求结束后回补 TPM token 用量并释放并发连接。
限流检查主流程为 executeCheckLimitPolicy:先按 ClientApiKey 查绑定策略列表,过滤 Enabled 为 false 的策略,用 matchModel 过滤模型,然后按「并发(Concurrency)→ RPM → TPM」顺序逐项检查。RPM 检查失败时通过 executePolicyAction 构造响应:当 hit_action.cmd = FINISH 时,按命中类型生成 AiError(RPM 命中对应 CodeRpmLimitExceeded / LimitTypeRpm),返回 HTTP 429 并置 BfeHandlerFinish,请求不再转发到后端。
7.2 QPM 限流器与滑动窗口 Lua 脚本
RPM 在代码中以 QPM(Queries Per Minute)实现:QPMLimiter.Check 最终调用 agent.QpmCheck(redisKey, period, limit, reqToConsume)(redis_qpm_agent.go),实际执行逻辑在 Redis 端 Lua 脚本 redis_qpm_limit_check.lua 中原子完成:
local t = redis.call('TIME')
local now = t[1] + t[2] / 1000000
redis.call('ZREMRANGEBYSCORE', key, 0, now - period) -- 剔除窗口外成员
local count = redis.call('ZCARD', key)
if count >= limit then
return {current_time, 0, count, now} -- 拒绝
end
local member = tostring(now) .. ':' .. tostring(t[2])
redis.call('ZADD', key, now, member) -- 记录本次请求
redis.call('EXPIRE', key, math.ceil(period + 60)) -- 键过期 = period + 60s
return {current_time, 1, count + emission_cost, now} -- 放行
要点:
- 数据结构:Redis 键是一个 ZSET,成员为
now:微秒,score 为请求时间戳; - 窗口裁剪:先
ZREMRANGEBYSCORE剔除超过period(本用例 60 秒)的旧成员,再ZCARD统计窗口内请求数; - 原子性:整个「裁剪-计数-写入-续期」在一个 Lua 脚本内完成,杜绝并发请求下的竞态;
- 键生命周期:
EXPIRE设置为period + 60秒,保证冷键自动回收,同时窗口内不会因过期丢失计数。
回到 TC-01:第 1 次请求后 ZSET 中写入一个时间戳成员;第 2 次请求 ZCARD 计数为 1 ≥ limit(1),拒绝并 429;重启改名后第 3 次请求使用同一个 Redis 键(default_bfe_rlp-0001_RL_RPM_rlp-0001_0),窗口未过、成员仍在,继续拒绝 429。整个链路(键生成 → Lua 计数 → 429 构造)与规则名完全解耦。
八、集成测试实现对照
TC-01 的实际落地实现是 TestTC01_RPMCounterPersistsAcrossNameChange,其流程与设计文档严格对应:
- 构造
testEnv:启动 mock backend(返回 200 + usage 响应体)、嵌入式 Redis、编译/运行环境; rateLimitPolicy("old-rule", "gpt-4", rpmRedisKey)动态生成限流数据并startBFE;- 发送第 1 次请求,断言 200;发送第 2 次请求,断言 429;
e.stopBFE()停止 BFE 进程;rateLimitPolicy("new-rule", "gpt-4", rpmRedisKey)重新生成配置并startBFE(Redis 未重启,计数器保留);- 发送第 3 次请求,断言仍为 429。
测试还通过 logBFEException() 在断言失败时输出 exception.log 与 bfe.log 尾部,便于定位问题。公共基础设施方面:嵌入式 Redis 由 common/redis_server.go 提供;ai_rate_limit.data 由 common/bfe_config_builder.go 根据 RateLimitPolicyData 动态生成并替换模板占位(含 Redis 地址、mock 后端地址等);真实 BFE 进程由 ProcessEnv.StartBFE 启动,其 mod_ai_rate_limit.conf 指向 Bns = 127.0.0.1:<redis端口> 并开启 IsRejectOnRedisError = true(见 SC07 测试用 mod_ai_rate_limit.conf),与仓库示例配置 conf/mod_ai_rate_limit/mod_ai_rate_limit.conf 结构一致。
九、同场景其他用例与运维启示
| 用例 | 核心验证点 | 与 TC-01 的差异 |
|---|---|---|
| TC-02 | 使用稳定 redis_key,请求模型从 gpt-4 变更为 gpt-3.5 后第二次请求仍被限流 |
变更维度是 Models 而非 Name,请求体同步改为新模型以命中规则 |
| TC-03 | 无 redis_key 时按规则名生成键,行为向后兼容 |
验证分支 3 的回退路径 |
对限流规则治理的启示(依据上文源码行为,属实现事实推导):
redis_key应作为计数器的稳定身份锚点:只要redis_key不变,规则的改名、模型调整都不会重置线上计数,适合「先建规则、后调参数」的平滑演进;- 命名建议:在
redis_key中携带策略 ID 与限流类型(如RL_RPM_rlp-0001_0、仓库示例中的RL_TPM_rlp-0001_1,见 conf/mod_ai_rate_limit/ai_rate_limit.data),可读性与可排查性更好; - 注意回退陷阱:未配置
redis_key的旧规则若被改名,计数器身份会改变(等价于短暂重置),升级到支持redis_key的版本时建议为存量规则补齐稳定的redis_key; - Redis 错误策略:模块支持
IsRejectOnRedisError,为 true 时 Redis 异常直接拒绝(返回 429),为 false 时放行 —— 键设计同时影响限流的可用性边界,参见 conf_load.go 的配置项说明。
十、清理与复现指引
清理:停止 bfe 进程、mock 后端与嵌入式 Redis,删除临时目录。
复现方式:本用例属于仓库集成测试的一部分。编译 BFE 后,可在 tests/integration/implementation/scenario-SC07-ai-rate-limit-redis-key 目录下运行 go test -run TestTC01_RPMCounterPersistsAcrossNameChange(测试会自动构建临时配置、启动嵌入式 Redis 与真实 BFE 进程并执行三次请求断言)。测试模板配置(路由、host、gslb、token auth 等)位于该目录的 testdata/ 下,其中 ai_route.data 展示了 apikey_ak_ratelimit → ratelimit-default → cluster_ratelimit(权重 100)的路由结构,与设计文档第 4.3 节的路由表设计一一对应。
验证结论:通过 TC-01 的 200/429/429 断言序列与「mock backend 仅命中 1 次」的观测,可以确认 mod_ai_rate_limit 的 redis_key 机制满足「键稳定性优先于规则名」的设计意图 —— 这正是 AI 网关在限流规则频繁调整场景下保持计费与限流连续性的关键保障。