BFE AI 网关 anthropic 协议路径改写实战:从 `/v1/messages` 到 `/apps/anthropic/v1/messages`(TC-02 用例深度解析)

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

BFE AI 网关 anthropic 协议路径改写实战:从 /v1/messages 到 /apps/anthropic/v1/messages(TC-02 用例深度解析)

本文以 BFE 开源仓库集成测试用例 TC-02(anthropic 协议路径改写)为核心,系统讲解 AIConf.ProtocolPaths 如何将 Anthropic 兼容协议的客户端标准入口 /v1/messages 改写为 provider 上游基路径(百炼形态 /apps/anthropic/v1/messages)。文章覆盖配置模型、改写公式、协议识别、fallback 重算语义与源码级验证,读者可据此理解并复现 AI 网关按协议改写上游路径的完整链路。

一、用例定位:SC17 场景中的 TC-02

TC-02 属于集成测试场景 SC17「AI 协议路径改写(AIConf.ProtocolPaths)」,该场景共 8 个用例(TC-01 ~ TC-08),围绕同一核心特性展开:

  • TC-01 / TC-02 / TC-03:openai、anthropic 单协议改写及双协议 cluster 独立改写;
  • TC-04:fallback 时从原始客户端路径重算(专利场景,本特性的正确性关键);
  • TC-05 / TC-08:未配置 ProtocolPaths 时的逐字节透传(向后兼容);
  • TC-06:非标准入口路径永不改写;
  • TC-07:openai 无 /v1 入口改写(issue #1379,兼容 Trae 等直连 base_url 的客户端)。

TC-02 锁定的是 anthropic 语义与 openai 语义的核心差异:anthropic 的改写是追加完整路径(/apps/anthropic + /v1/messages),而 openai 是去 /v1 前缀后追加(/compatible-mode/v1 + /chat/completions)。这一差异的根源在于两个协议官方 SDK 的 base_url 语义不同,详见下文第四节。

相关说明文档见 场景说明.md,对应设计文档为 ai_protocol_paths.md 与 design-changes.md。

二、测试目的与运行模式

2.1 测试目的

验证 anthropic 协议请求 /v1/messages(携带 x-api-key 认证头)在命中 cluster_primary 后被改写为 {ProtocolPaths["anthropic"]}/v1/messages,即百炼形态的 /apps/anthropic/v1/messages。同时断言 cluster_fallback 零命中,确保改写只发生在主 cluster 且不会触发非预期的降级。

2.2 运行模式:单组件模式

本用例采用单组件模式:仅启动真实 bfe 进程,不依赖 ai-gateway-api 与 conf-agent。AIConf.ProtocolPaths 由测试代码经 BFEConfigBuilder 直接写入动态生成的 cluster_conf.data(见 sc17_ai_protocol_paths_rewrite_test.go 中 newTestEnv 的 builder.Build() 调用),mock AI 后端通过 common.MockBackend 启动,并以 URLPaths() 观测点记录后端实际收到的请求路径。

该场景涉及的 BFE 配置文件如下:

文件 说明
bfe.conf 加载 mod_ai_route(不加载 mod_ai_token_auth,apikey 仅用于路由查找)
mod_ai_route/ai_route.data apikey 级路由:ak_user_a 命中 default_t() 规则 → cluster_primary,fallback 至 cluster_fallback
server_data_conf/host_rule.data / route_rule.data / vip_rule.data 产品线 Host、basic 路由(basic 路由引用 cluster_default)、VIP 配置
cluster_conf/gslb.data cluster_primary / cluster_fallback / cluster_default 的 subcluster 权重
cluster_conf/cluster_table.data 运行时根据 mock 后端地址动态生成
cluster_conf/cluster_conf.data 运行时动态生成,按测试例注入各 cluster 的 AIConf(含 ProtocolPaths 与 ModelProtocols)

其中路由配置的真实样例位于 testdata/mod_ai_route/ai_route.data:apikey_ak_user_a 规则的条件为 default_t(),targets 指向 cluster_primary(权重 100),fallbacks 指向 cluster_fallback。

三、前置条件:cluster_primary 的 AIConf 配置

TC-02 用例中 cluster_primary.AIConf 配置如下:

{
    "Type": 0,
    "ModelProtocols": ["openai", "anthropic"],
    "ProtocolPaths": {"anthropic": "/apps/anthropic"}
}

要点解读:

  • ModelProtocols 必须显式声明 anthropic:ModelProtocols 为空时默认仅支持 openai(向后兼容语义,见 cluster_conf_load.go 中 AIConf 结构体注释);anthropic 请求会在协议匹配处被 PROVIDER_PROTOCOL_MISMATCH 拒绝。协议匹配发生在 doSingleAIForward 中,通过 clusterSupportsAuthStyle 比较请求 AuthStyle 与 cluster.AIConf.ModelProtocols(见 reverseproxy.go):
    if cluster.AIConf != nil && !clusterSupportsAuthStyle(cluster.AIConf.ModelProtocols, aiMeta.AuthStyle) {
        // 返回 CodeProviderProtocolMismatch 错误
    }
    
  • ProtocolPaths 的 key 取值域为 {openai, anthropic},与 ModelProtocols 同命名空间;AuthStyle 直接作为 key 使用(bfe_basic.AuthStyleAnthropic = "anthropic",见 request_ai_basic.go)。
  • ProtocolPaths 值为该协议官方 SDK base_url 的 path 部分:anthropic 不含 /v1(Anthropic SDK 自行拼接 /v1/messages),因此 /apps/anthropic + SDK 拼接的 /v1/messages = 百炼真实上游路径 /apps/anthropic/v1/messages。

cluster_fallback 与 cluster_default 在本用例中不配置 ProtocolPaths(场景说明中 TC-02 行的 fallback 列为「无」)。

3.1 加载期校验:fail-fast

AIConf.ProtocolPaths 并非任意字符串映射,加载期即做严格校验。校验入口为 AIConfCheck → AIProtocolPathsCheck → checkUpstreamBasePath(见 cluster_conf_load.go):

  • key 白名单:必须为 openai 或 anthropic,未知 key(拼写错误、控制面 bug、手工改 conf 引入的 gemini 等)返回 error,导致启动失败或热加载拒绝;
  • value 格式:必须以 / 开头、不以 / 结尾、不含 .. / ? / #、长度 ≤ 128。

这一设计遵循 fail-fast 原则:配置错误在加载期响亮失败,而不是运行期静默透传成上游 404。完整字段说明与合法性条件见 cluster_conf.data.md。

四、BFE 请求构造

TC-02 发送 1 次 POST 请求,字段如下:

字段 值
目标地址 http://127.0.0.1:<bfePort>/v1/messages
Host api.example.org
x-api-key ak_user_a
Body {"model":"test-model","messages":[...],"max_tokens":1}

请求特征对应源码中的发送构造(见 sc17_ai_protocol_paths_rewrite_test.go 的 sendAnthropic 与 sendRequest):

  • Host 固定为 api.example.org(命中产品线 Host 规则);
  • 认证头使用 x-api-key 而非 Authorization: Bearer——这是 anthropic 风格的凭证形态;
  • Body 为 anthropic 消息体:{"model":"test-model","messages":[{"role":"user","content":"hello"}],"max_tokens":1}。

4.1 协议识别:x-api-key → AuthStyle=anthropic

BFE 对请求协议的识别链在 detect.go 中实现,分两层:

  1. DetectProtocolAndKey(凭据提取,Authorization 优先):
    • 优先取 Authorization: Bearer(剥离 Bearer 与 sk- 前缀)→ openai 风格;
    • 回退到 x-api-key → anthropic 风格;
    • 再回退到 x-goog-api-key → gemini 风格。
  2. DetectProtocol(纯路径/头特征推断):
    • /v1/messages 前缀直接判定为 anthropic;
    • :generateContent / :streamGenerateContent 后缀或 /v1beta/models/ 前缀判定为 gemini;
    • 仅有 x-api-key 而无 Authorization 时判定为 anthropic。

TC-02 请求携带 x-api-key: ak_user_a 且路径为 /v1/messages,两条路径均指向 anthropic,AuthStyle 稳定取值为 anthropic。协议识别结果由 bfe_basic.DetectAuthStyle(request_ai_basic.go)在 doSingleAIForward 中兜底探测并写入 aiMeta.AuthStyle。

五、改写计算:anthropic 的追加完整路径语义

TC-02 文档给出的改写计算四步为:

  1. 协议识别:x-api-key → AuthStyle=anthropic;
  2. 协议匹配:ModelProtocols 含 anthropic,放行;
  3. 路径判定:/v1/messages 命中标准入口;
  4. 改写:anthropic 语义为追加完整路径——upstream = /apps/anthropic + /v1/messages。

对应源码实现为 rewriteUpstreamPath(ai_path_rewrite.go):

func rewriteUpstreamPath(reqPath string, authStyle string, aiConf *cluster_conf.AIConf) string {
    if aiConf == nil {
        return reqPath
    }
    base, ok := aiConf.ProtocolPaths[authStyle]
    if !ok {
        return reqPath
    }
    if authStyle == bfe_basic.AuthStyleAnthropic {
        if !isStandardV1Prefix(reqPath) {
            return reqPath
        }
        return base + reqPath
    }
    // openai: 去 /v1 前缀后追加 base
    ...
}

5.1 标准入口判定 isStandardV1Prefix

anthropic 分支要求请求路径命中「标准入口」,判定规则为(ai_path_rewrite.go):

func isStandardV1Prefix(reqPath string) bool {
    return reqPath == "/v1" || strings.HasPrefix(reqPath, "/v1/")
}

即:reqPath == "/v1" 或 /v1/ 前缀才进入改写;/v10/xxx、/v1beta/... 等路径不匹配,一律透传。/v1/messages 满足 /v1/ 前缀条件,进入改写分支。

5.2 anthropic 与 openai 语义对照

协议 SDK base_url 形态 改写公式 TC-02 计算
anthropic 不含 /v1(/apps/anthropic、/coding、/anthropic) base + reqPath(追加完整路径) /apps/anthropic + /v1/messages → /apps/anthropic/v1/messages
openai 含 /v1 尾(/compatible-mode/v1、/api/v3、/coding/v1) base + reqPath[len("/v1"):](去 /v1 前缀后追加) /compatible-mode/v1 + /chat/completions → /compatible-mode/v1/chat/completions

这一语义与两个协议官方 SDK 的行为完全自洽:OpenAI SDK 向含 /v1 尾的 base_url 追加 /chat/completions 等资源路径;Anthropic SDK 向不含 /v1 的 base_url 自行拼接 /v1/messages。选择「SDK base_url 的 path 部分」作为配置语义,使配置值可直接照抄各 provider 官方文档的 base_url 一栏,降低配置错误率(详见 ai_protocol_paths.md §3.3)。

5.3 改写落点:私有 URL 拷贝,绝不污染入站请求

改写的执行函数为 applyAIProtocolPathRewrite(ai_path_rewrite.go),其关键正确性设计是:

u := *outreq.URL   // 拷贝 URL 结构体
u.Path = newPath   // 只改拷贝
u.RawPath = ""
outreq.URL = &u    // 挂回 outreq
  • 改写结果只写入 outreq 的私有 URL 拷贝,入站请求 basicReq.HttpRequest.URL.Path 永不被修改;
  • doSingleAIForward 每次 attempt 都从原始请求重新拷贝 outreq(*outreq = *req,见 reverseproxy.go),因此 每次 cluster attempt(含 route 级 fallback)都从原始客户端路径重新计算,与 computeTargetModel「Always start from ClientModel for every cluster attempt」的既有原则同构;
  • 未配置改写的请求保持原 URL 指针,行为与纯透传逐字节一致。

applyAIProtocolPathRewrite 在 reverseproxy.go 处被调用,位置在 outreq 创建之后、clusterInvoke 之前,此时协议(aiMeta.AuthStyle)与 cluster(cluster.AIConf)均已确定。

六、预期结果与断言

TC-02 的断言表如下:

断言 预期
响应状态码 200
cluster_primary 后端收到的请求路径 [/apps/anthropic/v1/messages]
cluster_fallback 命中数 0

对应测试实现 TestTC02_AnthropicPathRewrite(sc17_ai_protocol_paths_rewrite_test.go):

resp, respBody, err := e.sendAnthropic(anthropicBody())
assertStatus(t, e, resp, respBody, http.StatusOK)
assertPaths(t, e.backends[clusterPrimary], []string{"/apps/anthropic/v1/messages"})
if e.backends[clusterFallback].Hits() != 0 {
    t.Fatalf("expected 0 hit on %s, got %d", clusterFallback, e.backends[clusterFallback].Hits())
}

其中 assertPaths 通过 mock 后端的 URLPaths() 观测点断言实际接收到的请求路径列表,Hits() 统计后端命中次数。三层断言共同验证:改写结果正确、主 cluster 恰好承接请求、fallback 未发生。

七、场景级纵深:边界行为与正确性关键

TC-02 验证的是 anthropic 改写的「正向路径」,而 SC17 场景的其余用例为这一特性划定了完整的边界:

7.1 fallback 路径重算(TC-04,专利场景)

route 级 fallback 切换到不同 ProtocolPaths 配置的 cluster 时,第二次 attempt 从原始客户端路径按 fallback cluster 自身配置重算,而非继承第一次 attempt 的改写结果。TC-04 用两个差异显著的前缀(百炼 /apps/anthropic vs Kimi Code /coding)把「继承错误」变成可观测的路径断言:

attempt cluster 计算 结果
第 1 次 cluster_primary(返回 503) /apps/anthropic + /v1/messages /apps/anthropic/v1/messages
第 2 次 cluster_fallback 原始 /v1/messages → /coding + /v1/messages /coding/v1/messages

若改写污染了入站请求,第 2 次 attempt 的 reqPath 将是 /apps/anthropic/v1/messages——不命中标准入口判定,落入透传,fallback 后端将收到错误路径。详见 TC-04-fallback路径重算.md。

7.2 未配置透传(TC-05 / TC-08)

ProtocolPaths 为空/nil(AIConf 为 nil)时,openai 与 anthropic 请求路径均原样转发(/v1/chat/completions、/v1/messages),行为与现状逐字节一致,保证向后兼容。详见 TC-05-未配置透传.md。

7.3 非标准入口透传(TC-06)

即使配置了 ProtocolPaths,provider 原生路径(如 /compatible-mode/v1/chat/completions)与 /v10/xxx 等非标准入口也永不改写——客户端始终可以以 provider 原生路径访问网关(透传模式不受影响)。详见 TC-06-非标准入口透传.md。

7.4 双协议独立改写(TC-03)

同一 cluster 可同时配置 openai 与 anthropic 两条 ProtocolPaths(Kimi Code 形态:{"openai": "/coding/v1", "anthropic": "/coding"}),openai 与 anthropic 请求按各自公式独立改写:/v1/chat/completions → /coding/v1/chat/completions,/v1/messages → /coding/v1/messages。详见 TC-03-双协议cluster独立改写.md。

7.5 openai 无 /v1 入口(TC-07 / TC-08,issue #1379)

客户端直连 base_url(如 Trae)时入口可能不带 /v1(/chat/completions)。openai 语义保证带不带 /v1 的入口改写结果相同:均得到 /compatible-mode/v1/chat/completions;未配置 ProtocolPaths 时则逐字节透传。详见 TC-07-openai无v1入口改写.md 与 TC-08-openai无v1入口未配置透传.md。

7.6 常见 provider 的 ProtocolPaths 参考值

以下参考值来自 cluster_conf.data.md,可直接对照使用:

provider ProtocolPaths
百炼 DashScope {"openai": "/compatible-mode/v1", "anthropic": "/apps/anthropic"}
Kimi 开放平台(api.moonshot.cn) {"openai": "/v1", "anthropic": "/anthropic"}
Kimi Code 会员(api.kimi.com) {"openai": "/coding/v1", "anthropic": "/coding"}
DeepSeek {"openai": "/v1", "anthropic": "/anthropic"}
火山方舟·按量 {"openai": "/api/v3", "anthropic": "/api/compatible"}
火山方舟·Coding Plan {"openai": "/api/coding/v3", "anthropic": "/api/coding"}

八、运行方式

在仓库根目录执行以下命令运行 SC17 场景全部集成测试:

go test ./tests/integration/implementation/scenario-SC17-ai-protocol-paths-rewrite/ -v

若要单独运行 TC-02:

go test ./tests/integration/implementation/scenario-SC17-ai-protocol-paths-rewrite/ -run TestTC02 -v

测试框架的公共前置条件(见 测试场景总体说明.md):测试直接使用当前源码 go build 编译的 bfe 可执行文件(产物缓存于 bfe/tests/integration/.integration-test-bin/,同一次运行只编译一次);每个测试例拥有独立临时工作目录与随机监听端口;mock AI 后端经 httptest.Server 启动,其地址在测试运行时动态写入 cluster_table.data。

九、总结

TC-02 以最小的单请求形态,完整验证了 BFE AI 网关 anthropic 协议路径改写的主链路:x-api-key 触发 anthropic 协议识别 → ModelProtocols 协议放行 → /v1/messages 命中标准入口 → 按「追加完整路径」公式改写为 /apps/anthropic/v1/messages。其背后的设计要点可归纳为:

  1. 配置驱动、单机制公式化:是否改写、改写到什么前缀完全由 cluster 的 AIConf.ProtocolPaths 决定,BFE 代码不硬编码任何 provider 品牌;
  2. 协议差异内化在公式里:anthropic 追加完整路径、openai 去 /v1 前缀,分别对应两个 SDK 的 base_url 拼接行为;
  3. 原始路径不被污染:改写只落在 outreq 的私有 URL 拷贝,保证 fallback 每次 attempt 从原始客户端路径重算;
  4. 严格边界:标准入口判定(/v1 / /v1/ 前缀)、key 白名单与 value 格式的加载期校验、未配置时逐字节透传,共同构成向后兼容与 fail-fast 的双重保障。
登录后查看全文
bfe