docs:"Codex Responses 续接归属与 WebSocket 设计(待评审)"
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
1 parent
aef5356c54
commit
c04b9262c4
2 files changed
+170
-2
No files matched your search
@@ -22,8 +22,8 @@
|
|||||||
| SEC-05 | Provider 有界 HTTP Transport | 部分完成:异步 JSON/multipart/音频/媒体已接有界读取和总期限;同步/SSE 生命周期尚未统一抽取 | 超大 chunk、慢响应体、已观察拒绝状态、取消、重定向及原适配器回归 |
|
| SEC-05 | Provider 有界 HTTP Transport | 部分完成:异步 JSON/multipart/音频/媒体已接有界读取和总期限;同步/SSE 生命周期尚未统一抽取 | 超大 chunk、慢响应体、已观察拒绝状态、取消、重定向及原适配器回归 |
|
||||||
| SEC-06 | 媒体下载出站 / SSRF | 服务端参考图下载的代码级 DNS 绑定已实现并通过本地回归;生产网络隔离与实际部署验收仍未完成 | 一次解析、整组地址校验、固定地址直连、原域名 TLS/SNI、禁代理与跳转;109 项新增回归,见 26 号文档 |
|
| SEC-06 | 媒体下载出站 / SSRF | 服务端参考图下载的代码级 DNS 绑定已实现并通过本地回归;生产网络隔离与实际部署验收仍未完成 | 一次解析、整组地址校验、固定地址直连、原域名 TLS/SNI、禁代理与跳转;109 项新增回归,见 26 号文档 |
|
||||||
| SEC-07 | 整体安全审查与生产验收 | 未完成:已补验证码/账号原子性;本轮进一步分离加密投递、统一已知/未知账号重置受理和限额,外部投递不再持 DB 事务;管理接口全审查、时序残余、默认配置、依赖与备份恢复仍需继续 | 本轮新增 22 项投递数据库回归,全量 390 项通过;真实邮件/短信与规格驱动验收未执行,禁止宣称“全仓库安全” |
|
| SEC-07 | 整体安全审查与生产验收 | 未完成:已补验证码/账号原子性;本轮进一步分离加密投递、统一已知/未知账号重置受理和限额,外部投递不再持 DB 事务;管理接口全审查、时序残余、默认配置、依赖与备份恢复仍需继续 | 本轮新增 22 项投递数据库回归,全量 390 项通过;真实邮件/短信与规格驱动验收未执行,禁止宣称“全仓库安全” |
|
||||||
| COD-01 | Codex 协议能力及验收矩阵 | 未实现完整兼容;保留有限文本 Responses 的明确拒绝语义 | 指定客户端版本、模型、工具和计费联合验收 |
|
| COD-01 | Codex 协议能力及验收矩阵 | 未实现;HTTP 续接方案见 30 号设计文档(待评审),保留有限文本 Responses 的明确拒绝语义 | 指定客户端版本、模型、工具和计费联合验收 |
|
||||||
| COD-02 | Responses WebSocket 与响应归属续接 | 未实现,不可宣传完整 Codex 支持 | 原账号/凭据版本归属、断线、取消、租约、费用一致性 |
|
| COD-02 | Responses WebSocket 与响应归属续接 | 未实现;响应归属表与 WebSocket 方案见 30 号设计文档(待评审),不可宣传完整 Codex 支持 | 原账号/凭据版本归属、断线、取消、租约、费用一致性 |
|
||||||
| COD-03 | 长请求连接/空闲/总期限与续租 | 部分完成:同步/流式上游拆分首字节、空闲、总期限(总期限上限 3600 秒,默认仍 90 秒);执行期间每 60 秒续期钱包预留与 Redis 并发租约,结束即停,丢失的租约不会被重建。部署侧 nginx `proxy_read_timeout 120s` 与云端 Compose 未透传新变量,放宽前须同步调整;原生请求 256 KiB / 32K 输出上限未动 | 并发租约、钱包预留恢复、长流/取消共同验证 |
|
| COD-03 | 长请求连接/空闲/总期限与续租 | 部分完成:同步/流式上游拆分首字节、空闲、总期限(总期限上限 3600 秒,默认仍 90 秒);执行期间每 60 秒续期钱包预留与 Redis 并发租约,结束即停,丢失的租约不会被重建。部署侧 nginx `proxy_read_timeout 120s` 与云端 Compose 未透传新变量,放宽前须同步调整;原生请求 256 KiB / 32K 输出上限未动 | 并发租约、钱包预留恢复、长流/取消共同验证 |
|
||||||
| SCH-01 | 独立上游账号生命周期与调度 | 仅共享 Key 轮换/冷却/指纹,非完整账号实体 | 凭据版本、额度、模型范围、权重及解释能力 |
|
| SCH-01 | 独立上游账号生命周期与调度 | 仅共享 Key 轮换/冷却/指纹,非完整账号实体 | 凭据版本、额度、模型范围、权重及解释能力 |
|
||||||
| SCH-02 | 公平排队 / 取消 / 共享等待预算 | 部分完成:模型+Key 配对准入改为模型级 FIFO(到达顺序 ZSET,过期/超时/放弃即出队;仅因自身 Key 满而等待者不占模型队位),真实 Redis 回归证明旧脚本会被插队;跨路由共享等待预算、优先级与横向压测仍缺 | 多客户端饥饿/FIFO/取消回收与横向并发验证 |
|
| SCH-02 | 公平排队 / 取消 / 共享等待预算 | 部分完成:模型+Key 配对准入改为模型级 FIFO(到达顺序 ZSET,过期/超时/放弃即出队;仅因自身 Key 满而等待者不占模型队位),真实 Redis 回归证明旧脚本会被插队;跨路由共享等待预算、优先级与横向压测仍缺 | 多客户端饥饿/FIFO/取消回收与横向并发验证 |
|
||||||
|
|||||||
@@ -0,0 +1,168 @@
|
|||||||
|
# Codex 兼容:Responses 续接归属与 WebSocket 设计(COD-01/COD-02)
|
||||||
|
|
||||||
|
日期:2026-10-22(Asia/Shanghai)。状态:**设计待评审,未实现**。对应 24 号任务表 COD-01、COD-02,承接 29 号文档第五节与第八节第二阶段。
|
||||||
|
|
||||||
|
## 1. 目标与非目标
|
||||||
|
|
||||||
|
目标:
|
||||||
|
|
||||||
|
- 让 Codex 等编程客户端通过 MOYI 使用 Responses 协议的增量续接(`previous_response_id`),不再每轮发送完整上下文。
|
||||||
|
- 提供 Responses WebSocket 入口,单连接多轮、顺序执行。
|
||||||
|
- 每个上游响应都能追溯到产生它的渠道账号与凭据版本,续接**只能**发往同一账号;无法满足时明确失败,不静默换号。
|
||||||
|
- 计费、预留、并发租约、用量审计与现有 HTTP 路径共用同一套合同(`GatewayRequestExecutionService`),不另起账本。
|
||||||
|
|
||||||
|
非目标(本期不做):
|
||||||
|
|
||||||
|
- 上游 `store=true` 的云端会话、`conversation` 对象、`background` 后台任务。
|
||||||
|
- 图片、文件、托管工具(web_search、code_interpreter 等)。它们需要单独计费适配器,仍按现状拒绝。
|
||||||
|
- OAuth 订阅账号池(OPS-02,可选方案,须先核实授权)。
|
||||||
|
- 跨实例共享 WebSocket 连接。单个连接只存在于持有它的 API 实例。
|
||||||
|
|
||||||
|
## 2. 依据与当前代码事实
|
||||||
|
|
||||||
|
外部协议依据(Azure OpenAI Responses WebSocket 文档,2026-10-22 读取;OpenAI 官方页面在本机网络不可访问,未直接核对):
|
||||||
|
|
||||||
|
- 连接路径为 `/v1/responses`,客户端发送 `{"type":"response.create", ...}`,载荷同 HTTP 创建请求,但不适用 `stream`、`background`。
|
||||||
|
- 同一连接内**顺序执行**,同时只有一个进行中的响应。(部分资料提及按 `stream_id` 并行的新版本,未经核实,本设计按顺序执行实现,并在客户端验收中确认实际版本。)
|
||||||
|
- 连接本地缓存**最近一个**响应状态;`store=false` 时引用不在缓存中的 ID 返回 `previous_response_not_found`;某一轮 4xx/5xx 失败会从缓存驱逐被引用的父响应。
|
||||||
|
- 连接最长 60 分钟,到期返回 `websocket_connection_limit_reached`,须重连;`store=false` 下重连后只能不带 `previous_response_id`、重发完整上下文。
|
||||||
|
- 可用 `generate:false` 预热,返回可续接的响应 ID 但不产生输出。
|
||||||
|
|
||||||
|
本仓库当前事实(已读代码核实):
|
||||||
|
|
||||||
|
| 位置 | 现状 | 对本设计的影响 |
|
||||||
|
|---|---|---|
|
||||||
|
| `gateway/NativeProtocolMeter.java` | 拒绝 `previous_response_id`、`conversation`、`background`;强制 `store=false`;请求上限 256 KiB;输出上限 32768 | 续接需放开 `previous_response_id`,其余限制保留 |
|
||||||
|
| `provider/UpstreamHealth.java` | `X-Moyi-Session` 加平台 Key 做 rendezvous 哈希选号;账号冷却后会改选其他账号 | 只能算“尽量同号”,不能保证续接归属 |
|
||||||
|
| `provider/OpenAiCompatibleProvider.java` | 账号选择、401/403/429 换号重试都在一次请求内部完成;不对外暴露最终使用的账号 | 需要把“实际使用的账号指纹”返回给调用方 |
|
||||||
|
| `model_tasks.provider_key_fingerprint`(V33) | 异步任务已按账号指纹绑定轮询 | 同步续接沿用相同的指纹方案,不存明文 Key |
|
||||||
|
| `gateway/request/GatewayRequestExecutionService` | 统一准入、预留、续期(COD-03)、结算、失败释放 | WebSocket 每一轮都走它,复用续期 |
|
||||||
|
| nginx `infra/moyi/nginx/routes.conf`、`prototype/nginx.conf` | 无 `Upgrade`/`Connection` 转发,读超时 120 秒 | WebSocket 必须改代理配置,属部署变更 |
|
||||||
|
|
||||||
|
## 3. 核心设计:响应归属记录
|
||||||
|
|
||||||
|
### 3.1 记录什么
|
||||||
|
|
||||||
|
新增表 `responses_ownership`(迁移 V51),每个**成功完成**的上游 Responses 响应写一行:
|
||||||
|
|
||||||
|
| 列 | 说明 |
|
||||||
|
|---|---|
|
||||||
|
| `response_id` | 上游返回的 `id`,主键(`varchar(128)`) |
|
||||||
|
| `user_id`、`api_key_id` | 发起方。续接时必须与当前调用方一致,防止拿别人的 ID 续接 |
|
||||||
|
| `route_id`、`provider_id`、`upstream_model` | 产生该响应的路由快照 |
|
||||||
|
| `account_fingerprint` | 实际使用账号的 SHA-256 指纹(同 `UpstreamHealth.fingerprint`),不存明文 |
|
||||||
|
| `credential_version` | 渠道凭据版本,见 3.3 |
|
||||||
|
| `transport` | `http` 或 `websocket` |
|
||||||
|
| `connection_id` | WebSocket 连接 ID(HTTP 为空) |
|
||||||
|
| `parent_response_id` | 本轮引用的上一响应,便于审计链路 |
|
||||||
|
| `usage_event_id` | 对应 `usage_events.id`(即计费 ticket) |
|
||||||
|
| `created_at`、`expires_at` | 默认保留 24 小时,到期由定时任务清理 |
|
||||||
|
|
||||||
|
不存储请求或响应正文。只存路由与账号指纹,满足“可追溯但不留内容”。
|
||||||
|
|
||||||
|
### 3.2 续接时如何使用
|
||||||
|
|
||||||
|
收到带 `previous_response_id` 的请求(HTTP 或 WebSocket):
|
||||||
|
|
||||||
|
1. 按 `response_id` 查归属行。不存在或已过期:返回 `400 previous_response_not_found`(与上游错误码一致),**不发往上游**、不预留。
|
||||||
|
2. `user_id`/`api_key_id` 与当前调用方不一致:同样返回 `previous_response_not_found`,不泄露该 ID 是否存在。
|
||||||
|
3. 路由已下线、模型不一致、账号指纹不在当前可用账号集合中、凭据版本已变化、或账号处于冷却:返回 `409 RESPONSE_OWNER_UNAVAILABLE`,提示客户端不带 `previous_response_id` 重发完整上下文。**不换号**:其他账号持有的上游状态里没有这个响应,换号只会得到上游的 `previous_response_not_found`,还可能已经产生费用。
|
||||||
|
4. 校验通过:以“指定账号”方式调用上游(新增 `OpenAiCompatibleProvider` 的 pinned-key 入口),禁用该请求内的 401/403/429 换号重试与 `GatewayFailover` 备用路由。
|
||||||
|
|
||||||
|
### 3.3 凭据版本
|
||||||
|
|
||||||
|
当前渠道 Key 来自 `model_providers.credential_ciphertext` 或环境变量 Key 池,没有版本号。方案:
|
||||||
|
|
||||||
|
- 数据库渠道:`credential_version` 取渠道 `updated_at`。注意当前任何渠道编辑(包括改名)都会更新该字段,所以编辑渠道会让已有续接失效。这是偏保守的取舍,不新增管理界面。
|
||||||
|
- 环境变量 Key 池:没有版本号,只靠账号指纹。Key 被替换后指纹必然改变,旧响应同样失效。
|
||||||
|
- 自 `1a608f8` 起,修改渠道 Base URL 必须重填凭据,因此地址变更一定会触发失效,走 3.2 第 3 步。
|
||||||
|
|
||||||
|
真正独立的账号实体与版本属于 SCH-01,本期不扩展。
|
||||||
|
|
||||||
|
### 3.4 写入时机与一致性
|
||||||
|
|
||||||
|
- HTTP 非流式:在 `settle` 成功之后写入归属行。结算失败(`SETTLEMENT_PENDING`)时仍写入,因为上游响应已存在;归属不影响账务。
|
||||||
|
- 流式/WebSocket:收到 `response.completed` 或 `response.incomplete` 事件、拿到 `response.id` 后写入。
|
||||||
|
- 写入失败只记日志、不影响本轮返回;代价是下一轮续接得到 `previous_response_not_found`,客户端按规范回退为完整上下文。这是安全方向的失败。
|
||||||
|
|
||||||
|
## 4. HTTP 续接(COD-01,先做)
|
||||||
|
|
||||||
|
改动点:
|
||||||
|
|
||||||
|
1. `NativeProtocolMeter.request`:允许 `previous_response_id`(字符串,1–128 字符);继续拒绝 `conversation`、`background`、媒体与托管工具;继续强制 `store=false`。
|
||||||
|
2. 新增 `ResponsesOwnershipService`(`gateway/responses` 包):查询、校验、写入、清理。依赖方向测试中禁止它依赖 HTTP 客户端与凭据解密。
|
||||||
|
3. `OpenAiCompatibleProvider`:
|
||||||
|
- 新增返回“实际使用账号指纹”的结果包装,供写归属。
|
||||||
|
- 新增 pinned-key 调用:只用指定指纹对应的 Key;该 Key 不在 Key 池或已冷却时在发送前报 `RESPONSE_OWNER_UNAVAILABLE`。
|
||||||
|
4. `NativeGatewayController`:带 `previous_response_id` 时跳过 `GatewayFailover`,只走原路由。
|
||||||
|
5. 计费:不变。续接请求的输入 Token 由上游 `usage.input_tokens` 计量(包含被续接的历史上下文),`input_tokens_details.cached_tokens` 走现有缓存价。预留按本轮请求体估算,偏低部分由结算时的实际用量和现有欠费处理兜底。
|
||||||
|
|
||||||
|
## 5. WebSocket 入口(COD-02,后做)
|
||||||
|
|
||||||
|
### 5.1 连接与鉴权
|
||||||
|
|
||||||
|
- 路径 `GET /v1/responses`,`Upgrade: websocket`。使用 Spring WebSocket(新增 `spring-boot-starter-websocket`,版本跟随 Spring Boot parent)。
|
||||||
|
- 握手时用 `Authorization: Bearer <MOYI Key>` 鉴权,复用 `CatalogService.authenticateKey` 与 `EnterprisePolicies.access`(IP 白名单、过期)。不接受 URL 查询参数里的 Key。
|
||||||
|
- 每个平台 Key 的并发 WebSocket 连接数设上限(默认 4,复用 Key 并发配置),超出时拒绝握手。
|
||||||
|
|
||||||
|
### 5.2 连接内的每一轮
|
||||||
|
|
||||||
|
- 每个 `response.create` 视为一次独立的计费请求:走 `GatewayRequestExecutionService.execute`,独立准入、预留、续期、结算、用量记录。连接本身不预留费用。
|
||||||
|
- 同一连接顺序执行:上一轮未结束时收到新的 `response.create`,返回 `error` 事件(`code: response_in_progress`),不排队,避免隐性占用资源。
|
||||||
|
- 上游侧:每个客户端连接对应**一个**上游 WebSocket 连接,绑定首轮选中的账号。后续轮次固定使用该账号,不换号。上游连接断开时,本地也关闭客户端连接,并返回上游的错误码,让客户端按协议重连。
|
||||||
|
- 首轮无 `previous_response_id` 时正常选号;首轮带 `previous_response_id` 时,按第 3.2 节归属选择上游账号。
|
||||||
|
- 连接最长 60 分钟(与上游一致,可配置更短)。到期发送 `websocket_connection_limit_reached` 后关闭。
|
||||||
|
|
||||||
|
### 5.3 中断、取消与计费
|
||||||
|
|
||||||
|
| 情况 | 处理 |
|
||||||
|
|---|---|
|
||||||
|
| 客户端在一轮进行中断开 | 继续读取上游直至该轮完成并结算(与现有 SSE“浏览器断开不变成免费调用”一致),然后关闭上游连接 |
|
||||||
|
| 上游在一轮进行中断开 | 已有完整 `response.completed` 则结算;否则按现有规则 `UPSTREAM_STREAM_INCOMPLETE`,释放预留,记 `cost_status='pending'` 待核账 |
|
||||||
|
| 空闲(无进行中轮次)超时 | 关闭连接,无费用 |
|
||||||
|
| 服务重启 | 进行中轮次由预留过期恢复处理(COD-03 续期停止后最多 5 分钟释放或按已持久化用量结算) |
|
||||||
|
|
||||||
|
### 5.4 部署前置条件
|
||||||
|
|
||||||
|
- nginx 两处配置都要为 `/v1/responses` 增加 `proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";`,读超时不低于连接上限。
|
||||||
|
- 云端 Compose 透传 COD-03 的超时变量。
|
||||||
|
- 这些都是线上配置变更,单独评审,不随代码自动生效。
|
||||||
|
|
||||||
|
## 6. 安全与滥用边界
|
||||||
|
|
||||||
|
- 归属校验是访问控制:A 用户的响应 ID 对 B 用户统一表现为“不存在”。
|
||||||
|
- 不接受客户端指定上游账号、Base URL、凭据(现有限制保留)。
|
||||||
|
- `previous_response_id` 只作为字符串透传,长度限制并做字符集校验(`[A-Za-z0-9_-]`),避免日志或 SQL 注入面。
|
||||||
|
- WebSocket 单帧大小上限沿用 256 KiB 请求上限;超限关闭连接。
|
||||||
|
|
||||||
|
## 7. 测试与验收
|
||||||
|
|
||||||
|
自动化(本地,与现有门禁一起跑):
|
||||||
|
|
||||||
|
- 归属:写入、过期、跨用户统一返回 `previous_response_not_found`、路由下线/指纹变化/冷却时 409 且不发上游请求。
|
||||||
|
- pinned-key:只用指定 Key,不触发换号重试与备用路由。
|
||||||
|
- HTTP 续接:上游桩返回带 `id` 的完成响应,第二轮带 `previous_response_id` 只打到同一 Key。
|
||||||
|
- WebSocket:握手鉴权、顺序执行拒绝并发、客户端断开仍结算一次、上游中断释放预留、60 分钟上限(用可配置短时限测试)。
|
||||||
|
- 依赖方向:`gateway/responses` 不依赖 HTTP 客户端与凭据。
|
||||||
|
|
||||||
|
客户端验收(需要你授权真实上游与付费调用,未授权前不做):
|
||||||
|
|
||||||
|
- 指定 Codex CLI 版本,配置 MOYI 为 Responses 端点,跑一组固定任务:多轮工具调用、断线重连、超过 60 分钟的会话。
|
||||||
|
- 每轮核对:上游账号一致、用量与扣费一致、续接失败时客户端能回退完整上下文。
|
||||||
|
- 结果记录到兼容矩阵(客户端 × 协议 × 上游 × 能力),并保存日期与证据。
|
||||||
|
|
||||||
|
## 8. 实施顺序
|
||||||
|
|
||||||
|
1. V51 归属表与 `ResponsesOwnershipService`,附单元与数据库回归。
|
||||||
|
2. Provider 返回实际账号指纹与 pinned-key 入口。
|
||||||
|
3. HTTP 续接放开与路由固定(COD-01 主体)。
|
||||||
|
4. WebSocket 入口与连接管理(COD-02)。
|
||||||
|
5. 部署配置评审与客户端验收。
|
||||||
|
|
||||||
|
每一步单独提交,全量测试通过后再进入下一步。
|
||||||
|
|
||||||
|
## 9. 待你确认
|
||||||
|
|
||||||
|
1. 归属记录默认保留 24 小时是否合适(越长越占库,越短越容易让长会话回退完整上下文)。
|
||||||
|
2. 归属账号不可用时直接返回 409、由客户端重发完整上下文,而不是服务端自动重放历史。服务端不保存正文,所以无法自动重放,这是设计取舍。
|
||||||
|
3. 是否需要 WebSocket。只做 HTTP 续接(第 1–3 步)已经能让 Codex 增量续接,WebSocket 主要节省延迟,代价是代理配置和连接管理。
|
||||||
Reference in new issue
Block a user