BFE AI 网关 anthropic 协议路径改写实战:从 `/v1/messages` 到 `/apps/anthropic/v1/messages`(TC-02 用例深度解析)
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值为该协议官方 SDKbase_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 中实现,分两层:
DetectProtocolAndKey(凭据提取,Authorization优先):- 优先取
Authorization: Bearer(剥离Bearer与sk-前缀)→ openai 风格; - 回退到
x-api-key→ anthropic 风格; - 再回退到
x-goog-api-key→ gemini 风格。
- 优先取
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 文档给出的改写计算四步为:
- 协议识别:
x-api-key→ AuthStyle=anthropic; - 协议匹配:
ModelProtocols含 anthropic,放行; - 路径判定:
/v1/messages命中标准入口; - 改写: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。其背后的设计要点可归纳为:
- 配置驱动、单机制公式化:是否改写、改写到什么前缀完全由 cluster 的
AIConf.ProtocolPaths决定,BFE 代码不硬编码任何 provider 品牌; - 协议差异内化在公式里:anthropic 追加完整路径、openai 去
/v1前缀,分别对应两个 SDK 的base_url拼接行为; - 原始路径不被污染:改写只落在
outreq的私有 URL 拷贝,保证 fallback 每次 attempt 从原始客户端路径重算; - 严格边界:标准入口判定(
/v1//v1/前缀)、key 白名单与 value 格式的加载期校验、未配置时逐字节透传,共同构成向后兼容与 fail-fast 的双重保障。