《micro-one-api 拆解》第 32 篇 代码核对:
v0.41.0/372391f(2026-11-12) 主要改动:B2/C2 与 v0.37.1 中继修复,2026-10-29 至 11-12 主要来源:B2 冻结契约、B2/C2 runbook、v0.37.1/v0.38.0/v0.41.0 release note
0. 客户端看到 [DONE] 的时候,账到底落了没有
v0.37.1 里有一条很小的顺序修改:Chat SSE 正常结束时,不再先发 data: [DONE] 再结算,而是按“内容交付 → commit → DONE → usage log”收尾。
这行顺序看起来只影响几毫秒,实际改变的是客户端对成功的理解。旧顺序里,客户端已经收到成功终止标记,Billing 的 commit 才可能失败;前端或 SDK 会把这次请求当成完整响应,但账本里可能没有成功结算。反过来的错误也存在:如果 commit 已经成功,网关却因为写 DONE 失败又重试一次,就可能重复收费或把已完成的 reservation 重新释放。
我把这条边界定成:
- 上游错误、解析拒绝或缺少完成标记:取消上游、释放预扣、发一次脱敏 SSE error,不发 DONE,不重试;
- commit 被拒绝或结果不确定:保留 reservation,不释放、不重试,返回已转发中断标记;
- 客户端取消或内容写失败:取消上游、释放预扣,不再尝试追加错误事件;
- DONE 写失败发生在内容交付和结算之后:保留已提交结算和 usage log,不回滚。
这些分支都在 internal/server/chat_stream_terminal_test.go 里有独立用例。特别是错误与完成标记同时出现时,错误优先;不能因为上游已经发了一个 Complete,就把它当成功。
第 28 篇最后留下的是上游契约和七天观察窗口。这一篇讲的是之后新增的两个入口:原生 Gemini v1beta 和 /v1/rerank。它们看起来属于协议层,实际上仍然要经过鉴权、路由、预扣、结算和日志;入口变了,钱的顺序不能变。
1. B2/C2 和 v0.37.1 的来源
这三个包的时间顺序不是 B2 → C2:v0.37.1 先补共享 provider 和 SSE 边界,B2 随后接原生 Gemini,C2 最后才加 rerank。把来源摆在一起,是为了区分“共享修复已经存在”和“新入口自己又验证了什么”。
| 包 | 契约 / 需求 | 实施与验收 | 关键提交 |
|---|---|---|---|
| v0.37.1 中继安全 | docs/releases/release-v0.37.1.md |
docs/runbooks/relay-safety-v0.37.1-2026-10-29.md |
36d15bfd、782a002b、daedefeb |
| B2 原生 Gemini | docs/design/b2-native-gemini-contract-2026-10-30.md、docs/releases/release-v0.38.0.md |
docs/runbooks/b2-native-gemini-acceptance-2026-10-30.md、docs/runbooks/evidence/b2-native-gemini-engineering-2026-10-30.json |
7d3f4cbf |
| C2 rerank | docs/design/next-stage-plan-2026-11-08.md、docs/releases/release-v0.41.0.md |
docs/runbooks/c2-rerank-acceptance-2026-11-12.md |
7cac5234 |
| executor 观察窗口 | docs/design/v0.23-executor-observation.md |
docs/design/next-stage-plan-2026-11-08.md 第 5 节 |
没有新增观察提交;状态保持 INSUFFICIENT |
B2 和 C2 都是“新增入口”的故事,v0.37.1 是“入口背后的共享边界”。如果只读 release note 标题,会以为它们分别是三个独立功能;实际代码里,B2 复用 staged executor 和 canonical usage,C2 复用 raw relay,v0.37.1 则改了所有入口共用的 provider 读取和 SSE 终止策略。
2. B2:Gemini 原生入站不是把 JSON 换个名字
B2 做的是 /v1beta/models/{model}:generateContent 和 streamGenerateContent。它接在既有 staged executor、Identity/Channel 鉴权、模型映射、Billing 预扣/结算和 Log canonical 用量上,不是另起一套中转。
2.1 入口和凭据
原生入口接受 x-goog-api-key、Authorization: Bearer ...、?key=,兼容 x-api-key。同时提供不同凭据、重复凭据 header/query 时拒绝;原生凭据在共享中间件前转换成 Bearer,query 中的密钥移除;上游使用渠道自己的 x-goog-api-key,不透传客户端密钥。
URL 模型名进入既有 Identity 授权、模型白名单、Channel 路由、模型映射和重试流程。模型名限 1–128 个 ASCII 字母/数字/点/下划线/短横线,首字符为字母或数字;路径、转义路径和扩展上下文后缀不支持。模型映射只改变上游 URL,不在 Gemini body 中插入 OpenAI model 字段。
请求入口的 body 上限独立设为 4 MiB,别和 Chat 的 8 MiB JSON 预算混在一起。Gemini 原生协议通常会带工具声明和历史函数调用,不能因为体积比纯文本大就顺手放宽所有入口。
原生入口的实际链路是:
client token / query key
→ 凭据归一化(移除 query secret)
→ Identity 鉴权与 user/model 授权
→ Channel 路由和明确 model mapping
→ Billing reserve(带估算上限)
→ staged executor / Gemini provider
→ canonical usage 核验
→ Billing commit 或 release
→ Log usage / attempt 记录
这条链路和旧 Chat/Responses 复用同一套 owner,不因为协议叫 Gemini 就绕开账户、渠道或预算。唯一新增的是 URL 形状、请求/响应 parser 和 Gemini 的 usage 解释。原入口的 retry 规则仍保留:每次尝试重新选择来源并预扣,响应已完成、协议解析失败、客户端已经收到流或结算失败后不重放上游。
2.2 支持和拒绝矩阵
B2 首版支持的是一小块可解释的协议:
| 能力 | 行为 |
|---|---|
contents / systemInstruction 文本 |
支持单轮/多轮,校验 role、非空 parts、字段类型 |
| 函数声明、调用和结果 | 保留 functionDeclarations、functionCall、functionResponse、toolConfig、id、参数、结果和 thought signature |
| 输出参数 | temperature、topP、topK、stopSequences、maxOutputTokens;candidateCount 只允许 1 |
| 结构化文本 | text/plain、application/json、responseSchema/responseJsonSchema;仍按文本 token 结算 |
| thinking | 透传 thinkingBudget/thinkingLevel/includeThoughts,保留 thought/signature |
| safetySettings | 透传类别/阈值;原生安全阻断响应保留 |
| protobuf JSON 拼写 | 支持 camelCase 和 snake_case;同一字段两个别名同时出现拒绝;用户参数/schema 的键不改名 |
明确拒绝的部分同样重要:
- 图片、音频、视频、PDF、文件、inlineData、fileData、responseModalities、speechConfig 返回 400;
- 搜索、代码执行、URL context 等服务端工具返回 400;
cachedContent、continuationToken、隐藏会话返回 400,但允许供应商自动缓存的实际cachedContentTokenCount;- serviceTier/service_tier 返回 400,A3/B1 的服务档位、长上下文、忙闲计价不静默套用;
Idempotency-Key响应缓存在共享中间件前返回 400,防止不同原生凭据共用缓存或不完整 SSE 被缓存;- durable execution / native usage v2 试点命中 allowlist 时,在预扣前返回 501。
这张矩阵看起来保守,但它解决的是“一个 200 响应到底能证明什么”。图片、工具、隐藏状态和 durable 执行各自有不同的语义,不能因为文本请求测通,就把它们当成同一类能力。
2.3 canonical 五桶和 SSE
三库 owner 链路用临时 SQLite / MySQL 8.4 / PostgreSQL 18 跑了 15 个用例:HTTP 进入,经 Identity/Channel gRPC,到 Billing/Log 真实 SQL。测试用的 Gemini 样本是:
prompt=10, cached=3, candidates=4, thoughts=2, total=16
canonical=(uncached 7, cache_read 3, cache_create 0, cache_create_1h 0, output 6)
按测试价格 input=.001、output=.002、cache_read=.0002,平台消费是 196。重复提交不同 ActualTokens 仍返回第一次的 196,只写一条 consume;缺 usage 和客户端取消释放 reservation。
SSE 的终止帧在 usage 核验通过前不发给客户端。上游流断、缺终态、缺 usage、错误或超限分别进入失败分支;真实零用量允许结算;Billing 失败不重放。这个顺序和 v0.37.1 的 Chat SSE 修复是同一个原则:客户端看到的完成标记必须晚于服务端的账务决定。
B2 的失败路径也按资金结果拆开:
| 失败路径 | reservation 和账本结果 | 是否重放 |
|---|---|---|
| 请求里含媒体、服务端工具、隐藏缓存或 service tier | 预扣前 400,不进入上游 | 不重放 |
| 命中 durable execution allowlist | 预扣前 501 | 不重放 |
| 上游 JSON/SSE 缺 usage、usage 非法或 bucket 冲突 | 释放 reservation,不写 consume | 不重放 |
| 客户端取消或流中断 | 用脱离请求取消的 settlement context 释放预扣,保留失败证据 | 不重放 |
| Billing commit 失败 | 保留失败结果,不把内容当成功,不释放后重试 | 不重放 |
| 相同实际用量重复提交 | 第一次 196,后续返回同一结果,只写一条 consume | 幂等 |
这里最容易写错的不是主路径,而是“内容已经发给客户端,但账务失败”这一段。Gemini 原生 SSE 要等 usage 完整,不能先发 terminal 再补 commit;客户端取消也不能让释放操作跟着已经取消的上下文一起消失。
生产部署只更新 Relay,14 项公网检查覆盖缺密钥 401、错误 JSON/媒体/服务端工具/响应缓存 400、不支持方法 501、冲突凭据 401、旧 Chat/Responses 鉴权 401、CORS 和 healthz。真实 Gemini 渠道、模型和 SDK 没有执行,B2 不能写成“Gemini 已真实计费”。
3. C2:/v1/rerank 走 raw relay,不伪装成 embeddings
C2 加了 POST /v1/rerank,请求体预算是 8 MiB,和 embeddings 等文本 JSON 入口一样。路由注册后走 raw relay 的 handleRawRelay,再按响应里的 usage 计量并提交 Billing;每次 attempt 仍有日志。
发布 note 早期有一句“复用 embeddings 计费管线”,后来校正为复用 raw relay 路径。两者不能写成同一个东西:embeddingCostBound 只对 /embeddings 生效,rerank 没有那个 typed embedding 的价格上界。它能复用 raw relay 的鉴权、路由、attempt、usage 提取和结算骨架,但不能顺手套用 embeddings 的专用费用算法。
工程验收只做到:
internal/server/http_raw_test.go的路由、转发、usage 提交和缺模型校验;- relay 单测与全仓
make test-unit、make test-race; - 生产部署后
POST /v1/rerank返回 401missing authorization header,证明路由已挂载,而不是 404。
真实付费调用还没做。需要维护者先确认上游渠道、模型价格和小额预算,再核对 quota、账单流水和 usage 字段。现在把 401 写成“rerank 已上线并通过”是不诚实的。
4. v0.37.1 的三处修复,都发生在请求边界
B2/C2 之前,v0.37.1 先补了三处边界。它们不是新功能,但都直接影响新入口能不能安全接进来。
4.1 SSRF 旁路告警
PROVIDER_DISABLE_SSRF_CHECK=true 会在进程内关闭所有 provider 的 SSRF 校验,包括 DNS/IP 和重定向防护。原提示只在 Relay main,其他服务或直接校验路径可以静默使用这个全局旁路。修复把安全告警放到共享 provider 边界,覆盖 factory、HTTP/SSE client 构造、URL 校验、dial 和 redirect;每进程只记录一次 Warn,日志尚未就绪时保留后续告警机会。旁路开关没有新增第二个,安全边界仍由原配置控制。
隔离验证用子进程覆盖七个入口,原实现 warnings = 0, want 1,修复后通过。这里的重点不是“加一条日志”,而是让所有复用 provider 的服务都不能悄悄绕过安全边界。
4.2 上游错误体
非流式路径原来先按 128MB 成功上限读取,再看 HTTP 状态;上游返回一个大错误体就能放大进程内存。八条路径统一使用共享读取函数:
- typed Chat 只有 HTTP 200 成功;
- raw 是 HTTP 2xx 成功;
- 成功响应保留 128MB 上限;
- 错误响应统一 1MB
MaxUpstreamErrorBody; - HTTP 状态和
Retry-After保持原语义。
回归里 429 大错误体和 typed 201 错误原来都缓冲 2,097,152 字节,期望是 1,048,576;修复后通过。raw 201 的大响应仍完整返回,避免收紧错误上限时误截正常 2xx。
4.3 SSE 结算和终止
修复后,StreamError、InvalidPayload、缺终端帧、commit 失败、正常用量、取消和写失败分别有明确出口。正常顺序是“内容交付 → commit → DONE → usage log”;异常只发一次脱敏 SSE error,不发 DONE,内容里不带上游私有错误文本。
真实 provider → HTTP 链路的六个原失败场景转绿,覆盖错误与完成标记并存、InvalidPayload、未完成流、commit 失败、正常用量、取消及写失败。这里还有一个容易忽略的细节:DONE 写失败发生在内容交付和结算之后,保留已提交结算,不回滚;客户端取消或内容写失败发生在结算前,释放预扣,不再尝试追加错误事件。
这三处有一个共同点:以前都能在“请求已经发出去”之后才暴露。安全告警、错误体和流终止都不是业务主路径,但一旦入口增加,它们就是每个入口都要共享的边界。
5. 第 28 篇的七天窗口有没有推进
没有。
docs/design/v0.23-executor-observation.md 当前仍写着:10 月 18 日时新旧 Responses SSE 都有样本,但原始增量分别在不同时间,没有同窗可比对照;正式七天起点/终点为空,状态是 INSUFFICIENT。11 月 8 日的计划继续引用这份事实源,明确不重开观察窗口、不追认旧 FAIL、不恢复 PAUSED 自动任务。
B2 和 C2 增加了新入口,不等于旧的 executor 观察自动获得样本。观察要求同 endpoint/stream 的 orchestrator 与 legacy 对照,且连续 7×24 小时、有精确起点;部署一个新路由、跑一组三库 fixture,或者把新入口的 SSE 测通,都不能拼出那个窗口。
这一篇我把它单独写出来,是因为工程交付很容易把“代码已部署”和“那条长期门已经过了”混在一起。B2 的真实来源、SDK、付费用量没验;C2 的真实付费调用没验;executor 七天窗口仍 INSUFFICIENT。这些不是同一层缺口,不能用一条绿色 CI 代替。
6. 新入口的证据表
| 问题 | B2 Gemini | C2 rerank | v0.37.1 |
|---|---|---|---|
| 路由和鉴权 | 三库 owner、三种凭据、公网 401/400/501 拒绝 | raw relay 路由、鉴权、缺模型 400、生产 401 | 不改路由 |
| 请求上限 | /v1beta/models/ 4 MiB |
/v1/rerank 8 MiB |
错误体 1MB,成功体 128MB |
| 用量和资金 | prompt/cache/candidates/thoughts 的 canonical 五桶,缺 usage 不收费 | raw usage 提交,真实价格待确认 | commit 失败不重试、不释放;异常不发 DONE |
| SSE 终态 | usage 核验前扣留终止帧 | 走 raw relay 现有流边界 | 内容 → commit → DONE → usage log |
| 真实上游 | 未接真实 Gemini 渠道/SDK | 未做真实付费调用 | 未新增供应商调用 |
| 长期观察 | 不属于 executor 七天窗口 | 同上 | 旧窗口仍 INSUFFICIENT |
这张表里最容易被忽略的是最后一列。新入口通过工程测试,只能说明“按照我写的拒绝矩阵和测试价格,它没有把明显错误的请求当成功”。真实上游的用量、供应商账单、协议版本漂移和七天对照,仍然各自需要一段独立的证据。
7. 入口可以继续加,顺序不能省
写到这里,我对新增入口的判断标准已经很固定:
- 先确定它能不能被现有鉴权、路由、reservation、Billing、Log 边界完整接住;
- 再确定哪些请求必须显式拒绝,尤其是媒体、隐藏状态、工具和多轮协议;
- 然后确定用量字段怎么映射成 canonical 五桶,缺证据时释放还是保留 reservation;
- 最后才看 SSE/JSON 的终止帧和客户端成功语义。
Gemini 原生入口在 B2 里只做窄范围,C2 只把 rerank 挂到 raw relay;这不是功能上保守,而是我不想让一个“看起来能用”的协议把不可解释的用量混进账本。v0.37.1 的顺序修复也说明,[DONE] 是客户端看到的完成,不是服务端的结算完成。
下一篇换一个方向:审计表里已经有记录以后,我为什么先补了一个只读入口,而不是继续往写路径上加功能。
代码与阅读入口
| 想核对的内容 | 仓库入口 |
|---|---|
| Gemini 原生路由、拒绝矩阵、三库 owner 链路 | internal/server/gemini_handler.go、internal/server/gemini_handler_test.go、internal/integration/iam_b2_owner_test.go |
| Gemini 契约、provider 与 canonical usage | docs/design/b2-native-gemini-contract-2026-10-30.md、domain/upstream/provider/gemini.go、internal/server/http_raw_cache_creation_test.go |
| rerank 路由与 raw relay | internal/server/routes.go、internal/server/http_raw_test.go、platform/middleware/bodylimit.go、docs/runbooks/c2-rerank-acceptance-2026-11-12.md |
| SSE 结算顺序和终端错误 | internal/server/chat_stream_terminal_test.go、internal/server/stream_reliability_test.go、internal/server/request_timing_test.go |
| SSRF 和错误体边界 | domain/upstream/provider/ssrf_warning_test.go、domain/upstream/provider/safety_regression_test.go、domain/upstream/provider/provider.go |
| 观察窗口状态 | docs/design/v0.23-executor-observation.md、docs/design/next-stage-plan-2026-11-08.md |
| 验收记录 | docs/runbooks/b2-native-gemini-acceptance-2026-10-30.md、docs/runbooks/c2-rerank-acceptance-2026-11-12.md、docs/runbooks/relay-safety-v0.37.1-2026-10-29.md |
| 版本边界 | docs/releases/release-v0.37.1.md、docs/releases/release-v0.38.0.md、docs/releases/release-v0.41.0.md |
上一篇是第 31 篇:备份恢复与发布门禁;下一篇是第 33 篇:操作审计台。