diff --git a/docs/24-security-and-cpr-task-tracker.md b/docs/24-security-and-cpr-task-tracker.md index 8a6990f..85932a5 100644 --- a/docs/24-security-and-cpr-task-tracker.md +++ b/docs/24-security-and-cpr-task-tracker.md @@ -22,8 +22,8 @@ | SEC-05 | Provider 有界 HTTP Transport | 部分完成:异步 JSON/multipart/音频/媒体已接有界读取和总期限;同步/SSE 生命周期尚未统一抽取 | 超大 chunk、慢响应体、已观察拒绝状态、取消、重定向及原适配器回归 | | SEC-06 | 媒体下载出站 / SSRF | 服务端参考图下载的代码级 DNS 绑定已实现并通过本地回归;生产网络隔离与实际部署验收仍未完成 | 一次解析、整组地址校验、固定地址直连、原域名 TLS/SNI、禁代理与跳转;109 项新增回归,见 26 号文档 | | SEC-07 | 整体安全审查与生产验收 | 未完成:已补验证码/账号原子性;本轮进一步分离加密投递、统一已知/未知账号重置受理和限额,外部投递不再持 DB 事务;管理接口全审查、时序残余、默认配置、依赖与备份恢复仍需继续 | 本轮新增 22 项投递数据库回归,全量 390 项通过;真实邮件/短信与规格驱动验收未执行,禁止宣称“全仓库安全” | -| COD-01 | Codex 协议能力及验收矩阵 | 未实现;HTTP 续接方案见 30 号设计文档(待评审),保留有限文本 Responses 的明确拒绝语义 | 指定客户端版本、模型、工具和计费联合验收 | -| COD-02 | Responses WebSocket 与响应归属续接 | 未实现;响应归属表与 WebSocket 方案见 30 号设计文档(待评审),不可宣传完整 Codex 支持 | 原账号/凭据版本归属、断线、取消、租约、费用一致性 | +| COD-01 | Codex 协议能力及验收矩阵 | 暂缓(2026-10-22 决定):不允许上游存储,HTTP 续接不可行;恢复时与 Sub2API 对齐,见 30 号文档第 0 节。保留有限文本 Responses 的明确拒绝语义 | 指定客户端版本、模型、工具和计费联合验收 | +| COD-02 | Responses WebSocket 与响应归属续接 | 暂缓(2026-10-22 决定):增量续接唯一途径是 WebSocket,须同时改 nginx 并补连接管理;对齐清单见 30 号文档第 0 节,不可宣传完整 Codex 支持 | 原账号/凭据版本归属、断线、取消、租约、费用一致性 | | COD-03 | 长请求连接/空闲/总期限与续租 | 部分完成:同步/流式上游拆分首字节、空闲、总期限(总期限上限 3600 秒,默认仍 90 秒);执行期间每 60 秒续期钱包预留与 Redis 并发租约,结束即停,丢失的租约不会被重建。部署侧 nginx `proxy_read_timeout 120s` 与云端 Compose 未透传新变量,放宽前须同步调整;原生请求 256 KiB / 32K 输出上限未动 | 并发租约、钱包预留恢复、长流/取消共同验证 | | SCH-01 | 独立上游账号生命周期与调度 | 仅共享 Key 轮换/冷却/指纹,非完整账号实体 | 凭据版本、额度、模型范围、权重及解释能力 | | SCH-02 | 公平排队 / 取消 / 共享等待预算 | 部分完成:模型+Key 配对准入改为模型级 FIFO(到达顺序 ZSET,过期/超时/放弃即出队;仅因自身 Key 满而等待者不占模型队位),真实 Redis 回归证明旧脚本会被插队;跨路由共享等待预算、优先级与横向压测仍缺 | 多客户端饥饿/FIFO/取消回收与横向并发验证 | diff --git a/docs/30-codex-responses-continuation-design.md b/docs/30-codex-responses-continuation-design.md index edc4c65..ca3fbbe 100644 --- a/docs/30-codex-responses-continuation-design.md +++ b/docs/30-codex-responses-continuation-design.md @@ -1,6 +1,44 @@ # Codex 兼容:Responses 续接归属与 WebSocket 设计(COD-01/COD-02) -日期:2026-10-22(Asia/Shanghai)。状态:**设计待评审,未实现**。对应 24 号任务表 COD-01、COD-02,承接 29 号文档第五节与第八节第二阶段。 +日期:2026-10-22(Asia/Shanghai)。状态:**暂缓实施(2026-10-22 决定,见第 0 节)**。对应 24 号任务表 COD-01、COD-02,承接 29 号文档第五节与第八节第二阶段。 + +## 0. 决定(2026-10-22) + +1. **暂不实施** COD-01/COD-02。现有行为不变:Responses 入口继续拒绝 `previous_response_id`,不提供 WebSocket。 +2. **不允许上游存储对话**,继续强制 `store=false`。 +3. **本阶段目标是在 Sub2API 的能力基础上做企业化**(组织、权限、人民币计费、审计、运维治理),不做协议层的革新设计。日后恢复续接与 WebSocket 时,以 Sub2API 的行为为基线对齐,见 0.2。 + +### 0.1 不存储对话的后果 + +`store=false` 时上游不保存响应,HTTP 请求里的 `previous_response_id` 一定得到 `previous_response_not_found`。**增量续接的唯一途径是 WebSocket**:上游只在一条活动连接的内存里缓存最近的响应状态,连接断开或满 60 分钟即失效。因此恢复这项工作时必须同时完成: + +- **服务器 nginx 配置**:`infra/moyi/nginx/routes.conf` 与 `prototype/nginx.conf` 为 `/v1/responses` 转发 `Upgrade` 和 `Connection: upgrade`;读超时不低于连接上限(Sub2API 上游读超时 900 秒,连接上限 60 分钟);云端 Compose 透传 COD-03 的超时变量。这是线上配置变更,须单独评审。 +- **连接管理**: + - 每个平台 Key 的连接数上限; + - 首条消息读取超时、两轮之间的空闲超时、60 分钟连接上限; + - 每个客户端连接绑定一条上游连接及其账号; + - 连接内存里保留本连接的历史输入,用于续接失败时服务端重放一次,不落库; + - 客户端或上游断开时,进行中的一轮按现有规则结算或释放预留。 + +HTTP 续接只有在允许 `store=true` 时才可行,与第 2 条决定冲突,本阶段不做。 + +### 0.2 恢复实施时与 Sub2API 对齐的清单 + +依据第 10 节的源码核对。 + +| 事项 | Sub2API 行为 | MOYI 实施时 | +|---|---|---| +| 归属存储 | Redis,Key 为 `response_id` 的 SHA-256,按分组隔离;进程内热缓存 | 对齐:用现有 Tair,同样只存哈希 Key 和账号 ID | +| 保留时间 | 1 小时(`sticky_response_id_ttl_seconds: 3600`) | 对齐:1 小时,可配置 | +| 归属校验 | 校验用户与 Key,不匹配返回 400 | 对齐 | +| 消息 ID 误用 | 拒绝 `msg_`、`item_` 等前缀 | 对齐 | +| 原账号不可用 | 放弃粘连,正常调度另选账号;带未覆盖的 `function_call_output` 时只能走原账号 | 对齐 | +| `previous_response_not_found` | WebSocket 内用连接内存的历史去掉 `previous_response_id` 重放一次(未向客户端输出、无工具输出、每轮一次) | 对齐 | +| WebSocket 参数 | 每 Key 64 连接、轮间空闲 300 秒、首消息 30 秒、上游读 900 秒、`store=false` 时优先新建连接、预热默认关闭 | 作为默认值起点,按服务器容量调整 | + +MOYI 保留自己的企业化部分:每一轮独立走人民币钱包预留、续期与结算(`GatewayRequestExecutionService`)、用量审计、凭据加密存储。这些属于企业化而非协议创新。 + +第 3–5 节是对齐决定之前的初稿。其中与 0.2 冲突的设计(PostgreSQL 归属表、凭据版本、原账号不可用时 409 不换号)不再采用,归档在第 11 节。 ## 1. 目标与非目标 @@ -158,24 +196,19 @@ - 每轮核对:上游账号一致、用量与扣费一致、续接失败时客户端能回退完整上下文。 - 结果记录到兼容矩阵(客户端 × 协议 × 上游 × 能力),并保存日期与证据。 -## 8. 实施顺序 +## 8. 恢复实施时的顺序 -1. V51 归属表与 `ResponsesOwnershipService`,附单元与数据库回归。 -2. Provider 返回实际账号指纹与 pinned-key 入口。 -3. 按第 9 节的决定二选一: - - 保持 `store=false`:做 WebSocket 入口与连接管理(COD-02),增量续接只在连接内有效;HTTP 继续拒绝 `previous_response_id`。 - - 允许 `store=true`:先放开 HTTP 续接与路由固定(COD-01),WebSocket 之后再做。 -4. 部署配置评审(WebSocket 需改 nginx)与客户端验收。 +1. Tair 归属记录(对齐 0.2),附回归。 +2. Provider 返回实际使用的账号,并支持按账号调用。 +3. WebSocket 入口与连接管理(0.1),每一轮接入现有计费合同。 +4. nginx 与云端 Compose 配置评审。 +5. 客户端验收(需授权真实上游与付费调用)。 每一步单独提交,全量测试通过后再进入下一步。 -## 9. 待你确认 +## 9. 已决定事项 -(2026-10-22 按第 10 节 Sub2API 对照修订) - -1. **是否允许上游存储(`store=true`)**。这是最先要定的:不允许,则增量续接只能走 WebSocket;允许,则 HTTP 续接可用,但用户对话会存在上游服务商处,需告知并按用户或 Key 开启。 -2. 归属记录默认保留 1 小时,可配置。 -3. 原账号不可用时返回 409、由客户端重发完整上下文,不换号。若做 WebSocket,可在连接内存中保留本连接历史,用于一次性服务端重放(参考 Sub2API)。 +见第 0 节:暂不实施;不允许上游存储;恢复时与 Sub2API 对齐,保留时间 1 小时,原账号不可用时按 Sub2API 换号并在连接内重放一次。 ## 10. Sub2API 对照(2026-10-22 源码核对) @@ -218,4 +251,13 @@ | 原账号不可用 | 换号重发(工具输出链路除外);WebSocket 内可用连接内存里的历史自动重放一次 | 保持 **409、由客户端重发**。我们 `store=false`,换号后上游一定找不到该响应,换号只会多一次失败请求;不保存正文也就无法服务端重放。若之后做 WebSocket,可考虑像 Sub2API 一样只在连接内存中保留本连接的历史,用于一次性重放 | | WebSocket | 默认开启,功能完整但复杂度高 | 取决于是否允许 `store=true`(见第 4 节更正):不允许,则 WebSocket 是唯一的增量续接方式;允许,则可先做 HTTP 续接。Sub2API 的规模说明 WebSocket 是独立的一大块工作 | -注:本节依据源码阅读,没有部署 Sub2API 或实测其行为。 +注:本节依据源码阅读,没有部署 Sub2API 或实测其行为。表中“建议”一列是对齐决定之前的看法,已被第 0 节取代。 + +## 11. 备选想法(未采纳,留档) + +以下是对齐 Sub2API 之前的设计思路,保留供以后企业化或合规需要时参考: + +- **PostgreSQL 归属表**:比 Redis 更利于审计追溯(第 3.1 节字段),代价是写库压力。若日后客户要求“每个响应可追溯到上游账号”,可在 Tair 之外异步落库。 +- **凭据版本**:把渠道凭据版本记入归属,凭据替换后旧响应立即失效(第 3.3 节)。Sub2API 不做这一层。 +- **原账号不可用时 409、不换号**:在 `store=false` 下换号必然得到 `previous_response_not_found`,直接让客户端重发完整上下文可以少一次上游请求。对齐后改为 Sub2API 的“换号 + 连接内重放一次”,效果相近,但多一次失败的上游请求。 +- **按 Key 开启 `store=true` 的 HTTP 续接**:实现最简单,但用户对话会保存在上游服务商处(OpenAI 默认 30 天),需要在条款和隐私说明中告知。本阶段已决定不允许。