上游会话 id:客户端显式带 x-opencode-session 时优先用它

老板要求:「x-opencode-session 如果 api 请求有带的话优先用请求上的,没有再用 apikey 的那个方式」。

取值优先级(_upstream_session):
  ① 入站 x-opencode-session 头(本轮新增) → sha256("s:{账号}:{客户端值}")[:32]
  ② conversation_id                          → sha256("{账号}:{conversation_id}")[:32]
  ③ 用这个 API Key 自己(一个 Key 一个稳定会话)→ sha256("k:{去前缀Key}")[:32]
  ④ 登录页会话(无 Key)                      → sha256("u:{账号}")[:32]

- 仍按账号哈希:保留第二十六轮的账号隔离(两个账号写同一个值也不会被绑到同一上游会话标识)
- 入站值过 conversation_id 同款入口校验(仅 ASCII、≤128 字符),非法值静默丢弃并回退
  (可选头不该把请求打回 400);三个调用点(直传 / managed 非流式 / managed 流式)全接
- 新增 _inbound_session(request) 与 SESSION_HEADER 常量

实测(生产):同一会话头连打两次同一段 4k 前缀 → cached 0 → 1920(稳定复用);不带头回退
Key 派生也命中。同时更正一条旧认知:上游缓存**并非严格按 session 隔离**(换会话头同前缀
照样命中 1920),会话 id 是「纳入缓存」的前提而非隔离边界 —— README 与代码注释已同步。

测试 204 → 206 全过(新增取值优先级+账号隔离、入站头端到端两条);ci_check 全绿。
This commit is contained in:
api-gateway committed 2026-09-28 19:35:59 +08:00
1 parent b67b9390f2
commit 54924b76cc
4 files changed
+190 -15

No files matched your search

+29
View File
@@ -1,5 +1,34 @@
# CHANGELOG # CHANGELOG
## 2026-09-28 · 上游会话 id 支持客户端显式指定(`x-opencode-session` 优先)
老板要求:「x-opencode-session 如果 api 请求有带的话优先用请求上的,没有再用 apikey 的那个方式」。
**取值优先级**(`_upstream_session()`):
| 优先级 | 来源 | 派生 |
| --- | --- | --- |
| ① | **入站 `x-opencode-session` 头**(本轮新增) | `sha256("s:{账号}:{客户端值}")[:32]` |
| ② | 请求里的 `conversation_id` | `sha256("{账号}:{conversation_id}")[:32]` |
| ③ | 用这个 API Key 自己(一个 Key 一个稳定会话) | `sha256("k:{去前缀Key}")[:32]` |
| ④ | 登录页会话(无 Key) | `sha256("u:{账号}")[:32]` |
- 客户端带了就用客户端的(它最清楚哪几次调用算同一段对话),**但仍按账号哈希** —— 保留
第二十六轮定下的账号隔离:两个账号即便写同一个值,也不会被绑到同一个上游会话标识上;
- 入站值同样过 `conversation_id` 那套入口校验(仅 ASCII、≤128 字符),**非法值静默丢弃并回退**
(可选头不该把请求打回 400);非 ASCII 值在 HTTP 层就发不出去(httpx 直接拒),校验是兜底;
- 三个调用点(直传端点、managed 非流式、managed 流式)全部接上。
**实测(生产,2026-09-28)**:同一会话头连打两次同一段 4k 前缀 → `cached 0 → 1920`(稳定复用);
不带头(回退 Key 派生)两次都命中。
**顺带更正一条旧认知**:上游提示词缓存**并非严格按 session 隔离** —— 换一个会话头、同一段前缀
照样命中(1920)。所以稳定会话 id 是「纳入缓存」的前提之一,**不是隔离边界**,也不能拿缓存
命中率当会话隔离的判据(README 与代码注释已同步更正)。
**测试**:新增「取值优先级 + 账号隔离」与「入站头端到端(稳定/换头/回退/非法值)」两条回归,
测试数 204 → **206 全过**;`ci_check.sh` 全绿。
## 2026-09-28 · 修「token 统计恒 0」+ token 细分(缓存命中 / 推理) ## 2026-09-28 · 修「token 统计恒 0」+ token 细分(缓存命中 / 推理)
老板报「token 数统计有问题,一直都是 0」。 老板报「token 数统计有问题,一直都是 0」。
+24 -5
View File
@@ -54,12 +54,31 @@ api-gateway/
> `extra_headers`**(适配器缓存会把它冻结)。会话 id 的取值逻辑(方案 A + 第二十六轮加固): > `extra_headers`**(适配器缓存会把它冻结)。会话 id 的取值逻辑(方案 A + 第二十六轮加固):
> 前端对话页为「同一段对话」维持一个稳定 `conversation_id` 并随请求带来;**纯 API 调用**则在请求体 > 前端对话页为「同一段对话」维持一个稳定 `conversation_id` 并随请求带来;**纯 API 调用**则在请求体
> 里带同名字段(用 OpenAI SDK 时放 `extra_body={"conversation_id": ...}`)。网关**不原样透传**, > 里带同名字段(用 OpenAI SDK 时放 `extra_body={"conversation_id": ...}`)。网关**不原样透传**,
> 而是派生成 `sha256("{账号}:{conversation_id}")[:32]` 再作为 `x-opencode-session` 发往上游: > 而是按下面的**优先级**派生成一个稳定值再作为 `x-opencode-session` 发往上游
> 同一账号的同一段对话**恒定不变**(给上游一个语义正确的「对话级」标识,而不是每请求一个随机值), > (第三十五轮更新;任何一级都**不再回退成随机 UUID** —— 随机 = 缓存命中率恒为 0):
> 不同账号之间**天然隔离**(两人碰巧用了同一个字符串,也不会共用同一个上游会话标识);
> 请求未带(或传空白串)时回退为每次请求一个随机 UUID(仍能过强校验)。
> >
> - **关于提示词缓存(实测更正,2026-09-18):不要指望用稳定会话 id 来吃缓存。** > | 优先级 | 来源 | 派生方式 |
> | --- | --- | --- |
> | ① | **入站 `x-opencode-session` 头**(客户端显式指定,第三十五轮新增) | `sha256("s:{账号}:{客户端值}")[:32]` |
> | ② | 请求里的 `conversation_id` | `sha256("{账号}:{conversation_id}")[:32]` |
> | ③ | 都没带 → 用**这个 API Key 自己**(一个 Key 一个稳定会话) | `sha256("k:{去前缀Key}")[:32]` |
> | ④ | 连 Key 都没有(登录页会话) | `sha256("u:{账号}")[:32]` |
>
> - ①「客户端带了就用客户端的」:客户端最清楚哪几次调用算同一段对话,比网关拿 Key 兜底更贴合
> 它的会话划分;但**仍按账号哈希**,保留账号隔离 —— 否则两个账号只要用同一个值就会共用上游
> 缓存作用域。值同样过 `conversation_id` 那套入口校验
> (仅 ASCII、≤128 字符),非法值**静默丢弃并回退**(可选头不该把请求打回 400)。
> - 同一账号的同一段对话**恒定不变**,不同账号之间**天然隔离**(两人碰巧用了同一个字符串也不会
> 共用同一个上游会话标识)。
>
> - **关于提示词缓存**:会话 id 稳定是**吃到缓存的前提**,但不是充分条件(上游缓存本身是
> 机会性的)。2026-09-28 复测:同一个稳定会话下、同一段 4k token 前缀连打两次,
> 第二次 `cached_tokens=1920`(命中);而 2026-09-18 的观测里同一 session 连打 6 次
> 得到 `[0,0,0,0,896,896]`(前几次未命中、之后才命中)。所以:**别把它当保证**,
> 但**千万别让它随机** —— 每请求一个随机 UUID 等于永远不命中。
> **2026-09-28 实测更正**:上游缓存**并非严格按 session 隔离** —— 换一个会话头、同一段 4k
> 前缀照样命中(1920)。所以会话 id 是「纳入缓存」的前提之一,**不是隔离边界**,也别拿缓存
> 命中率当会话隔离的判据。
> 多轮实测(真实 key、长 prompt 约 940 token)显示 `cached_tokens` 与该头**没有稳定关系**: > 多轮实测(真实 key、长 prompt 约 940 token)显示 `cached_tokens` 与该头**没有稳定关系**:
> 同一 session 连打 6 次得到 `[0,0,0,0,896,896]`(前 4 次未命中,之后才命中); > 同一 session 连打 6 次得到 `[0,0,0,0,896,896]`(前 4 次未命中,之后才命中);
> 等缓存落定后**换全新 session** 打同一 prompt,也是「命中 936」与「不命中 0」混合出现。 > 等缓存落定后**换全新 session** 打同一 prompt,也是「命中 936」与「不命中 0」混合出现。
+51 -10
View File
@@ -1524,7 +1524,8 @@ async def _passthrough(request: Request, protocol: str):
# 定点改写:model 换成真实 id(别名场景)+ 盖模型级强制参数;其余字段一个不动 # 定点改写:model 换成真实 id(别名场景)+ 盖模型级强制参数;其余字段一个不动
payload = adapter.prepare_payload(model_in, clean) payload = adapter.prepare_payload(model_in, clean)
session = _upstream_session(conv, caller, getattr(request.state, "key_token", None)) session = _upstream_session(conv, caller, getattr(request.state, "key_token", None),
_inbound_session(request))
if stream: if stream:
return await _passthrough_stream(request, rid, caller, protocol, adapter, cb, return await _passthrough_stream(request, rid, caller, protocol, adapter, cb,
@@ -1824,23 +1825,59 @@ async def chat_completions(request: Request, req: ChatRequest, _auth=Depends(req
return await _chat_once(cfg, rid, caller, request, req, model_id, messages, tools) return await _chat_once(cfg, rid, caller, request, req, model_id, messages, tools)
def _upstream_session(conversation_id: str | None, account: str, key_token: str | None = None) -> str: # 入站显式会话头(第三十五轮):客户端自己指定的上游会话 id。
"""把调用的标识派生成**稳定**的上游 session id(第二十六轮 + 第二十九轮强化)。 SESSION_HEADER = "x-opencode-session"
def _inbound_session(request) -> str | None:
"""读入站的 `x-opencode-session`(客户端显式指定的会话 id)。
与 `conversation_id` 走**同一套入口校验**(非 ASCII / 过长一律丢弃)—— 两者最终都会
成为发往上游的 header,脏值不能在这里放过。校验不过时**静默回退**(当作没带):
一个可选头不该把请求打回 400。
"""
raw = request.headers.get(SESSION_HEADER)
if not raw:
return None
try:
return normalize_conversation_id(raw)
except ValueError as e:
log.warning("[rid=%s] 入站 %s 非法(%s),忽略并回退到派生会话",
getattr(request.state, "rid", "-"), SESSION_HEADER, e)
return None
def _upstream_session(conversation_id: str | None, account: str, key_token: str | None = None,
client_session: str | None = None) -> str:
"""把调用的标识派生成**稳定**的上游 session id(第二十六轮 + 第二十九轮 + 第三十五轮)。
上游(OpenCode Go)的提示词缓存以 `x-opencode-session` 为作用域 —— 实测:同一 session 上游(OpenCode Go)的提示词缓存以 `x-opencode-session` 为作用域 —— 实测:同一 session
的第二次请求 `cached_tokens` 全量命中,换成另一个 session 则恒为 0(换 session = 完全不 的第二次请求 `cached_tokens` 全量命中,换成另一个 session 则恒为 0(换 session = 完全不
吃缓存)。所以这个值**必须在一次最近的重复调用间恒定**。取值优先级: 吃缓存)。所以这个值**必须在一次最近的重复调用间恒定**。取值优先级:
① 客户端带了 `conversation_id`(第二十六轮):first 「账号:会话」后哈希 —— 同一段对话 ① **客户端显式带了 `x-opencode-session`(第三十五轮,老板要求)**:客户端最清楚
恒定 → 该对话内反复出现的前缀命中;不同账号天然隔离。 "哪几次调用算同一个会话",带了就听它的(比网关用 Key 兜底更贴合它的会话划分)。
② 没带(QwenPaw / 多数 agent 不发这个字段,第二十九轮老板决策):用**这个 API Key 仍然**按账号哈希**(`s:账号:客户端值`)—— 保持第二十六轮定下的账号隔离:两个账号
即便写了同一个值,也不会被绑到同一个上游会话标识上(上游按它记会话/日志;缓存那层
见下注,别指望靠它做隔离)。
② 客户端带了 `conversation_id`(第二十六轮):按「账号:会话」哈希 —— 同一段对话恒定
→ 该对话内反复出现的前缀命中;不同账号天然隔离。
③ 没带(QwenPaw / 多数 agent 不发这些字段,第二十九轮老板决策):用**这个 API Key
自己**派生 —— 一个 Key 一个稳定会话,比"每调随机"命中率高得多。但**先哈希再传**: 自己**派生 —— 一个 Key 一个稳定会话,比"每调随机"命中率高得多。但**先哈希再传**:
直接把 `wjd-` 后面那串原样发给上游等于泄露 Key 凭证内容给第三方(见 _key_token)。 直接把 `wjd-` 后面那串原样发给上游等于泄露 Key 凭证内容给第三方(见 _key_token)。
③ 连 Key 都没有(登录页面会话,kind=session):按账号稳定兜底,同样不再随机。 ④ 连 Key 都没有(登录页面会话,kind=session):按账号稳定兜底,同样不再随机。
这三级都**不再回退成每个调用一个随机 UUID** —— 随机=缓存命中率恒为 0。上游只看到 这四级都**不再回退成每个调用一个随机 UUID** —— 随机=缓存命中率恒为 0。上游只看到
32 位十六进制串,不暴露账号名、业务命名或 Key 明文。 32 位十六进制串,不暴露账号名、业务命名或 Key 明文。
★ 2026-09-28 实测更正:上游的提示词缓存**并不是严格按 session 隔离的** ——
同一段 4k 前缀,用同一个会话头连打(0 → 1920 命中)能命中;**换成另一个会话头**
再打同一段前缀,照样命中(1920)。所以「稳定会话 id」是**吃到缓存的前提之一、但不是隔离边界**,
更不是保证(2026-09-18 还观测到同一 session 连打 6 次才陆续命中)。
别把缓存命中率当成会话隔离的判据。
""" """
if client_session:
return hashlib.sha256(f"s:{account}:{client_session}".encode("utf-8")).hexdigest()[:32]
if conversation_id: if conversation_id:
return hashlib.sha256(f"{account}:{conversation_id}".encode("utf-8")).hexdigest()[:32] return hashlib.sha256(f"{account}:{conversation_id}".encode("utf-8")).hexdigest()[:32]
if key_token: if key_token:
@@ -1892,7 +1929,9 @@ async def _chat_once(cfg, rid, caller, request, req, model_id, messages, tools):
max_tokens=req.max_tokens, stop=req.stop, max_tokens=req.max_tokens, stop=req.stop,
tools=tools, tool_choice=tool_choice, tools=tools, tool_choice=tool_choice,
extra=req.upstream_extra() or None, extra=req.upstream_extra() or None,
session_id=_upstream_session(req.conversation_id, caller, getattr(request.state, "key_token", None)), session_id=_upstream_session(req.conversation_id, caller,
getattr(request.state, "key_token", None),
_inbound_session(request)),
) )
ok = True ok = True
break break
@@ -1997,7 +2036,9 @@ def _stream_response(request, req, model_id, messages, tools):
max_tokens=req.max_tokens, stop=req.stop, max_tokens=req.max_tokens, stop=req.stop,
tools=tools, tool_choice=req.tool_choice, tools=tools, tool_choice=req.tool_choice,
extra=req.upstream_extra() or None, extra=req.upstream_extra() or None,
session_id=_upstream_session(req.conversation_id, caller, getattr(request.state, "key_token", None)), session_id=_upstream_session(req.conversation_id, caller,
getattr(request.state, "key_token", None),
_inbound_session(request)),
) )
async for chunk in stream_gen: async for chunk in stream_gen:
if chunk.get("done"): if chunk.get("done"):
+86
View File
@@ -5473,6 +5473,92 @@ def test_metrics_record_tokens_breakdown_accumulates():
assert t["cached"] <= t["prompt"] and t["reasoning"] <= t["completion"] assert t["cached"] <= t["prompt"] and t["reasoning"] <= t["completion"]
def test_upstream_session_priority_and_account_isolation():
"""第三十五轮:上游会话 id 的取值优先级 + 账号隔离。
① 入站 `x-opencode-session` 优先(客户端最清楚哪几次算同一个会话);
② 没带才依次回退 conversation_id → API Key → 账号;
③ 带了客户端会话时仍**按账号哈希** —— 否则两个账号用同一个值就会共用上游缓存作用域
(第二十六轮定下的账号隔离被绕过)。
"""
import hashlib
import app.main as m
h = lambda x: hashlib.sha256(x.encode("utf-8")).hexdigest()[:32] # noqa: E731
# ① 客户端显式会话优先,且不受 conversation_id 影响
a = m._upstream_session(None, "acct", "tok", "conv-abc")
b = m._upstream_session("conv-xyz", "acct", "tok", "conv-abc")
assert a == b, "带了入站会话头时不该再被 conversation_id 改写"
assert a == h("s:acct:conv-abc"), a
# ③ 同值不同账号必须隔离
assert a != m._upstream_session(None, "other", "tok", "conv-abc"), "账号隔离不能绕过"
# ② 没带则按原优先级回退
assert m._upstream_session("c1", "acct", "tok") == h("acct:c1")
assert m._upstream_session(None, "acct", "tok") == h("k:tok")
assert m._upstream_session(None, "acct", None) == h("u:acct")
# 都稳定(缓存要靠它),且都是 32 位十六进制
for v in (a, m._upstream_session("c1", "acct", "tok"), m._upstream_session(None, "acct", None)):
assert len(v) == 32 and all(c in "0123456789abcdef" for c in v), v
def test_inbound_opencode_session_header_reaches_upstream():
"""第三十五轮端到端:入站的 `x-opencode-session` 真的决定了发给上游的会话 id。
- 同一个头 → 稳定(缓存前提);
- 换头 → 换会话;
- 不带头 → 回退到 Key 派生(结果与带头不同);
- 非法头(非 ASCII / 过长)→ 丢弃并回退,绝不把脏值带去上游。
"""
from fastapi.testclient import TestClient
import app.main as m
seen: list[str | None] = []
class FakeAdapter:
async def chat_stream(self, model=None, messages=None, session_id=None, **kw):
seen.append(session_id)
yield {"id": "c1", "choices": [{"index": 0, "delta": {"content": "hi"}}]}
yield {"done": True}
orig = m._get_adapter
m._get_adapter = lambda model_id, timeout=None, cfg=None: (
FakeAdapter(), "agnes", m._cfg().providers["agnes"])
body = {"model": "agnes-3.0-flash", "messages": [{"role": "user", "content": "hi"}],
"stream": True}
try:
client = TestClient(m.app)
def run(headers):
with client.stream("POST", "/v1/chat/completions", headers=headers, json=body) as r:
assert r.status_code == 200, r.read()
"".join(r.iter_text())
run({"x-opencode-session": "conv-A"})
run({"x-opencode-session": "conv-A"})
run({"x-opencode-session": "conv-B"})
run({})
run({"x-opencode-session": "x" * 500}) # 过长(ASCII)→ 丢弃并回退
assert len(seen) == 5, seen
assert seen[0] == seen[1], "同一个入站会话头必须映射到稳定的上游会话"
assert seen[0] != seen[2], "换会话头应换上游会话"
assert seen[0] != seen[3], "带了会话头就不该再用 Key 派生"
assert seen[4] == seen[3], "过长会话头应等同没带(回退到派生)"
assert all(isinstance(x, str) and len(x) == 32 for x in seen), seen
# 非 ASCII 值在 HTTP 层就发不出去(httpx 直接拒),所以用桩验门口的校验:
class _S:
rid = "t"
class _Req:
headers = {"x-opencode-session": "中文会话"}
state = _S()
assert m._inbound_session(_Req()) is None, "非 ASCII 会话头必须被丢弃(不能带进上游 header)"
finally:
m._get_adapter = orig
# 直接运行(非 pytest)—— 必须留在文件末尾,见上方 `test_image_request_goes_to_requested_model` # 直接运行(非 pytest)—— 必须留在文件末尾,见上方 `test_image_request_goes_to_requested_model`
# 之前的旁注:运行器只会收集执行到这一行时已经存在的 globals。 # 之前的旁注:运行器只会收集执行到这一行时已经存在的 globals。
if __name__ == "__main__": if __name__ == "__main__":