docs:"补充 Sub2API 续接与 WebSocket 对照并更正 store=false 下 HTTP 续接不可用"
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
1 parent
fd860a87a2
commit
f2ac810572
1 file changed
+63
-10
@@ -56,7 +56,7 @@
|
|||||||
| `connection_id` | WebSocket 连接 ID(HTTP 为空) |
|
| `connection_id` | WebSocket 连接 ID(HTTP 为空) |
|
||||||
| `parent_response_id` | 本轮引用的上一响应,便于审计链路 |
|
| `parent_response_id` | 本轮引用的上一响应,便于审计链路 |
|
||||||
| `usage_event_id` | 对应 `usage_events.id`(即计费 ticket) |
|
| `usage_event_id` | 对应 `usage_events.id`(即计费 ticket) |
|
||||||
| `created_at`、`expires_at` | 默认保留 24 小时,到期由定时任务清理 |
|
| `created_at`、`expires_at` | 默认保留 1 小时(可配置,与上游 WebSocket 连接上限及 Sub2API 默认值一致),到期由定时任务清理 |
|
||||||
|
|
||||||
不存储请求或响应正文。只存路由与账号指纹,满足“可追溯但不留内容”。
|
不存储请求或响应正文。只存路由与账号指纹,满足“可追溯但不留内容”。
|
||||||
|
|
||||||
@@ -85,11 +85,18 @@
|
|||||||
- 流式/WebSocket:收到 `response.completed` 或 `response.incomplete` 事件、拿到 `response.id` 后写入。
|
- 流式/WebSocket:收到 `response.completed` 或 `response.incomplete` 事件、拿到 `response.id` 后写入。
|
||||||
- 写入失败只记日志、不影响本轮返回;代价是下一轮续接得到 `previous_response_not_found`,客户端按规范回退为完整上下文。这是安全方向的失败。
|
- 写入失败只记日志、不影响本轮返回;代价是下一轮续接得到 `previous_response_not_found`,客户端按规范回退为完整上下文。这是安全方向的失败。
|
||||||
|
|
||||||
## 4. HTTP 续接(COD-01,先做)
|
## 4. HTTP 续接(COD-01)
|
||||||
|
|
||||||
|
> **更正(2026-10-22,核对 Sub2API 后)**:HTTP 续接要求上游保存响应(`store=true`)。本设计强制 `store=false`,上游不保存,HTTP 请求里的 `previous_response_id` 会稳定返回 `previous_response_not_found`。Sub2API 同样只允许 API Key 类账号在 HTTP 下续接,也是依赖上游存储。因此:
|
||||||
|
>
|
||||||
|
> - 若保持 `store=false`(不让上游保存用户对话,当前的隐私与数据驻留立场),**HTTP 续接没有意义**,增量续接只能通过 WebSocket 连接内的缓存实现,见第 5 节。
|
||||||
|
> - 若允许 `store=true`,HTTP 续接可用,但用户的输入和输出会存储在上游服务商处(OpenAI 默认保留 30 天),须在服务条款和隐私说明中告知,并按用户或 Key 单独开启。
|
||||||
|
>
|
||||||
|
> 以下改动点在两种选择下都需要(归属记录、指定账号、跳过备用路由),只是第 1 条的 `store` 处理不同。
|
||||||
|
|
||||||
改动点:
|
改动点:
|
||||||
|
|
||||||
1. `NativeProtocolMeter.request`:允许 `previous_response_id`(字符串,1–128 字符);继续拒绝 `conversation`、`background`、媒体与托管工具;继续强制 `store=false`。
|
1. `NativeProtocolMeter.request`:允许 `previous_response_id`(字符串,1–128 字符);继续拒绝 `conversation`、`background`、媒体与托管工具。`store` 按上面的决定处理:默认仍强制 `false`;若开启存储,则只对已授权的用户或 Key 允许 `true`。
|
||||||
2. 新增 `ResponsesOwnershipService`(`gateway/responses` 包):查询、校验、写入、清理。依赖方向测试中禁止它依赖 HTTP 客户端与凭据解密。
|
2. 新增 `ResponsesOwnershipService`(`gateway/responses` 包):查询、校验、写入、清理。依赖方向测试中禁止它依赖 HTTP 客户端与凭据解密。
|
||||||
3. `OpenAiCompatibleProvider`:
|
3. `OpenAiCompatibleProvider`:
|
||||||
- 新增返回“实际使用账号指纹”的结果包装,供写归属。
|
- 新增返回“实际使用账号指纹”的结果包装,供写归属。
|
||||||
@@ -97,7 +104,7 @@
|
|||||||
4. `NativeGatewayController`:带 `previous_response_id` 时跳过 `GatewayFailover`,只走原路由。
|
4. `NativeGatewayController`:带 `previous_response_id` 时跳过 `GatewayFailover`,只走原路由。
|
||||||
5. 计费:不变。续接请求的输入 Token 由上游 `usage.input_tokens` 计量(包含被续接的历史上下文),`input_tokens_details.cached_tokens` 走现有缓存价。预留按本轮请求体估算,偏低部分由结算时的实际用量和现有欠费处理兜底。
|
5. 计费:不变。续接请求的输入 Token 由上游 `usage.input_tokens` 计量(包含被续接的历史上下文),`input_tokens_details.cached_tokens` 走现有缓存价。预留按本轮请求体估算,偏低部分由结算时的实际用量和现有欠费处理兜底。
|
||||||
|
|
||||||
## 5. WebSocket 入口(COD-02,后做)
|
## 5. WebSocket 入口(COD-02)
|
||||||
|
|
||||||
### 5.1 连接与鉴权
|
### 5.1 连接与鉴权
|
||||||
|
|
||||||
@@ -155,14 +162,60 @@
|
|||||||
|
|
||||||
1. V51 归属表与 `ResponsesOwnershipService`,附单元与数据库回归。
|
1. V51 归属表与 `ResponsesOwnershipService`,附单元与数据库回归。
|
||||||
2. Provider 返回实际账号指纹与 pinned-key 入口。
|
2. Provider 返回实际账号指纹与 pinned-key 入口。
|
||||||
3. HTTP 续接放开与路由固定(COD-01 主体)。
|
3. 按第 9 节的决定二选一:
|
||||||
4. WebSocket 入口与连接管理(COD-02)。
|
- 保持 `store=false`:做 WebSocket 入口与连接管理(COD-02),增量续接只在连接内有效;HTTP 继续拒绝 `previous_response_id`。
|
||||||
5. 部署配置评审与客户端验收。
|
- 允许 `store=true`:先放开 HTTP 续接与路由固定(COD-01),WebSocket 之后再做。
|
||||||
|
4. 部署配置评审(WebSocket 需改 nginx)与客户端验收。
|
||||||
|
|
||||||
每一步单独提交,全量测试通过后再进入下一步。
|
每一步单独提交,全量测试通过后再进入下一步。
|
||||||
|
|
||||||
## 9. 待你确认
|
## 9. 待你确认
|
||||||
|
|
||||||
1. 归属记录默认保留 24 小时是否合适(越长越占库,越短越容易让长会话回退完整上下文)。
|
(2026-10-22 按第 10 节 Sub2API 对照修订)
|
||||||
2. 归属账号不可用时直接返回 409、由客户端重发完整上下文,而不是服务端自动重放历史。服务端不保存正文,所以无法自动重放,这是设计取舍。
|
|
||||||
3. 是否需要 WebSocket。只做 HTTP 续接(第 1–3 步)已经能让 Codex 增量续接,WebSocket 主要节省延迟,代价是代理配置和连接管理。
|
1. **是否允许上游存储(`store=true`)**。这是最先要定的:不允许,则增量续接只能走 WebSocket;允许,则 HTTP 续接可用,但用户对话会存在上游服务商处,需告知并按用户或 Key 开启。
|
||||||
|
2. 归属记录默认保留 1 小时,可配置。
|
||||||
|
3. 原账号不可用时返回 409、由客户端重发完整上下文,不换号。若做 WebSocket,可在连接内存中保留本连接历史,用于一次性服务端重放(参考 Sub2API)。
|
||||||
|
|
||||||
|
## 10. Sub2API 对照(2026-10-22 源码核对)
|
||||||
|
|
||||||
|
核对对象:[Wei-Shaw/sub2api](https://github.com/Wei-Shaw/sub2api) 主分支 `dba770d5`(2026-10-22),最新发布 `v0.2.17`。通过 GitHub API 读取以下文件,只读未复制代码(Sub2API 为 LGPL):`backend/internal/service/openai_ws_state_store.go`、`openai_account_scheduler.go`、`openai_ws_forwarder*.go`、`openai_ws_forwarder_payload.go`、`backend/internal/handler/openai_gateway_handler.go`、`deploy/config.example.yaml`。
|
||||||
|
|
||||||
|
### 10.1 归属记录与保留时间
|
||||||
|
|
||||||
|
- 存储:`response_id → account_id` 与 `response_id → (user_id, api_key_id)` 存 Redis,Key 为 `response_id` 的 SHA-256,进程内另有热缓存(单表上限 65536 条,满了随机淘汰一条)。`response_id → conn_id` 只在进程内。按分组 ID 隔离。
|
||||||
|
- 保留时间:`sticky_response_id_ttl_seconds: 3600`,即 **1 小时**,会话粘性 `sticky_session_ttl_seconds` 也是 1 小时。代码默认值同为 1 小时。
|
||||||
|
- 读不到 Redis 时按“未命中”降级,不阻断请求。
|
||||||
|
- 归属校验:HTTP 带 `previous_response_id` 时先校验用户与 Key,不匹配返回 `400 previous_response_id is not available for this user`。另外会拒绝看起来像消息 ID(`msg_`、`item_` 等)的值。
|
||||||
|
|
||||||
|
与本设计的差异:我们用 PostgreSQL 表、默认 24 小时;Sub2API 用 Redis、1 小时。Sub2API 不记录凭据版本。
|
||||||
|
|
||||||
|
### 10.2 原账号不可用时
|
||||||
|
|
||||||
|
- 调度器先按 `previous_response_id` 找原账号;原账号不兼容(分组、模型、传输方式、被封禁、隔离等)时**放弃粘连,按正常调度另选账号**,请求照常发出,不直接报错。
|
||||||
|
- 例外:输入里带 `function_call_output` 且上下文不能覆盖所有调用 ID 时,`previous_response_id` 视为不可迁移(`previousResponseCanMove=false`),只能走原账号。
|
||||||
|
- HTTP 模式下 OAuth 订阅账号不支持 `previous_response_id`,会跳过这类账号,全部不行时返回 400。
|
||||||
|
|
||||||
|
### 10.3 续接失败的恢复
|
||||||
|
|
||||||
|
- WebSocket 接入模式下,上游返回 `previous_response_not_found` 时,默认 `ingress_previous_response_recovery_enabled: true`:**服务端去掉 `previous_response_id`,用自己保留的前几轮输入拼成完整上下文,重放一次**。
|
||||||
|
- 前提:这一轮还没向客户端写出内容;请求不含 `function_call_output`(否则上游会报找不到工具调用);每轮最多尝试一次。
|
||||||
|
- 重放所需的历史输入只保存在**该 WebSocket 连接的内存里**,不落库,连接断开即丢失。所以重连后仍需客户端自己发完整上下文。
|
||||||
|
- HTTP 模式没有这种服务端重放,失败直接返回错误。
|
||||||
|
|
||||||
|
### 10.4 WebSocket
|
||||||
|
|
||||||
|
- 默认开启(`openai_ws.enabled: true`,协议特性 `responses_websockets_v2: true`),有全局回退 HTTP 的紧急开关 `force_http`。
|
||||||
|
- 关键参数:每个 Key 最多 64 个客户端连接;两轮之间空闲 300 秒关闭;首条消息读取超时 30 秒;上游读超时 900 秒;每个上游账号最多 128 条连接、按账号并发 × 5 动态限制;`store=false` 且无可复用连接时默认强制新建连接(隔离优先);`generate:false` 预热默认关闭。
|
||||||
|
- 有多种接入模式(`ctx_pool` 连接池、`passthrough` 直通、`http_bridge` 转成 HTTP 请求),实现规模大(WebSocket 相关源码超过 30 万字节)。
|
||||||
|
- 部署文档未单独说明反向代理的 WebSocket 配置(未找到相关段落)。
|
||||||
|
|
||||||
|
### 10.5 对本设计三个问题的影响
|
||||||
|
|
||||||
|
| 问题 | Sub2API 做法 | 建议 |
|
||||||
|
|---|---|---|
|
||||||
|
| 保留时间 | Redis 1 小时 | 已改为默认 **1 小时**、可配置。上游 WebSocket 连接最长 60 分钟,`store=false` 下连接一断响应就找不到,保留更久意义不大 |
|
||||||
|
| 原账号不可用 | 换号重发(工具输出链路除外);WebSocket 内可用连接内存里的历史自动重放一次 | 保持 **409、由客户端重发**。我们 `store=false`,换号后上游一定找不到该响应,换号只会多一次失败请求;不保存正文也就无法服务端重放。若之后做 WebSocket,可考虑像 Sub2API 一样只在连接内存中保留本连接的历史,用于一次性重放 |
|
||||||
|
| WebSocket | 默认开启,功能完整但复杂度高 | 取决于是否允许 `store=true`(见第 4 节更正):不允许,则 WebSocket 是唯一的增量续接方式;允许,则可先做 HTTP 续接。Sub2API 的规模说明 WebSocket 是独立的一大块工作 |
|
||||||
|
|
||||||
|
注:本节依据源码阅读,没有部署 Sub2API 或实测其行为。
|
||||||
Reference in new issue
Block a user