wishforge-ide/docs/reference/provider-proxy.md
eust-w e1c381486d 🐛 Keep long model streams alive and retry rejected model requests
The proxy aborted every upstream call 120 seconds after it started, even
while the model was still streaming, so a long reasoning turn ended as an
unknown outcome that an admin had to reconcile. Calls now stop only when
no bytes arrive for 2 minutes, or after 10 minutes in total, inside the
15 minutes after which the reaper treats a request as lost. The recorded
reason says which limit stopped it.

A rejected request (a 429, an invalid request, or one stopped before
upstream I/O) was stored and replayed for every retry of the same body,
so one rate limit stalled the run for the rest of its lease. Rejections
use no tokens, so a retry is now sent again; completed responses are
still replayed and unknown outcomes still wait for reconciliation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-25 04:04:27 +08:00

52 lines
6.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 运行级 Codex 模型代理
生产中的执行环境拿到的是代理令牌,而不是租户长期有效的 OpenAI API Key;只有控制面(经 Vault)能解密原始密钥。
- **上游**:代理自己构造上游地址,POST 只能到 `<上游>/responses`,GET 只能到 `<上游>/models`。上游默认是 `https://api.openai.com/v1`,运维可以用 `WF_OPENAI_BASE_URL` 换成 OpenAI 兼容的模型网关(必须支持 Responses 接口)。
- **拒绝**:客户端指定的上游地址、重定向、任意请求头与其他 API 路由一律拒绝。
## 配置
| 变量 | 说明 |
|---|---|
| `WF_PROVIDER_PROXY_PUBLIC_URL` | 代理的公开基址,以 `/provider-proxy/v1` 结尾;生产必须是 HTTPS,开发可以是本机 HTTP |
| `WF_PROVIDER_PROXY_SIGNING_KEY` | 独立的签名密钥,至少 32 字符 |
| `WF_PROVIDER_PROXY_ALLOWED_MODELS` | 运维批准的模型 ID,逗号分隔 |
| `WF_PROVIDER_PROXY_ENABLED=true` | 开发模式下启用代理(生产始终启用) |
| `WF_CODEX_DEFAULT_MODEL` | Agent 配置没有指定模型时使用的默认模型;使用网关时应设为网关提供的模型 |
| `WF_OPENAI_BASE_URL` | 可选,OpenAI 兼容网关的基址(如 `https://ai-gateway.example/v1`),必须是 HTTPS 且不含凭据;只由运维配置,租户无法指定 |
生产中解密原始密钥使用外部 Vault Transit(`VAULT_ADDR`、`VAULT_TOKEN`、`VAULT_TRANSIT_KEY`)。CodeBuddy 与 Claude Code 在生产中保持禁用,直到有同等的代理协议(`providerCatalog` 中的 `proxied`)。
## 令牌与绑定
executor 通过运行上下文得到 `{ apiKey: 代理令牌, baseUrl, expiresAt, metering: 'proxy' }`。代理令牌有独立的 issuer 与 audience,有效期不超过剩余执行预算且不超过一小时,绑定租户、运行、执行代次、租约 token、worker 身份与凭据连接的确切版本。每个请求都重新校验这些绑定;流式响应期间至少每秒复核一次,发现取消、租约过期、代次更替或凭据撤销时中止上游读取。复核有间隔,不是瞬时断网,已经发出的请求在中止后仍可能产生用量。
`/provider-proxy/v1/*` 路由不经过普通的 OIDC 或内部服务鉴权,由代理自己验证令牌。凭据带有 `metering: proxy`,执行器上报的 token 不会再计费一次。
## 请求与预算
- 每个运行同一时间只允许一个上游请求。发出前在租户事务中先记录请求;请求以「运行、代次、租约、连接、幂等键」为键,同一个键换了请求体会被拒绝。只有 `Idempotency-Key` 头算幂等键:Codex 的 `x-client-request-id` 是它的会话 ID,同一会话的每个请求都一样;没有幂等键时用请求体摘要。已完成的有界响应可以重放,不再请求上游。被上游拒绝的请求(如 429 限流、400)以及发出前就中止的请求没有产生用量,重试时会重新发送,而不是重放这次拒绝。
- 支持自包含的文本、本地 `function`/`custom` 工具以及只包含这两类工具的命名空间;拒绝会话与历史响应引用、存储的提示模板、远程 MCP 与托管工具、后台执行、多模态与文件输入以及未经核实的顶层参数。代理强制 `store: false`、默认服务等级,以及按租户与运行区分的缓存和安全标识。
- 输入预留按序列化后的文本字节加上保守的协议开销估算(一个字节记一个 token),`max_output_tokens` 不超过运行剩余的预留。这是准入估算,不是精确的分词或报价。Codex 一次请求带着指令与工具定义,约 5 万字节并逐轮增长,所以运行预算要留出这部分余量。剩余预算不够下一次请求的预留时,代理拒绝该请求,并让运行进入 `budget` 等待,写明需要与剩余的数量。
- 实际用量只采信上游 JSON 或 Responses SSE 结束事件中的 usage(`input_tokens + output_tokens == total_tokens`),每个请求只记账一次。实际用量超出剩余预算时按实际记录,并停止后续执行。
- SSE 帧跨字节与 CRLF 边界解析、限长并在转发与缓存前脱敏;不转发上游的鉴权与错误头,非成功响应体替换为通用错误,避免回显密钥。限制:请求 2 MiB、单帧 1 MiB、响应 16 MiB、重放缓存 2 MiB;上游调用 2 分钟没有收到新数据,或总时长超过 10 分钟,就中止。
## 结果未知时
POST 请求超时(记录原因 `upstream_idle` 或 `upstream_deadline`)、流在没有可信用量的情况下结束、或客户端断开时,请求记录变为 `unknown`:保留它的预留额度,运行进入 `ambiguous_execution` 等待,之后的请求(包括新租约下的请求)都不会盲目重发。代理进程本身丢失、请求超过 15 分钟仍处于进行中时,后台维护循环同样把它标记为 `unknown`。
解除方式(需要 owner/admin 在 Web 中操作):
1. `GET /v1/runs/:id/provider-requests` 查看该运行的模型请求及状态。
2. `POST /v1/runs/:id/provider-requests/reconcile`,body `{"requestId": "...", "usageTokens": 1234}`:按服务商后台查到的实际用量结算;不知道实际用量时省略 `usageTokens`,按该请求的预留额度结算。
3. 结算后运行可以继续,模型请求恢复可用。
请求记录中不保存原始提示词与原始凭据;重放数据属于租户的模型输出,受平台的保留策略约束。
参考:[Responses create](https://developers.openai.com/api/reference/resources/responses/methods/create)、[streaming Responses](https://developers.openai.com/api/docs/guides/streaming-responses)。
## 测试
`tests/provider-proxy.test.ts` 使用注入的本地假上游,覆盖 audience 隔离、租户/租约/代次/连接绑定、SSE 分块、密钥脱敏、一次性计量、路由/工具/模型拒绝、取消、凭据轮换、预算准入、结果未知与人工对账。`WF_CODEX_SDK_INTEGRATION=1 npx vitest run tests/integration/codex-sdk.test.ts` 让固定版本的 Codex SDK/CLI 经真实代理访问本地假上游,不会调用真实模型。