BFE AI 限流 Redis 键稳定性验证:规则重命名后 RPM 计数器保持连续的实现原理与测试设计(SC07 TC-01)

原创2026-10-11 16:17:571,352 阅读
文章标签:后端网络/通信云原生

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 前置条件

  1. 已编译 bfe 可执行文件;
  2. 嵌入式 Redis 已启动;
  3. mock 后端 cluster_ratelimit 已启动,返回 200;
  4. 临时 BFE 配置已生成并加载,包含 mod_ai_rate_limit 规则:
    • 规则名:old-rule
    • 模型:gpt-4
    • redis_key: RL_RPM_rlp-0001_0
    • MaxRequests: 1
    • WindowMinutes: 1
    • Burst: 1
  5. ai_route.data 中 apikey_ak_ratelimit 命中 ratelimit-default,target 为 cluster_ratelimit;
  6. 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_ratelimit mock 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)))
}

对应三种分支:

  1. 完整键直通:redis_key 以 default_bfe_ 开头(新格式),视为控制面下发的完整键,直接使用;
  2. 后缀拼接: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;
  3. 按规则名回退: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,其流程与设计文档严格对应:

  1. 构造 testEnv:启动 mock backend(返回 200 + usage 响应体)、嵌入式 Redis、编译/运行环境;
  2. rateLimitPolicy("old-rule", "gpt-4", rpmRedisKey) 动态生成限流数据并 startBFE;
  3. 发送第 1 次请求,断言 200;发送第 2 次请求,断言 429;
  4. e.stopBFE() 停止 BFE 进程;
  5. rateLimitPolicy("new-rule", "gpt-4", rpmRedisKey) 重新生成配置并 startBFE(Redis 未重启,计数器保留);
  6. 发送第 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 网关在限流规则频繁调整场景下保持计费与限流连续性的关键保障。

登录后查看全文
bfe