BFE AI 协议路径改写之"非标准入口透传":TC-06 用例的技术原理与验证
BFE AI 协议路径改写之"非标准入口透传":TC-06 用例的技术原理与验证
BFE(Baidu Front End)是百度开源的现代化七层负载均衡器,其 AIConf.ProtocolPaths 特性支持按 AI 协议(openai / anthropic)将客户端入口路径改写为 provider 上游 API 基路径。本文以集成测试设计文档 TC-06 非标准入口透传 为核心,完整还原该用例的前置条件、请求构造、改写计算与断言设计,并结合 ai_path_rewrite.go 等源码与 SC17 场景说明 展开原理级解读,帮助读者理解"标准入口判定"的精确边界,以及 BFE 如何保证非标准入口路径永不改写(透传模式不受影响)。
一、用例所属场景:SC17 AI 协议路径改写
TC-06 是 SC17 场景(AI 协议路径改写,AIConf.ProtocolPaths)的 6 号测试用例。该场景解决的业务问题是:不同 model provider 的上游路径各不相同,且同一 provider 的不同协议(OpenAI 兼容 / Anthropic 兼容)挂在不同前缀下——例如百炼的 OpenAI 兼容端点为 /compatible-mode/v1、Anthropic 兼容端点为 /apps/anthropic;火山方舟按量为 /api/v3、Coding Plan 为 /api/coding/v3。
AIConf.ProtocolPaths 允许按协议声明上游 API 基路径(即该协议官方 SDK base_url 的 path 部分),BFE 在转发时将客户端入口路径改写为 provider 专属前缀。完整的设计背景与公式推导见 ai_protocol_paths.md,SC17 场景共包含 8 个测试用例(TC-01 至 TC-08),覆盖:
- openai / anthropic 两种协议分别按配置改写(含双协议 cluster 独立改写,TC-03);
- cluster 级 fallback 时按原始客户端路径重算上游路径(TC-04);
- 未配置
ProtocolPaths时请求路径逐字节透传(TC-05,向后兼容); - 非标准入口路径永不改写(TC-06,本文主题);
- openai 无
/v1入口改写为与/v1入口相同结果(TC-07 / TC-08,issue #1379)。
TC-06 的定位是上述场景验证清单中的第 4 条:"非标准入口路径(provider 原生路径、/v10/xxx、gemini 风格路径)与未命中 openai 标准端点的路径永不被改写(透传模式不受影响)"。它是整个改写特性的边界安全网——保证特性只作用于标准 /v1/... 入口,绝不误伤其他路径。
二、测试目的与两类"非标准入口"
TC-06 的测试目的是:验证 ProtocolPaths 已配置时,非标准入口路径仍永不改写。用例聚焦两类典型场景:
- provider 原生路径:
/compatible-mode/v1/chat/completions——客户端按 provider 原生路径访问的透传模式不受影响。注意该路径虽形似标准入口(内含/v1段),但整条路径不以/v1开头,因此不被判定为标准入口; - 形似但不匹配的前缀:
/v10/xxx——标准入口判定要求reqPath == "/v1"或以"/v1/"开头,/v10只是与/v1共享字符前缀,前缀判定不会误伤。
用一句话概括:改写特性存在时,只有"标准 /v1 入口"被改写,其余所有路径一律原样透传。
三、运行模式与前置条件
TC-06 采用单组件模式:仅启动真实 bfe 进程,不涉及 ai-gateway-api 与 conf-agent。AIConf.ProtocolPaths 由测试代码经 BFEConfigBuilder 直接写入生成的 cluster_conf.data(场景说明的"运行模式"一节明确说明,参见 场景说明.md)。
测试环境的 cluster_primary 配置如下(AIConf 形态与 sc17_ai_protocol_paths_rewrite_test.go 中 TestTC06_NonStandardEntryPassthrough 的构造完全一致):
{
"Type": 0,
"ModelProtocols": ["openai", "anthropic"],
"ProtocolPaths": {"openai": "/api/v3"}
}
关键配置语义:
ModelProtocols: ["openai", "anthropic"]:声明 cluster 支持的协议。场景说明强调,所有测试例的cluster_primary/cluster_fallback均声明这两个协议,否则 anthropic 请求会在协议匹配处被PROVIDER_PROTOCOL_MISMATCH拒绝;ProtocolPaths: {"openai": "/api/v3"}:openai 协议的上游基路径为/api/v3(火山方舟按量的 SDKbase_urlpath 形态)。该配置是"改写已就绪"的证据——TC-06 要验证的正是在改写开关已打开的情况下,非标准路径依然透传;cluster_fallback在本用例不配置ProtocolPaths,且断言其命中数为 0。
另外,测试环境还启动 cluster_default mock 后端(basic 路由引用,测试断言不命中),其细节同样可见于 场景说明.md 的"涉及的 BFE 配置文件"一节。
四、BFE 请求构造
TC-06 按序发送 2 次 openai 风格请求,均为 POST,Host 为 api.example.org,认证头为 Authorization: Bearer ak_user_a(ak_user_a 用于 mod_ai_route 的 apikey 级路由查找,命中 default_t() 规则 → cluster_primary,fallback → cluster_fallback):
| 序号 | 请求路径 | 判定 |
|---|---|---|
| 1 | /compatible-mode/v1/chat/completions |
非标准入口(不以 /v1 开头) |
| 2 | /v10/xxx |
非标准入口(/v10 不等于 /v1,前缀判定不匹配) |
测试代码中,这两条请求通过 sendRequest(path, authHeader, body) 发送(参见 sc17_ai_protocol_paths_rewrite_test.go 中 TestTC06_NonStandardEntryPassthrough),请求体为 openai 风格的 {"model":"test-model","messages":[{"role":"user","content":"hello"}]}。
五、改写计算:为什么这两条路径"永不改写"
两条请求均不满足 isStandardV1Prefix,落入透传分支:upstream = reqPath。这一点需要结合源码逐层理解。
5.1 入口判定:isStandardV1Prefix
改写公式的入口判定实现在 ai_path_rewrite.go 中:
// isStandardV1Prefix reports whether reqPath is exactly "/v1" or starts
// with "/v1/". Paths like "/v10/xxx" do not match.
func isStandardV1Prefix(reqPath string) bool {
return reqPath == "/v1" || strings.HasPrefix(reqPath, "/v1/")
}
关键点在于 strings.HasPrefix(reqPath, "/v1/") 的写法:它要求 /v1 之后必须紧跟 /。因此:
/v10/xxx虽然以/v1开头,但第 4 个字符是0而非/,HasPrefix("/v10/xxx", "/v1/")为false,且reqPath != "/v1",故判定为非标准入口;/compatible-mode/v1/chat/completions以/c开头,前缀判定直接不成立,同样落入非标准分支。
对比之下,若误用 strings.HasPrefix(path, "/v1")(缺少末尾斜杠)实现,/v10/xxx 会被 /v1 命中并改写成 /api/v3/0/xxx——这正是 TC-06 的"改写计算"一节所警示的实现错误:"第二条若误用 strings.HasPrefix(path, "/v1") 实现,会被 /v10 命中并改写成 /api/v3/0/xxx——本用例的断言能暴露该实现错误。"也就是说,本用例的存在价值之一就是以断言捕获这种边界实现缺陷。
5.2 透传分支:rewriteUpstreamPath
整体改写函数 rewriteUpstreamPath 依次经过三道拦截,任何一道命中即返回原路径:
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、/v1/ 或剥离 /v1 后命中标准端点才改写
if reqPath == "/v1" || reqPath == "/v1/" {
return base
}
rest := bfe_basic.StripV1Prefix(reqPath)
if !bfe_basic.IsOpenAIEndpoint(rest) {
return reqPath
}
return base + rest
}
对 TC-06 的两条 openai 风格请求(authStyle == "openai",base = "/api/v3")逐一推演:
/compatible-mode/v1/chat/completions:既不是/v1也不是/v1/;StripV1Prefix仅剥离开头的/v1/前缀,该路径开头是/compatible-mode,剥离步骤恒等返回原路径;IsOpenAIEndpoint("/compatible-mode/v1/chat/completions")无法命中 openai_endpoint.go 中openAIEndpointModes表的任何标准端点(端点匹配要求路径本身以/chat/completions等标准端点开头,或剥离/v1后匹配)——最终透传,upstream = /compatible-mode/v1/chat/completions;/v10/xxx:不满足isStandardV1Prefix(见 5.1 节);即便继续走到StripV1Prefix,/v10/xxx也不以/v1/开头,剥离恒等;IsOpenAIEndpoint("/v10/xxx")为false(既不在端点表中,也不以任何端点 +/开头)——最终透传,upstream = /v10/xxx。
值得注意的还有 openai_endpoint.go 中 StripV1Prefix 的注释明确写到的边界语义:"paths without the prefix (including /v10/xxx and provider-native paths such as /compatible-mode/v1/chat/completions) are returned unchanged"。该函数被 DetectModeFromPath(计费模式识别)与 bfe_server 路径改写共享,保证"端点兼容性判定"与"计费模式识别"对标准端点的认定永远一致。
5.3 openai 与 anthropic 的入口判定差异
值得注意的是,两条透传分支的入口判定在源码中有两处独立的实现:
- anthropic 分支:直接调用
isStandardV1Prefix,只改写/v1或/v1/...(Anthropic SDK 自行拼接/v1/messages,故基路径不含/v1尾); - openai 分支:不调用
isStandardV1Prefix,而是"精确/v1、/v1/返回基路径;否则StripV1Prefix+IsOpenAIEndpoint双条件"(OpenAI SDK 向含/v1尾的 base_url 拼接/chat/completions等资源路径,客户端入口可能带也可能不带/v1前缀,issue #1379)。
但两分支对 TC-06 两类路径的结论一致:非标准入口一律透传。这正是设计文档 ai_protocol_paths.md 第 4.2 节"三个要点"中的第一条:"本特性依赖'网关对外入口 = /v1/...'这一约定……客户端直连 provider 原生路径(透传模式)不受影响——非 /v1 开头的路径一律透传"。
5.4 改写只落在 outreq 的私有 URL 拷贝
最后一步保障来自 applyAIProtocolPathRewrite:即使发生改写,结果也只写入 outreq 的私有 URL 拷贝(u := *outreq.URL; u.Path = newPath; u.RawPath = ""),入站请求 URL 永不修改,因此每次 cluster attempt(包括 fallback)都从原始客户端路径重新计算(参见 ai_path_rewrite.go 的 applyAIProtocolPathRewrite 与 reverseproxy.go 中 doSingleAIForward 调用点 applyAIProtocolPathRewrite(outreq, aiMeta.AuthStyle, cluster.AIConf))。TC-06 的两条透传路径改写前后相等,applyAIProtocolPathRewrite 直接提前返回,共享 URL 指针,行为与未配置特性时逐字节一致。
六、预期结果与断言设计
TC-06 的预期结果如下:
| 断言 | 预期 |
|---|---|
| 两次响应状态码 | 200 |
cluster_primary 后端收到的路径序列 |
[/compatible-mode/v1/chat/completions, /v10/xxx],与请求路径逐一相等 |
cluster_fallback 命中数 |
0 |
对应的实现为 sc17_ai_protocol_paths_rewrite_test.go 中 TestTC06_NonStandardEntryPassthrough:
- 通过
assertStatus(t, e, resp, respBody, http.StatusOK)断言两次响应均为 200; - 通过
assertPaths(t, e.backends[clusterPrimary], []string{"/compatible-mode/v1/chat/completions", "/v10/xxx"})断言cluster_primary后端按序收到两条与原请求路径逐一相等的路径(透传),这是本用例最核心的断言; - 用例未显式断言
cluster_fallback命中数为 0,但路由设计保证请求命中cluster_primary且 primary 返回 200,fallback 不会触发。
其中 mock 后端的路径观测点 URLPaths() 实现在 mock_backend.go(func (b *MockBackend) URLPaths() []string,返回所有观测到的请求 URL 路径的深拷贝),是 场景说明.md 所述"新增 URLPaths() 观测点记录后端收到的请求路径"的落地。
七、TC-06 在整个 SC17 场景中的价值
将 TC-06 与相邻用例对比,可以更清晰地看出其独特价值:
| 用例 | 配置形态 | 验证点 |
|---|---|---|
| TC-01 | {openai: /compatible-mode/v1} |
标准 /v1/chat/completions 入口被改写 |
| TC-05 | 无 AIConf(nil) | 未配置时全路径透传(向后兼容) |
| TC-06 | {openai: /api/v3} |
配置已打开时,非标准入口仍透传 |
| TC-07 | {openai: /compatible-mode/v1} |
无 /v1 入口与 /v1 入口改写结果相同 |
TC-05 与 TC-06 看似都在验证"透传",但语义截然不同:TC-05 验证的是特性关闭时的默认行为(cluster.AIConf == nil → rewriteUpstreamPath 第一分支直接返回原路径);TC-06 验证的是特性开启时改写公式的边界不变量——ProtocolPaths 只对"标准 /v1 入口"生效,对 provider 原生路径与形似前缀(/v10/xxx)绝不误伤。
这一"永不改写"保证具有重要的业务含义:
- 透传模式不受影响:客户端直连 provider 原生路径的存量调用方式,在配置了
ProtocolPaths后行为不变,无需迁移; - 实现缺陷可被暴露:若标准入口判定实现不当(如
strings.HasPrefix(path, "/v1")缺少末尾斜杠),TC-06 的路径序列断言会立即失败,将/v10/xxx被错误改写为/api/v3/0/xxx的实现错误暴露在测试期而非线上。
设计文档 ai_protocol_paths.md 第 4.3 节场景验证表也明确列出该边界:"边界:/v1 精确值与 /v1/ 前缀才进入改写;/v10/xxx、gemini 风格 /v1beta/... 一律透传。"TC-06 正是该边界声明的可执行化验证。
八、运行方式
SC17 场景的集成测试整体运行方式见 场景说明.md 的"运行方式"一节:
go test ./tests/integration/implementation/scenario-SC17-ai-protocol-paths-rewrite/ -v
该命令会依次执行 TC-01 至 TC-08 全部用例(对应 sc17_ai_protocol_paths_rewrite_test.go 中的 TestTC01 至 TestTC08 各测试函数),其中 -v 用于输出每个用例的执行详情。测试框架负责启动真实 bfe 进程与 mock 后端、动态生成 cluster_conf.data 与 cluster_conf/cluster_table.data(后端地址动态写入),并按用例注入不同 AIConf。
总结
TC-06 非标准入口透传是 SC17 AI 协议路径改写场景的边界守护用例。它用两个精心构造的请求(provider 原生路径 /compatible-mode/v1/chat/completions 与形似前缀 /v10/xxx)验证了改写公式的不变量:ProtocolPaths 已配置时,非标准入口路径仍永不改写。其背后是 ai_path_rewrite.go 中 isStandardV1Prefix 的精确前缀判定(/v1 或 /v1/ 开头)、openai_endpoint.go 中 StripV1Prefix 与 IsOpenAIEndpoint 的标准端点白名单,以及"改写只落 outreq 私有 URL 拷贝、入站路径永不污染"的正确性设计。理解 TC-06,就等于理解了 BFE 协议路径改写特性"只改标准、绝不误伤"的完整边界。