
> 《micro-one-api 拆解》第 32 篇
> 代码核对：`v0.41.0` / `372391f`

---

## 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 原生协议通常会带工具声明和历史函数调用，不能因为体积比纯文本大就顺手放宽所有入口。

原生入口的实际链路是：

```text
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 样本是：

```text
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` 返回 401 `missing 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. 入口可以继续加，顺序不能省

写到这里，我对新增入口的判断标准已经很固定：

1. 先确定它能不能被现有鉴权、路由、reservation、Billing、Log 边界完整接住；
2. 再确定哪些请求必须显式拒绝，尤其是媒体、隐藏状态、工具和多轮协议；
3. 然后确定用量字段怎么映射成 canonical 五桶，缺证据时释放还是保留 reservation；
4. 最后才看 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` |


《micro-one-api 拆解》第 32 篇 代码核对：v0.41.0 / 372391f

[DONE] 之前先结账：两个新入口和一条我没松的边界

后端

《micro-one-api拆解》第32篇代码核对v0.41.0/372391f0：详解ChatSSE顺序修复（内容交付→commit→DONE→usagelog），避免客户端误判成功与重复计费。新增Gemini原生入口与/v1/rerank，严格复用鉴权路由、Billing预扣结算边界。明确拒绝矩阵与canonical五桶用量映射，强调新入口不替代真实上游与七天观察窗口验证。

代码解释

中间件

路由

JSON

腾讯云双十一大促

apigw

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

《micro-one-api拆解》第32篇代码核对v0.41.0/372391f0：详解ChatSSE顺序修复（内容交付→commit→DONE→usagelog），避免客户端误判成功与重复计费。新增Gemini原生入口与/v1/rerank，严格复用鉴权路由、Billing预扣结算边界。明确拒绝矩阵与canonica...

[DONE] 之前先结账：两个新入口和一条我没松的边界-腾讯云开发者社区-腾讯云

[DONE] 之前先结账：两个新入口和一条我没松的边界

[DONE] 之前先结账：两个新入口和一条我没松的边界

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐