BFE AI 限流 Redis 键连续性:模型变更后 RPM 计数器保持不断的原理与验证(SC07 TC-02)

原创2026-10-11 14:44:271,639 阅读
文章标签:后端网络/通信云原生

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 键的解析顺序是典型的"三态分支":

  1. RedisKey 非空且以 default_bfe_ 开头:视为控制面下发的完整 Redis Key,直接原样使用,不再做任何拼接;
  2. RedisKey 非空但不以 default_bfe_ 开头:视为"后缀",按 default_bfe_<policyId>_<suffix> 格式拼接出完整键(兼容旧格式下发);
  3. 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 前置条件

  1. 已编译 bfe 可执行文件;
  2. 嵌入式 Redis 已启动;
  3. mock 后端 cluster_ratelimit 已启动,返回 200;
  4. 临时 BFE 配置已生成并加载,包含 mod_ai_rate_limit 规则:
    • 规则名:rule-1
    • 模型:gpt-4
    • redis_key: RL_RPM_rlp-0001_0
    • MaxRequests: 1
    • WindowMinutes: 1
    • Burst: 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_ratelimit mock 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 的设计可以提炼出两条可直接落地的实践原则:

  1. 希望计数器跨配置变更保持连续:在 ai_rate_limit.data 中为规则显式配置稳定的 redis_key(例如 RL_RPM_rlp-0001_0),并保持其在规则调整、模型列表变更、策略改名过程中不变;
  2. 希望计数随规则重置:不配置 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 源码。

登录后查看全文
bfe