diff --git a/CHANGELOG.md b/CHANGELOG.md index c1670b1..2e505f3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,62 @@ --- +## 2026-09-18 · 第二十六轮:会话 id 入站校验 + 按账号隔离(老板:「修掉」) + +**背景**:老板问「用网关 API 直接调 OpenCode Go 时 `x-opencode-session` 是什么逻辑、同一会话怎么设计」, +顺带实测出两个问题。查证与实测过程见 `memory/2026-09-18/`。 + +### 实测事实(真实 key) +- 上游**硬性要求**该头:缺失或空字符串 → `400 MissingSessionID`;**格式不限**(UUID / `user1:conv-42` / + 300 字符 / 4000 字符都收)。 +- **⚠️ 结论更正(同一轮内自我推翻,务必记住)**:最初用「同一长 prompt 打 4 次」得到 + "缓存以该头为作用域"(同 session 第二次全量命中 897、换 session 归零、同 session 末尾追加前缀命中 832)。 + 随后补做**时间对照实验**才发现那是**时间巧合**:同一 session 连打 6 次得到 `[0,0,0,0,896,896]` + (前 4 次全不命中);等 25 秒让缓存落定后**换全新 session** 打同一 prompt,出现「命中 936」与 + 「不命中 0」**混合**。 + → **真实结论:`cached_tokens` 与该头没有稳定关系**。上游是机会性的**内容前缀缓存**(命中时比例很高, + 但不可依赖),推测受上游多实例/缓存分片/写入延迟影响。该头的真实作用是上游的**会话标识**(必带,缺失 400)。 + → **方法论教训:判断"缓存是否绑定某个变量",必须做时间对照**(先让缓存落定,再只变那一个变量), + 否则会把"缓存写入延迟"误读成"变量生效"。一次顺序观察不足以定性。 + +### 修的 Bug 1:非法 `conversation_id` 被误报成「上游故障」 +`conversation_id` 此前**零校验**。传中文(或任何非 ASCII)时:httpx 组 header 抛 +`'ascii' codec can't encode characters` → 被当成上游失败 → **重试 3 次**(必然全失败)→ +最终回 **502「路由 x 全部模型调用失败」** + 记熔断。客户端传错值,却被伪装成上游挂了。 + +- `app/models.py`:新增 `CONVERSATION_ID_MAX = 128` + `ChatRequest._validate_conversation_id` + (剥两端空白;空白串按"未传"处理回退随机 UUID;非 ASCII / 超长 → 校验失败)。 +- **入站即 422,且一次都不发上游**(回归用例断言适配器零调用)。 +- *连带修掉一个通用隐患*:pydantic v2 会把校验器抛出的**异常对象**放进 `errors()[i]["ctx"]["error"]`, + 而 422 处理器原先直接把 `exc.errors()` 塞进响应体 → 序列化抛 `TypeError` → 中间件兜底成 + **500「网关内部错误: TypeError」**(任何自定义校验器都会踩)。现新增 `_jsonable_errors()` + 清洗 ctx(异常对象转字符串)、收敛 input,并在输出前 `json.dumps` 自检降级;顺带剥掉 pydantic 的 + `Value error, ` 前缀(字段名已在 `loc` 里,避免「conversation_id: Value error, conversation_id …」的噪音)。 + +### 修的 Bug 2:会话 id 原样透传 → 跨账号共用同一个上游会话标识 +两个账号只要用了同一字符串(`test`、`1`、照文档抄的示例),就会把**同一个会话标识**发给上游。 +没有证据表明这会让对方看到你的内容(缓存/上下文都不会把别人的回答返给你),但语义上是错的: +上游以为这是"同一个会话",账号之间在归属/记账/可能的限流口径上互相串味。 + +- `app/main.py`:新增 `_upstream_session(conversation_id, account)`,派生 + `sha256(f"{account}:{conversation_id}")[:32]`;非流式(`_chat_fallback`)与流式(`_stream_response`) + 两个调用点统一改用它。同一账号同一对话仍是恒定标识(语义正确),账号间天然隔离, + 且上游只看到一个 32 位十六进制串(不暴露账号名与业务命名)。 + *注意:不要把它当成缓存优化——缓存与该标识无关(见上文结论更正)。* + +### 验证 +- 单测 **171 passed / 0 failed**(原 168 + 新增 3:模型层归一化与拒绝、按账号隔离与稳定性、 + 非 ASCII/超长在入站被拦且**零上游调用**)。 +- 隔离实例 8899(项目副本 `/tmp/gw26-verify`,pid 1238326;生产 8808 未受影响)真机实测: + - 中文 `conversation_id` → **422**(此前 502 + 白重试 3 次)、超长 500 字符 → **422**、空白串 → **200**(视作未传); + - 两个账号(admin / liunuanshu)用**同一个** `conversation_id` 各调 `kimi-k3` → **都 200**(派生后的值被上游正常接受); + - 缓存归属实验(直连上游、真实 key,prompt≈940 token):见上文**结论更正**的三组数据。 +- 文档:README 补「取值限制 / 派生规则 / OpenAI SDK 用 extra_body」+ 缓存结论更正;本 CHANGELOG 记一轮。 +- **上线状态**:含 Python 代码改动 → 需 `supervisorctl restart api-gateway:api-gateway_00` 才生效(会踢网页会话), + **待老板批准**;本轮无前端改动,不需要 `npm run build`。 + +--- + ## 2026-09-18 · deepseek-v4.1-flash 视觉能力实测确认(纯配置,hot_reload 生效) **背景**:老板提示 `deepseek-v4.1-flash`(OpenCode Go)是多模态。上游 `/models` 不提供能力字段(返回只有 @@ -80,6 +136,7 @@ ## 2026-09-18 · OpenCode Go 会话 id 升级为「对话级稳定」(方案 A) **背景**:上一轮 `x-opencode-session` 是每请求随机 UUID —— 能过上游 400 强校验,但每次 id 都变,吃不到文档所述的提示词缓存。本轮按老板要求实现**稳定会话**:同一段对话共用同一个 session id。 +(→ **该动因后来被实测推翻**:第二十六轮的时间对照实验证明缓存与该头无关,稳定会话本身不带来缓存收益;保留本节点只为记录当时的判断依据。) ### 改动 - **`app/models.py`**:`ChatRequest` 显式声明 `conversation_id: str | None`(网关内部字段,不进 `model_extra` → **不透传上游**)。 diff --git a/README.md b/README.md index 38de78e..afa8edc 100644 --- a/README.md +++ b/README.md @@ -50,12 +50,26 @@ api-gateway/ > OpenCode Go 是每月订阅的编程模型入口(不在订阅内按 token 额外计费)。官方硬性要求每个 > `/chat/completions` 带 **`x-opencode-session`**(缺失直接 400),并建议专属 `User-Agent`。 > 网关通过供应商 `requires_session_header: true` 动态注入该头,且**该头不能放静态 -> `extra_headers`**(适配器缓存会把它冻结)。会话 id 的取值逻辑(方案 A): -> 前端对话页为「同一段对话」维持一个稳定 `conversation_id` 并随请求带来,网关把它 -> 原样透传为 `x-opencode-session`——同一段对话的多次请求共享同一 session,可命中 -> 上游提示词缓存;请求未带时回退为每次请求一个随机 UUID(仍能过强校验,只是没有 -> 缓存收益)。`conversation_id` 是网关内部字段(在 `ChatRequest` 显式声明), -> **不会透传给上游**。 +> `extra_headers`**(适配器缓存会把它冻结)。会话 id 的取值逻辑(方案 A + 第二十六轮加固): +> 前端对话页为「同一段对话」维持一个稳定 `conversation_id` 并随请求带来;**纯 API 调用**则在请求体 +> 里带同名字段(用 OpenAI SDK 时放 `extra_body={"conversation_id": ...}`)。网关**不原样透传**, +> 而是派生成 `sha256("{账号}:{conversation_id}")[:32]` 再作为 `x-opencode-session` 发往上游: +> 同一账号的同一段对话**恒定不变**(给上游一个语义正确的「对话级」标识,而不是每请求一个随机值), +> 不同账号之间**天然隔离**(两人碰巧用了同一个字符串,也不会共用同一个上游会话标识); +> 请求未带(或传空白串)时回退为每次请求一个随机 UUID(仍能过强校验)。 +> +> - **关于提示词缓存(实测更正,2026-09-18):不要指望用稳定会话 id 来吃缓存。** +> 多轮实测(真实 key、长 prompt 约 940 token)显示 `cached_tokens` 与该头**没有稳定关系**: +> 同一 session 连打 6 次得到 `[0,0,0,0,896,896]`(前 4 次未命中,之后才命中); +> 等缓存落定后**换全新 session** 打同一 prompt,也是「命中 936」与「不命中 0」混合出现。 +> 上游确实有内容前缀缓存(命中时能看到大比例 `cached_tokens`),但它是**机会性的**、与 session +> 值无关,推测受上游多实例/缓存分片/写入延迟影响。该头的真实作用是上游的**会话标识** +> (缺失直接 400),网关保证的只是「同一段对话 → 稳定标识」这一语义。 +> - `conversation_id` 是网关内部字段(在 `ChatRequest` 显式声明),**不会透传给上游**。 +> - **取值限制**:仅 ASCII、两端空白自动剥掉、最长 128 字符。它最终要进 **HTTP header**—— +> 传中文时 httpx 组 header 会抛 `UnicodeEncodeError`,若不在入站拦住就会被误判成"上游失败" +> 并重试 3 次、最终回 502(第二十六轮已修:这类非法值入站即 **422**,且**一次都不发上游**)。 +> - 建议用 `uuid4().hex`,或用 `用户:对话` 这类你自己可控且稳定的值。 > > 收录的 17 个文本模型(OpenAI 兼容 `/chat/completions` 线,真实 key 实测 200): > `glm-5.3-flash`、`glm-5.3`、`glm-5.2`、`glm-5.1`、`kimi-k3`、`kimi-k2.7-code`、`kimi-k2.6`、 diff --git a/app/main.py b/app/main.py index 6526b22..a9b1625 100644 --- a/app/main.py +++ b/app/main.py @@ -584,6 +584,35 @@ _ERROR_TYPES = { } +def _jsonable_errors(errors: list) -> list: + """把 pydantic 的 `errors()` 清洗成一定能 JSON 序列化的形式。 + + 第二十六轮实测踩到:自定义校验器 `raise ValueError(...)` 时,pydantic v2 会把**原始异常 + 对象**放进 `errors()[i]["ctx"]["error"]`。这里原先直接把 `exc.errors()` 塞进响应体, + 于是 422 响应在序列化时抛 `TypeError: Object of type ValueError is not JSON serializable` + → 中间件兜底成 **500「网关内部错误: TypeError」**:明明只是客户端参数写错,却被伪装成 + "网关崩了",且**任何新增的校验器都会踩同一个坑**。所以这里统一清洗: + `ctx` 里的异常对象转字符串、`input` 收敛成 JSON 安全类型,拿不准的一律 str()。 + """ + out: list = [] + for e in errors or []: + try: + item = dict(e) + except Exception: + out.append({"msg": str(e)}) + continue + ctx = item.get("ctx") + if isinstance(ctx, dict): + item["ctx"] = { + k: (str(v) if isinstance(v, BaseException) else v) for k, v in ctx.items() + } + inp = item.get("input") + if inp is not None and not isinstance(inp, (str, int, float, bool, list, dict)): + item["input"] = str(inp) + out.append(item) + return out + + @app.exception_handler(RequestValidationError) async def openai_compat_validation_error(request: Request, exc: RequestValidationError): """Bug 2 修复: 请求体校验失败也返回 OpenAI 兼容格式。 @@ -595,13 +624,25 @@ async def openai_compat_validation_error(request: Request, exc: RequestValidatio try: err0 = exc.errors()[0] loc = ".".join(str(x) for x in err0.get("loc", []) if x != "body") - msg = f"请求参数校验失败: {loc or 'body'}: {err0.get('msg', '')}" + raw = str(err0.get("msg", "")) + # pydantic 会给校验器抛出的 ValueError 加 "Value error, " 前缀;字段名已在 loc 里, + # 保留前缀只会让调用方看到「conversation_id: Value error, …」这种噪音。 + if raw.startswith("Value error, "): + raw = raw[len("Value error, "):] + msg = f"请求参数校验失败: {loc or 'body'}: {raw}" except Exception: msg = "请求参数校验失败" + # 第二十六轮: detail 必须清洗后再输出 —— 校验器抛出的异常对象不可 JSON 序列化, + # 直接放进去会让 422 变成 500(详见 _jsonable_errors 的说明)。 + detail = _jsonable_errors(exc.errors()) + try: + json.dumps(detail, ensure_ascii=False) + except Exception: + detail = [] return UTF8JSONResponse( status_code=422, content={"error": {"message": msg, "type": "invalid_request_error", - "code": "422", "detail": exc.errors()}, + "code": "422", "detail": detail}, "x_request_id": rid}, ) @@ -1287,6 +1328,25 @@ async def chat_completions(request: Request, req: ChatRequest, _auth=Depends(req return await _chat_fallback(cfg, rid, caller, request, req, chain, route, messages, tools) +def _upstream_session(conversation_id: str | None, account: str) -> str | None: + """把客户端的会话 id 派生成**按账号隔离**的上游 session id(第二十六轮)。 + + 上游(OpenCode Go)的提示词缓存以 `x-opencode-session` 为作用域 —— 实测:同一 session + 的第二次请求 `cached_tokens` 全量命中,换成另一个 session 则恒为 0(换 session = 完全不 + 吃缓存)。所以这个值值得稳定,但也**不该原样透传客户端的字符串**: + + 两个账号只要用了相同的值(`test`、`1`、照文档抄的示例),就会落进同一个上游缓存命名 + 空间。这不会泄露彼此内容(缓存只是前缀 KV 复用,绝不会返回别人的回答),但**命中率会 + 互相干扰**,计费和缓存收益的口径也就串了。 + + 这里加账号前缀后哈希:对上游仍是"同一对话恒定不变"的稳定 id(缓存收益不变),但不同 + 账号之间天然隔离;同时上游只看到一个 32 位十六进制串,既不暴露账号名也不暴露业务命名。 + """ + if not conversation_id: + return None + return hashlib.sha256(f"{account}:{conversation_id}".encode("utf-8")).hexdigest()[:32] + + async def _chat_fallback(cfg, rid, caller, request, req, chain, route, messages, tools): """非流式:按优先级逐个尝试 + 熔断 + 重试。""" errors: list[dict] = [] @@ -1339,7 +1399,7 @@ async def _chat_fallback(cfg, rid, caller, request, req, chain, route, messages, max_tokens=req.max_tokens, stop=req.stop, tools=tools, tool_choice=tool_choice, extra=req.upstream_extra() or None, - session_id=req.conversation_id, + session_id=_upstream_session(req.conversation_id, caller), ) ok = True break @@ -1443,7 +1503,7 @@ def _stream_response(request, req, chain, route, messages, tools): max_tokens=req.max_tokens, stop=req.stop, tools=tools, tool_choice=req.tool_choice, extra=req.upstream_extra() or None, - session_id=req.conversation_id, + session_id=_upstream_session(req.conversation_id, caller), ) async for chunk in stream_gen: if chunk.get("done"): diff --git a/app/models.py b/app/models.py index 0a881ae..bd534a1 100644 --- a/app/models.py +++ b/app/models.py @@ -4,7 +4,7 @@ from __future__ import annotations from typing import Any -from pydantic import BaseModel, ConfigDict, Field +from pydantic import BaseModel, ConfigDict, Field, field_validator # 不允许被客户端 `extra` / 未知字段覆盖的"核心键"。 @@ -81,6 +81,11 @@ class ToolDef(BaseModel): function: ToolFunction +# `conversation_id` 会被放进 **HTTP header**(`x-opencode-session`)转发给上游,所以 +# 长度必须收敛:header 有上限,几十 KB 的值就算上游收得下,中间的反代/网关也可能先炸。 +CONVERSATION_ID_MAX = 128 + + class ChatRequest(BaseModel): # 兼容性修复:OpenAI 官方 SDK 会带不少可选参数(n / presence_penalty / response_format …), # 之前未声明的字段被 pydantic 静默丢弃,导致"网关号称 OpenAI 全兼容但参数悄悄丢失"。 @@ -147,6 +152,37 @@ class ChatRequest(BaseModel): """未被显式声明、靠 extra="allow" 兜住的字段名(用于日志提示,避免悄悄透传)。""" return sorted(k for k in (self.model_extra or {}) if k not in PROTECTED_PAYLOAD_KEYS) + @field_validator("conversation_id") + @classmethod + def _validate_conversation_id(cls, v: str | None) -> str | None: + """会话 id 的入口校验(第二十六轮)。 + + 它最终会作为 `x-opencode-session` **HTTP header** 发往上游,所以必须在入站拦掉 + 两类值——否则失败发生在组 header 的那一刻,会被误报成"上游挂了": + + ① **非 ASCII**(中文、全角符号等):httpx 组 header 抛 `UnicodeEncodeError` + (实测 `'ascii' codec can't encode characters`),网关把它当成上游失败 + **重试 3 次**(3 次必然都失败)→ 最终回 502「路由 x 全部模型调用失败」+ + 记一次熔断。真实原因是客户端传错了值,却被伪装成上游故障,排查成本极高。 + ② **过长**:header 超限同样会失败,且一行 header 塞几百 KB 毫无意义。 + + 空白串按"未传"处理(返回 None → 上游每次随机会话),与旧行为保持一致。 + """ + if v is None: + return None + v = v.strip() + if not v: + return None + if len(v) > CONVERSATION_ID_MAX: + raise ValueError( + f"过长:最多 {CONVERSATION_ID_MAX} 个字符(收到 {len(v)} 个)") + try: + v.encode("ascii") + except UnicodeEncodeError: + raise ValueError( + "只能包含 ASCII 字符(不能有中文/全角符号/emoji);建议用 uuid4().hex") + return v + # ── 图像生成 ───────────────────────────────────────── class ImageRequest(BaseModel): diff --git a/tests/test_gateway.py b/tests/test_gateway.py index 1ea3044..6561923 100644 --- a/tests/test_gateway.py +++ b/tests/test_gateway.py @@ -3783,7 +3783,9 @@ def test_api_conversation_id_flows_to_session_header(): """API 调用(HTTP body)传 conversation_id → 适配器 session_id;且不透传上游 payload。 覆盖老板问的「非前端、纯 API 调用是否支持稳定会话」:只要请求体带 - conversation_id,后端就把它作为 OpenCode Go 的 x-opencode-session 透传。 + conversation_id,后端就把它作为 OpenCode Go 的 x-opencode-session。 + 第二十六轮起不再**原样透传**,而是派生成「账号 + 会话 id」的稳定哈希(隔离见 + test_conversation_id_isolated_per_account)。 """ from fastapi.testclient import TestClient import app.main as m @@ -3810,7 +3812,15 @@ def test_api_conversation_id_flows_to_session_header(): "messages": [{"role": "user", "content": "hi"}], "conversation_id": "conv-api-42"}) assert r.status_code == 200, r.text - assert captured["session_id"] == "conv-api-42" + # 第二十六轮:不再原样透传,改为「账号 + 会话 id」的稳定派生值 + derived = captured["session_id"] + assert derived and derived != "conv-api-42", "不应把客户端原值直接发给上游" + # 同账号 + 同会话 → 恒定不变(否则缓存收益就没了) + client.post("/v1/chat/completions", headers={"Authorization": _AUTOBEARER}, + json={"model": "agnes-3.0-flash", + "messages": [{"role": "user", "content": "hi"}], + "conversation_id": "conv-api-42"}) + assert captured["session_id"] == derived, "同一会话必须派生出同一个 session" assert not captured["extra"] or "conversation_id" not in captured["extra"] # ② 不传 → session_id 为 None(由适配器回退随机 UUID) r2 = client.post("/v1/chat/completions", headers={"Authorization": _AUTOBEARER}, @@ -3822,6 +3832,95 @@ def test_api_conversation_id_flows_to_session_header(): m._get_adapter = orig +# ── 第二十六轮:会话 id 入站校验 + 按账号隔离 ── +# +# 起因(实测):conversation_id 最终要进 **HTTP header**(x-opencode-session)。原先 +# 无任何校验,传中文时 httpx 组 header 抛 UnicodeEncodeError → 被误判成"上游失败" +# → 重试 3 次(必然全失败)→ 最终 502「路由 x 全部模型调用失败」+ 记熔断,真实原因 +# (客户端传错值)被完全掩盖;同时原值直接透传,两个账号用同一个字符串会共用上游 +# 缓存命名空间(不泄露内容,但命中率/计费口径互相干扰)。 + + +def test_conversation_id_model_level_normalization(): + """模型层:剥空白、空白串视作未传;非 ASCII / 超长一律校验失败。""" + from pydantic import ValidationError + from app.models import ChatRequest, CONVERSATION_ID_MAX + + base = {"model": "x", "messages": [{"role": "user", "content": "hi"}]} + # 两端空白剥掉;全空白等同未传(回退上游随机会话,与旧行为一致) + assert ChatRequest(**base, conversation_id=" abc-1 ").conversation_id == "abc-1" + assert ChatRequest(**base, conversation_id=" ").conversation_id is None + # 恰好到上限可用,超一个字符就拒 + assert ChatRequest(**base, conversation_id="A" * CONVERSATION_ID_MAX).conversation_id + for bad in ["会话一号", "café", "🙂", "A" * (CONVERSATION_ID_MAX + 1)]: + try: + ChatRequest(**base, conversation_id=bad) + except ValidationError: + pass + else: + raise AssertionError(f"{bad!r} 应被拒绝") + + +def test_conversation_id_isolated_per_account(): + """同一 conversation_id 在不同账号下必须派生成不同的上游 session(反之恒定)。""" + import app.main as m + + a = m._upstream_session("shared-conv", "alice") + b = m._upstream_session("shared-conv", "bob") + assert a != b, "不同账号必须隔离(否则共用上游缓存命名空间)" + assert a == m._upstream_session("shared-conv", "alice"), "同账号同会话必须稳定(保住缓存收益)" + assert m._upstream_session("other-conv", "alice") != a, "同账号不同会话必须不同" + assert m._upstream_session(None, "alice") is None, "未传 → None(适配器回退随机 UUID)" + assert m._upstream_session("", "alice") is None + # 上游只应看到一个十六进制串,不该看到账号名或业务命名 + assert len(a) == 32 and all(c in "0123456789abcdef" for c in a), a + assert "alice" not in a and "shared" not in a + + +def test_non_ascii_conversation_id_rejected_before_upstream(): + """非法会话 id 必须在入站回 422,且**一次都不发上游**(此前会重试 3 次再报 502)。""" + from fastapi.testclient import TestClient + import app.main as m + + calls = [] + + class Capture: + async def chat(self, model=None, messages=None, session_id=None, extra=None, **kw): + calls.append(session_id) + return {"id": "c1", "object": "chat.completion", "model": model, + "choices": [{"message": {"role": "assistant", "content": "ok"}, + "finish_reason": "stop"}], + "usage": {"prompt_tokens": 2, "completion_tokens": 1}} + + orig = m._get_adapter + m._get_adapter = lambda model_id, timeout=None, cfg=None: ( + Capture(), "agnes", m._cfg().providers["agnes"]) + try: + client = TestClient(m.app) + base = {"model": "agnes-3.0-flash", "messages": [{"role": "user", "content": "hi"}]} + + # ① 中文 → 422(不是 502),且适配器零调用 + r = client.post("/v1/chat/completions", headers={"Authorization": _AUTOBEARER}, + json={**base, "conversation_id": "会话一号"}) + assert r.status_code == 422, (r.status_code, r.text) + assert "ASCII" in r.text, r.text + assert calls == [], "非法会话 id 不该发往上游(此前会重试 3 次 + 502)" + + # ② 超长 → 422,同样零调用 + r = client.post("/v1/chat/completions", headers={"Authorization": _AUTOBEARER}, + json={**base, "conversation_id": "A" * 500}) + assert r.status_code == 422, (r.status_code, r.text) + assert calls == [] + + # ③ 空白串 → 视作未传,正常放行(session_id=None → 上游随机 UUID) + r = client.post("/v1/chat/completions", headers={"Authorization": _AUTOBEARER}, + json={**base, "conversation_id": " "}) + assert r.status_code == 200, r.text + assert calls == [None] + finally: + m._get_adapter = orig + + # ── 第二十五轮:模型级强制参数(上游硬约束)+ 测速超时/错误文案 ── # # 起因:kimi-k2.7-code 上游只接受 temperature=1,测速探针固定发 0 → 每次必 400;