BFE AI 限流 Redis 键连续性:模型变更后 RPM 计数器保持不断的原理与验证(SC07 TC-02)
BFE AI 限流 Redis 键连续性:模型变更后 RPM 计数器保持不断的原理与验证(SC07 TC-02)
本篇技术指南聚焦 BFE 开源项目(现代七层负载均衡器,bfe.go)中 mod_ai_rate_limit 模块的 Redis 计数键设计,以集成测试场景 SC07 的 TC-02 用例为主线,讲解为什么在规则模型变更而 redis_key 不变时,RPM(每分钟请求数)限流计数器不会重置,并结合源码剖析 Redis 键的生成优先级、滑动窗口限流的底层实现以及测试的完整构造方式。读完本文,你将掌握 ai_rate_limit.data 中 redis_key 字段的语义与回退规则,理解如何通过固定 Redis 键实现跨配置热更新的限流连续性,并能复现该场景的集成测试。
一、场景背景:SC07 为什么关注 Redis 键
mod_ai_rate_limit 是 BFE 中按规则维度对 AI 请求做 RPM/TPM 限流的模块,其限流计数器持久化在 Redis 中,而不是进程内存中。这意味着 Redis 键的生成规则直接决定了两件事:
- 计数器在规则重命名、模型变更、BFE 重启后是否还能延续;
- 不同规则、不同策略之间是否会互相“串扰”。
SC07(场景说明)专门围绕这一点设计了三个用例,覆盖三种典型变更场景:
| 用例 | 核心验证点 |
|---|---|
| TC-01 规则重命名后 RPM 计数器保持连续 | 使用稳定 redis_key,规则名变更后第二次请求仍被限流 |
| TC-02 模型变更后 RPM 计数器保持连续(本文主角) | 使用稳定 redis_key,请求模型变更后第二次请求仍被限流 |
| TC-03 未配置 redis_key 时按规则名回退 | 无 redis_key 时,BFE 使用规则名生成 Redis key,行为向后兼容 |
TC-02 的测试目的可以概括为一句话:验证 redis_key 不变时,模型变更不会导致计数器重置。该用例以"单组件模式"运行——只启动真实 bfe 进程与嵌入式 Redis,不涉及 ai-gateway-api 与 conf-agent。
二、Redis 键的生成优先级:源码级解析
TC-02 的结论建立在 mod_ai_rate_limit 对 redis_key 的处理逻辑之上。该逻辑的核心实现位于 bfe_modules/mod_ai_rate_limit/policy_limiter.go,其中两个关键函数分别是 RPM 与 TPM 限流器的键构造入口:
func buildRedisKey(policyId string, suffix string) string {
return fmt.Sprintf("%s_%s_%s", "default_bfe", policyId, suffix)
}
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)))
}
从源码结构看,RPM Redis 键的解析顺序是典型的"三态分支":
RedisKey非空且以default_bfe_开头:视为控制面下发的完整 Redis Key,直接原样使用,不再做任何拼接;RedisKey非空但不以default_bfe_开头:视为"后缀",按default_bfe_<policyId>_<suffix>格式拼接出完整键(兼容旧格式下发);RedisKey为空:回退到基于规则名(或规则参数指纹)生成键,即default_bfe_<policyId>_rpm_<instId>,其中instId由 buildRpmInstId 决定——优先取rule.Name,规则未命名时才退化为rpm_<TimeWindow>_<MaxRequests>_<Burst>参数指纹。
TPM 限流器的 buildTpmRedisKey 采用完全相同的分支策略,只是回退后缀从 rpm_ 变为 tpm_。
这一设计直接解释了 TC-02 的现象:只要 RedisKey 显式配置为稳定值,Redis 键就与规则名、模型完全解耦;模型字段 Models 只参与"规则是否命中当前请求"的匹配判断(见下文第五节),不参与键的构造。
另外值得注意,在构建限流器实例时(newPolicyLimiterSet),rpmInstId 也会在配置了 RedisKey 时被同步替换为该键,用于指标统计与命中信息上报的一致性:
rpmInstId := buildRpmInstId(rule)
if rule.RedisKey != "" {
rpmInstId = rule.RedisKey
}
2.1 键格式与 default_bfe_ 前缀的兼容性
default_bfe_<policyId>_<suffix> 是 BFE 侧的"统一前缀 + 策略 ID + 自定义后缀"三段式结构。TC-02 用例中的键 RL_RPM_rlp-0001_0 即属于第二种分支——它不以 default_bfe_ 开头,因此最终落库的完整键为 default_bfe_rlp-0001_RL_RPM_rlp-0001_0。理解这一点对排查 Redis 中实际存储的 key 非常有帮助。
三、TC-02 用例全景:前置条件与配置构造
TC-02 的完整测试设计见 TC-02-模型变更后RPM计数器保持连续.md,其前置条件与配置构造如下。
3.1 前置条件
- 已编译
bfe可执行文件; - 嵌入式 Redis 已启动;
- mock 后端
cluster_ratelimit已启动,返回 200; - 临时 BFE 配置已生成并加载,包含
mod_ai_rate_limit规则:- 规则名:
rule-1 - 模型:
gpt-4 redis_key:RL_RPM_rlp-0001_0MaxRequests: 1WindowMinutes: 1Burst: 1
- 规则名:
3.2 cluster_ratelimit 的 AIConf
cluster_ratelimit 作为 AI 请求的后端集群,其 AIConf 配置了 API Key 信息:
{
"AIConf": {
"Type": 0,
"Keys": [
{"Name": "ratelimit-key", "Key": "sk-ratelimit-key", "Weight": 100}
]
}
}
3.3 初始限流规则(RPM)
{
"Name": "rlp-0001",
"Enabled": true,
"Rules": {
"RPM": [
{
"Name": "rule-1",
"WindowMinutes": 1,
"MaxRequests": 1,
"Burst": 1,
"Models": ["gpt-4"],
"RedisKey": "RL_RPM_rlp-0001_0"
}
]
}
}
这里的 RedisKey 就是整个用例的"锚点":测试通过改变 Models(模型),保持 RedisKey 不变,从而验证计数器的持久性。WindowMinutes=1、MaxRequests=1、Burst=1 的组合意味着每分钟最多放行 1 个请求、突发容量为 1,第二次请求必然触发限流。
3.4 路由与绑定
- 路由表
apikey_ak_ratelimit中规则ratelimit-default的条件为default_t(),targets 指向cluster_ratelimit,无 fallbacks; ApikeyRouteTableBindings将ak_ratelimit绑定到apikey_ak_ratelimit;- API Key
ak_ratelimit通过ApikeyRateLimitPolicyBindings绑定限流策略rlp-0001。
四、执行步骤与预期结果
4.1 BFE 请求序列
| 步骤 | Body | 说明 |
|---|---|---|
| 1 | {"model":"gpt-4"} |
初始模型,首次请求应放行 |
| 2 | {"model":"gpt-4"} |
同一模型,应被限流 |
3(重启 BFE 后,规则模型改为 gpt-3.5) |
{"model":"gpt-3.5"} |
模型变更,但 redis_key 不变 |
请求的公共特征为:Host: ratelimit.example.org、Path: /v1/chat/completions、Authorization: Bearer ak_ratelimit。
4.2 预期结果
- 三次请求分别返回 200、429、429;
cluster_ratelimitmock backend 被命中 1 次(只有第一次真正转发到了后端,后两次在 BFE 侧即被限流拦截)。
第三次请求返回 429 是整个用例的关键断言:虽然规则模型从 gpt-4 改为 gpt-3.5、BFE 进程也经历了重启,但 Redis 中的计数器仍延续了第二步已消耗的额度,证明计数器状态完全由 Redis 键承载,与进程生命周期、规则模型无关。
五、模型匹配与限流判定:底层调用链
TC-02 之所以有效,前提是 BFE 能正确地把携带 {"model":"gpt-3.5"} 的第三步请求重新匹配到变更后的规则上。这一过程由 mod_ai_rate_limit.go 中的处理链完成。
5.1 模型匹配(matchModel)
在 executeCheckLimitPolicy 中,模块先按 API Key 找到绑定的策略列表,随后执行两层模型匹配:
if !matchModel(policy.Models, targetModel) {
continue
}
checkRPM 内部对每条 RPM 规则再次调用 matchModel 逐条过滤,只有规则 Models 命中请求模型时才计入 matchCount 并执行限流判定:
func matchModel(policyModels []string, model string) bool {
if len(policyModels) == 0 {
return true
}
if model == "" {
return false
}
for _, m := range policyModels {
if m == "*" {
return true
}
if m == model {
return true
}
}
return false
}
注意源码细节:Models 为空表示不限制模型,"*" 表示通配全部模型。TC-02 中规则模型从 ["gpt-4"] 改为 ["gpt-3.5"],请求体同步改为 {"model":"gpt-3.5"},恰好保证"规则重新命中 + 计数器延续"两个条件同时成立。
5.2 滑动窗口限流(QPM)
RPM 限流的执行体是 bfe_util/limit_rate/redis_qpm_limiter.go 中的 QPMLimiter,其 Check 方法最终调用 RedisLRAgent.QpmCheck,将限流判定下沉到 Redis 侧的 Lua 脚本原子执行:
func (l *QPMLimiter) Check(reqToConsume int64, agent *RedisLRAgent) (bool, int64, float64, error) {
...
// check remote
currentTime, isAllowed, tat, err := agent.QpmCheck(l.redisKey, period, limit, reqToConsume)
...
}
QpmCheck 的注释明确说明其采用滑动窗口算法:"Main window: key stores timestamps in a ZSET, period seconds, max limit requests"。也就是说,Redis 中键对应的 ZSET 存储了窗口内的请求时间戳,Lua 脚本(luaScriptQpmCheck,见 redis_lr_agent.go)在单个原子操作内完成"清理过期时间戳 + 统计当前窗口计数 + 判定是否放行"。
这从底层印证了 TC-02 的核心结论:
- 限流状态不在 BFE 进程内存中,而在 Redis 键对应的数据结构里;
redis_key决定读写哪个 ZSET,模型与规则名都不参与;- 因此无论规则名怎么改、模型怎么换、BFE 重启多少次,只要键不变,窗口内的请求计数就不断。
5.3 限流命中后的响应构造
当 checkRPM 返回 false(isAllowed=false)时,模块通过 executePolicyAction 执行产品规则中配置的 hit_action(TC-02 中为 FINISH),依据命中信息生成 CodeRpmLimitExceeded 类型的 AI 错误响应并结束请求处理(BfeHandlerFinish),客户端最终收到 429。
六、测试实现对照:如何复现与断言
TC-02 的自动化实现位于 tests/integration/implementation/scenario-SC07-ai-rate-limit-redis-key/sc07_ai_rate_limit_redis_key_test.go,函数为 TestTC02_RPMCounterPersistsAcrossModelChange。
6.1 测试环境的装配
测试通过 newTestEnv 建立三类基础设施:
common.NewMockBackend(clusterRateLimit, http.StatusOK, usageResponse):mock 后端,返回 200 与带usage字段的响应体;common.NewRedisServer(t):嵌入式 Redis 服务;common.NewProcessEnv(t):进程环境,负责编译并拉起真实bfe。
BFE 配置目录由 tests/integration/common/bfe_config_builder.go 中的 BFEConfigBuilder 基于 testdata 模板动态生成,其中 RateLimitPolicyData 会按测试意图写入 mod_ai_rate_limit/ai_rate_limit.data(见 writeRateLimitPolicyData),这正是"运行时动态控制规则名、模型与 redis_key"的实现机制。
6.2 策略构造函数 rateLimitPolicy
测试用 rateLimitPolicy(ruleName, model, redisKey) 一行式地构造限流策略数据,TC-02 的核心调用是:
// Start BFE with model "gpt-4" and a stable redis_key.
e.startBFE(rateLimitPolicy("rule-1", "gpt-4", rpmRedisKey))
// ... 第一、二次请求断言 200 / 429 ...
// Restart BFE with the same redis_key but a different model.
e.stopBFE()
e.startBFE(rateLimitPolicy("rule-1", "gpt-3.5", rpmRedisKey))
// Send a request matching the new model; the counter should still persist.
resp, body, err = e.sendRequestWithBody([]byte(`{"model":"gpt-3.5"}`))
if resp.StatusCode != http.StatusTooManyRequests {
t.Fatalf("expected third request still 429 after model change, got %d, body: %s", resp.StatusCode, body)
}
三段式断言与设计文档完全一致:200 → 429(重启+换模型)→ 429。测试中 rpmRedisKey 常量即 "RL_RPM_rlp-0001_0",policyID 常量即 "rlp-0001",与设计文档的配置一一对应。sendRequestWithBody 构造的请求固定使用 Host: ratelimit.example.org、Path: /v1/chat/completions、Authorization: Bearer ak_ratelimit。
6.3 关键源码常量
const (
apiHost = "ratelimit.example.org"
apiPath = "/v1/chat/completions"
apiKey = "ak_ratelimit"
clusterRateLimit = "cluster_ratelimit"
policyID = "rlp-0001"
rpmRedisKey = "RL_RPM_rlp-0001_0"
)
七、配置参考:模块配置与规则校验边界
7.1 mod_ai_rate_limit.conf
模块自身的配置文件为 conf/mod_ai_rate_limit/mod_ai_rate_limit.conf,集成测试模板为 testdata/mod_ai_rate_limit/mod_ai_rate_limit.conf,各字段含义如下:
| 配置段 | 字段 | 说明 |
|---|---|---|
[basic] |
ProductRulePath |
限流规则文件 ai_rate_limit.data 的路径 |
[basic] |
IsRejectOnRedisError |
Redis 故障时是否直接拒绝请求(true 拒绝并上报 IsRedisError,false 放行) |
[redis] |
Bns |
Redis 地址或 BNS 名,集成测试中由构建器重写为嵌入式 Redis 地址 |
<a href="https://link.gitcode.com/i/475d48233f2739d305cd0e73c996040d" target="_blank">redis] |
ConnectTimeout / ReadTimeout / WriteTimeout |
连接、读、写超时(ms),配置校验要求三者均大于 0(见 [conf_load.go) |
[redis] |
MaxIdle / MaxActive |
连接池最大空闲数 / 最大活跃数(0 表示不限) |
[log] |
OpenDebug |
是否开启调试日志 |
7.2 ai_rate_limit.data 的字段校验
规则文件的数据结构定义在 bfe_modules/mod_ai_rate_limit/data_load.go,RPM 规则(RPMRuleConfFile)包含 name、window_minutes、max_requests、burst、models、redis_key 六个字段。加载时的 Check 校验规则如下:
window_minutes必须落在[1, 360]区间,换算为TimeWindow = WindowMinutes * 60秒;name必填;burst小于 1 时自动修正为 1;- 同策略内 RPM 规则最多 3 条,且
name不允许重复(LimitRulesConfFile.Check); tpm/rpm/max_concurrency至少配置其一。
TC-02 的 MaxRequests=1, WindowMinutes=1, Burst=1 恰好是"每 60 秒窗口内最多 1 个请求"的最简配置,用于在最小时间尺度上验证连续性。
八、用例体系与运维启示
8.1 三个用例形成闭环
SC07 的三个用例从正反两个方向锁定了 Redis 键语义:
- TC-01(规则重命名) 证明键的优先级是
redis_key> 规则名——改名不丢计数; - TC-02(模型变更,本文) 证明键与模型解耦——换模型不丢计数;
- TC-03(未配置 redis_key) 证明回退路径存在——未显式配置时按规则名生成键,保证旧版本配置的向后兼容。
三者共同验证了 policy_limiter.go 中 buildRpmRedisKey 的三态分支逻辑在真实运行环境下的行为。
8.2 对线上运维的启示
从 SC07 的设计可以提炼出两条可直接落地的实践原则:
- 希望计数器跨配置变更保持连续:在
ai_rate_limit.data中为规则显式配置稳定的redis_key(例如RL_RPM_rlp-0001_0),并保持其在规则调整、模型列表变更、策略改名过程中不变; - 希望计数随规则重置:不配置
redis_key,让 BFE 回退到基于规则名(或参数指纹)的默认键;此时一旦改名,键随之变化,计数器自然清零——这正是 TC-03 验证的兼容行为。
此外,由于计数器存在于 Redis 而非 BFE 进程,重启 BFE 不会丢计数(TC-02 步骤 3 即利用了这一特性),限流状态天然具备跨实例一致性,适合多副本部署场景。
九、清理与运行模式说明
TC-02 属于单组件模式:仅启动真实 bfe 进程与测试框架提供的嵌入式 Redis,不涉及 ai-gateway-api 与 conf-agent。测试结束后,testEnv.Close() 会依次停止 bfe 进程、关闭 mock 后端与嵌入式 Redis,同时 ProcessEnv 负责清理临时配置目录与日志目录。
从依赖关系看,SC07 依赖 SC01 已验证的 mod_ai_route 路由表查找与绑定能力、SC02 已验证的多 API-Key 基础能力,但不依赖 SC03 的 RMB 配额扣减逻辑——这也解释了为何用例只需一个返回 200 的 mock 后端即可完整运行。
小结:TC-02 通过"固定 redis_key、变更 Models、重启 BFE、再次请求仍 429"的严谨三步,验证了 BFE AI 限流计数器的持久性完全由 Redis 键承载。其背后的 buildRpmRedisKey 三态分支、matchModel 规则命中与 QpmCheck 滑动窗口原子判定,构成了 mod_ai_rate_limit 可热更新、可跨重启、可多实例共享的限流能力基石。如需深入,可继续阅读 场景说明 与 policy_limiter.go 源码。