Compare commits

...
17 Commits
Author SHA1 Message Date
ZyyandCodex 188a6817d1 chore: bump version to 3.53.1
Co-authored-by: Codex <noreply@openai.com>
2026-11-19 18:41:20 +08:00
ZyyandCodex d44bc64d1a fix(usage): improve request record layout and error summaries
Co-authored-by: Codex <noreply@openai.com>
2026-11-19 18:10:51 +08:00
github-actions[bot] 6006cc8394 chore(release): update release channels to 3.53.0 2026-11-19 09:36:04 +00:00
ZyyandCodex e7f8b5a354 chore: bump version to 3.53.0
Co-authored-by: Codex <noreply@openai.com>
2026-11-19 17:18:26 +08:00
d62868b692 feat(openai): make the WebSocket fast-path budget configurable (#747)
Co-authored-by: Zyy <zyycn@users.noreply.github.com>
Co-authored-by: Codex <noreply@openai.com>
2026-11-19 17:10:41 +08:00
0922f3486c fix(responses): return HTTP 400 for early WebSocket request errors (#746)
Co-authored-by: Zyy <zyycn@users.noreply.github.com>
Co-authored-by: Codex <noreply@openai.com>
2026-11-19 16:59:11 +08:00
ZyyandCodex f4058c1d2e test: align backend coverage with current behavior
Remove obsolete field assertions and the ignored Codex binary TLS comparison. Keep coverage for request validation, compatibility, and local TLS handshakes.

Co-authored-by: Codex <noreply@openai.com>
2026-11-19 15:56:12 +08:00
Zyy 8253fbc497 fix(errors): show specific causes in admin feedback and request records 2026-11-19 15:41:32 +08:00
ZyyandCodex 193e83f9f3 fix(accounts): keep stale connection tests from closing a new stream
Co-authored-by: Codex <noreply@openai.com>
2026-11-19 15:06:20 +08:00
ZyyandCodex a9e8fa8a44 refactor(openai): simplify account selection and session admission
Co-authored-by: Codex <noreply@openai.com>
2026-11-19 15:06:20 +08:00
ZyyandCodex 437322ee4b refactor(core): centralize attempt preparation failure handling
Co-authored-by: Codex <noreply@openai.com>
2026-11-19 15:06:19 +08:00
Zyy 843e1367bd docs: streamline guides and clarify current behavior 2026-11-19 14:49:42 +08:00
ZyyandCodex ab1bf4372c fix(api): apply the CLI version gate to Desktop-hosted TUI clients
Co-authored-by: Codex <noreply@openai.com>
2026-11-19 14:15:35 +08:00
dca9806961 feat(usage): filter request errors by origin and focus the detail table (#743)
* feat(usage): filter request errors by origin and focus the detail table

Co-authored-by: Codex <noreply@openai.com>

* fix(usage): preserve request columns and fill the error table

Keep reasoning effort separate and use the success table's column order. Let the error summary fill the space left by hidden columns and reuse the decoded upstream body when filtering saved errors.

Co-authored-by: Codex <noreply@openai.com>

---------

Co-authored-by: Codex <noreply@openai.com>
Co-authored-by: Zyy <zyycn@users.noreply.github.com>
2026-11-19 13:40:05 +08:00
ZyyandCodex 15ed54d452 fix(ui): refine subscription badge colors and table spacing
Co-authored-by: Codex <noreply@openai.com>
2026-11-19 13:08:31 +08:00
ZyyandCodex 050214860e docs(readme): streamline setup and highlight project support and activity
Co-authored-by: Codex <noreply@openai.com>
2026-11-19 12:08:36 +08:00
github-actions[bot] d917f948cf chore(release): update release channels to 3.52.2 2026-11-19 01:40:04 +00:00
127 changed files with 2308 additions and 1883 deletions
+28 -83
View File
@@ -12,7 +12,7 @@
[![GHCR](https://img.shields.io/badge/GHCR-codex--proxy--rs-2496ED?logo=docker&logoColor=white&style=flat-square)](https://github.com/zyycn/codex-proxy-rs/pkgs/container/codex-proxy-rs)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square)](LICENSE)
[快速预览](#快速预览) · [快速开始](#快速开始) · [客户端接入](#客户端接入) · [文档](#文档) · [社区](#社区) · [许可证](#许可证)
[快速预览](#快速预览) · [快速开始](#快速开始) · [文档](#文档) · [社区](#社区) · [贡献者](#贡献者) · [Star History](#star-history) · [支持项目](#支持项目) · [许可证](#许可证)
</div>
@@ -21,105 +21,28 @@
## 快速预览
无需部署即可体验管理端的系统概览、账号分组、代理管理与用量统计:
| 登录信息 | 默认值 |
| --- | --- |
| 地址 | <https://codex-proxy-rs.ainz.cc> |
| 登录身份 | 管理员 |
| 账号 | `admin@cpr.local` |
| 密码 | `039c18de2aeac46d23ead7766bb07bbbe3747233c66a128e` |
预览服务运行已发布版本,展示的账号、代理与使用记录均为模拟数据,每天北京时间 `00:00` 自动生成当天数据
这是公开共享的功能预览环境,不提供真实模型调用;请勿导入真实账号、密钥或其他敏感信息
## 快速开始
使用 Docker Compose 部署版本固定的发布镜像,同时启动 PostgreSQL 和 Redis
以下命令适用于 Linux amd64/arm64,需要 Docker Engine、Docker Compose Plugin、curl 和 OpenSSL
macOS 从[发行页](https://github.com/zyycn/codex-proxy-rs/releases)下载对应的归档:Intel 机型选 `darwin_amd64`,Apple Silicon 机型选 `darwin_arm64`。
Windows x64 / ARM64 的安装步骤见 [Windows 二进制部署](deploy/README.md#windows-二进制部署)
已有部署请先看 [升级说明](deploy/README.md#镜像升级与源码构建),不要覆盖原配置
### 一键安装
请确保当前用户能访问 Docker,并可通过 `sudo` 或 root 设置目录权限
在已安装 Docker Engine、Docker Compose Plugin、curl 和 OpenSSL 的 Linux amd64/arm64 主机上运行
```bash
curl -fsSL https://raw.githubusercontent.com/zyycn/codex-proxy-rs/main/deploy/install.sh -o install.sh && bash install.sh
```
[安装脚本](deploy/install.sh) 默认安装到当前目录下的 `codex-proxy-rs/`,下载同一正式 Release 的部署文件,
自动生成密码、设置目录权限并启动服务
完成后保存显示的访问地址和管理员密码,再[登录管理端](#登录管理端)并[添加账号与客户端密钥](#添加账号与客户端密钥)
可在执行 `bash install.sh` 时传入环境变量:
| 变量 | 用途 | 默认值 |
| --- | --- | --- |
| `INSTALL_DIR` | 安装目录,建议使用绝对路径 | 当前目录下的 `codex-proxy-rs/` |
| `CPR_RELEASE_TAG` | 指定发布标签 | 最新正式版本 |
| `ADMIN_PASSWORD` | 管理员初始密码,至少 12 位,不能包含 `$`,不能使用常见弱口令 | 随机生成 |
例如,自定义安装目录:
```bash
INSTALL_DIR="$HOME/services/codex-proxy-rs" bash install.sh
```
重复运行时请使用同一安装目录,检测到 `deploy/config.yaml` 后,脚本保留现有配置和部署文件,
忽略传入的管理员密码,也不执行版本升级
### 手动安装
自行下载部署文件、配置密码和启动服务的完整步骤见 [部署文档](deploy/README.md#手动安装)
### 登录管理端
部署完成后,打开 `http://127.0.0.1:8080`,使用 `admin@cpr.local` 和管理员密码登录
API Key 持有者可在登录页切换身份,查看自己的用量与额度,并通过「密钥配置」复制 Codex 配置或导入 CC Switch
默认地址只能在服务器本机访问,从其他设备使用时,需要配置
[HTTPS 反向代理](deploy/README.md#公网访问)
### 添加账号与客户端密钥
1. 在「账号」中添加账号,完成授权或导入
2. 按需建立账号分组,再创建客户端密钥并选择可用分组,**不选分组表示可使用全部账号**
3. [连接客户端](#客户端接入)
## 客户端接入
**Codex CLI / 桌面端**:在「使用密钥」中按操作系统复制配置,合并配置后重启 Codex;也可通过「导入到」把服务连接与密钥添加到 CC Switch
完整步骤、生图配置与排障见[客户端配置](deploy/README.md#客户端配置)
**其他 API 客户端**:API Key 填写管理端创建的客户端密钥。按客户端自动追加的请求路径填写 Base URL;远程接入时将本机地址换成服务器的 HTTPS 地址
| 客户端自动追加的路径 | Base URL(本机部署) |
| --- | --- |
| OpenAI Responses:`/responses`;Chat Completions:`/chat/completions` | `http://127.0.0.1:8080/v1` |
| Anthropic Messages:`/v1/messages` | `http://127.0.0.1:8080` |
查询该密钥可见的模型目录:
```bash
curl http://127.0.0.1:8080/v1/models \
-H 'Authorization: Bearer <client-api-key>'
```
[安装脚本选项](deploy/README.md#安装脚本选项) · [macOS 发行包](https://github.com/zyycn/codex-proxy-rs/releases) · [Windows 安装](deploy/README.md#windows-二进制部署) · [已有部署升级](deploy/README.md#镜像升级与源码构建)
## 文档
| 任务 | 文档 |
| 主题 | 文档 |
| --- | --- |
| 部署与使用 | [部署、备份与恢复](deploy/README.md) · [客户端接入与生图](deploy/README.md#客户端配置) |
| 接口集成 | [API 参考](docs/api.md) · [模型定价](docs/api.md#模型定价) |
| 部署与使用 | [部署、备份与恢复](deploy/README.md) · [客户端接入](deploy/README.md#客户端配置) |
| 接口集成 | [API 参考](docs/api.md) · [模型目录](docs/api.md#模型目录) · [模型定价](docs/api.md#模型定价) |
| 使用插件 | [安装、配置与使用](docs/plugins.md) |
| 开发插件 | [SDK 与合同](backend/crates/gateway-plugin/sdk/README.md) · [打包工具](backend/apps/plugin-cli/README.md) · [官方示例](https://github.com/zyycn/codex-proxy-plugins/blob/main/README.md) |
| 开发共用组件 | [组件库说明](https://github.com/zyycn/codex-proxy-ui/blob/main/README.md) · [组件参考](https://github.com/zyycn/codex-proxy-ui/blob/main/playground/components/index.md) · [Playground](https://zyycn.github.io/codex-proxy-ui/) |
@@ -132,6 +55,28 @@ curl http://127.0.0.1:8080/v1/models \
感谢 [LINUX DO](https://linux.do) 社区提供开放、友善的技术交流平台
## 贡献者
[<img src="https://contrib.rocks/image?repo=zyycn/codex-proxy-rs&amp;columns=10" alt="查看 GitHub 贡献者列表" width="480">](https://github.com/zyycn/codex-proxy-rs/graphs/contributors)
## Star History
<a href="https://simrepo.dera.page/#zyycn/codex-proxy-rs&amp;Date">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://simrepo.dera.page/svg?repos=zyycn/codex-proxy-rs&amp;type=Date&amp;theme=dark">
<img src="https://simrepo.dera.page/svg?repos=zyycn/codex-proxy-rs&amp;type=Date" alt="Codex Proxy RS 的 GitHub Star 增长趋势" width="560">
</picture>
</a>
## 支持项目
如果 Codex Proxy RS 帮助到你了,欢迎请我喝杯咖啡 ☕
[![Support me on Ko-fi](docs/donations/ko-fi.svg)](https://ko-fi.com/zyycn)
[<img src="docs/donations/wechat-tips.png" alt="WeChat appreciation code" width="138">](docs/donations/wechat-tips.png)&nbsp;
[<img src="docs/donations/alipay.png" alt="Alipay QR code" width="138">](docs/donations/alipay.png)
## 许可证
本项目基于 [Apache License 2.0](LICENSE) 开源
+8 -13
View File
@@ -1,7 +1,6 @@
# Codex Proxy Plugin CLI
`cpr-plugin` 校验并规范化作者清单、收集声明的资源,生成可安装归档及 SHA-256 校验文件。
输出合同与 [SDK 版本](../../crates/gateway-plugin/sdk/README.md)一致
`cpr-plugin` 按 [SDK 合同](../../crates/gateway-plugin/sdk/README.md)校验清单,将插件可执行文件与声明的资源打包,并输出 SHA-256 校验文件
## 安装
@@ -11,7 +10,7 @@
cargo +1.99.1 install --locked --path backend/apps/plugin-cli --root /path/to/local-tools
```
将 `/path/to/local-tools/bin` 加入 `PATH`,或使用可执行文件的完整路径;工具链与宿主 [验证命令](../../../docs/architecture.md#验证命令)一致
将 `/path/to/local-tools/bin` 加入 `PATH`,或使用可执行文件的完整路径
## 打包
@@ -26,24 +25,20 @@ cpr-plugin package \
--output-dir /path/to/output
```
`--resource-map web=web/dist` 将包内 `web/` 前缀映射到作者清单所在目录下的 `web/dist/`。
可重复传入不同前缀,源目录必须位于项目内;没有对应资源时省略该参数,未使用的映射会被拒绝。
未映射的资源按清单中的相对路径读取,只收集 `resources` 声明的文件
资源文件须在 `resources` 中声明,默认从清单所在目录按相对路径读取。
`--resource-map web=web/dist` 从项目内的 `web/dist/` 读取包内 `web/` 资源。可为不同前缀重复传参,未匹配任何资源的映射会报错
输出为 `<插件 ID>-<版本>-<目标 triple>.tar.gz` 及同名 `.tar.gz.sha256`;归档根目录直接包含 `plugin.json`、可执行文件和声明资源。
输出为 `<插件 ID>-<版本>-<目标 triple>.tar.gz` 及对应的 `.tar.gz.sha256`。归档根目录包含 `plugin.json`、可执行文件和声明资源。
输入清单及生成后的清单均不得超过 64 KiB,压缩包上限为 32 MiB,展开归档上限为 128 MiB
作者清单不填写 `package`;字段省略规则、能力版本和挂载阶段见 [SDK 扩展项声明](../../crates/gateway-plugin/sdk/docs/manifest.md#扩展项简写)。
CLI 生成规范化后的 `plugin.json`,补入协议版本、目标平台和文件摘要。打包成功只证明输入符合包合同,实际启动与能力仍需在目标宿主验证
作者清单须省略 `package`。CLI 将协议版本、目标平台和文件摘要写入 `plugin.json`。可省略的声明字段见 [SDK 扩展项声明](../../crates/gateway-plugin/sdk/docs/manifest.md#扩展项简写)
支持 `x86_64-unknown-linux-gnu`、`aarch64-unknown-linux-gnu` 和 `aarch64-apple-darwin`。
完整开发示例在独立仓库 `codex-proxy-plugins` 的 `examples/workbench`,可通过[子模块](../../../docs/development.md#源码联调)检出;本工具不负责源码构建、上传或启用插件
打包后在目标宿主验证启动和插件功能。完整示例见插件[子模块](../../../docs/development.md#源码联调)的 `examples/workbench`
### 图标资源
在作者清单的 `icon` 中指定图标,并在 `resources` 中登记对应路径与 MIME 类型,配置方式见
[SDK 插件图标](../../crates/gateway-plugin/sdk/docs/manifest.md#插件图标)。图标与其他声明资源一样参与打包和摘要计算,
无需额外命令参数;工具保留文件原始内容,宿主安装时验证图标内容与资源限制
按 [SDK 插件图标](../../crates/gateway-plugin/sdk/docs/manifest.md#插件图标)填写 `icon` 和 `resources`。CLI 自动打包原文件并计算摘要,宿主在安装时校验
## 开发
@@ -14,15 +14,25 @@ use super::{PageSize, Revision, observability::DecimalAmount};
pub fn validate_group_fields(
name: &str,
description: Option<&str>,
) -> Result<(), super::AdminModelError> {
if name.trim() != name
|| name.is_empty()
|| name.chars().count() > 100
|| name.chars().any(char::is_control)
|| description
.is_some_and(|value| value.len() > 4096 || value.chars().any(char::is_control))
{
return Err(super::AdminModelError::InvalidAccountGroupFields);
) -> Result<(), super::AdminError> {
if name.trim().is_empty() {
return Err(super::AdminError::invalid("请输入账号组名称"));
}
if name.chars().count() > 100 {
return Err(super::AdminError::invalid("账号组名称最多 100 个字符"));
}
if name.trim() != name || name.chars().any(char::is_control) {
return Err(super::AdminError::invalid(
"账号组名称不能包含首尾空白或控制字符",
));
}
if let Some(description) = description {
if description.len() > 4096 {
return Err(super::AdminError::invalid("账号组描述最多 4096 字节"));
}
if description.chars().any(char::is_control) {
return Err(super::AdminError::invalid("账号组描述不能包含控制字符"));
}
}
Ok(())
}
@@ -236,8 +236,6 @@ pub enum AdminModelError {
InvalidPageSize(u16),
#[error("observability page size {0} is outside 1..=100")]
InvalidObservabilityPageSize(u16),
#[error("account group name or description is invalid")]
InvalidAccountGroupFields,
#[error("client key group IDs are duplicated or exceed 1000 entries")]
InvalidClientKeyGroups,
#[error("client key page size must be inside 1..=65535")]
@@ -180,7 +180,7 @@ pub struct UsageFilter {
pub enum UsageRecordStatus {
#[default]
Success,
Error,
Error(Option<UsageErrorOrigin>),
All,
}
@@ -814,6 +814,17 @@ pub enum UsageErrorOrigin {
Unknown,
}
/// 来源规则所依赖的已保存事实,供内存投影与持久层分页查询共同解释
#[derive(Clone, Copy)]
pub enum UsageErrorEvidence {
ProviderErrorCode,
UpstreamStatusAtLeast(u16),
SavedUpstreamErrorOrClose,
ErrorKind(&'static [&'static str]),
Continuation(&'static [&'static str]),
ConnectionExit(&'static [&'static str]),
}
impl UsageErrorOrigin {
#[must_use]
pub const fn as_str(self) -> &'static str {
@@ -480,6 +480,7 @@ pub trait AccountGroupStore: Send + Sync {
context: &MutationContext,
) -> AdminStoreResult<AccountGroupMutation>;
/// 仍有 API Key 引用分组时返回 Conflict
async fn delete_account_group(
&self,
command: DeleteAccountGroup,
@@ -24,7 +24,7 @@ use crate::{
NewAccountGroup, SetAccountGroupEnabled, UpdateAccountGroup,
},
},
ports::store::{AccountGroupStore, AccountRuntimeStore},
ports::store::{AccountGroupStore, AccountRuntimeStore, AdminStoreErrorKind},
};
use super::{map_store_error, publish_committed};
@@ -159,8 +159,7 @@ impl AccountGroupService for DefaultAccountGroupService {
crate::model::account_groups::validate_group_fields(
&command.name,
command.description.as_deref(),
)
.map_err(|_| AdminError::invalid("账号组请求不合法"))?;
)?;
let id = AccountGroupId::new(format!("grp_{}", Uuid::now_v7().simple()))
.map_err(|_| AdminError::internal("创建账号组 ID 失败"))?;
self.publish(
@@ -189,8 +188,7 @@ impl AccountGroupService for DefaultAccountGroupService {
crate::model::account_groups::validate_group_fields(
&command.name,
command.description.as_deref(),
)
.map_err(|_| AdminError::invalid("账号组请求不合法"))?;
)?;
self.publish(self.store.update_account_group(command, context).await)
.await
}
@@ -209,8 +207,12 @@ impl AccountGroupService for DefaultAccountGroupService {
context: &MutationContext,
command: DeleteAccountGroup,
) -> Result<AccountGroupMutation, AdminError> {
self.publish(self.store.delete_account_group(command, context).await)
.await
match self.store.delete_account_group(command, context).await {
Err(error) if error.kind() == AdminStoreErrorKind::Conflict => {
Err(AdminError::conflict("分组仍绑定 API Key,请先解除绑定").with_source(error))
}
result => self.publish(result).await,
}
}
}
@@ -314,7 +314,6 @@ impl ClientKeyService for DefaultClientKeyService {
fn map_client_key_write_error(error: AdminStoreError) -> AdminError {
match error.kind() {
AdminStoreErrorKind::DuplicateName => AdminError::conflict("名称已存在"),
AdminStoreErrorKind::Conflict => AdminError::conflict("API Key 已存在,请使用其他密钥"),
_ => map_store_error(error, "client API key"),
}
@@ -4,20 +4,15 @@ use crate::model::{AdminError, AdminErrorKind};
use crate::ports::store::{AdminStoreError, AdminStoreErrorKind};
pub(super) fn map_store_error(error: AdminStoreError, resource: &'static str) -> AdminError {
let kind = match error.kind() {
AdminStoreErrorKind::Invalid => AdminErrorKind::Invalid,
AdminStoreErrorKind::NotFound => AdminErrorKind::NotFound,
AdminStoreErrorKind::StaleRevision
| AdminStoreErrorKind::DuplicateName
| AdminStoreErrorKind::Conflict => AdminErrorKind::Conflict,
AdminStoreErrorKind::Unavailable => AdminErrorKind::Unavailable,
};
let message = match kind {
AdminErrorKind::Invalid => "请求参数不合法",
AdminErrorKind::NotFound => "请求的资源不存在",
AdminErrorKind::Conflict => "当前资源状态冲突,请刷新后重试",
AdminErrorKind::Unavailable => "依赖服务暂不可用",
_ => "服务内部错误",
let (kind, message) = match error.kind() {
AdminStoreErrorKind::Invalid => (AdminErrorKind::Invalid, "请求参数不合法"),
AdminStoreErrorKind::NotFound => (AdminErrorKind::NotFound, "请求的资源不存在"),
AdminStoreErrorKind::StaleRevision => {
(AdminErrorKind::Conflict, "数据已更新,请刷新后再操作")
}
AdminStoreErrorKind::DuplicateName => (AdminErrorKind::Conflict, "名称已存在"),
AdminStoreErrorKind::Conflict => (AdminErrorKind::Conflict, "当前资源状态不允许此操作"),
AdminStoreErrorKind::Unavailable => (AdminErrorKind::Unavailable, "存储服务暂不可用"),
};
AdminError::new(kind, message).with_source(OperationFailure {
operation: resource,
@@ -49,9 +44,8 @@ pub(super) fn map_provider_error(
ProviderAdminErrorKind::Conflict => "服务商资源状态冲突,请刷新后重试",
ProviderAdminErrorKind::BadGateway => "上游服务请求失败",
ProviderAdminErrorKind::Ambiguous => "上游执行结果未知,请刷新状态后再决定是否重试",
ProviderAdminErrorKind::Unavailable | ProviderAdminErrorKind::CredentialRefreshRequired => {
"服务商暂不可用"
}
ProviderAdminErrorKind::Unavailable => "服务商暂不可用",
ProviderAdminErrorKind::CredentialRefreshRequired => "账号凭据需要刷新",
ProviderAdminErrorKind::Internal => "服务内部错误",
};
AdminError::new(kind, error.public_message().unwrap_or(message)).with_source(OperationFailure {
@@ -225,7 +225,7 @@ impl KeyUsageService for DefaultKeyUsageService {
.list_usage_records(UsageQuery {
status: match query.kind {
KeyUsageRecordKind::Success => UsageRecordStatus::Success,
KeyUsageRecordKind::Error => UsageRecordStatus::Error,
KeyUsageRecordKind::Error => UsageRecordStatus::Error(None),
KeyUsageRecordKind::All => UsageRecordStatus::All,
},
range: query.usage.range,
@@ -1,6 +1,8 @@
//! 从已保存的错误事实投影管理端来源,不参与执行错误分类或重试
use crate::model::observability::{UsageErrorOrigin, UsageListRecord, UsageRecord};
use crate::model::observability::{
UsageErrorEvidence, UsageErrorOrigin, UsageListRecord, UsageRecord,
};
impl UsageListRecord {
#[must_use]
@@ -47,107 +49,124 @@ fn error_origin(
continuation_reason: Option<&str>,
connection_exit_reason: Option<&str>,
) -> UsageErrorOrigin {
if has_upstream_error
|| upstream_code.is_some_and(|code| !code.is_empty())
|| websocket_close_code.is_some()
|| upstream_status_code.is_some_and(|status| status >= 400)
|| matches!(
continuation_reason,
Some("upstream_rejected" | "quota_exhausted")
)
|| matches!(
error_kind,
// 这里匹配内部 errorKind;message_too_big 只由收到的上游 close 1009 产生
Some("permission_denied" | "message_too_big" | "upstream_capacity_unavailable")
)
{
return UsageErrorOrigin::Upstream;
}
if matches!(
continuation_reason,
Some(
"scope_unavailable"
| "pool_unavailable"
| "fresh_connection_required"
| "connection_busy"
| "latest_response_mismatch"
| "reused_connection_lost"
| "transport_payload_too_large"
)
) || matches!(
error_kind,
Some(
"process_interrupted"
| "process_terminated"
| "internal_error"
| "model_not_found"
| "no_available_provider"
| "no_eligible_account"
| "account_capacity_unavailable"
| "middleware_capacity_unavailable"
| "concurrency_queue_full"
| "concurrency_queue_timeout"
| "provider_infrastructure_unavailable"
| "session_policy_restricted"
| "request_policy_denied"
| "policy_denied"
| "budget_exhausted"
)
) || matches!(
connection_exit_reason,
Some(
"command_channel_closed"
| "local_close"
| "message_receiver_closed"
| "client_cancelled"
| "downstream_send_failed"
| "downstream_connection_closed"
| "downstream_rebound"
| "pool_shutdown"
| "max_age_expired"
| "idle_timeout_expired"
| "proxy_capacity_evicted"
| "search_activation_required"
)
) {
return UsageErrorOrigin::Proxy;
}
if matches!(
connection_exit_reason,
Some(
"upstream_close"
| "normal_close"
| "unexpected_binary_event"
| "incomplete_response"
| "failed_response"
)
) {
return UsageErrorOrigin::Upstream;
}
if error_kind == Some("transport")
|| matches!(
connection_exit_reason,
Some(
"eof"
| "unexpected_eof"
| "transport_error"
| "connection_reset"
| "connection_aborted"
| "broken_pipe"
| "tcp_reset"
| "reset_without_closing_handshake"
| "transport_timeout"
| "outbound_transport_error"
| "receive_idle_timeout"
| "pong_timeout"
| "ping_write_timeout"
| "pong_write_timeout"
)
)
{
return UsageErrorOrigin::Connection;
}
// invalid_request、protocol、rate_limited 等分类同时用于本地和上游失败
// 发送状态与笼统的连接退出摘要也不能替代缺失的来源事实
UsageErrorOrigin::Unknown
use UsageErrorEvidence::*;
UsageErrorOrigin::RULES
.iter()
.find(|(evidence, _)| match evidence {
ProviderErrorCode => upstream_code.is_some_and(|code| !code.is_empty()),
UpstreamStatusAtLeast(min) => upstream_status_code.is_some_and(|status| status >= *min),
SavedUpstreamErrorOrClose => has_upstream_error || websocket_close_code.is_some(),
ErrorKind(values) => error_kind.is_some_and(|value| values.contains(&value)),
Continuation(values) => {
continuation_reason.is_some_and(|value| values.contains(&value))
}
ConnectionExit(values) => {
connection_exit_reason.is_some_and(|value| values.contains(&value))
}
})
.map_or(UsageErrorOrigin::Unknown, |(_, origin)| *origin)
}
impl UsageErrorOrigin {
/// 第一条命中的规则决定来源;含义不唯一的分类在缺少其他证据时保留 unknown
pub const RULES: &'static [(UsageErrorEvidence, Self)] = {
use UsageErrorEvidence::*;
&[
(ProviderErrorCode, Self::Upstream),
(UpstreamStatusAtLeast(400), Self::Upstream),
(
Continuation(&["upstream_rejected", "quota_exhausted"]),
Self::Upstream,
),
// message_too_big 只由收到的上游 close 1009 产生
(
ErrorKind(&[
"permission_denied",
"message_too_big",
"upstream_capacity_unavailable",
]),
Self::Upstream,
),
(SavedUpstreamErrorOrClose, Self::Upstream),
(
Continuation(&[
"scope_unavailable",
"pool_unavailable",
"fresh_connection_required",
"connection_busy",
"latest_response_mismatch",
"reused_connection_lost",
"transport_payload_too_large",
]),
Self::Proxy,
),
(
ErrorKind(&[
"process_interrupted",
"process_terminated",
"internal_error",
"model_not_found",
"no_available_provider",
"no_eligible_account",
"account_capacity_unavailable",
"middleware_capacity_unavailable",
"concurrency_queue_full",
"concurrency_queue_timeout",
"provider_infrastructure_unavailable",
"session_policy_restricted",
"request_policy_denied",
"policy_denied",
"budget_exhausted",
]),
Self::Proxy,
),
(
ConnectionExit(&[
"command_channel_closed",
"local_close",
"message_receiver_closed",
"client_cancelled",
"downstream_send_failed",
"downstream_connection_closed",
"downstream_rebound",
"pool_shutdown",
"max_age_expired",
"idle_timeout_expired",
"proxy_capacity_evicted",
"search_activation_required",
]),
Self::Proxy,
),
(
ConnectionExit(&[
"upstream_close",
"normal_close",
"unexpected_binary_event",
"incomplete_response",
"failed_response",
]),
Self::Upstream,
),
(ErrorKind(&["transport"]), Self::Connection),
(
ConnectionExit(&[
"eof",
"unexpected_eof",
"transport_error",
"connection_reset",
"connection_aborted",
"broken_pipe",
"tcp_reset",
"reset_without_closing_handshake",
"transport_timeout",
"outbound_transport_error",
"receive_idle_timeout",
"pong_timeout",
"ping_write_timeout",
"pong_write_timeout",
]),
Self::Connection,
),
]
};
}
@@ -60,7 +60,7 @@ async fn explicit_service_calls_freeze_empty_plan_and_cancel_before_entering_ter
)
.await
.unwrap();
// 内部 pricing 不再单独进入插件链;显式调用只解析一次发布集合
// 每次显式调价只解析一次插件发布集合
assert_eq!(resolutions.load(Ordering::SeqCst), expected);
}
store.updated.lock().unwrap().take();
@@ -51,7 +51,6 @@ impl From<gateway_admin::model::account_groups::AccountGroupRef> for AccountGrou
}
const DEFAULT_PAGE_SIZE: u32 = 50;
const MAX_PAGE_SIZE: u32 = 200;
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
@@ -66,7 +65,7 @@ impl ListAccountGroupsQuery {
fn into_command(self) -> Result<AccountGroupListQuery, WireValidationError> {
let page = self.page.unwrap_or(1);
let page_size = self.page_size.unwrap_or(DEFAULT_PAGE_SIZE);
if page == 0 || page_size == 0 || page_size > MAX_PAGE_SIZE {
if page == 0 {
return Err(WireValidationError::new("page"));
}
let search = self
@@ -507,11 +506,16 @@ fn group_color(value: &str) -> Result<AccountGroupColor, AdminError> {
fn validate_group_fields(name: &str, description: Option<&str>) -> Result<(), AdminError> {
gateway_admin::model::account_groups::validate_group_fields(name, description)
.map_err(|_| AdminError::bad_request("账号组请求不合法"))
.map_err(map_admin_service_error)
}
fn map_wire_error(_: WireValidationError) -> AdminError {
AdminError::bad_request("账号组查询参数不合法")
fn map_wire_error(error: WireValidationError) -> AdminError {
match error.field() {
"page" => AdminError::bad_request("页码须大于 0"),
"pageSize" => AdminError::bad_request(format!("每页数量须为 1 至 {}", PageSize::MAX)),
"search" => AdminError::bad_request("搜索内容最多 256 字节,不能包含控制字符"),
field => AdminError::bad_request(format!("{field} 字段不合法")),
}
}
fn map_service_error(error: gateway_admin::model::AdminError) -> AdminError {
@@ -1092,7 +1092,7 @@ fn map_wire_error(error: WireValidationError) -> AdminError {
"search" => "搜索内容过长或包含控制字符",
"sortBy" => "排序字段不受支持",
"sortDirection" => "排序方向必须为 asc(升序)或 desc(降序)",
_ => "API Key 请求参数不合法",
field => return AdminError::bad_request(format!("{field} 字段不合法")),
};
AdminError::bad_request(message)
}
@@ -1410,7 +1410,14 @@ pub(crate) fn map_wire_error(error: WireValidationError) -> AdminError {
"dimension" => "诊断维度不合法",
"id" => "用量记录 ID 不能为空",
"cursor" => "观测数据游标不合法",
_ => "观测查询参数不合法",
"currentPage" => "页码须大于 0",
"pageSize" => {
return AdminError::bad_request(format!("每页数量须为 1 至 {}", DomainPageSize::MAX));
}
"status" => "请求状态须为 success、error 或 all",
"errorOrigin" => "错误来源须为 proxy、upstream、connection 或 unknown",
"errorOriginStatus" => "仅错误请求支持按错误来源筛选",
field => return AdminError::bad_request(format!("{field} 字段不合法")),
};
AdminError::bad_request(message)
}
@@ -34,6 +34,7 @@ pub struct UsageQuery {
pub client_api_key_name: Option<String>,
pub account_search: Option<String>,
pub status: Option<String>,
pub error_origin: Option<String>,
pub current_page: Option<u32>,
pub page_size: Option<u16>,
pub provider: Option<String>,
@@ -354,11 +355,21 @@ pub(crate) fn usage_command(
let page_size_value =
DomainPageSize::new(page_size).map_err(|_| WireValidationError::new("pageSize"))?;
Ok(domain::UsageQuery {
status: match query.status.as_deref() {
None | Some("success") => domain::UsageRecordStatus::Success,
Some("error") => domain::UsageRecordStatus::Error,
Some("all") => domain::UsageRecordStatus::All,
Some(_) => return Err(WireValidationError::new("status")),
status: match (query.status.as_deref(), query.error_origin.as_deref()) {
(None | Some("success"), None) => domain::UsageRecordStatus::Success,
(Some("all"), None) => domain::UsageRecordStatus::All,
(Some("error"), origin) => domain::UsageRecordStatus::Error(match origin {
None => None,
Some("proxy") => Some(domain::UsageErrorOrigin::Proxy),
Some("upstream") => Some(domain::UsageErrorOrigin::Upstream),
Some("connection") => Some(domain::UsageErrorOrigin::Connection),
Some("unknown") => Some(domain::UsageErrorOrigin::Unknown),
Some(_) => return Err(WireValidationError::new("errorOrigin")),
}),
(None | Some("success" | "all"), Some(_)) => {
return Err(WireValidationError::new("errorOriginStatus"));
}
(Some(_), _) => return Err(WireValidationError::new("status")),
},
range: usage_range(
query.start_time.as_deref(),
+2 -2
View File
@@ -215,12 +215,12 @@ const METHOD_NOT_ALLOWED: AdminErrorSpec = AdminErrorSpec::new(
const TOO_MANY_LOGIN_ATTEMPTS: AdminErrorSpec = AdminErrorSpec::new(
StatusCode::TOO_MANY_REQUESTS,
AdminErrorCode::TOO_MANY_LOGIN_ATTEMPTS,
"登录尝试过多,请稍后重试",
"登录尝试过多",
);
const RATE_LIMITED: AdminErrorSpec = AdminErrorSpec::new(
StatusCode::TOO_MANY_REQUESTS,
AdminErrorCode::RATE_LIMITED,
"请求过于频繁,请稍后重试",
"请求过于频繁",
);
const INTERNAL: AdminErrorSpec = AdminErrorSpec::new(
StatusCode::INTERNAL_SERVER_ERROR,
+45 -45
View File
@@ -178,7 +178,7 @@ pub(crate) fn client_access_error_response(error: ClientAccessError) -> Response
response
}
/// Desktop 优先于内嵌 CLI/Core;未知客户端及未提供应用版本的手机远程客户端返回 `None`
/// 识别 Desktop 应用或 CLI/Core;未知客户端及未提供应用版本的手机远程客户端返回 `None`
#[must_use]
pub fn identify_codex_client(headers: &HeaderMap) -> Option<IdentifiedCodexClient> {
const MAXIMUM_HEADER_LENGTH: usize = 4096;
@@ -196,25 +196,35 @@ pub fn identify_codex_client(headers: &HeaderMap) -> Option<IdentifiedCodexClien
"codex_mcp_server",
];
let originator = bounded_ascii_header(headers, "originator", MAXIMUM_HEADER_LENGTH);
let user_agent = bounded_ascii_header(headers, "user-agent", MAXIMUM_HEADER_LENGTH);
let is_desktop = originator.is_some_and(|value| value.eq_ignore_ascii_case("Codex Desktop"))
let ascii_header = |name: &'static str| headers.get(name).and_then(|value| value.to_str().ok());
let raw_user_agent = ascii_header("user-agent");
// HeaderValue::to_str 只接受 ASCII,可以按字节截取搜索范围
let user_agent = raw_user_agent.map(|ua| &ua[..ua.len().min(MAXIMUM_HEADER_LENGTH)]);
let is_desktop = ascii_header("originator")
.is_some_and(|value| value.eq_ignore_ascii_case("Codex Desktop"))
|| user_agent.is_some_and(|value| contains_ascii_case_insensitive(value, "Codex Desktop"));
if is_desktop {
let explicit_version = bounded_ascii_header(headers, "version", MAXIMUM_HEADER_LENGTH);
let version_header = headers.get("version");
let user_agent_version = user_agent.and_then(desktop_version_from_user_agent);
// 手机远程初始化会覆盖进程级 UA 后缀,保留的 Desktop/Core 前缀不代表应用版本
// 仅缺失版本信息时免于门禁;已提供的版本即使非法,也继续按 Desktop 校验
if !headers.contains_key("version")
&& user_agent_version.is_none()
&& headers
.get("user-agent")
.is_some_and(|value| value.as_bytes().len() <= MAXIMUM_HEADER_LENGTH)
&& user_agent.is_some_and(has_chatgpt_remote_user_agent_suffix)
if user_agent_version.is_none()
&& let Some(ua) = raw_user_agent.filter(|ua| ua.len() <= MAXIMUM_HEADER_LENGTH)
&& let Some(client) = user_agent_client_name(ua)
{
return None;
// 共享 App Server 可保留 Desktop 进程名,TUI 请求的 version 头也可能重复 Core 版本
if client.eq_ignore_ascii_case("codex-tui")
&& let Some(core) = desktop_core_version(ua)
&& version_header.is_none_or(|value| value.as_bytes() == core.as_bytes())
{
return Some(IdentifiedCodexClient {
kind: CodexClientKind::Cli,
version: CodexClientVersion::parse(core).ok(),
});
}
if version_header.is_none() && is_chatgpt_remote_client(client) {
return None;
}
}
let version = match explicit_version {
let version = match version_header.and_then(|value| value.to_str().ok()) {
Some(value) => CodexClientVersion::parse(value).ok(),
None => user_agent_version.and_then(|value| CodexClientVersion::parse(value).ok()),
};
@@ -244,18 +254,6 @@ pub fn identify_codex_client(headers: &HeaderMap) -> Option<IdentifiedCodexClien
None
}
fn bounded_ascii_header<'a>(
headers: &'a HeaderMap,
name: &'static str,
maximum_length: usize,
) -> Option<&'a str> {
let value = headers.get(name)?.to_str().ok()?;
if !value.is_ascii() {
return None;
}
Some(&value[..value.len().min(maximum_length)])
}
fn desktop_version_from_user_agent(user_agent: &str) -> Option<&str> {
let marker = "Codex Desktop;";
let start = find_ascii_case_insensitive(user_agent, marker)? + marker.len();
@@ -266,27 +264,29 @@ fn desktop_version_from_user_agent(user_agent: &str) -> Option<&str> {
.next()
}
fn has_chatgpt_remote_user_agent_suffix(user_agent: &str) -> bool {
let Some((_, suffix)) = user_agent
.strip_suffix(')')
.and_then(|value| value.rsplit_once(" ("))
else {
return false;
};
let Some((name, version)) = suffix.split_once("; ") else {
return false;
};
let Some(platform) = name
.strip_prefix("codex_chatgpt_")
.and_then(|value| value.strip_suffix("_remote"))
else {
return false;
};
[platform, version].into_iter().all(|value| {
fn desktop_core_version(user_agent: &str) -> Option<&str> {
let (product, rest) = user_agent.split_once('/')?;
let (version, _) = rest.split_once(' ')?;
product
.eq_ignore_ascii_case("Codex Desktop")
.then_some(version)
}
fn user_agent_client_name(user_agent: &str) -> Option<&str> {
let (_, suffix) = user_agent.strip_suffix(')')?.rsplit_once(" (")?;
let (name, version) = suffix.split_once("; ")?;
let valid_token = |value: &str| {
!value.is_empty()
&& !value.contains(['(', ')', ';'])
&& !value.bytes().any(|byte| byte.is_ascii_whitespace())
})
};
(valid_token(name) && valid_token(version)).then_some(name)
}
fn is_chatgpt_remote_client(name: &str) -> bool {
name.strip_prefix("codex_chatgpt_")
.and_then(|value| value.strip_suffix("_remote"))
.is_some_and(|platform| !platform.is_empty())
}
fn contains_ascii_case_insensitive(haystack: &str, needle: &str) -> bool {
@@ -19,8 +19,8 @@ use super::{
use crate::ApiState;
// 公开协议路径由 API 层统一定义;Core 使用操作类型,不根据这些路径分派业务
pub(super) const RESPONSES_PATH: &str = "/v1/responses";
// Core 使用操作类型,不根据这些协议路径分派业务
pub(super) use gateway_protocol::openai::RESPONSES_PATH;
pub(super) const MESSAGES_PATH: &str = "/v1/messages";
pub(super) const MESSAGE_TOKENS_PATH: &str = "/v1/messages/count_tokens";
pub(super) const CHAT_COMPLETIONS_PATH: &str = "/v1/chat/completions";
@@ -215,7 +215,7 @@ async fn mutation_route_should_reject_unknown_json_fields() {
"name": "Unknown field",
"description": null,
"color": "#2563EBFF",
"providerKind": "openai"
"unknownField": true
})),
true,
)
@@ -232,7 +232,7 @@ async fn create_route_should_reject_six_digit_color_without_alpha() {
Method::POST,
"/api/admin/account-groups/create",
Some(json!({
"name": "Opaque legacy color",
"name": "Color without alpha",
"description": null,
"color": "#2563EB"
})),
@@ -341,7 +341,7 @@ async fn account_quota_refresh_time_uses_server_clock_and_deployment_timezone()
));
let future = now + Duration::days(1);
let future_display = zone.local(future).format("%Y-%m-%d %H:%M:%S").to_string();
for (observed_at, expected, legacy) in [
for (observed_at, expected, display) in [
(None, json!(null), "—"),
(Some(now), json!({ "kind": "just_now" }), "刚刚"),
(
@@ -389,7 +389,7 @@ async fn account_quota_refresh_time_uses_server_clock_and_deployment_timezone()
let value: serde_json::Value = serde_json::from_slice(&body).unwrap();
let quota = &value["data"]["items"][0]["quota"];
assert_eq!(quota["refreshedAtRelative"], expected);
assert_eq!(quota["refreshedAtDisplay"], legacy);
assert_eq!(quota["refreshedAtDisplay"], display);
let refreshed_at = quota["refreshedAt"]
.as_str()
.map(|value| DateTime::parse_from_rfc3339(value).unwrap().to_utc());
@@ -610,7 +610,7 @@ fn xai_profile_override_distinguishes_omission_from_explicit_inheritance() {
}
#[test]
fn generic_profile_overrides_accept_native_providers_and_reject_legacy_conflicts() {
fn profile_overrides_accept_matching_native_values_and_reject_conflicts_and_unknown_providers() {
let profile = json!({"preset":"desktop"});
let xai = json!({"preset":"managed"});
let request: CreateClientKeyRequest = serde_json::from_value(json!({
@@ -676,7 +676,7 @@ fn generic_profile_overrides_accept_native_providers_and_reject_legacy_conflicts
}
#[test]
fn generic_profile_override_clear_rejects_conflicting_legacy_update() {
fn clearing_an_xai_profile_override_conflicts_with_an_explicit_xai_value() {
let request: UpdateClientKeyRequest = serde_json::from_value(json!({
"id":"key_profile",
"name":"profile",
@@ -513,6 +513,12 @@ mod provider {
(Kind::Unsupported, 400, 40001, "该服务商不支持此操作"),
(Kind::BadGateway, 502, 50201, "上游服务请求失败"),
(Kind::Unavailable, 503, 50301, "服务商暂不可用"),
(
Kind::CredentialRefreshRequired,
503,
50301,
"账号凭据需要刷新",
),
(
Kind::Ambiguous,
502,
@@ -1726,6 +1726,8 @@ async fn observability_queries_reject_group_filters_and_analytics_search() {
"routingGroupRefs=group-a",
),
("/api/admin/usage/records/summary", "search=request-prefix"),
("/api/admin/usage/records/summary", "errorOrigin=proxy"),
("/api/admin/usage/insights/overview", "errorOrigin=proxy"),
(
"/api/admin/usage/insights/overview",
"search=request-prefix",
@@ -1820,27 +1822,50 @@ pub(super) fn ops_error_record() -> gateway_admin::model::observability::OpsErro
}
#[tokio::test]
async fn usage_status_query_accepts_three_modes_and_rejects_unknown_values() {
async fn usage_record_query_accepts_error_sources_only_for_error_status() {
use crate::admin::{AdminTestFixture, AdminTestState};
use axum::{
body::{Body, to_bytes},
http::{Request, StatusCode, header},
};
use gateway_admin::model::observability::{UsageErrorOrigin, UsageRecordStatus};
use gateway_api::admin::observability;
use tower::ServiceExt as _;
let fixture = AdminTestFixture::new().await;
fixture.auth.insert_session("valid-session");
for (status, expected) in [
("success", StatusCode::OK),
("error", StatusCode::OK),
("all", StatusCode::OK),
("failed", StatusCode::BAD_REQUEST),
for (query, expected) in [
("", Some(UsageRecordStatus::Success)),
("status=success", Some(UsageRecordStatus::Success)),
("status=error", Some(UsageRecordStatus::Error(None))),
("status=all", Some(UsageRecordStatus::All)),
(
"status=error&errorOrigin=proxy",
Some(UsageRecordStatus::Error(Some(UsageErrorOrigin::Proxy))),
),
(
"status=error&errorOrigin=upstream",
Some(UsageRecordStatus::Error(Some(UsageErrorOrigin::Upstream))),
),
(
"status=error&errorOrigin=connection",
Some(UsageRecordStatus::Error(Some(UsageErrorOrigin::Connection))),
),
(
"status=error&errorOrigin=unknown",
Some(UsageRecordStatus::Error(Some(UsageErrorOrigin::Unknown))),
),
("status=failed", None),
("errorOrigin=proxy", None),
("status=success&errorOrigin=proxy", None),
("status=all&errorOrigin=unknown", None),
("status=error&errorOrigin=other", None),
("status=error&errorOrigin=", None),
] {
let response = observability::router::<AdminTestState>()
.with_state(fixture.state())
.oneshot(
Request::builder()
.uri(format!("/api/admin/usage/records?status={status}"))
.uri(format!("/api/admin/usage/records?{query}"))
.header(header::COOKIE, "cpr_session=valid-session")
.header("x-request-id", "usage_status_fixture")
.body(Body::empty())
@@ -1852,17 +1877,15 @@ async fn usage_status_query_accepts_three_modes_and_rejects_unknown_values() {
let body = to_bytes(response.into_body(), 1024 * 1024).await.unwrap();
assert_eq!(
actual,
expected,
"{status}: {}",
if expected.is_some() {
StatusCode::OK
} else {
StatusCode::BAD_REQUEST
},
"{query}: {}",
String::from_utf8_lossy(&body)
);
if expected == StatusCode::OK {
use gateway_admin::model::observability::UsageRecordStatus;
let status_value = match status {
"success" => UsageRecordStatus::Success,
"error" => UsageRecordStatus::Error,
_ => UsageRecordStatus::All,
};
if let Some(status_value) = expected {
assert_eq!(
fixture
.observations
@@ -2059,7 +2082,7 @@ async fn dashboard_relative_time_preserves_server_anchor_boundaries_and_deployme
("Asia/Kathmandu", "2026-06-15 05:45:01"),
("America/New_York", "2026-06-14 20:00:01"),
] {
for (elapsed_ms, expected, legacy) in [
for (elapsed_ms, expected, display) in [
(None, json!(null), "—"),
(
Some(-1_000),
@@ -2174,7 +2197,7 @@ async fn dashboard_relative_time_preserves_server_anchor_boundaries_and_deployme
account["lastUsedRelative"], expected,
"{zone}: {elapsed_ms:?}"
);
assert_eq!(account["lastUsed"], legacy, "{zone}: {elapsed_ms:?}");
assert_eq!(account["lastUsed"], display, "{zone}: {elapsed_ms:?}");
assert_eq!(account["lastUsedAt"], json!(last_used_at));
}
}
@@ -431,7 +431,7 @@ fn settings_request_accepts_unlimited_default_account_concurrency() {
}
#[test]
fn settings_request_validates_cron_and_allows_disabled_empty_schedule() {
fn warmup_cron_is_required_and_may_be_empty_only_when_disabled() {
for (enabled, cron, valid) in [
(false, "", true),
(true, "", false),
@@ -461,10 +461,9 @@ fn settings_request_validates_cron_and_allows_disabled_empty_schedule() {
let request: UpdateRuntimeSettingsRequest = serde_json::from_value(oversized).unwrap();
assert_eq!(request.validate().unwrap_err().field(), "accountWarmupCron");
let mut legacy = update_body();
legacy.as_object_mut().unwrap().remove("accountWarmupCron");
legacy["accountWarmupScheduleTime"] = json!("08:00");
assert!(serde_json::from_value::<UpdateRuntimeSettingsRequest>(legacy).is_err());
let mut missing = update_body();
missing.as_object_mut().unwrap().remove("accountWarmupCron");
assert!(serde_json::from_value::<UpdateRuntimeSettingsRequest>(missing).is_err());
}
#[test]
@@ -705,8 +704,6 @@ async fn admin_auth_should_accept_a_configured_request_id_header_name() {
let fixture = AdminTestFixture::new().await;
fixture.auth.insert_session("valid-session");
// 部署把 api.request_id_header 改名后,注入的 header 不再叫 x-request-id;
// 管理请求仍须拿到请求上下文,而不是退化为 500
let custom = HeaderName::from_static("x-trace-id");
let app = app(fixture.state()).layer(SetRequestIdLayer::new(custom, MakeRequestUuid));
let unlabelled = Request::builder()
@@ -919,7 +916,7 @@ fn global_profile_can_be_omitted_but_cannot_be_cleared() {
}
#[tokio::test]
async fn generic_global_profiles_decode_native_providers_and_reject_legacy_conflicts() {
async fn global_profiles_decode_native_providers_and_reject_conflicting_openai_settings() {
let mut body = update_body();
body["providerRequestProfiles"] = json!({
"openai":{"preset":"desktop"},
@@ -198,7 +198,7 @@ mod response {
response_json(generic).await,
json!({
"code": 42902,
"message": "请求过于频繁,请稍后重试",
"message": "请求过于频繁",
"data": null
})
);
@@ -212,7 +212,7 @@ mod response {
response_json(login).await,
json!({
"code": 42901,
"message": "登录尝试过多,请稍后重试",
"message": "登录尝试过多",
"data": null
})
);
@@ -345,7 +345,7 @@ async fn records_keep_pagination_and_hide_admin_and_upstream_data() {
assert_eq!(data.records.len(), 3);
for (query, status) in data.records.iter().zip([
UsageRecordStatus::Success,
UsageRecordStatus::Error,
UsageRecordStatus::Error(None),
UsageRecordStatus::All,
]) {
assert_eq!(query.status, status);
+60 -13
View File
@@ -228,6 +228,46 @@ fn desktop_headers_should_take_precedence_over_embedded_cli_marker() {
);
}
#[test]
fn desktop_hosted_tui_should_use_core_unless_a_desktop_version_is_supplied() {
for (core, version_header, kind, version) in [
("0.170.0", None, CodexClientKind::Cli, Some("0.170.0")),
(
"0.170.0",
Some("0.170.0"),
CodexClientKind::Cli,
Some("0.170.0"),
),
("invalid", None, CodexClientKind::Cli, None),
(
"0.170.0",
Some("26.1023.51421"),
CodexClientKind::Desktop,
Some("26.1023.51421"),
),
("0.170.0", Some("invalid"), CodexClientKind::Desktop, None),
] {
let mut headers = HeaderMap::new();
headers.insert("originator", HeaderValue::from_static("Codex Desktop"));
headers.insert(
"user-agent",
HeaderValue::from_str(&format!(
"Codex Desktop/{core} (Ubuntu 26.4.0; aarch64) xterm-256color (codex-tui; 0.169.0)"
))
.unwrap(),
);
if let Some(value) = version_header {
headers.insert("version", HeaderValue::from_static(value));
}
let client = identify_codex_client(&headers).unwrap();
assert_eq!(client.kind(), kind);
assert_eq!(
client.version().map(ToString::to_string).as_deref(),
version
);
}
}
#[test]
fn official_core_clients_should_use_the_core_version_instead_of_the_app_suffix() {
for product in [
@@ -322,7 +362,7 @@ fn chatgpt_remote_desktop_without_app_version_should_not_use_a_version_gate() {
}
#[test]
fn chatgpt_remote_marker_should_require_a_complete_exact_client_suffix() {
fn desktop_should_require_a_complete_exact_client_suffix() {
for suffix in [
"(codex_chatgpt_android_remote_extra; dev)",
"(unofficial_codex_chatgpt_ios_remote; dev)",
@@ -340,6 +380,9 @@ fn chatgpt_remote_marker_should_require_a_complete_exact_client_suffix() {
"(Codex Desktop; ) (codex_chatgpt_android_remote; dev)",
"(Codex Desktop; invalid) (codex_chatgpt_ios_remote; dev)",
"(Codex Desktop)",
"(codex-tui-custom; 0.169.0)",
"(codex-tui; 0.169.0) trailing",
"(codex-tui; )",
] {
let mut headers = HeaderMap::new();
headers.insert(
@@ -395,19 +438,23 @@ fn chatgpt_remote_marker_should_not_override_an_existing_desktop_version_suffix(
}
#[test]
fn chatgpt_remote_suffix_created_by_header_truncation_should_not_skip_the_gate() {
let suffix = " (codex_chatgpt_android_remote; dev)";
let mut user_agent = "Codex Desktop/0.154.0-alpha.6.2 ".to_owned();
user_agent.push_str(&"x".repeat(4096 - user_agent.len() - suffix.len()));
user_agent.push_str(suffix);
user_agent.push_str(" (another_client; dev)");
let mut headers = HeaderMap::new();
headers.insert("user-agent", HeaderValue::from_str(&user_agent).unwrap());
fn truncated_client_suffix_should_not_change_the_desktop_gate() {
for suffix in [
" (codex_chatgpt_android_remote; dev)",
" (codex-tui; 0.169.0)",
] {
let mut user_agent = "Codex Desktop/0.154.0-alpha.6.2 ".to_owned();
user_agent.push_str(&"x".repeat(4096 - user_agent.len() - suffix.len()));
user_agent.push_str(suffix);
user_agent.push_str(" (another_client; dev)");
let mut headers = HeaderMap::new();
headers.insert("user-agent", HeaderValue::from_str(&user_agent).unwrap());
let client =
identify_codex_client(&headers).expect("incomplete headers still require a version");
assert_eq!(client.kind(), CodexClientKind::Desktop);
assert!(client.version().is_none());
let client =
identify_codex_client(&headers).expect("incomplete headers still require a version");
assert_eq!(client.kind(), CodexClientKind::Desktop);
assert!(client.version().is_none());
}
}
#[tokio::test]
@@ -743,7 +743,7 @@ async fn request_context_should_resolve_forwarded_precedence_and_peer_fallback()
operation_kind: OperationKind::Generate,
input: Some(json!("hello")),
client_metadata: None,
// 客户端 User-Agent 仅用于本地展示,不再透传给上游指纹上下文
// 客户端 User-Agent 仅用于本地展示
protocol_context: Some(json!({"opaque_request_headers": [
["cf-connecting-ip", STANDARD.encode(b"198.51.100.1")],
["x-real-ip", STANDARD.encode(b"198.51.100.2")],
@@ -1378,27 +1378,40 @@ async fn streaming_error_after_initial_keepalive_should_be_a_terminal_sse_failur
}
#[tokio::test(start_paused = true)]
async fn streaming_late_upstream_error_should_preserve_extended_error_fields() {
async fn streaming_bad_request_preserves_extended_error_fields_before_and_after_keepalive() {
let mut error = json!({
"type": "invalid_request_error", "code": "misalignment_policy_violation",
"message": "synthetic policy error", "misalignment": {"category": "synthetic"},
"extension": {"opaque": true}
});
let failure = ProviderError::new(ProviderErrorKind::InvalidRequest, UpstreamSendState::Sent)
.with_client_visible_upstream_response(
ClientVisibleUpstreamResponse::new(
400,
Some(b"application/json".to_vec()),
Bytes::from(json!({"error": error}).to_string()),
let failure = || {
ProviderError::new(ProviderErrorKind::InvalidRequest, UpstreamSendState::Sent)
.with_client_visible_upstream_response(
ClientVisibleUpstreamResponse::new(
400,
Some(b"application/json".to_vec()),
Bytes::from(json!({"error": error}).to_string()),
)
.with_headers(headers(&[("retry-after", "7")])),
)
.with_headers(headers(&[("retry-after", "7")])),
);
error["headers"] = json!({"retry-after": "7"});
};
let immediate = FakeSession::streaming(
Arc::new(Trace::default()),
vec![NextStep::Error(EngineError::Provider(failure()))],
);
let response = stream_execution_response(Box::new(immediate), None).await;
assert_eq!(response.status(), StatusCode::BAD_REQUEST);
assert_eq!(response.headers()[CONTENT_TYPE], "application/json");
let bytes = to_bytes(response.into_body(), usize::MAX).await.unwrap();
assert_eq!(
serde_json::from_slice::<Value>(&bytes).unwrap(),
json!({"error": error})
);
let session = FakeSession::streaming(
Arc::new(Trace::default()),
vec![NextStep::DelayedError(
Duration::from_secs(30),
EngineError::Provider(failure),
EngineError::Provider(failure()),
)],
);
let response = stream_execution_response(Box::new(session), None).await;
@@ -1410,6 +1423,7 @@ async fn streaming_late_upstream_error_should_preserve_extended_error_fields() {
.find(|event| event.event.as_deref() == Some("response.failed"))
.unwrap();
let payload: Value = serde_json::from_str(&failed.data).unwrap();
error["headers"] = json!({"retry-after": "7"});
assert_eq!(payload["response"]["error"], error);
assert!(bytes.ends_with(b"data: [DONE]\n\n"));
}
@@ -2954,20 +2968,21 @@ struct SessionExecution {
#[tokio::test]
async fn official_core_clients_should_be_version_checked_before_starting_responses() {
let admin = crate::admin::AdminTestFixture::new().await.services;
for product in [
"codex-tui",
"codex_exec",
"codex_vscode",
"codex_sdk_ts",
"codex_python_sdk",
for (product, client) in [
("codex-tui", "codex-tui"),
("codex_exec", "codex_exec"),
("codex_vscode", "codex_vscode"),
("codex_sdk_ts", "codex_sdk_ts"),
("codex_python_sdk", "codex_python_sdk"),
("Codex Desktop", "codex-tui"),
] {
for (version, allowed) in [("0.158.0", false), ("0.162.0", true)] {
for (version, allowed) in [("0.168.0", false), ("0.170.0", true)] {
let trace = Arc::new(Trace::default());
let execution = Arc::new(SessionExecution {
client: authenticated_client_with_min_versions(
"sk_version_test",
None,
Some("0.162.0"),
Some("26.1023.51421"),
Some("0.170.0"),
),
session: Mutex::new(Some(Box::new(FakeSession::streaming(
Arc::clone(&trace),
@@ -2985,7 +3000,7 @@ async fn official_core_clients_should_be_version_checked_before_starting_respons
let request = Request::post("/v1/responses")
.header(AUTHORIZATION, "Bearer sk_version_test")
.header("user-agent", format!(
"{product}/{version} (Mac OS 26.6.2; arm64) Apple_Terminal ({product}; 0.165.0)"
"{product}/{version} (Ubuntu 26.4.0; aarch64) xterm-256color ({client}; 0.169.0)"
))
.body(Body::from(json!({"model": "model-a", "input": "synthetic", "stream": true}).to_string()))
.unwrap();
@@ -3006,8 +3021,9 @@ async fn official_core_clients_should_be_version_checked_before_starting_respons
assert_eq!(status, StatusCode::BAD_REQUEST, "{product}/{version}");
let value: Value = serde_json::from_slice(&body).unwrap();
assert_eq!(value["error"]["code"], "client_version_too_old");
assert_eq!(value["error"]["client"], "codex_cli");
assert_eq!(value["error"]["current_version"], version);
assert_eq!(value["error"]["min_version"], "0.162.0");
assert_eq!(value["error"]["min_version"], "0.170.0");
assert!(execution.session.lock().unwrap().is_some());
}
}
@@ -492,7 +492,7 @@ fn decoder_should_strip_http_transport_but_leave_source_headers_for_provider() {
HeaderValue::from_static(r#"{"scheme":"https"}"#),
);
headers.insert("accept-encoding", HeaderValue::from_static("br, gzip"));
// 正文未压缩;入口现在消费 Content-Encoding,但仍不得向上游透传
// identity 与未压缩的正文匹配,Content-Encoding 由入口消费
headers.insert("content-encoding", HeaderValue::from_static("identity"));
headers.insert("x-openai-future-mode", HeaderValue::from_static("keep"));
@@ -358,7 +358,7 @@ async fn rewrite_upgrade_and_control_active_response_keep_http_context_until_con
);
let (trace, mut socket, server) =
start_active_response_with(Some(frozen), "/custom/websocket", "codex-tui/0.166.0").await;
// 升级后的默认会话仍持有入口上下文;101 正文结束不再提前取消它
// 101 响应完成后,WebSocket 会话继续持有入口上下文
assert!(
!plan
.http_cancellation
@@ -255,7 +255,7 @@ impl Stream for TestSocket {
fn poll_next(mut self: Pin<&mut Self>, context: &mut Context<'_>) -> Poll<Option<Self::Item>> {
let event = self.incoming.poll_recv(context);
// 模拟 Axum transport 的自动 Pong;pump 不再重复实现协议层应答
// 模拟 Axum 传输层收到 Ping 时自动回复 Pong
if let Poll::Ready(Some(Ok(Message::Ping(payload)))) = &event {
self.written
.send(Message::Pong(payload.clone()))
@@ -1227,12 +1227,16 @@ fn upgrade_request(authorization: &str) -> Request<Body> {
#[tokio::test]
async fn official_core_version_gate_should_run_before_websocket_upgrade() {
let app = api_router(ModelsExecution::with_cli_min("0.162.0")).await;
let app = api_router(ModelsExecution::with_cli_min("0.170.0")).await;
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let address = listener.local_addr().unwrap();
let server = tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
for version in ["0.158.0", "0.162.0"] {
for (product, version) in [
("codex-tui", "0.158.0"),
("Codex Desktop", "0.168.0"),
("Codex Desktop", "0.170.0"),
] {
let mut request = format!("ws://{address}/v1/responses")
.into_client_request()
.unwrap();
@@ -1243,12 +1247,12 @@ async fn official_core_version_gate_should_run_before_websocket_upgrade() {
request.headers_mut().insert(
"user-agent",
HeaderValue::from_str(&format!(
"codex-tui/{version} (Mac OS 26.6.2; arm64) Apple_Terminal (codex-tui; 0.165.0)"
"{product}/{version} (Ubuntu 26.4.0; aarch64) xterm-256color (codex-tui; 0.169.0)"
))
.unwrap(),
);
let result = connect_async(request).await;
if version == "0.162.0" {
if version == "0.170.0" {
let (mut socket, response) = result.expect("current Core upgrades successfully");
assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);
socket.close(None).await.unwrap();
@@ -1261,8 +1265,9 @@ async fn official_core_version_gate_should_run_before_websocket_upgrade() {
assert_eq!(response.status(), StatusCode::BAD_REQUEST);
let value: Value = serde_json::from_slice(response.body().as_deref().unwrap()).unwrap();
assert_eq!(value["error"]["code"], "client_version_too_old");
assert_eq!(value["error"]["current_version"], "0.158.0");
assert_eq!(value["error"]["min_version"], "0.162.0");
assert_eq!(value["error"]["client"], "codex_cli");
assert_eq!(value["error"]["current_version"], version);
assert_eq!(value["error"]["min_version"], "0.170.0");
}
}
server.abort();
@@ -37,7 +37,7 @@ use crate::event::{
use crate::lifecycle::{CancellationToken, Deadline, LeaseGuard};
use crate::metering::Decimal;
use crate::operation::{Operation, ProviderSessionState};
use crate::routing::RoutingPlan;
use crate::routing::{ProviderCandidate, RoutingPlan};
use futures::future::{BoxFuture, Fuse};
use futures::{FutureExt, StreamExt, pin_mut, select_biased};
use futures_timer::Delay;
@@ -1239,142 +1239,11 @@ where
}
ProviderBoundary::Result(result) => match *result {
Ok(stream) => stream,
Err(mut error) => {
attempt_trace.record_provider_failure(&error);
if self.continuation_attempt == ContinuationAttempt::RotateForClientReplay
&& error.continuation_recovery_disposition()
== Some(ContinuationRecoveryDisposition::ClientReplayRequired)
&& let Some(original) = self.last_retryable_failure.take()
{
// 迁移只改变客户端恢复指令;失败分类、发送事实与运维正文仍属于原请求
error = original.with_client_recovery_from(error);
self.last_retryable_failure_events.clear();
}
let connection_fallback = self.connection_rotation.is_some()
&& self
.last_retryable_failure
.as_ref()
.and_then(ProviderError::unreachable_proxy)
.is_none()
&& !self.connection_budget.exhausted()
&& !error.retry_is_prohibited()
&& error.send_state() == UpstreamSendState::NotSent
&& matches!(
error.kind(),
ProviderErrorKind::NoEligibleAccount
| ProviderErrorKind::AccountCapacityUnavailable
| ProviderErrorKind::QuotaExhausted
| ProviderErrorKind::ConcurrencyQueueFull
| ProviderErrorKind::ConcurrencyQueueTimeout
);
let continuation_retry = !error.retry_is_prohibited()
&& self.prepare_unavailable_native_continuation_replay(&error);
let candidate_retry = !error.retry_is_prohibited() && !connection_fallback && !continuation_retry
&& matches!(
error.kind(),
ProviderErrorKind::AccountCapacityUnavailable
| ProviderErrorKind::NoEligibleAccount
| ProviderErrorKind::QuotaExhausted
| ProviderErrorKind::ProviderInfrastructureUnavailable
| ProviderErrorKind::ConcurrencyQueueFull
| ProviderErrorKind::ConcurrencyQueueTimeout
)
&& error.send_state() == UpstreamSendState::NotSent
&& self.current_send_state() == UpstreamSendState::NotSent
&& matches!(
self.continuation_attempt,
ContinuationAttempt::None | ContinuationAttempt::ReplayAny
)
// 跨 Provider 候选推进必然换号(账号行按 Provider 隔离),
// 预算耗尽后不再推进,交回容量类失败的原有终态语义。
&& self.has_account_rotation_budget()
&& self.advance_provider_candidate();
let retryable = self
.apply_retry_policy(super::policy::RetryFacts {
attempt_index: next_attempt,
provider: candidate.provider().clone(),
model: candidate
.upstream_model()
.map(|model| model.as_str().to_owned()),
error_kind: error.kind(),
upstream_status: error.upstream_status(),
send_state: error.send_state(),
remaining_routing_attempts: self
.plan
.max_attempts()
.get()
.saturating_sub(self.routing_attempts),
remaining_deadline: Duration::ZERO,
retry_allowed: connection_fallback
|| continuation_retry
|| candidate_retry,
})
.await?;
attempt_trace.record("retry.decided", json!({
"phase": "prepare", "retryable": retryable,
"continuationRetry": continuation_retry, "candidateRetry": candidate_retry,
"connectionFallback": connection_fallback,
"retryProhibited": error.retry_is_prohibited(),
"sendState": error.send_state().as_str(),
"requestSendState": self.current_send_state().as_str(),
"continuation": format!("{:?}", self.continuation_attempt),
"accountRotations": self.account_rotations,
"maxAccountRotations": self.plan.account_selection_policy().max_account_rotations(),
"remainingRoutingAttempts": self.plan.max_attempts().get().saturating_sub(self.routing_attempts),
}));
if retryable {
if connection_fallback {
let recovery = self
.connection_rotation
.take()
.expect("pending connection rotation");
self.excluded_accounts.remove(&recovery.account);
self.pending_retry = Some(recovery);
} else if candidate_retry {
// 原账号只属于原 Provider,跨候选后不能拿旧钉选作恢复兜底
self.connection_rotation = None;
}
return Ok(Some(PullOutcome::AttemptDiscarded));
}
if matches!(
error.kind(),
ProviderErrorKind::AccountCapacityUnavailable
| ProviderErrorKind::NoEligibleAccount
| ProviderErrorKind::SessionPolicyRestricted
| ProviderErrorKind::QuotaExhausted
| ProviderErrorKind::ConcurrencyQueueFull
| ProviderErrorKind::ConcurrencyQueueTimeout
) && let Some(last_failure) = self.last_retryable_failure.take()
{
let send_state = self.current_send_state();
let mut events = std::mem::take(&mut self.last_retryable_failure_events);
if !events.is_empty() {
self.observe_atomic_terminal_events(&mut events);
self.budget_attempt_already_counted = true;
return Ok(Some(PullOutcome::TerminalFailure {
events,
error: last_failure,
send_state,
}));
}
self.finish_provider_error(&last_failure).await?;
return Err(provider_engine_error(last_failure));
}
if !(matches!(
error.kind(),
ProviderErrorKind::AccountCapacityUnavailable
| ProviderErrorKind::NoEligibleAccount
| ProviderErrorKind::SessionPolicyRestricted
| ProviderErrorKind::QuotaExhausted
| ProviderErrorKind::ProviderInfrastructureUnavailable
| ProviderErrorKind::ConcurrencyQueueFull
| ProviderErrorKind::ConcurrencyQueueTimeout
) && error.send_state() == UpstreamSendState::NotSent)
{
self.record_provider_failure(candidate.provider().clone());
}
self.finish_provider_error(&error).await?;
return Err(provider_engine_error(error));
Err(error) => {
return self
.handle_prepare_failure(error, &candidate, next_attempt, &attempt_trace)
.await
.map(Some);
}
},
};
@@ -1560,6 +1429,131 @@ where
Ok(None)
}
async fn handle_prepare_failure(
&mut self,
mut error: ProviderError,
candidate: &ProviderCandidate,
next_attempt: NonZeroU32,
attempt_trace: &TraceContext,
) -> Result<PullOutcome, EngineError> {
attempt_trace.record_provider_failure(&error);
if self.continuation_attempt == ContinuationAttempt::RotateForClientReplay
&& error.continuation_recovery_disposition()
== Some(ContinuationRecoveryDisposition::ClientReplayRequired)
&& let Some(original) = self.last_retryable_failure.take()
{
// 迁移只改变客户端恢复指令;失败分类、发送事实与运维正文仍属于原请求
error = original.with_client_recovery_from(error);
self.last_retryable_failure_events.clear();
}
let kind = error.kind();
let account_unavailable = matches!(
kind,
ProviderErrorKind::NoEligibleAccount
| ProviderErrorKind::AccountCapacityUnavailable
| ProviderErrorKind::QuotaExhausted
| ProviderErrorKind::ConcurrencyQueueFull
| ProviderErrorKind::ConcurrencyQueueTimeout
);
let infrastructure_unavailable =
kind == ProviderErrorKind::ProviderInfrastructureUnavailable;
let selection_failed =
account_unavailable || kind == ProviderErrorKind::SessionPolicyRestricted;
let not_sent = error.send_state() == UpstreamSendState::NotSent;
let retry_allowed = !error.retry_is_prohibited();
let connection_fallback = self.connection_rotation.is_some()
&& self
.last_retryable_failure
.as_ref()
.and_then(ProviderError::unreachable_proxy)
.is_none()
&& !self.connection_budget.exhausted()
&& retry_allowed
&& not_sent
&& account_unavailable;
let continuation_retry =
retry_allowed && self.prepare_unavailable_native_continuation_replay(&error);
let candidate_retry = retry_allowed
&& !connection_fallback
&& !continuation_retry
&& (account_unavailable || infrastructure_unavailable)
&& not_sent
&& self.current_send_state() == UpstreamSendState::NotSent
&& matches!(
self.continuation_attempt,
ContinuationAttempt::None | ContinuationAttempt::ReplayAny
)
// 跨 Provider 候选推进必然换号(账号行按 Provider 隔离),
// 预算耗尽后不再推进,交回容量类失败的原有终态语义
&& self.has_account_rotation_budget()
&& self.advance_provider_candidate();
let retryable = self
.apply_retry_policy(super::policy::RetryFacts {
attempt_index: next_attempt,
provider: candidate.provider().clone(),
model: candidate
.upstream_model()
.map(|model| model.as_str().to_owned()),
error_kind: kind,
upstream_status: error.upstream_status(),
send_state: error.send_state(),
remaining_routing_attempts: self
.plan
.max_attempts()
.get()
.saturating_sub(self.routing_attempts),
remaining_deadline: Duration::ZERO,
retry_allowed: connection_fallback || continuation_retry || candidate_retry,
})
.await?;
attempt_trace.record("retry.decided", json!({
"phase": "prepare", "retryable": retryable,
"continuationRetry": continuation_retry, "candidateRetry": candidate_retry,
"connectionFallback": connection_fallback,
"retryProhibited": error.retry_is_prohibited(),
"sendState": error.send_state().as_str(),
"requestSendState": self.current_send_state().as_str(),
"continuation": format!("{:?}", self.continuation_attempt),
"accountRotations": self.account_rotations,
"maxAccountRotations": self.plan.account_selection_policy().max_account_rotations(),
"remainingRoutingAttempts": self.plan.max_attempts().get().saturating_sub(self.routing_attempts),
}));
if retryable {
if connection_fallback {
let recovery = self
.connection_rotation
.take()
.expect("pending connection rotation");
self.excluded_accounts.remove(&recovery.account);
self.pending_retry = Some(recovery);
} else if candidate_retry {
// 原账号只属于原 Provider,跨候选后不能拿旧钉选作恢复兜底
self.connection_rotation = None;
}
return Ok(PullOutcome::AttemptDiscarded);
}
if selection_failed && let Some(last_failure) = self.last_retryable_failure.take() {
let send_state = self.current_send_state();
let mut events = std::mem::take(&mut self.last_retryable_failure_events);
if !events.is_empty() {
self.observe_atomic_terminal_events(&mut events);
self.budget_attempt_already_counted = true;
return Ok(PullOutcome::TerminalFailure {
events,
error: last_failure,
send_state,
});
}
self.finish_provider_error(&last_failure).await?;
return Err(provider_engine_error(last_failure));
}
if !(not_sent && (selection_failed || infrastructure_unavailable)) {
self.record_provider_failure(candidate.provider().clone());
}
self.finish_provider_error(&error).await?;
Err(provider_engine_error(error))
}
fn advance_provider_candidate(&mut self) -> bool {
let Some(next) = self.candidate_index.checked_add(1) else {
return false;
@@ -2063,7 +2057,11 @@ where
.pending_terminal_failure
.as_ref()
.ok_or(EngineError::NoActiveAttempt)?;
if pending.events.is_empty() {
// 在保活提交前冻结 HTTP 错误,否则必须交付原流内事件
if pending.events.is_empty()
|| (pending.error.client_visible_upstream_response().is_some()
&& self.response_commit.finish())
{
return Err(provider_engine_error(
self.finalize_pending_terminal_failure().await?,
));
@@ -42,9 +42,12 @@ impl ResponseCommit {
self.committed_at().is_some()
}
pub(crate) fn finish(&self) {
// 执行已结束且未提交时保留原 HTTP 错误,不能因外层插件迟迟返回再改成 200
let _ = self.first.set(TransportState::Finished);
/// 冻结交付状态,返回是否仍可发送独立的 HTTP 错误响应
pub(crate) fn finish(&self) -> bool {
matches!(
self.first.get_or_init(|| TransportState::Finished),
TransportState::Finished
)
}
#[must_use]
@@ -643,6 +643,11 @@ impl AttemptContext {
self.request.client_transport
}
#[must_use]
pub fn endpoint(&self) -> &str {
self.request.endpoint()
}
/// 原生响应可交付可替换前导事件;中间件可能改变其输出语义
#[must_use]
pub fn allows_replayable_prelude(&self) -> bool {
+3 -3
View File
@@ -425,7 +425,7 @@ impl ProviderConnectionObservation {
/// 只供当前客户端请求使用的 HTTP 失败响应
///
/// 通常保留原始上游响应;Provider 也可为明确的恢复流程准备客户端投影
/// Provider 可透传上游 HTTP 响应,也可按客户端协议构造错误正文
/// 投影不能覆盖 [`ProviderError`] 中用于诊断和记账的真实上游事实
///
/// 该值不属于稳定诊断事实,不能进入日志或持久化
@@ -833,7 +833,7 @@ impl ProviderError {
self
}
/// 附加仅可返回给当前请求方的原始上游 HTTP 失败响应
/// 附加仅可返回给当前请求方的 HTTP 失败响应
#[must_use]
pub fn with_client_visible_upstream_response(
mut self,
@@ -1018,7 +1018,7 @@ impl ProviderError {
self.client_visible_upstream_error.as_deref()
}
/// 返回只供当前协议响应使用的原始上游 HTTP 失败响应
/// 返回仅供当前请求方使用的 HTTP 失败响应
#[must_use]
pub fn client_visible_upstream_response(&self) -> Option<&ClientVisibleUpstreamResponse> {
self.client_visible_upstream_response.as_deref()
@@ -143,10 +143,10 @@ fn zero_or_absent_window_weights_disable_reset_scores_and_tolerance() {
}]
.into(),
);
let legacy = json!({"loadWeight":0,"quotaWeight":0,"healthWeight":0,"latencyWeight":0,"resetWeight":10,"queueWeight":0});
let mut disabled = legacy.clone();
let omitted = json!({"loadWeight":0,"quotaWeight":0,"healthWeight":0,"latencyWeight":0,"resetWeight":10,"queueWeight":0});
let mut disabled = omitted.clone();
disabled["resetWindowWeights"] = json!({"fiveHour":0,"weekly":0,"monthly":0});
for wire in [legacy, disabled] {
for wire in [omitted, disabled] {
let config: SmartSchedulingConfig = serde_json::from_value(wire).unwrap();
context.policy = context.policy.with_smart_scheduling(config);
let trace = gateway_core::diagnostics::TraceContext::new("req_zero_windows");
@@ -7436,6 +7436,80 @@ fn transport_keepalive_preserves_pre_output_recovery_and_first_business_commit()
assert!(state.finalizations[0].committed);
}
#[test]
fn atomic_http_failure_uses_wire_only_after_downstream_data_or_keepalive() {
for (prelude, keepalive) in [(false, false), (true, false), (false, true)] {
let operation = generate_operation();
let route_plan = plan(&operation);
let detail = json!({"code":"invalid_value", "message":"Invalid input."});
let wire = json!({"type":"error","status":400,"error":detail});
let mut items = Vec::new();
if prelude {
items.push(Ok(ProviderEvent::canonical(GatewayEvent::Started(
ResponseMeta::new("response-1", "gpt-5"),
))
.with_replayable_prelude()));
}
items.push(Err(ProviderError::new(
ProviderErrorKind::InvalidRequest,
UpstreamSendState::Sent,
)
.with_status(400)
.with_client_visible_upstream_response(ClientVisibleUpstreamResponse::new(
400,
Some(b"application/json".to_vec()),
Bytes::from(json!({"error":detail}).to_string()),
))
.with_atomic_client_events(vec![ProviderEvent::wire(
ProtocolWireEvent::json("openai", Some("error".into()), wire.clone()).unwrap(),
)])));
let (coordinator, store, _) = coordinator(vec![Script::ObservedStream {
account_id: "acct_first",
items,
}]);
let mut session = block_on(coordinator.start(
model_request(&operation, SystemTime::now() + Duration::from_secs(30)),
operation,
route_plan,
None,
None,
CancellationToken::new(),
))
.unwrap();
let transport = session.response_commit();
if prelude {
block_on(session.next_event()).unwrap().unwrap();
block_on(session.commit_downstream(Some(200))).unwrap();
}
if keepalive {
assert!(transport.record(Some(200)));
}
if prelude || keepalive {
let batch = block_on(session.next_event()).unwrap().unwrap();
let events = batch.into_provider_events();
assert_eq!(events.len(), 1);
assert_eq!(events[0].wire_event().unwrap().data(), &wire);
if keepalive {
block_on(session.commit_downstream(Some(200))).unwrap();
}
}
let EngineError::Provider(error) = block_on(session.next_event()).unwrap_err() else {
panic!("expected the upstream bad request");
};
assert_eq!(
error.client_visible_upstream_response().unwrap().status(),
400
);
assert!(session.is_finalized());
assert_eq!(transport.record(Some(200)), prelude || keepalive);
let state = store.state.lock().unwrap();
assert_eq!(state.attempts.len(), 1);
assert_eq!(state.finalizations.len(), 1);
assert_eq!(state.finalizations[0].committed, prelude || keepalive);
assert_eq!(state.finalizations[0].upstream_status_code, Some(400));
}
}
#[test]
fn transport_keepalive_records_late_failure_as_incomplete_http_200() {
let operation = generate_operation();
@@ -69,7 +69,7 @@ fn privacy_rule_requires_steps_and_rejects_unknown_fields() {
missing_steps.as_object_mut().unwrap().remove("steps");
assert!(serde_json::from_value::<PrivacyRule>(missing_steps).is_err());
let mut unknown_rule_field = value.clone();
unknown_rule_field["scope"] = serde_json::json!("request_body");
unknown_rule_field["unexpected"] = serde_json::json!(true);
assert!(serde_json::from_value::<PrivacyRule>(unknown_rule_field).is_err());
let mut unknown_step_field = value;
unknown_step_field["steps"][0]["unexpected"] = serde_json::json!(true);
@@ -139,7 +139,7 @@ fn blocked_file_output_keeps_http_and_streaming_responsive_and_reserves_errors()
);
let (release, released) = std::sync::mpsc::channel();
let reader = std::thread::spawn(move || {
// 超时只用于让旧的同步实现能退出测试,接口必须在解除阻塞之前完成
// 请求必须在读端放行前完成,超时让写入阻塞时的测试也能退出
let _ = released.recv_timeout(Duration::from_secs(3));
let mut body = String::new();
fs::File::open(fifo)
@@ -327,7 +327,6 @@ async fn managed_http_enforces_the_callers_body_limit_before_sending() {
.mount(&server)
.await;
let client = HttpClient::new().unwrap();
// 覆盖旧固定上限之外的正文,并验证同一个客户端逐次使用调用方的预算
let maximum = 17 * 1024 * 1024;
for (size, limit, accepted) in [
(maximum, maximum, true),
@@ -24,9 +24,9 @@ async fn invalid_update_state_should_keep_raw_details_out_of_public_error() {
}
#[tokio::test]
async fn update_status_should_reconcile_manual_deployment_without_reusing_legacy_success() {
async fn manual_deployment_reports_the_running_version_and_preserves_the_last_operation() {
let fixture = Fixture::new();
fs::write(fixture.state(), r#"{"previousVersion":"3.14.0","currentVersion":"3.14.1","operation":{"operationId":"legacy","kind":"update","status":"succeeded","targetVersion":"3.14.1"}}"#).expect("legacy state");
fs::write(fixture.state(), r#"{"previousVersion":"3.14.0","currentVersion":"3.14.1","operation":{"operationId":"completed-update","kind":"update","status":"succeeded","targetVersion":"3.14.1"}}"#).expect("completed update state");
let mut config = fixture.config("https://api.github.com/repos");
config.version = "3.15.0".to_owned();
config.deployment_mode = "docker".to_owned();
@@ -645,7 +645,7 @@ async fn concurrent_calls_keep_their_wire_ids_monotonic() {
}
ready.wait().await;
entered.await;
// 旧实现会在 begin 前分配后续 ID;等其他线程进入该窗口后再释放首调用
// 暂停首个 begin,给其他并发调用留出竞争发送顺序的时间
tokio::time::sleep(Duration::from_millis(20)).await;
callbacks.release();
for call in calls {
@@ -542,8 +542,6 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
);
if let Some(expected) = configuration.get("expected_fast_source") {
let sources = &call.request.head.settings_sources["execution"];
assert!(sources.get("disable_fast").is_none());
assert!(sources["input"].get("disable_fast").is_none());
assert_eq!(sources["input"]["fast_mode"], "default");
assert_eq!(&sources["fast_mode"], expected);
}
+9 -24
View File
@@ -1,15 +1,9 @@
# Gateway Plugin SDK
用于编写 Codex Proxy 插件的 Rust 合同与可选会话辅助。插件只依赖本包,不依赖宿主 Core、Admin、Store 或 Host。
SDK 包版本为 `0.1.0`,独立于网关版本,处于实验阶段。能力是否可用取决于宿主支持、清单声明与实际注册
Rust 插件只需依赖 `gateway-plugin-sdk`。SDK `0.1.0` 处于实验阶段,独立于网关发版。清单、进程协议和能力分别版本化,插件可用能力取决于宿主支持、清单声明与实际注册
清单、进程协议和各项能力分别版本化,当前版本与声明规则统一见[插件清单](docs/manifest.md)
开发顺序:编写[清单](docs/manifest.md) → 实现[能力处理器](docs/capabilities.md) → 用 [CLI](../../../apps/plugin-cli/README.md)
打包 → [安装、配置与启用](../../../../docs/plugins.md)。完整可运行示例位于独立仓库
`codex-proxy-plugins` 的 `examples/workbench`
使用 AI 协作开发时,可调用仓库技能 [`$cpr-plugin-dev`](../../../../.agents/skills/cpr-plugin-dev/SKILL.md),按任务定位合同、示例和验证入口
编写[清单](docs/manifest.md) → 实现[处理器](docs/capabilities.md) → 用 [CLI 打包](../../../apps/plugin-cli/README.md) → [安装并启用](../../../../docs/plugins.md)。
完整示例见 `codex-proxy-plugins/examples/workbench`,AI 协作入口见 [cpr-plugin-dev](../../../../.agents/skills/cpr-plugin-dev/SKILL.md)
## 模块与依赖
@@ -29,11 +23,7 @@ SDK 包版本为 `0.1.0`,独立于网关版本,处于实验阶段。能力
| `call::management` | 管理 API、页面与资源声明、公开回调,以及 CLI 命令与待保存账号 |
| `client` | 通过 `io` feature 开启的 `PluginBuilder`、会话、中间件与异步帧收发 |
`call/` 按业务能力组织数据,`message.rs` 定义消息与帧。已有请求链的请求/响应改写、协议转换和思考参数映射使用
`call::middleware`;需要指定业务上游并解析结果时使用 `call::upstream_adapter`,作为洋葱链终端复用宿主账号与结算。
下游 WebSocket 改写使用 `websocket` 中间件;上游发送前的请求准备使用 `outbound` 中间件,响应观察接口保留只读合同
插件使用的导入路径例如:
`message.rs` 定义消息与帧。改写现有请求、响应或推理参数使用 `call::middleware`,其中 `websocket` 处理下游消息,`outbound` 处理上游发送前的请求。响应观察只读。需要自行选择业务上游并解析响应时使用 `call::upstream_adapter`
```rust
use gateway_plugin_sdk::{Frame, Message, PluginFault};
@@ -42,10 +32,8 @@ use gateway_plugin_sdk::call::{host::ModelEventBatch, model::ExecutionEvent};
use gateway_plugin_sdk::client::{read_frame, write_frame};
```
默认 feature 不引入异步运行时。`io` 除帧编解码外,还提供 `PluginBuilder`、
`PluginSession::accept/run` 和 `PluginHandler`。组合插件从作者清单建立类型化方法,SDK 自动生成
`plugin.register`;作者不需要复制贡献项或手写方法名、阶段和敏感载荷编解码。
会话管理握手、有界并发、父调用关联、回调、流信用、取消、排空与关闭,容量与计时见[并发与期限](#并发与期限)
默认 feature 不引入异步运行时。`io` 提供帧编解码、`PluginBuilder`、`PluginSession::accept/run` 和 `PluginHandler`。
[类型化构建器](docs/capabilities.md#类型化作者入口)按清单注册处理器。会话管理握手、并发、父调用关联、回调、流信用、取消、排空与关闭,容量与计时见[并发与期限](#并发与期限)
`HostClient::scan_usage_records` 与 `query_usage_statistics` 提供用量明细扫描和完整分组统计,按批读取与关闭见[用量查询](docs/usage-data.md#完整扫描与分组统计)
@@ -149,9 +137,8 @@ session.run(handler).await?;
### 帧与会话
`CallContext.timeout_ms` 限定初始处理期限。宿主对由流或连接 owner 管理的调用设置 `resource_stream`:
首个流式结果成功返回后,正文、会话及关联回调由资源取消与终态回收,不再沿用初始期限。
普通调用继续使用原期限;资源模式仍保留并发容量、Credit、父调用关联及取消约束
普通调用受 `CallContext.timeout_ms` 限制。对标记为 `resource_stream` 的调用,初始期限只到首个流式结果成功返回。
其后的正文、会话及回调由资源终态或取消回收,仍受并发容量、Credit 和父调用约束
协议 v7 的帧头由大端 `u32` 元数据长度和大端 `u64` 载荷长度组成,随后依次传输 JSON 元数据和二进制载荷。
元数据保留 64 KiB 上限;正文总量不由插件传输层额外限制。传输内部以 256 KiB 为单次 I/O 块,
@@ -210,6 +197,4 @@ RUST_MIN_STACK=16777216 cargo +1.99.1 test --manifest-path backend/Cargo.toml -p
RUST_MIN_STACK=16777216 RUSTDOCFLAGS='-D warnings' cargo +1.99.1 doc --manifest-path backend/Cargo.toml -p gateway-plugin-sdk --all-features --no-deps --locked
```
源码中的类型和字段是当前合同;宿主接入、目录边界、内置 Provider 与 Runtime 集成验证见
[系统架构](../../../../docs/architecture.md#31-插件扩展)。
单元测试与文档构建不代替目标平台上的安装、配置及实际能力验证
宿主集成见[系统架构](../../../../docs/architecture.md#31-插件扩展)。插件还须在目标平台验证安装、配置和实际功能
@@ -27,22 +27,15 @@ let plugin = PluginBuilder::from_json(include_bytes!("../plugin.json"))?
session.run(plugin).await?;
```
`PluginBuilder::from_json` 与 `cpr-plugin package` 使用同一个作者清单规范化入口。构建器负责:
- 自动响应 `plugin.register`,注册内容直接来自规范化后的清单
- 按方法合同解码控制参数和二进制载荷,并在进入业务处理器前检查调用阶段
- 保留 `TypedCall` 中的调用上下文、宿主客户端和取消信号
- 按方法合同编码 `TypedReply`,流式结果继续复用有界 `ResponseStream`
- 在 `build()` 时核对能力与必需处理器,避免清单与分派表漂移
`PluginBuilder::from_json` 与打包 CLI 共用[作者清单入口](manifest.md),按清单响应 `plugin.register`,并在 `build()` 时核对必需处理器。
构建器在分派前检查阶段、解码控制参数与载荷。`TypedCall` 携带上下文、宿主客户端及取消信号,结果编码为 `TypedReply`,流式结果使用有界 `ResponseStream`
`management`、`command_line` 和 `middleware` 是常用组合入口;其余能力使用
`on(methods::..., handler)`。方法常量固定请求、响应、阶段与载荷位置,作者不手写 RPC 方法名。
状态迁移不是 capability:清单任一 `state[]` 声明了 `migratesFrom` 时,注册
`methods::STATE_MIGRATE`,构建器也会要求该处理器存在
类型化合同故意区分三种数据:普通控制元数据、可能敏感的 JSON 二进制载荷、原始字节。
例如 CLI 参数、账号凭据和状态迁移批次使用二进制 JSON,管理 HTTP 正文保持原始字节。
错误地把敏感载荷放进控制参数会在业务处理器运行前被拒绝
控制参数只放普通元数据。CLI 参数、账号凭据和状态迁移批次使用二进制 JSON,管理 HTTP 正文使用原始字节。敏感载荷放进控制参数会在分派前被拒绝
## 请求上下文
@@ -252,9 +245,7 @@ SDK 不自动重试。超时或断连不能证明写入未提交;重试上限
### Key、模型与模型调用
模型调用方法:
- `host.keys.list`:只返回 `{id, name, enabled}`,不返回 Key 明文、前缀或隐藏 scope
- `host.keys.list`:分页返回 `{id, name, enabled}`
- `host.models.list`:以显式 `client_key_id` 查询该 Key 当前可见的模型目录
- `host.model.execute[_stream]`:交给 Core 的路由、准入、租约、重试、账本和计费链路执行
- `host.model.stream_read/close`:读取或关闭当前父调用创建的有界流
@@ -266,9 +257,8 @@ SDK 不自动重试。超时或断连不能证明写入未提交;重试上限
`invalid_input`,不启动模型执行。上游适配器的请求 `GPAQ` 也使用请求预算,响应事件仍受
原有 8 MiB 编码上限、Runtime 缓冲预算及流控窗口限制
HTTP 和 request 中间件中的模型回调沿用有效请求设置;attempt、outbound、路由、调度、重试和上游适配器
沿用该次模型请求冻结的正文预算。显式 Key 模型调用的预检与执行使用同一身份快照,
同一父调用内复用 Key 时不受后续配置发布影响;父调用结束后重新解析身份才读取新配置,无需重新启用插件
HTTP 和 request 中间件使用有效请求设置。attempt、outbound、路由、调度、重试及上游适配器沿用冻结的模型请求预算。
显式 Key 的预检与执行共用父调用内的身份快照,后续发布的配置在新的父调用解析身份时生效
`ModelExecuteRequest.client_key_id` 可显式选择执行 Key,不与触发插件的父请求 Key 求交。省略时继承现有模型父请求身份;没有模型父请求的调用必须提供 Key。所选 Key 的启用状态、模型规则、账号组、并发和预算继续由 Core 执行
嵌套调用与显式 Key 调用继承入口快照中的客户端 IP 和 User-Agent;没有 HTTP 入口的后台调用保持来源未知
@@ -276,7 +266,7 @@ HTTP 和 request 中间件中的模型回调沿用有效请求设置;attempt
模型事件使用 `call::model::ExecutionEvent` 的 `GPE2` 封套,将 canonical 事实、宿主事实和原始 wire 分段编码。`host` 包含费用及定价明细、完整上游观测、会话状态和改写来源;当前 wire 与原始 wire 都保留二进制字节;`WirePayload::WebSocket` 独立保留完整文本消息和可选 JSON 视图,不把未知文本改造成 SSE。读取或回传快照不触发第二次计费、续接提交或发送状态更新。
非流式模型结果通过 `ModelEventBatch` 的 `HME1` 有界二进制批次返回;流式句柄只在创建它的父调用内有效。
发起回调的插件实例在子调用中跳过,Core 在单次执行的子调用图内限制递归深度、总数和并发,避免插件调用自身形成环。
显式 Key 的身份快照随父调用保留,每个模型执行独立计时并建立调用图;父调用结束会取消尚未完成的执行,连接空闲不消耗后续执行的期限
每次模型执行独立计时并建立调用图。父调用结束会取消未完成的执行,连接空闲不消耗后续执行的期限
`host.affinity.lookup` 查询 Provider 已持久化的真实亲和键。命中只是账号偏好,
后续执行仍重新检查当前 Key 规则、账号资格和租约
@@ -288,16 +278,11 @@ HTTP 和 request 中间件中的模型回调沿用有效请求设置;attempt
父调用取消或结束时宿主回收未关闭的流,SDK 不后台预读。取消一次 `read()` 等待后,再次读取会继续同一次操作,不丢弃已经返回的分块。
账号上游使用同一正文对象,使用方式见[受管上游](upstream-adapters.md)
`HostClient::account_http(AccountHttpRequest { account_id, credential_revision, request }, body)` 使用指定账号的当前代理配置,
经 `host.http.account` 返回同一 `HostHttpBody`。每次发送核对账号存在、启用和凭据版本,版本变化须由插件重新读取后决定下一步。
请求 headers 与正文完全由插件提供;宿主不注入账号认证、不申请推理租约。无显式代理时使用部署默认出口,代理不可用时直接失败,不回退直连。
这项能力与上游适配器的账号推理 HTTP 分开,适用于插件自行构造的账号网络请求
`HostClient::account_http(AccountHttpRequest { account_id, credential_revision, request }, body)` 经 `host.http.account` 使用账号代理并返回 `HostHttpBody`。每次发送要求账号存在、已启用且凭据版本匹配。版本变化时须重新读取凭据。
插件提供请求头与正文,宿主不注入账号认证或申请推理租约。无显式代理时使用部署默认出口,代理不可用时直接失败
`HostClient::proxy_http(ProxyHttpRequest { proxy_id, request }, body)` 经 `host.http.proxy` 使用指定代理的当前配置,
返回同一响应头与 `HostHttpBody`,不要求账号存在或绑定代理,也不校验账号凭据版本。
代理不存在、禁用或连接失败时返回错误,不回退直连;未测试或历史测试失败不阻止实际请求。
每次发送重新读取代理,已发出的请求沿该次解析的出口完成,不锁定整个插件业务流程的代理配置。
目标请求的 headers 与正文由插件提供,宿主不注入账号认证;代理连接所需认证由宿主处理
`HostClient::proxy_http(ProxyHttpRequest { proxy_id, request }, body)` 经 `host.http.proxy` 使用指定代理,无需绑定账号,返回响应头与 `HostHttpBody`。
宿主每次发送读取代理配置,已发出的请求沿该出口完成。代理不存在、禁用或连接失败时直接报错,历史测试结果不限制发送。插件提供目标请求头与正文,宿主仅处理代理认证
`HostClient::list_proxies(ProxyListRequest { page, page_size, search })` 经 `host.proxies.list` 查询代理目录。
`page` 从 1 开始,`page_size` 为 1–200,`search` 可省略,默认空字符串,最多 256 字节且不能包含控制字符。
@@ -387,7 +372,7 @@ let status = host.service::<SetResetCreditAutomation>((account_id, true)).await?
`HttpCall.request` 提供 method、URI(含 query)、HTTP version、完整多值 headers、`settings`、`timeout_ms` 和 `HttpBody`。
调用发生在路由匹配之前,管理接口、模型接口和未知路径都可参与。`settings` 是同一请求快照中的宿主运行设置,
插件改写后用于后续认证、版本检查、正文解压及执行;不新增设置业务的中间件入口。`timeout_ms` 使用宿主 HTTP 超时基线,
插件改写后的设置用于认证、版本检查、正文解压及执行。`timeout_ms` 默认取宿主 HTTP 超时,
插件可改写或用 `None` 清除;终端按有效值执行,不恢复宿主默认值。宿主快照不可用时 `settings` 为 `null`
`POST /v1/chat/completions` 在 HTTP 挂载中保留 Chat 请求与 Chat JSON/SSE 响应视图,
@@ -756,7 +741,7 @@ keep、replace 或 delete;全部完成后宿主才原子提交新配置与状
需要跳转到外部页面时,在插件页面的用户点击处理器中调用 `openExternal(url): Promise<void>`。
地址必须是绝对 HTTPS URL,不能包含用户名或密码。宿主展示目标主机名和非默认端口,管理员可打开新标签页、复制链接或取消。
Promise 成功只表示宿主已接受确认请求,不代表链接已打开;无用户操作、地址无效或已有链接待确认时,请求会被拒绝。
切换页面会关闭确认框。兼容较早的 v2 宿主时,先检查 `typeof window.codexProxyPlugin.openExternal === 'function'`
切换页面会关闭确认框。插件需要适配缺少此方法的宿主时,先检查 `typeof window.codexProxyPlugin.openExternal === 'function'`
普通模型请求使用标准 `Response` 接口:
@@ -2,8 +2,7 @@
[返回 SDK](../README.md) · [能力与回调](capabilities.md)
`Manifest` 对应包内 `plugin.json`。作者源清单由 `Manifest::from_author_slice` 读取,CLI 打包也调用同一入口;
因此本地构建器、生成的安装清单和运行注册共享一份规范化结果
`Manifest` 对应包内的 `plugin.json`。本地构建器与打包 CLI 都通过 `Manifest::from_author_slice` 校验并规范化作者清单
| 字段 | 规则 |
| --- | --- |
@@ -14,11 +13,10 @@
| `configurationSchema` / `secretFields` | 普通设置的 schema / 单独保存的敏感字段 |
| `main` / `resources` | 包内可执行文件 / 资源路径与 MIME 类型 |
| `state` | [私有状态](capabilities.md#状态日志与迁移)的命名空间、schema 与配额 |
| `package` | CLI 生成的协议版本、单一目标平台与文件摘要,不需作者手写 |
| `package` | 作者清单须省略。CLI 填入协议版本、目标平台与文件摘要 |
作者清单不能包含 `package`。使用 `Manifest::from_author_slice()` 校验并规范化;直接反序列化的 `Manifest`
不会执行作者清单的 ID 与固定阶段推导,声明的可选字段仍使用其默认值。打包后,`main` 和所有资源都必须进入 `package.files`,
宿主校验包结构、目标平台与文件完整性,宿主范围和能力版本另行进行兼容检查。运行模式为 `trustedProcess`,信任边界见[完整信任](#完整信任)
直接反序列化 `Manifest` 只应用可选字段默认值。需要推导 ID 和固定阶段时使用作者清单入口。
打包后,`package.files` 须包含 `main` 与所有资源
宿主实际开放的合同由 [plugin-host-compatibility.json](../../runtime/plugin-host-compatibility.json)
声明,SDK 的 `Capability::contract_versions()` 只表示 SDK 能描述的行为版本,不能代替宿主支持检查
@@ -32,13 +30,9 @@
`capabilities` 使用扩展能力标识;Provider、模型和账号 ID 不属于这个集合
清单不接受 `permissions` 字段;插件按[完整信任](#完整信任)运行
CLI 按 SDK 合同校验声明。安装包清单拒绝未知字段,并校验必需字段、类型与版本。进程通信见 [RPC 合同](../README.md#通信边界),已安装元数据的读取见[制品与发布](../../../../../docs/architecture.md#制品配置与发布)
RPC v7 的帧布局、编码与会话生命周期见[通信边界](../README.md#通信边界)。插件使用 SDK 构建,并由 CLI 生成包含协议版本的安装包
安装包清单校验与已安装元数据读取是两个边界:清单拒绝未知字段,并检查必需字段、类型和版本;
数据库元数据的读取规则见[制品与发布](../../../../../docs/architecture.md#制品配置与发布),不改变清单或 RPC 合同。
`engines.codex-proxy-rs` 声明插件所需的宿主范围。范围或已声明能力版本不匹配时不自动启动,管理员确认风险后可尝试本次启动;确认不跨宿主重启保留。包结构、清单格式、平台与 RPC 封装校验失败阻止加载,不能通过风险确认绕过。CLI 严格校验作者声明是否符合 SDK 支持的合同
宿主版本超出 `engines.codex-proxy-rs` 范围或能力版本不匹配时,管理员可确认风险并尝试启动,确认仅对本次启动有效。包结构、文件完整性、清单格式、平台或 RPC 校验失败时无法加载
## 接口弃用
@@ -98,15 +92,11 @@ capability 固定并由工具生成:
安装并启用插件意味着信任其全部代码和行为。插件与宿主使用相同的系统身份,可以访问数据、凭据和网络;安全由安装者承担,宿主不提供插件安全沙箱
清单只声明处理器、配置和资源。宿主回调不需要权限声明,也不按调用阶段授予访问域;类型校验、期限、取消、实例 revision、事务及流资源生命周期仍然生效
运行模式为 `trustedProcess`。清单不接受 `permissions`,宿主回调无需声明权限。类型、期限、取消、实例 revision、事务与流资源约束均生效
## 插件图标
`icon` 指定管理端展示的插件图标。值可以是一个包内文件路径,也可以是包含 `light`、`dark` 两个路径的对象。
使用单个路径时,浅色和深色主题共用同一张图;使用主题对象时,管理端按当前主题选择,两项都必须填写。
不填写 `icon` 时显示通用图标。图标路径不是远程 URL,也不接受内置图标名称
在 `plugin.json` 中同时设置 `icon` 和对应的 `resources` 项。以下是单图标配置片段:
`icon` 可填包内路径(两种主题共用),或同时含 `light`、`dark` 路径的对象。每个文件均须在 `resources` 登记。省略 `icon` 时显示通用图标
```json
{
@@ -151,6 +141,4 @@ capability 固定并由工具生成:
- SVG 使用 UTF-8 编码,根元素为 SVG 命名空间中的 `<svg>`,XML 节点不超过 16384 个;不使用 DTD 实体或 XML 处理指令
- SVG 保留矢量、渐变、内联样式和 data URL 内嵌图片;图标不能依赖脚本、外部图片、外部样式或外部字体
将图标文件与清单一同交给 [插件 CLI](../../../../apps/plugin-cli/README.md) 打包。工具收集 `resources` 声明的文件,
生成 `package.files` 摘要;宿主在安装时验证图标内容。管理端通过 [图标读取接口](../../../../../docs/api.md#12-插件管理)
以图片方式展示,不将 SVG 源码插入页面 HTML
[插件 CLI](../../../../apps/plugin-cli/README.md) 打包图标,宿主在安装时校验内容。管理端通过[图标接口](../../../../../docs/api.md#图标读取)以图片展示 SVG
@@ -2,9 +2,8 @@
[返回 SDK](../README.md) · [清单声明](manifest.md#扩展项简写) · [能力与回调](capabilities.md)
`upstream_adapter` v5 是现有生成请求洋葱链的终端,只挂到内置 `openai` / `xai`,不替换独立图像或压缩端点。
插件定义 Base URL、业务路径、请求编码和响应解析;宿主继续持有身份、ACL、选号、租约、凭据、代理、重试和账本。
普通请求或响应加工使用 [middleware](capabilities.md#洋葱中间件)
`upstream_adapter` v5 处理内置 `openai` / `xai` 的生成请求,独立图像和压缩端点使用原生实现。
插件负责 Base URL、路径、请求编码和响应解析。宿主负责身份、ACL、选号、租约、凭据、代理、重试和账本。仅需加工请求或响应时使用[中间件](capabilities.md#洋葱中间件)
## 声明与绑定
@@ -26,18 +25,13 @@
| `models` | 公开请求模型的精确匹配,空集合沿用绑定范围 |
| `account_ids` | 上游账号 ID 范围,必填;空数组匹配所有账号 |
实例绑定沿用 Key、账号组、Provider、模型范围,只允许一次 `upstream` 绑定和 `reject` 故障策略。
多个声明命中时按发布顺序选择首个适配器,插件负责声明的业务含义。适配器未命中时仍使用原生上游,
已命中但不可用时拒绝请求。安装、配置、启停和升级使用已有插件管理
实例只允许一个 `upstream` 绑定,故障策略为 `reject`。Key、账号组、Provider 和模型限定请求范围,插件注册的 `account_ids` 只能进一步收窄账号范围
账号范围只收窄绑定,不能扩大 Key、分组或模型权限。宿主先排除适配器不可用或认证类型不兼容的账号,
再沿用原调度、亲和和租约;取得账号后从同一发布代次解析适配器。不同账号可以为同一公开模型选择不同适配器,
未匹配账号保持原生执行,重叠声明仍按发布顺序取首个匹配。
前置账号范围已匹配的可用适配器不受后置兜底声明故障影响。
xAI 原生编码不支持的请求仍可选择匹配的适配器账号;原生账号会在取得租约前被排除
同一模型可按账号使用不同适配器。每个账号按发布顺序取首个匹配声明,后续声明的故障不影响已匹配的适配器。未匹配时使用原生上游,命中但不可用时拒绝执行
账号范围由插件注册结果提供,不改变管理端 binding 中 `accountGroupIds` 的请求作用域语义。
停用或卸载实例会移除其绑定;维护时须先停用依赖该适配器的账号并排空请求,账号范围不提供永久依赖约束。
取得租约前,宿主排除适配器不可用或认证不兼容的账号。xAI 原生编码不支持请求时,仅排除原生账号,匹配的适配器账号仍可使用。宿主按亲和与调度策略取得租约后,从同一发布代次解析适配器
停用或卸载实例会移除绑定。维护前先停用依赖该适配器的账号并排空请求
能力、清单、进程 RPC 和宿主兼容声明分别校验各自版本,见[清单](manifest.md)。
Provider、业务协议和传输名称不能写入宿主兼容清单的 capability / RPC 版本位置
@@ -65,9 +59,8 @@ while let Some(bytes) = body.read().await? {
}
```
正文与普通 `HostClient::http` 共用 `read`、`collect(maximum_bytes)` 和 `close`;每次读取至多 64 KiB,
不后台预读,不向作者暴露流 ID。提前关闭及收集超限会释放正文,父调用结束或取消时宿主兜底回收。
JSON 可有界收集,SSE 应增量解析,不能把读取块当成完整事件。HTTP 版本、字节头及 trailers 的读取见[网络](capabilities.md#网络)
正文每次 `read` 至多 64 KiB,SDK 按需读取并管理流 ID。JSON 可用 `collect(maximum_bytes)`,SSE 须跨读取块增量解析。
显式 `close`、收集超限或父调用结束、取消时释放正文。HTTP 版本、字节头及 trailers 见[网络](capabilities.md#网络)
WebSocket 使用 `call.host.upstream_websocket(request).await?`,返回
`UpstreamWebSocketUpgrade::Connected { http_version, headers, connection }` 或 `Rejected { status, http_version, headers, body, trailers }`。
@@ -102,9 +95,7 @@ let (message, ()) = tokio::try_join!(
观测事件和该次 HTTP 的读流、关流不单独阻断;HTTP200 流内报错、WebSocket 拒绝及其他状态码不适用。
Core 仍复核续接归属、外部副作用、交付与重试预算;这不保证一定换号,也不证明完整信任插件绕过宿主执行的操作可重放
初始 RPC 回复受插件处理预算约束,默认上限为 120 秒;持续接收与解析应放在返回的流中。
初始流式回复后,流的寿命遵循模型请求期限与取消,受管 HTTP 正文每次读取单独计时。
持续有数据的流不会因初始 RPC 预算耗尽而结束,单次读取超时、客户端取消和流结束仍会回收资源
初始 RPC 回复默认限时 120 秒。持续接收与解析应放在返回的流中,遵循模型请求期限。受管 HTTP 正文每次读取单独计时,读取超时、客户端取消或流结束时回收资源
用量提交标准 `Usage`,费用由内置 Provider 按已冻结的上游模型与价格计算,响应回显模型不切换计价。
`observation.service_tier` 记录上游回显的最新档位,允许上游在完成时确定实际值;OpenAI 计价沿用请求策略,回显档位仅作观测。
@@ -15,7 +15,7 @@
| `WriteAggregates` | `usage.aggregates.write` | 按聚合键批量覆盖或删除统计贡献 |
| `EvaluatePricing` | `pricing.evaluate` | 根据当前价目或指定价格试算,逐项返回 `estimated` 或 `not_estimable` |
明细列表只列请求记录,聚合贡献参与统计但不生成请求明细。完整分组与全局总量使用下方统计读取,趋势使用既有统计查询
请求列表只含明细。全局与分组统计包含聚合贡献,趋势由统计查询提供
## 完整扫描与分组统计
@@ -93,21 +93,21 @@ async fn read_statistics(
## 聚合维护
`UsageAggregateKey` 由 `bucket_start_ms`、`dimensions` 和调用方的 `key` 共同构成。相同完整键的 `put` 覆盖旧值,重复提交相同内容不会累计;改变时间、维度或 `key` 会形成另一个目标,需要移动时由调用方删除旧键
`UsageAggregateKey` 由 `bucket_start_ms`、`dimensions` 和调用方的 `key` 组成。`put` 按完整键覆盖,重复提交不会累加。移动记录须写入新键并删除旧键
`dimensions` 支持 Provider、模型、账号、Key、操作和传输类型。`counts` 的键由 `UsageMetric` 定义,包括请求次数、各终态次数、已完成次数和各项 Token;`costs` 按币种保存十进制金额。计数与费用允许负值,供调用方表达统计修正
聚合按 `bucket_start_ms` 这个归属时间纳入 `[start_ms, end_ms)` 查询及趋势时间桶,宿主不自动摊分。导入日汇总时,调用方选择该日的归属时间;需要小时分布时,调用方自行提供小时数据
贡献按 `bucket_start_ms` 计入查询区间与趋势时间桶。日汇总不会自动摊到各小时,需要小时分布时须写入小时数据
查询只按实际提供的维度匹配,缺少的维度不会自动补全。未提供某个维度的贡献参与总量,完整分组读取使用独立未归属分组表达,其他维度查询只计入实际提供该维度的贡献。请求 ID、响应 ID、状态码、请求结果及文字搜索等明细筛选不包含聚合贡献,聚合也不生成延迟样本、尝试次数或请求列表页数。原生统计的无符号计数与非负金额若因贡献合计超出表示范围,查询返回错误,由调用方修正输入
贡献计入原生总量、趋势、维度统计和账号用量,维度匹配与越界处理见[分组与覆盖](#分组与覆盖)。按请求或响应 ID、状态码、请求结果或文字筛选时排除贡献。贡献不产生延迟样本、尝试次数或请求列表页数
聚合贡献参与原生总量、趋势、维度统计和账号用量,统计重建保留这些数据。贡献由调用方删除,不随请求历史保留任务清理;明细沿用请求历史保留策略
统计重建保留贡献,须由写入方删除。请求历史保留策略只清理明细
## 费用试算与写回
`EvaluatePricing` 使用 Provider 的原生单请求 Token 计价公式,支持当前价目和调用方指定的价格覆盖。OpenAI 与 xAI 提供此能力;不支持的 Provider、缺少必要 Token、图像用量或无法确定的价目返回 `not_estimable`
`EvaluatePricing` 按 OpenAI 或 xAI 的单请求公式,用当前价目或指定价格试算 Token 费用。须提供输入、输出、缓存读取、缓存写入和图像 Token,纯文本的图像 Token 填零。Provider 不支持、用量不全或价格未知时返回 `not_estimable`
试算输入需要明确输入、输出、缓存读取、缓存写入以及图像 Token;纯文本用量的图像 Token 填零。结果只包含 Token 费用,不自动处理图像、工具或其他附加费用,也不写入历史
试算不含图像、工具等附加费用,也不写入请求记录
调用方可查询明细、选择目标、逐条试算,再通过 `WriteRecords::Update` 写回费用。补全缺失时只处理 `unavailable`;全部覆盖时自行选择整个范围。日汇总若缺少逐请求分布,长上下文档位和逐请求舍入可能无法复现,计算方法由调用方决定
@@ -121,4 +121,4 @@ async fn read_statistics(
- 存储操作共享宿主观测连接与执行预算,超时、锁等待或取消会结束该次执行并释放资源
- 错误类型包括 `invalid_input`、`not_found`、`conflict`、`capacity_exceeded`、`unavailable`,分批读取还区分 `cancelled` 与 `timeout`
响应丢失时,调用方按稳定 ID 或聚合键查询、重试覆盖。宿主不保存任务、来源登记、幂等回执、调整历史或撤销计划;调用方负责来源映射、业务去重、重试策略、并发写入协调和恢复。服务输入不能指定审计主体,宿主从当前调用身份生成普通变更审计
响应丢失时,按稳定 ID 或聚合键查询后重试覆盖。调用方负责来源映射、去重、并发写入、进度、调整记录和恢复。宿主按当前调用身份记录变更审计,不提供幂等回执
@@ -3,6 +3,9 @@
/// OpenAI 线协议载荷与事件的协议标识
pub const OPENAI_PROTOCOL: &str = "openai";
/// 原生 Responses 客户端入口
pub const RESPONSES_PATH: &str = "/v1/responses";
/// Codex Responses Lite 的 HTTP 请求头
pub const X_OPENAI_INTERNAL_CODEX_RESPONSES_LITE_HEADER: &str =
"x-openai-internal-codex-responses-lite";
@@ -454,7 +454,10 @@ impl AccountGroupStore for PgAccountGroupRepository {
.await
.map_err(|source| unavailable("check account group delete conflict", source))?;
if exists {
Err(conflict(command.id.as_str()))
Err(conflict(
command.id.as_str(),
ConflictKind::InvalidTransition,
))
} else {
Err(not_found_store(command.id.as_str()))
}
@@ -681,11 +684,15 @@ fn require_one(rows: u64, id: &str) -> StoreResult<()> {
}
fn map_group_write_error(error: sqlx::Error, id: &str) -> StoreError {
if error
.as_database_error()
.is_some_and(|database| database.is_unique_violation())
if let Some(database) = error.as_database_error()
&& database.is_unique_violation()
{
conflict(id)
let kind = if database.constraint() == Some("account_groups_name_uq") {
ConflictKind::DuplicateName
} else {
ConflictKind::InvalidTransition
};
conflict(id, kind)
} else {
unavailable("write account group", error)
}
@@ -703,12 +710,12 @@ fn not_found_store(id: &str) -> StoreError {
}
}
fn conflict(id: &str) -> StoreError {
fn conflict(id: &str, kind: ConflictKind) -> StoreError {
StoreError::Conflict {
source: None,
entity: ENTITY,
id: id.to_owned(),
kind: ConflictKind::InvalidTransition,
kind,
}
}
@@ -130,18 +130,7 @@ pub(crate) fn push_usage_filter(
pub(crate) const USAGE_LIST_RECORD_SELECT: &str =
"select mr.id, mr.outcome, mr.provider_error_code as error_code, mr.error_message, mr.client_status_code, mr.client_api_key_name_snapshot as client_api_key_name, mr.endpoint, mr.client_transport, mr.requested_model_id,
mr.error_kind, mr.upstream_status_code,
exists (
select 1 from (values
(saved_error.body -> 'code'),
(saved_error.body -> 'type'),
(saved_error.body -> 'message')
) as field(value)
where jsonb_typeof(field.value) = 'string' and field.value <> '\"\"'::jsonb
) as has_upstream_error,
case when saved_upstream.body ->> 'type' = 'websocket.close'
and jsonb_typeof(saved_upstream.body -> 'code') = 'number'
then saved_upstream.body ->> 'code'
end as websocket_close_code,
facts.has_upstream_error, facts.websocket_close_code,
mr.continuation_unavailable_reason, mr.upstream_connection_exit_reason,
(mr.recovery_request_id is not null and mr.recovered_at is not null) as recovered,
mr.provider_kind, mr.provider_account_ref,
@@ -164,17 +153,36 @@ pub(crate) const USAGE_LIST_RECORD_SELECT: &str =
mr.reasoning_effort, mr.reasoning_preset, mr.subagent_kind, mr.compact,
mr.started_at
from model_request_observations mr
cross join lateral (
cross join lateral ";
// 列表与筛选共用已保存上游事实的解码,兼容早期的空值和非 JSON 错误详情
const SAVED_ERROR_FACTS: &str = "(select exists (
select 1 from (values
(saved_error.body -> 'code'),
(saved_error.body -> 'type'),
(saved_error.body -> 'message')
) as field(value)
where jsonb_typeof(field.value) = 'string' and field.value <> '\"\"'::jsonb
) as has_upstream_error,
case when saved_upstream.body ->> 'type' = 'websocket.close'
and jsonb_typeof(saved_upstream.body -> 'code') = 'number'
and (saved_upstream.body ->> 'code') ~ '^[0-9]{1,5}$'
and (saved_upstream.body -> 'code') <= '65535'::jsonb
then saved_upstream.body ->> 'code'
end as websocket_close_code
from lateral (
select case when pg_input_is_valid(mr.error_details, 'jsonb') then
case when jsonb_typeof(mr.error_details::jsonb -> 'upstream') = 'string'
and pg_input_is_valid(mr.error_details::jsonb ->> 'upstream', 'jsonb')
then (mr.error_details::jsonb ->> 'upstream')::jsonb
end
end as body
-- 保留子查询边界,让错误字段和关闭码复用同一行已解码的上游正文
offset 0
) saved_upstream
cross join lateral (
select coalesce(saved_upstream.body -> 'error', saved_upstream.body #> '{response,error}') as body
) saved_error";
) saved_error) facts";
pub(crate) const USAGE_RECORD_DETAIL_SELECT: &str =
"select mr.id, mr.client_api_key_ref, mr.config_revision,
@@ -261,7 +269,7 @@ async fn projected_usage_counts(
query: &UsageRecordQuery,
) -> StoreResult<Option<BTreeMap<DateTime<Utc>, u64>>> {
use admin_observability::UsageRecordStatus;
if query.status == UsageRecordStatus::Error {
if matches!(query.status, UsageRecordStatus::Error(_)) {
return Ok(None);
}
let Some(mut counts) = snapshot
@@ -351,7 +359,9 @@ async fn list_usage_record_items_at<'e, E: sqlx::Executor<'e, Database = Postgre
statement.push(" offset ");
statement.push_bind(offset);
statement.push(") ");
statement.push(USAGE_LIST_RECORD_SELECT);
statement
.push(USAGE_LIST_RECORD_SELECT)
.push(SAVED_ERROR_FACTS);
statement.push(
" join candidate_page page on page.id = mr.id order by page.started_at desc, page.id desc",
);
@@ -504,7 +514,7 @@ fn usage_counts_query(
},
);
}
if branch > 0 || status == UsageRecordStatus::Error {
if branch > 0 || matches!(status, UsageRecordStatus::Error(_)) {
push_non_success_count_filter(&mut statement, filter);
} else {
push_usage_filter(&mut statement, filter, "mr");
@@ -744,8 +754,11 @@ fn push_usage_record_status(
use admin_observability::UsageRecordStatus;
match status {
UsageRecordStatus::Success => push_completed_usage_fact_filter(statement, "mr"),
UsageRecordStatus::Error => {
UsageRecordStatus::Error(origin) => {
statement.push(" and mr.outcome in ('failed', 'incomplete')");
if let Some(origin) = origin {
push_usage_error_origin(statement, origin);
}
}
UsageRecordStatus::All => {
// 成功沿用用量边界,未成功记录保留真实生命周期,不把取消与执行中标为错误
@@ -756,3 +769,52 @@ fn push_usage_record_status(
}
}
}
fn push_usage_error_origin(
statement: &mut QueryBuilder<Postgres>,
origin: admin_observability::UsageErrorOrigin,
) {
use admin_observability::{UsageErrorEvidence::*, UsageErrorOrigin};
statement.push(" and case");
for &(evidence, result) in UsageErrorOrigin::RULES {
statement.push(" when ");
match evidence {
ProviderErrorCode => {
statement.push("mr.provider_error_code <> ''");
}
UpstreamStatusAtLeast(min) => {
statement
.push("mr.upstream_status_code >= ")
.push_bind(i32::from(min));
}
SavedUpstreamErrorOrClose => {
statement.push("mr.error_details is not null and (select facts.has_upstream_error or facts.websocket_close_code is not null from lateral ")
.push(SAVED_ERROR_FACTS).push(")");
}
ErrorKind(values) => {
statement
.push("mr.error_kind = any(")
.push_bind(values)
.push(")");
}
Continuation(values) => {
statement
.push("mr.continuation_unavailable_reason = any(")
.push_bind(values)
.push(")");
}
ConnectionExit(values) => {
statement
.push("mr.upstream_connection_exit_reason = any(")
.push_bind(values)
.push(")");
}
}
statement.push(" then ").push_bind(result.as_str());
}
statement
.push(" else ")
.push_bind(UsageErrorOrigin::Unknown.as_str())
.push(" end = ")
.push_bind(origin.as_str());
}
@@ -406,7 +406,7 @@ async fn health_counters_match_for_rollups_and_facts_without_counting_recovery_o
sqlx::query("update model_requests set recovered_at=completed_at,recovery_request_id='health_success',recovery_attempt_count=1,request_observation_json=request_observation_json||jsonb_build_object('recovery',jsonb_build_object('retryDelayMs',0,'totalLatencyMs',1)) where id='health_recovered'")
.execute(&database.pool).await.unwrap();
drain_analytics(&database.pool).await;
// 模拟旧桶曾把取消的 499 计入调用方错误,无需重建也应得到相同结果
// 即使已存储的桶把 499 计入调用方错误,查询也应将其归为取消
sqlx::raw_sql("update request_analytics_15m set counts=jsonb_set(counts,'{caller_error_count}','1') where outcome='cancelled'; update request_analytics_1h set counts=jsonb_set(counts,'{caller_error_count}','1') where outcome='cancelled'")
.execute(&database.pool).await.unwrap();
let repo = observability_repository(&database.pool);
@@ -930,7 +930,7 @@ async fn interrupted_quarters_restart_changed_versions_and_publish_one_consisten
.execute(&database.pool)
.await
.unwrap();
// 独立重建请求改变版本,验证旧前缀废弃后仍可恢复,普通源变更不再重启整桶
// 显式重建会更换版本,Worker 需要丢弃已处理的前缀并恢复构建
sqlx::query("update request_analytics_pending_buckets set change_version=nextval('request_analytics_change_version')")
.execute(&database.pool).await.unwrap();
drop(worker);
@@ -1034,7 +1034,7 @@ async fn backfill_coverage_uses_contiguous_cursor_instead_of_old_corrected_facts
] {
seed(&database.pool, id, now - TimeDelta::hours(age), &[]).await;
}
// 模拟迁移后历史队列为空,随后最旧请求发生单点修正
// 清空待处理队列后只修正最早的请求,验证中间的时间段仍需回填
sqlx::query("delete from request_analytics_pending_requests")
.execute(&database.pool)
.await
@@ -175,7 +175,7 @@ async fn usage_error_origins_agree_for_saved_errors_without_failure_status() {
.list_usage_records(UsageRecordQuery {
range,
filter: UsageRecordFilter::default(),
status: admin_observability::UsageRecordStatus::All,
status: admin_observability::UsageRecordStatus::Error(Some(origin)),
current_page: 1,
page_size: ObservabilityPageSize::new(10).unwrap(),
})
@@ -282,7 +282,7 @@ async fn usage_error_origins_preserve_saved_failure_and_connection_boundaries()
.list_usage_records(UsageRecordQuery {
range,
filter: UsageRecordFilter::default(),
status: admin_observability::UsageRecordStatus::All,
status: admin_observability::UsageRecordStatus::Error(Some(origin)),
current_page: 1,
page_size: ObservabilityPageSize::new(10).unwrap(),
})
@@ -993,10 +993,10 @@ async fn usage_account_filter_matches_only_historical_names_and_emails() {
let repo = observability_repository(&database.pool);
for (status, search, page, total, expected_id) in [
(Success, r"_%\", 1, 1, Some("req_observe_success")),
(Error, "team", 1, 1, Some("req_observe_failed")),
(Error(None), "team", 1, 1, Some("req_observe_failed")),
(All, "alice", 1, 2, Some("req_observe_failed")),
(All, "alice", 2, 2, Some("req_observe_success")),
(Error, "@example", 1, 0, None),
(Error(None), "@example", 1, 0, None),
(All, "ALICE", 1, 0, None),
(All, "alice%ops", 1, 0, None),
(All, "public-model", 1, 0, None),
@@ -460,7 +460,7 @@ async fn all_status_counts_keep_filters_delivery_rules_and_time_boundaries() {
vec![],
),
] {
for status in [UsageRecordStatus::All, UsageRecordStatus::Error] {
for status in [UsageRecordStatus::All, UsageRecordStatus::Error(None)] {
let expected = expected
.iter()
.copied()
@@ -584,7 +584,7 @@ async fn request_status_pages_share_one_request_timeline() {
.unwrap();
for (status, expected) in [
(UsageRecordStatus::Success, vec!["status_f", "status_a"]),
(UsageRecordStatus::Error, vec!["status_c", "status_b"]),
(UsageRecordStatus::Error(None), vec!["status_c", "status_b"]),
(
UsageRecordStatus::All,
vec![
@@ -619,7 +619,7 @@ async fn request_status_pages_share_one_request_timeline() {
}
let page = repo
.list_usage_records(UsageRecordQuery {
status: UsageRecordStatus::Error,
status: UsageRecordStatus::Error(None),
range,
filter: UsageRecordFilter {
search: Some("model_status_b".into()),
@@ -647,3 +647,123 @@ async fn request_status_pages_share_one_request_timeline() {
assert_eq!(errors.len(), 2);
database.close().await;
}
#[tokio::test]
async fn error_origin_filters_matching_requests_before_counting_and_paging() {
use gateway_admin::model::observability::{UsageErrorOrigin::*, UsageRecordStatus};
let Some(database) = TestDatabase::create("usage_error_origin_pages").await else {
return;
};
let start = Utc::now();
let repository = observability_repository(&database.pool);
let range = ObservabilityRange::new(start, start + TimeDelta::hours(1)).unwrap();
let saved =
|body: serde_json::Value| serde_json::json!({"upstream": body.to_string()}).to_string();
for (minute, (id, outcome, kind, status, details, model)) in [
("edge_0", "failed", "internal_error", None, None, "main"),
(
"edge_1",
"failed",
"internal_error",
Some(503_i32),
None,
"main",
),
("edge_2", "incomplete", "transport", Some(200), None, "main"),
(
"edge_3",
"incomplete",
"invalid_request",
None,
Some("old plain text".into()),
"main",
),
(
"edge_4",
"failed",
"internal_error",
None,
Some(saved(
serde_json::json!({"response":{"error":{"message":"sample"}}}),
)),
"main",
),
(
"edge_5",
"failed",
"internal_error",
None,
Some(saved(
serde_json::json!({"type":"websocket.close","code":1012}),
)),
"other",
),
(
"edge_6",
"failed",
"internal_error",
None,
Some(saved(
serde_json::json!({"type":"websocket.close","code":65536}),
)),
"main",
),
("edge_7", "cancelled", "internal_error", None, None, "main"),
("edge_8", "succeeded", "internal_error", None, None, "main"),
]
.into_iter()
.enumerate()
{
seed(
&database.pool,
id,
start + TimeDelta::minutes(minute as i64),
&[],
)
.await;
sqlx::query("update model_requests set outcome=$2, error_kind=$3, upstream_status_code=$4, error_details=$5, requested_model_id=$6 where id=$1")
.bind(id).bind(outcome).bind(kind).bind(status).bind(details).bind(model)
.execute(&database.pool).await.unwrap();
}
for (origin, model, ids) in [
(Proxy, None, vec!["edge_6", "edge_0"]),
(Upstream, None, vec!["edge_5", "edge_4", "edge_1"]),
(Connection, None, vec!["edge_2"]),
(Unknown, None, vec!["edge_3"]),
(Upstream, Some("main"), vec!["edge_4", "edge_1"]),
(Proxy, Some("other"), vec![]),
] {
for current_page in 1..=ids.len() + 1 {
let page = repository
.list_usage_records(UsageRecordQuery {
range,
status: UsageRecordStatus::Error(Some(origin)),
filter: UsageRecordFilter {
model_contains: model.map(str::to_owned),
..Default::default()
},
current_page: current_page as u32,
page_size: ObservabilityPageSize::new(1).unwrap(),
})
.await
.unwrap();
assert_eq!(page.total, ids.len() as u64, "{origin:?} / {model:?}");
let items: Vec<_> = page
.items
.iter()
.map(|item| (item.id.as_str(), item.error_origin()))
.collect();
let expected: Vec<_> = ids
.get(current_page - 1)
.map(|id| (*id, origin))
.into_iter()
.collect();
assert_eq!(
items, expected,
"{origin:?} / {model:?} / page {current_page}"
);
}
}
database.close().await;
}
+15 -7
View File
@@ -8,7 +8,9 @@ use url::Url;
use crate::credential::CodexQuotaRefreshPolicy;
use crate::transport::session::{CodexSessionIdentity, CodexSessionIdentityError};
use crate::transport::websocket::CodexWebSocketPoolConfig;
use crate::transport::websocket::{
CodexWebSocketPoolConfig, DEFAULT_FAST_PATH_BUDGET_MS, WEBSOCKET_CONNECT_TIMEOUT,
};
use crate::{
OFFICIAL_CODEX_BASE_URL,
credential::token_client::{
@@ -165,26 +167,24 @@ impl CodexApiConfig {
/// Codex Responses WebSocket pool 的 Provider-owned 启动设置
#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
#[serde(default)]
pub struct CodexWebSocketPoolSettings {
pub enabled: bool,
pub max_age_ms: u64,
pub max_connecting: usize,
#[serde(default = "default_websocket_pool_idle_timeout_ms")]
pub fast_path_budget_ms: u64,
pub idle_timeout_ms: u64,
pub stream_idle_timeout_ms: u64,
}
const fn default_websocket_pool_idle_timeout_ms() -> u64 {
300_000
}
impl Default for CodexWebSocketPoolSettings {
fn default() -> Self {
Self {
enabled: true,
max_age_ms: 55 * 60 * 1000,
max_connecting: 8,
idle_timeout_ms: default_websocket_pool_idle_timeout_ms(),
fast_path_budget_ms: DEFAULT_FAST_PATH_BUDGET_MS,
idle_timeout_ms: 300_000,
stream_idle_timeout_ms: 300_000,
}
}
@@ -192,6 +192,13 @@ impl Default for CodexWebSocketPoolSettings {
impl CodexWebSocketPoolSettings {
fn validate(&self) -> Result<(), OpenAiConfigError> {
if self.fast_path_budget_ms == 0
|| Duration::from_millis(self.fast_path_budget_ms) > WEBSOCKET_CONNECT_TIMEOUT
{
return Err(OpenAiConfigError::InvalidField(
"openai.ws_pool.fast_path_budget_ms",
));
}
if self.max_age_ms == 0 || self.max_connecting == 0 || self.idle_timeout_ms == 0 {
return Err(OpenAiConfigError::InvalidField("openai.ws_pool"));
}
@@ -203,6 +210,7 @@ impl CodexWebSocketPoolSettings {
enabled: self.enabled,
max_age: Duration::from_millis(self.max_age_ms),
max_connecting: self.max_connecting,
fast_path_budget: Duration::from_millis(self.fast_path_budget_ms),
idle_timeout: Duration::from_millis(self.idle_timeout_ms),
stream_idle_timeout: (self.stream_idle_timeout_ms != 0)
.then(|| Duration::from_millis(self.stream_idle_timeout_ms)),
@@ -1,6 +1,6 @@
//! AttemptContext 驱动的 Codex 账号选择与 Redis lease port
use std::collections::HashMap;
use std::collections::{BTreeSet, HashMap};
use std::fmt;
use std::sync::{Arc, Mutex};
use std::time::{Duration, SystemTime};
@@ -10,11 +10,11 @@ use gateway_core::account::CredentialRevision;
use gateway_core::error::ErrorSource;
use gateway_core::account::{
AccountAffinity, AccountCandidate, AccountCapacitySnapshot, AccountErrorReason,
AccountFeedbackStats, AccountModelAccessMode, AccountQuotaSignals, AccountRuntimeSignals,
AccountSchedulingBlocker, AccountSelectionContext, AccountSelectionPolicy, AccountSelector,
AccountStatus, CredentialState, PreferredAccountSelection, ProviderAccount, ProviderAccountId,
QuotaEvidence, RotationStrategy,
AccountAffinity, AccountCandidate, AccountCapacitySnapshot, AccountCooldown,
AccountCooldownKind, AccountErrorReason, AccountFeedbackStats, AccountModelAccessMode,
AccountQuotaSignals, AccountRuntimeSignals, AccountSchedulingBlocker, AccountSelectionContext,
AccountSelectionPolicy, AccountSelector, AccountStatus, CredentialState,
PreferredAccountSelection, ProviderAccount, ProviderAccountId, QuotaEvidence, RotationStrategy,
};
use gateway_core::concurrency::{
CapacityWait, ConcurrencyQueuePolicy, ConcurrencyWaitQueue, QueueRejection, WaitPriority,
@@ -30,7 +30,7 @@ use gateway_core::provider_ports::{
ProviderSessionAffinityPort, ProviderSessionBinding, ProviderSessionClaim,
ProviderSessionExclusionPort, ProviderSessionExclusions, ProviderStoreError,
};
use gateway_core::routing::ProviderKind;
use gateway_core::routing::{ProviderKind, UpstreamModelId};
use secrecy::ExposeSecret;
use thiserror::Error;
use url::Url;
@@ -185,48 +185,63 @@ impl AffinityEscapeReason {
}
#[derive(Debug, Default)]
struct AffinitySelection {
bound_account: Option<ProviderAccountId>,
preferred_account: Option<ProviderAccountId>,
escape_reason: Option<AffinityEscapeReason>,
enum AffinitySelection<'a> {
#[default]
Unbound,
Preferred(&'a ProviderAccountId),
Escaped(&'a ProviderAccountId, AffinityEscapeReason),
}
impl AffinitySelection {
fn preferred(account_id: ProviderAccountId) -> Self {
Self {
bound_account: Some(account_id.clone()),
preferred_account: Some(account_id),
escape_reason: None,
impl<'a> AffinitySelection<'a> {
fn for_binding(
account: &'a ProviderAccountId,
candidates: &[AccountCandidate],
now: SystemTime,
) -> Self {
let status = candidates
.iter()
.find(|candidate| candidate.account.id() == account)
.map(|candidate| {
candidate
.account
.status_projection(now, candidate.signals.cooldown)
.status
});
match status {
Some(AccountStatus::Normal) => Self::Preferred(account),
Some(AccountStatus::QuotaExhausted) => {
Self::Escaped(account, AffinityEscapeReason::QuotaExhausted)
}
Some(AccountStatus::RateLimited | AccountStatus::QuotaPaused) => {
Self::Escaped(account, AffinityEscapeReason::Cooldown)
}
Some(AccountStatus::Disabled | AccountStatus::Error) | None => {
Self::Escaped(account, AffinityEscapeReason::HardUnavailable)
}
}
}
fn escaped(account_id: ProviderAccountId, reason: AffinityEscapeReason) -> Self {
Self {
bound_account: Some(account_id),
preferred_account: None,
escape_reason: Some(reason),
fn bound_account(&self) -> Option<&'a ProviderAccountId> {
match self {
Self::Preferred(account) | Self::Escaped(account, _) => Some(account),
Self::Unbound => None,
}
}
fn bound_account(&self) -> Option<&ProviderAccountId> {
self.bound_account.as_ref()
}
fn preferred_account(&self) -> Option<&ProviderAccountId> {
self.preferred_account.as_ref()
fn preferred_account(&self) -> Option<&'a ProviderAccountId> {
match self {
Self::Preferred(account) => Some(account),
_ => None,
}
}
fn escape(&mut self, reason: AffinityEscapeReason) {
if self.bound_account.is_some() && self.escape_reason.is_none() {
self.escape_reason = Some(reason);
self.preferred_account = None;
if let Self::Preferred(account) = self {
*self = Self::Escaped(account, reason);
}
}
fn observe_preferred_selection(&mut self, selection: PreferredAccountSelection) {
if self.bound_account.is_none() || self.escape_reason.is_some() {
return;
}
match selection {
PreferredAccountSelection::Hit => {}
PreferredAccountSelection::OverriddenByPolicy => {
@@ -253,7 +268,7 @@ impl AffinitySelection {
}
fn observe_lease_busy(&mut self, account_id: &ProviderAccountId) {
if self.bound_account.as_ref() == Some(account_id) {
if self.preferred_account() == Some(account_id) {
self.escape(AffinityEscapeReason::LeaseSaturated);
}
}
@@ -264,14 +279,15 @@ impl AffinitySelection {
cache_preference: bool,
) -> AffinityTelemetry {
AffinityTelemetry {
affinity_hit: self.bound_account.as_ref() == Some(selected_account)
&& self.escape_reason.is_none(),
escape_reason: self.escape_reason,
// 仅因缓存偏好而分流时,客户端的轮次状态仍没有已知归属。
affinity_hit: self.preferred_account() == Some(selected_account),
escape_reason: match self {
Self::Escaped(_, reason) => Some(*reason),
_ => None,
},
// 仅因缓存偏好而分流时,客户端的轮次状态仍没有已知归属
account_switch: !cache_preference
&& self
.bound_account
.as_ref()
.bound_account()
.is_some_and(|bound| bound != selected_account),
}
}
@@ -556,6 +572,123 @@ impl CodexCredentialSelector {
})
}
async fn load_candidate_accounts(
&self,
attempt: &AttemptContext,
model: CodexSelectionModel<'_>,
adapter_model: Option<&UpstreamModelId>,
only_account: Option<&ProviderAccountId>,
) -> Result<Vec<ProviderAccount>, CredentialSelectionError> {
let diagnostic = attempt.account_eligibility().bypasses_local_eligibility();
// 固定归属或已有完整投影时只重查目标账号,诊断允许读取停用账号
if let Some(id) = only_account {
let account = self
.repository
.store()
.get_account(id)
.await
.map_err(|source| CredentialSelectionError::Store(ErrorSource::new(source)))?;
return Ok(account
.filter(|account| diagnostic || account.enabled())
.into_iter()
.collect());
}
if diagnostic {
return Ok(self.repository.list_for_provider().await?);
}
let account_ids: Vec<_> = attempt
.account_scope()
.into_iter()
.flat_map(|scope| scope.allowed_account_ids().cloned())
.collect();
let omissions = match (model, attempt.account_scope()) {
(CodexSelectionModel::Requested(model), Some(scope)) => {
self.catalog.omissions(model, &account_ids, |id| {
scope.directory().account(id).is_some_and(|account| {
account.model_access().mode() == AccountModelAccessMode::Allowlist
}) || adapter_model.is_some_and(|model| {
!matches!(
attempt.upstream_adapter_for_account(&self.provider_kind, model, id),
Ok(None)
)
})
})
}
_ => None,
};
let Some(filter) = omissions else {
return Ok(self.repository.list_for_accounts(&account_ids).await?);
};
let candidates = self
.repository
.store()
.list_catalog_candidates(&self.provider_kind, &account_ids, &filter)
.await
.map_err(CredentialRepositoryError::from)?;
if attempt.trace().is_enabled() {
attempt.trace().record(
"account.catalog_candidates",
serde_json::json!({
"scopedCount": account_ids.len(),
"candidateCount": candidates.len(),
}),
);
}
Ok(candidates)
}
async fn load_candidate_cooldowns(
&self,
accounts: &[ProviderAccount],
account_ids: &[ProviderAccountId],
native_accounts: &BTreeSet<ProviderAccountId>,
model: CodexSelectionModel<'_>,
) -> HashMap<ProviderAccountId, AccountCooldown> {
let native = accounts
.iter()
.filter(|account| native_accounts.contains(account.id()));
let model_cooldowns = async {
let CodexSelectionModel::Requested(model) = model else {
return Vec::new();
};
let Ok(model) = UpstreamModelId::new(model) else {
return Vec::new();
};
let ids: Vec<_> = native.clone().map(|account| account.id().clone()).collect();
self.cooldowns
.read_scoped_many(&ids, &ProviderCooldownScope::upstream_model(model))
.await
};
let (account_cooldowns, model_cooldowns) =
futures::join!(self.cooldowns.read_many(account_ids), model_cooldowns);
let mut active: HashMap<_, _> = account_ids
.iter()
.zip(account_cooldowns)
.filter_map(|(id, cooldown)| {
let state = cooldown.ok().flatten()?.scheduling_state();
state
.is_active(SystemTime::now())
.then(|| (id.clone(), state))
})
.collect();
for (account, cooldown) in native.zip(model_cooldowns) {
if let Some(cooldown) = cooldown.ok().flatten().filter(|cooldown| {
cooldown.credential_revision() == account.revision()
&& cooldown.until() > SystemTime::now()
}) {
// 两种冷却取较晚期限,保留账号级冷却的恢复探测语义
active
.entry(account.id().clone())
.and_modify(|state| state.until = state.until.max(cooldown.until()))
.or_insert(AccountCooldown {
until: cooldown.until(),
kind: AccountCooldownKind::RateLimit,
});
}
}
active
}
async fn select_inner_loop(
&self,
request: &CredentialSelectionInput<'_>,
@@ -567,7 +700,7 @@ impl CodexCredentialSelector {
) -> Result<CodexCredentialLease, CredentialSelectionError> {
let adapter_model = match model {
CodexSelectionModel::Requested(model) if request.managed_upstream => Some(
gateway_core::routing::UpstreamModelId::new(model)
UpstreamModelId::new(model)
.map_err(|_| CredentialSelectionError::NoEligibleCredential)?,
),
_ => None,
@@ -730,64 +863,18 @@ impl CodexCredentialSelector {
.as_ref()
.and_then(|_| binding.as_ref().map(ProviderSessionBinding::account_id));
let projection_started = std::time::Instant::now();
// 固定归属或已有完整投影的会话只查询目标账号,随后实时复核其资格和租约
// 常规调度排除停用账号,管理端诊断允许验证其真实上游状态
let accounts = if let Some(pinned) = pinned_account
let only_account = pinned_account
.as_ref()
.or(queued_account.as_ref())
.or(projected_account)
{
self.repository
.store()
.get_account(pinned)
.await
.map_err(|source| CredentialSelectionError::Store(ErrorSource::new(source)))?
.filter(|account| diagnostic || account.enabled())
.into_iter()
.collect()
} else if diagnostic {
self.repository.list_for_provider().await?
} else {
let account_ids = request
.attempt
.account_scope()
.into_iter()
.flat_map(|scope| scope.allowed_account_ids().cloned())
.collect::<Vec<_>>();
let omissions = match (model, request.attempt.account_scope()) {
(CodexSelectionModel::Requested(model), Some(scope)) => {
self.catalog.omissions(model, &account_ids, |id| {
scope.directory().account(id).is_some_and(|a| {
a.model_access().mode() == AccountModelAccessMode::Allowlist
}) || adapter_model.as_ref().is_some_and(|m| {
!matches!(
request.attempt.upstream_adapter_for_account(
&self.provider_kind,
m,
id
),
Ok(None)
)
})
})
}
_ => None,
};
if let Some(filter) = omissions {
let candidates = self
.repository
.store()
.list_catalog_candidates(&self.provider_kind, &account_ids, &filter)
.await
.map_err(CredentialRepositoryError::from)?;
if request.attempt.trace().is_enabled() {
request.attempt.trace().record("account.catalog_candidates",serde_json::json!({"scopedCount":account_ids.len(),"candidateCount":candidates.len()}));
}
candidates
} else {
self.repository.list_for_accounts(&account_ids).await?
}
};
.or(projected_account);
let accounts = self
.load_candidate_accounts(
request.attempt,
model,
adapter_model.as_ref(),
only_account,
)
.await?;
let mut model_access_rejected = 0_usize;
let accounts = accounts
.into_iter()
@@ -822,7 +909,7 @@ impl CodexCredentialSelector {
_ => None,
};
let mut catalog_rejected = 0_usize;
let mut native_accounts = std::collections::BTreeSet::new();
let mut native_accounts = BTreeSet::new();
for account in accounts {
let adapter = if let Some(model) = adapter_model.as_ref() {
match request.attempt.upstream_adapter_for_account(
@@ -943,65 +1030,12 @@ impl CodexCredentialSelector {
.iter()
.map(|account| account.id().clone())
.collect::<Vec<_>>();
let mut rate_limits = HashMap::with_capacity(accounts.len());
let model_scope = match model {
CodexSelectionModel::Requested(model) => {
gateway_core::routing::UpstreamModelId::new(model)
.ok()
.map(ProviderCooldownScope::upstream_model)
}
_ => None,
let rate_limits = if diagnostic {
HashMap::new()
} else {
self.load_candidate_cooldowns(&accounts, &account_ids, &native_accounts, model)
.await
};
if !diagnostic {
let model_account_ids = account_ids
.iter()
.filter(|id| native_accounts.contains(*id))
.cloned()
.collect::<Vec<_>>();
let model_cooldowns = async {
match model_scope.as_ref() {
Some(scope) => {
self.cooldowns
.read_scoped_many(&model_account_ids, scope)
.await
}
None => Vec::new(),
}
};
let (account_cooldowns, model_cooldowns) =
futures::join!(self.cooldowns.read_many(&account_ids), model_cooldowns,);
// 存储端有界批量读取,单项失败沿用未知冷却;待探测冻结由端口事实判断
for (id, cooldown) in account_ids.iter().zip(account_cooldowns) {
let state = cooldown
.ok()
.flatten()
.map(|value| value.scheduling_state());
rate_limits.insert(
id.clone(),
state.filter(|state| state.is_active(SystemTime::now())),
);
}
for (account, cooldown) in accounts
.iter()
.filter(|account| native_accounts.contains(account.id()))
.zip(model_cooldowns)
{
if let Some(cooldown) = cooldown.ok().flatten().filter(|cooldown| {
cooldown.credential_revision() == account.revision()
&& cooldown.until() > SystemTime::now()
}) {
// 两种冷却取较晚期限,账号保护保留其恢复探测语义
let until = rate_limits
.entry(account.id().clone())
.or_default()
.get_or_insert(gateway_core::account::AccountCooldown {
until: cooldown.until(),
kind: gateway_core::account::AccountCooldownKind::RateLimit,
});
until.until = until.until.max(cooldown.until());
}
}
}
let policy = request.attempt.account_selection_policy();
let client_key = request.attempt.client_api_key_ref();
let use_assignment_cursor = policy.strategy() == RotationStrategy::RoundRobin
@@ -1068,7 +1102,7 @@ impl CodexCredentialSelector {
first_output_latency_ms: None,
})
.with_provider_quota(quota)
.with_rate_limit(rate_limits.get(account.id()).copied().flatten())
.with_rate_limit(rate_limits.get(account.id()).copied())
.with_runtime_health(health.0, health.1);
AccountCandidate {
account,
@@ -1107,8 +1141,8 @@ impl CodexCredentialSelector {
.as_ref()
.filter(|_| affinity_mode != AccountAffinity::Relaxed)
.map_or_else(AffinitySelection::default, |binding| {
affinity_selection_for_bound_account(
binding.account_id().clone(),
AffinitySelection::for_binding(
binding.account_id(),
&candidates,
SystemTime::now(),
)
@@ -1410,17 +1444,13 @@ impl CodexCredentialSelector {
};
affinity.observe_preferred_selection(selection.preferred());
let selected = selection.candidate();
let account = candidates
.iter()
.find(|candidate| candidate.account.id() == selected.account.id())
.map(|candidate| candidate.account.clone())
.ok_or(CredentialSelectionError::InvalidCredential(None))?;
let account = &selected.account;
// 凭据、状态或额度结论的并发更新会使账号快照失效,必须重新选号并校验资格;
// 仅额度观测时刻前进时沿用最新快照
// 在占用租约前完成校验,避免重读被自己的异步释放挡住
let (account, runtime) = match self
.repository
.reload_selected_credential(&account)
.reload_selected_credential(account)
.await
{
Ok(reloaded) => reloaded,
@@ -1429,7 +1459,7 @@ impl CodexCredentialSelector {
self.scheduling_projection.invalidate(key);
}
refresh_candidates = true;
retry_account_snapshot(request.attempt, &account, &mut snapshot_retries)?;
retry_account_snapshot(request.attempt, account, &mut snapshot_retries)?;
continue 'capacity;
}
Err(error) => return Err(error.into()),
@@ -1445,7 +1475,7 @@ impl CodexCredentialSelector {
}
let allows_account_state_mutation =
eligibility.allows_account_state_mutation(account.enabled());
match self
let guard = match self
.leases
.try_acquire(ProviderLeaseRequest::Scheduling(
ProviderSchedulingLeaseRequest::new(
@@ -1474,167 +1504,117 @@ impl CodexCredentialSelector {
}
shortest_retry = minimum_duration(shortest_retry, retry_after);
busy_accounts.insert(account.id().clone());
continue;
}
ProviderLeaseAcquisition::Acquired(guard) => {
let mut binding_account = account.id();
if affinity_mode == AccountAffinity::Preferred
&& let Some(primary) = binding.as_ref()
&& (primary.account_id() == account.id()
|| pinned_account.is_some()
|| !self
.preferred_primary_needs_migration(
primary,
queue_policy.timeout,
)
.await?)
{
binding_account = primary.account_id();
}
let claim = binding_key.map(|key| ProviderSessionClaim {
key,
expected: binding.as_ref(),
account: binding_account,
ttl: policy.openai_session_affinity_ttl(),
});
// 插件委托与普通内置选号共享轮询,显式选择、亲和命中及等待不消耗位置
let admission = match assignment_cursor {
Some(cursor)
if !selection.is_policy_choice()
&& selection.preferred() != PreferredAccountSelection::Hit =>
{
Some(ProviderAccountAdmission::RoundRobin {
client_key,
cursor,
session: claim,
})
}
_ => claim.map(ProviderAccountAdmission::Session),
};
if let Some(admission) = admission {
let admitted = match self.admit_account(admission).await {
Ok(false) => false,
Err(error)
if cache_preference
&& affinity_mode == AccountAffinity::Preferred
&& admission.session().is_some() =>
{
tracing::warn!(%error, "OpenAI cache preference update unavailable");
// 缓存偏好允许丢失,实际的轮询分配仍须占用该位置
match admission {
ProviderAccountAdmission::RoundRobin {
client_key,
cursor,
..
} => {
self.admit_account(
ProviderAccountAdmission::RoundRobin {
client_key,
cursor,
session: None,
},
)
.await?
}
ProviderAccountAdmission::Session(_) => true,
}
}
Err(error) => return Err(error),
Ok(true) => {
if let Some(reason) = queue_rejection
&& let Some(previous) = binding.as_ref().filter(|binding| {
binding.account_id() != binding_account
})
{
tracing::info!(
request_id = %request.attempt.request_id(),
attempt_index = request.attempt.attempt_index().get(),
reason = %reason,
from_account_id = %previous.account_id(),
to_account_id = %binding_account,
"OpenAI 账号排队失败后已迁移绑定"
);
request.attempt.trace().record_evidence(
"account.binding.migrated",
serde_json::json!({
"reason": reason.to_string(),
"fromAccountId": previous.account_id().as_str(),
"toAccountId": binding_account.as_str(),
}),
);
}
true
}
};
if !admitted {
guard.release().await?;
if request.attempt.deadline().is_elapsed() {
return Err(CredentialSelectionError::AccountSnapshotChanged);
}
continue 'capacity;
}
}
let affinity_telemetry = affinity.telemetry(account.id(), cache_preference);
let affinity_observation = request.session_affinity_observation;
tracing::info!(
request_id = %request.attempt.request_id(),
attempt_index = request.attempt.attempt_index().get(),
rotation_strategy = policy.strategy().as_str(),
account_id = %account.id(),
affinity_hit = affinity_telemetry.affinity_hit,
escape_reason = affinity_telemetry
.escape_reason
.map_or("", AffinityEscapeReason::as_str),
account_switch = affinity_telemetry.account_switch,
affinity_key_hash = affinity_observation
.map_or("", CodexSessionAffinity::key_hash),
affinity_anchor_source = affinity_observation
.map_or("", CodexSessionAffinity::anchor_source),
affinity_anchor = affinity_observation
.map_or("", CodexSessionAffinity::anchor),
session_id = affinity_observation
.and_then(CodexSessionAffinity::session_id)
.unwrap_or(""),
session_id_present = affinity_observation
.is_some_and(CodexSessionAffinity::session_id_present),
"OpenAI account selected"
);
let cookies = runtime
.cookies
.into_iter()
.filter(|cookie| {
cookie
.expires_at
.is_none_or(|expires| expires > chrono::Utc::now())
&& self.cookie_policy.may_replay(
request.request_url,
&cookie.domain,
&cookie.path,
cookie.host_only,
cookie.secure,
)
})
.collect();
if !waiting.elapsed().is_zero() {
request.attempt.trace().record(
"account.queue.acquired",
serde_json::json!({"waitMs": waiting.elapsed().as_millis() as u64}),
);
}
return Ok(CodexCredentialLease {
installation_id: runtime.installation_id,
transport: runtime.transport,
account,
authentication: runtime.authentication,
cookies,
cyber_policy_scope,
allows_account_state_mutation,
affinity_telemetry,
admitted_session: binding_key.filter(|_| !cache_preference).cloned(),
capacity: capacity.map(AccountCapacitySnapshot::with_acquired_request),
_guard: guard,
});
}
ProviderLeaseAcquisition::Acquired(guard) => guard,
};
let mut binding_account = account.id();
if affinity_mode == AccountAffinity::Preferred
&& let Some(primary) = binding.as_ref()
&& (primary.account_id() == account.id()
|| pinned_account.is_some()
|| !self
.preferred_primary_needs_migration(primary, queue_policy.timeout)
.await?)
{
binding_account = primary.account_id();
}
let claim = binding_key.map(|key| ProviderSessionClaim {
key,
expected: binding.as_ref(),
account: binding_account,
ttl: policy.openai_session_affinity_ttl(),
});
// 插件委托与普通内置选号共享轮询,显式选择、亲和命中及等待不消耗位置
let admission = match assignment_cursor {
Some(cursor)
if !selection.is_policy_choice()
&& selection.preferred() != PreferredAccountSelection::Hit =>
{
Some(ProviderAccountAdmission::RoundRobin {
client_key,
cursor,
session: claim,
})
}
_ => claim.map(ProviderAccountAdmission::Session),
};
if let Some(admission) = admission
&& !self
.admit_selected_account(
admission,
cache_preference && affinity_mode == AccountAffinity::Preferred,
request.attempt,
queue_rejection,
)
.await?
{
guard.release().await?;
if request.attempt.deadline().is_elapsed() {
return Err(CredentialSelectionError::AccountSnapshotChanged);
}
continue 'capacity;
}
let affinity_telemetry = affinity.telemetry(account.id(), cache_preference);
let affinity_observation = request.session_affinity_observation;
tracing::info!(
request_id = %request.attempt.request_id(),
attempt_index = request.attempt.attempt_index().get(),
rotation_strategy = policy.strategy().as_str(),
account_id = %account.id(),
affinity_hit = affinity_telemetry.affinity_hit,
escape_reason = affinity_telemetry
.escape_reason
.map_or("", AffinityEscapeReason::as_str),
account_switch = affinity_telemetry.account_switch,
affinity_key_hash = affinity_observation
.map_or("", CodexSessionAffinity::key_hash),
affinity_anchor_source = affinity_observation
.map_or("", CodexSessionAffinity::anchor_source),
affinity_anchor = affinity_observation
.map_or("", CodexSessionAffinity::anchor),
session_id = affinity_observation
.and_then(CodexSessionAffinity::session_id)
.unwrap_or(""),
session_id_present = affinity_observation
.is_some_and(CodexSessionAffinity::session_id_present),
"OpenAI account selected"
);
let cookies = runtime
.cookies
.into_iter()
.filter(|cookie| {
cookie
.expires_at
.is_none_or(|expires| expires > chrono::Utc::now())
&& self.cookie_policy.may_replay(
request.request_url,
&cookie.domain,
&cookie.path,
cookie.host_only,
cookie.secure,
)
})
.collect();
if !waiting.elapsed().is_zero() {
request.attempt.trace().record(
"account.queue.acquired",
serde_json::json!({"waitMs": waiting.elapsed().as_millis() as u64}),
);
}
return Ok(CodexCredentialLease {
installation_id: runtime.installation_id,
transport: runtime.transport,
account,
authentication: runtime.authentication,
cookies,
cyber_policy_scope,
allows_account_state_mutation,
affinity_telemetry,
admitted_session: binding_key.filter(|_| !cache_preference).cloned(),
capacity: capacity.map(AccountCapacitySnapshot::with_acquired_request),
_guard: guard,
});
}
}
}
@@ -1717,6 +1697,60 @@ impl CodexCredentialSelector {
.map_err(binding_store_error)
}
async fn admit_selected_account(
&self,
admission: ProviderAccountAdmission<'_>,
optional_cache_binding: bool,
attempt: &AttemptContext,
queue_rejection: Option<QueueRejection>,
) -> Result<bool, CredentialSelectionError> {
let claim = admission.session();
match self.admit_account(admission).await {
Ok(false) => return Ok(false),
Err(error) if optional_cache_binding && claim.is_some() => {
tracing::warn!(%error, "OpenAI cache preference update unavailable");
// 缓存偏好允许丢失,实际的轮询分配仍须占用该位置
return match admission {
ProviderAccountAdmission::RoundRobin {
client_key, cursor, ..
} => {
self.admit_account(ProviderAccountAdmission::RoundRobin {
client_key,
cursor,
session: None,
})
.await
}
ProviderAccountAdmission::Session(_) => Ok(true),
};
}
Err(error) => return Err(error),
Ok(true) => {}
}
if let (Some(reason), Some(claim)) = (queue_rejection, claim)
&& let Some(previous) = claim.expected
&& previous.account_id() != claim.account
{
tracing::info!(
request_id = %attempt.request_id(),
attempt_index = attempt.attempt_index().get(),
reason = %reason,
from_account_id = %previous.account_id(),
to_account_id = %claim.account,
"OpenAI 账号排队失败后已迁移绑定"
);
attempt.trace().record_evidence(
"account.binding.migrated",
serde_json::json!({
"reason": reason.to_string(),
"fromAccountId": previous.account_id().as_str(),
"toAccountId": claim.account.as_str(),
}),
);
}
Ok(true)
}
async fn admit_account(
&self,
admission: ProviderAccountAdmission<'_>,
@@ -2194,49 +2228,6 @@ fn binding_store_error(
)))
}
fn affinity_selection_for_bound_account(
account_id: ProviderAccountId,
candidates: &[AccountCandidate],
now: SystemTime,
) -> AffinitySelection {
let Some(candidate) = candidates
.iter()
.find(|candidate| candidate.account.id() == &account_id)
else {
return AffinitySelection::escaped(account_id, AffinityEscapeReason::HardUnavailable);
};
match candidate
.account
.status_projection(now, candidate.signals.cooldown)
.status
{
AccountStatus::Normal => AffinitySelection::preferred(account_id),
AccountStatus::QuotaPaused
| AccountStatus::QuotaExhausted
| AccountStatus::RateLimited
| AccountStatus::Disabled
| AccountStatus::Error => {
AffinitySelection::escaped(account_id, affinity_unavailable_reason(candidate, now))
}
}
}
fn affinity_unavailable_reason(
candidate: &AccountCandidate,
now: SystemTime,
) -> AffinityEscapeReason {
match candidate
.account
.status_projection(now, candidate.signals.cooldown)
.status
{
AccountStatus::QuotaExhausted => AffinityEscapeReason::QuotaExhausted,
AccountStatus::RateLimited | AccountStatus::QuotaPaused => AffinityEscapeReason::Cooldown,
AccountStatus::Normal => AffinityEscapeReason::SelectionInvariant,
AccountStatus::Disabled | AccountStatus::Error => AffinityEscapeReason::HardUnavailable,
}
}
fn active_risk_recovery<'a>(
recovery: &'a mut HashMap<String, RiskRecoveryState>,
account_id: &str,
@@ -1250,9 +1250,7 @@ pub(super) fn cold_response_stream(response: ColdResponse) -> EventStream {
yield event;
}
} else if atomic_upstream_failure {
failure.error = failure
.error
.with_atomic_client_events(events);
failure.error = with_atomic_failure_events(failure.error, events, &context);
}
Err(continuation_recovery_error(
failure.error,
@@ -135,6 +135,32 @@ fn is_replaceable_prelude(event: &ProviderEvent) -> bool {
})
}
/// WS 拒绝请求时也保留原始 error 对象,供原生 Responses 在 HTTP 首字节前交付
pub(super) fn with_atomic_failure_events(
mut error: ProviderError,
events: Vec<ProviderEvent>,
context: &AttemptContext,
) -> ProviderError {
if error.kind() == ProviderErrorKind::InvalidRequest
&& error.upstream_status() == Some(400)
&& error.retry_is_prohibited()
&& context.client_transport() == gateway_core::engine::execution::ClientTransport::HttpSse
&& context.endpoint() == gateway_protocol::openai::RESPONSES_PATH
&& let [event] = events.as_slice()
&& let Some(wire) = event.wire_event()
&& wire.raw_websocket_message().is_some()
&& wire.event_type() == Some("error")
&& let Some(detail) = wire.data().get("error").and_then(Value::as_object)
{
error = error.with_client_visible_upstream_response(ClientVisibleUpstreamResponse::new(
400,
Some(b"application/json".to_vec()),
Bytes::from(json!({ "error": detail }).to_string()),
));
}
error.with_atomic_client_events(events)
}
#[derive(Clone, Copy)]
pub(super) enum ReplayBoundary {
BeforeSemanticOutput,
@@ -1500,15 +1526,12 @@ pub(super) fn map_upstream_failure(
.status
.is_some_and(|status| status.is_client_error())
&& is_cyber_policy_code(failure.code.as_deref());
let continuation_failure = failure
.upstream_code()
.filter(|code| is_history_failure_code(code))
.map(|_| ContinuationFailure::HistoryUnavailable);
let continuation_summary = failure.upstream_code().and_then(history_failure_summary);
let send_state = upstream_send_state(failure.send_phase);
let error_kind = if continuation_failure.is_some() {
ProviderErrorKind::ContinuationRecoveryRequired
let (error_kind, summary) = if let Some(summary) = continuation_summary {
(ProviderErrorKind::ContinuationRecoveryRequired, summary)
} else {
provider_error_kind(category)
upstream_failure_summary(category, failure.upstream_code())
};
let mut error = provider_error(error_kind, send_state)
.with_upstream_failure_fields(failure.upstream_fields.clone());
@@ -1517,7 +1540,7 @@ pub(super) fn map_upstream_failure(
let upgrade_required = failure.send_phase == CodexUpstreamSendPhase::BeforePayload
&& failure.status == Some(reqwest::StatusCode::UPGRADE_REQUIRED);
if category == CodexFailureCategory::FlexUnavailable
|| (!replay_safe && continuation_failure.is_none() && !upgrade_required)
|| (!replay_safe && continuation_summary.is_none() && !upgrade_required)
{
error = error.with_retry_prohibited();
}
@@ -1552,9 +1575,9 @@ pub(super) fn map_upstream_failure(
if replay_boundary.permits_provider_proof() && replay_safe {
error = error.with_replay_safe();
}
if let Some(continuation_failure) = continuation_failure {
if continuation_summary.is_some() {
error = error
.with_continuation_failure(continuation_failure)
.with_continuation_failure(ContinuationFailure::HistoryUnavailable)
.with_continuation_recovery_disposition(
ContinuationRecoveryDisposition::ClientReplayRequired,
)
@@ -1595,16 +1618,13 @@ pub(super) fn map_upstream_failure(
if let Some(request_id) = failure.request_id.as_deref() {
error = error.with_upstream_request_id(OpaqueUpstreamValue::new(request_id.to_owned()));
}
let status = error
.upstream_status()
.map_or_else(|| "none".to_owned(), |status| status.to_string());
let kind = error.kind().as_str();
let summary = if cyber_policy_failure {
"请求被上游安全策略拦截"
} else {
summary
};
error = error.with_diagnostic(
ProviderDiagnostic::new(format!(
"OpenAI upstream failure: kind={}, status={status}",
kind
))
.with_classification("upstream", "upstream_rejected"),
ProviderDiagnostic::new(summary).with_classification("upstream", "upstream_rejected"),
);
MappedProviderFailure {
error,
@@ -1633,38 +1653,80 @@ pub(super) fn is_cyber_policy_code(code: Option<&str>) -> bool {
code.is_some_and(|code| code.trim().eq_ignore_ascii_case("cyber_policy"))
}
pub(super) fn is_history_failure_code(code: &str) -> bool {
[
"previous_response_not_found",
"invalid_encrypted_content",
"missing_tool_output",
"no_tool_output",
]
.iter()
.any(|known| code.trim().eq_ignore_ascii_case(known))
fn history_failure_summary(code: &str) -> Option<&'static str> {
let code = code.trim();
if code.eq_ignore_ascii_case("previous_response_not_found") {
Some("上游找不到先前的响应")
} else if code.eq_ignore_ascii_case("invalid_encrypted_content") {
Some("上游拒绝了加密的历史内容")
} else if code.eq_ignore_ascii_case("missing_tool_output")
|| code.eq_ignore_ascii_case("no_tool_output")
{
Some("对话历史缺少工具调用结果")
} else {
None
}
}
pub(super) const fn provider_error_kind(category: CodexFailureCategory) -> ProviderErrorKind {
fn upstream_failure_summary(
category: CodexFailureCategory,
code: Option<&str>,
) -> (ProviderErrorKind, &'static str) {
match category {
CodexFailureCategory::ModelUnsupported => ProviderErrorKind::Unsupported,
CodexFailureCategory::CredentialExpired => ProviderErrorKind::Unauthorized,
CodexFailureCategory::IdentityVerificationRequired | CodexFailureCategory::Banned => {
ProviderErrorKind::PermissionDenied
CodexFailureCategory::ModelUnsupported => {
(ProviderErrorKind::Unsupported, "上游账号不支持此模型")
}
CodexFailureCategory::UsageLimitExhausted => ProviderErrorKind::QuotaExhausted,
CodexFailureCategory::RateLimited | CodexFailureCategory::TurnRateLimited => {
ProviderErrorKind::RateLimited
CodexFailureCategory::CredentialExpired => {
(ProviderErrorKind::Unauthorized, "上游账号凭据无效")
}
CodexFailureCategory::QuotaExhausted => ProviderErrorKind::QuotaExhausted,
CodexFailureCategory::CloudflareChallenge
| CodexFailureCategory::CloudflarePathBlocked
| CodexFailureCategory::FlexUnavailable
| CodexFailureCategory::Unavailable => ProviderErrorKind::Unavailable,
CodexFailureCategory::CapacityUnavailable => ProviderErrorKind::UpstreamCapacityUnavailable,
CodexFailureCategory::InvalidRequest => ProviderErrorKind::InvalidRequest,
CodexFailureCategory::PermissionDenied => ProviderErrorKind::PermissionDenied,
CodexFailureCategory::Timeout => ProviderErrorKind::Timeout,
CodexFailureCategory::Transport => ProviderErrorKind::Transport,
CodexFailureCategory::IdentityVerificationRequired => {
(ProviderErrorKind::PermissionDenied, "上游账号需要验证身份")
}
CodexFailureCategory::Banned => (ProviderErrorKind::PermissionDenied, "上游账号已被停用"),
CodexFailureCategory::UsageLimitExhausted => (
ProviderErrorKind::QuotaExhausted,
"当前用量窗口的额度已用完",
),
CodexFailureCategory::QuotaExhausted => {
(ProviderErrorKind::QuotaExhausted, "上游账号额度已用完")
}
CodexFailureCategory::RateLimited => (ProviderErrorKind::RateLimited, "上游请求频率受限"),
CodexFailureCategory::TurnRateLimited => {
(ProviderErrorKind::RateLimited, "当前对话轮次受到限流")
}
CodexFailureCategory::CloudflareChallenge => {
(ProviderErrorKind::Unavailable, "Cloudflare 要求验证请求")
}
CodexFailureCategory::CloudflarePathBlocked => {
(ProviderErrorKind::Unavailable, "上游接口返回空的 404 响应")
}
CodexFailureCategory::FlexUnavailable => {
(ProviderErrorKind::Unavailable, "Flex 服务容量不足")
}
CodexFailureCategory::CapacityUnavailable => (
ProviderErrorKind::UpstreamCapacityUnavailable,
"上游模型容量不足",
),
CodexFailureCategory::InvalidRequest => {
let summary = match code.map(str::trim) {
Some(code) if code.eq_ignore_ascii_case("unsupported_value") => {
"上游不支持该参数值"
}
Some(code) if code.eq_ignore_ascii_case("invalid_prompt") => "上游拒绝了提示词",
Some(code) if code.eq_ignore_ascii_case("context_length_exceeded") => {
"输入超出模型上下文长度"
}
_ => "上游拒绝了请求参数",
};
(ProviderErrorKind::InvalidRequest, summary)
}
CodexFailureCategory::PermissionDenied => (
ProviderErrorKind::PermissionDenied,
"上游账号无权执行此请求",
),
CodexFailureCategory::Timeout => (ProviderErrorKind::Timeout, "上游响应超时"),
CodexFailureCategory::Unavailable => (ProviderErrorKind::Unavailable, "上游服务暂不可用"),
CodexFailureCategory::Transport => (ProviderErrorKind::Transport, "上游返回了非预期响应"),
}
}
@@ -2,7 +2,10 @@
use gateway_core::diagnostics::{StreamCapture, StreamFormat, TraceContext, diagnostic_json};
use std::{sync::Arc, time::Instant};
use std::{
sync::Arc,
time::{Duration, Instant},
};
use futures::{StreamExt, TryStreamExt};
use gateway_protocol::openai::{
@@ -32,9 +35,10 @@ use crate::transport::{
},
response_meta,
websocket::{
CodexWebSocketConnection, CodexWebSocketExchangeError, CodexWebSocketPoolKey,
DEFAULT_STREAM_IDLE_TIMEOUT, PreviousResponseUnavailableReason, WEBSOCKET_FAST_PATH_BUDGET,
WebSocketFastPath, execute_prepared_response_create_request_stream, post_send_ambiguous,
CodexWebSocketConnection, CodexWebSocketExchangeError, CodexWebSocketPool,
CodexWebSocketPoolKey, DEFAULT_FAST_PATH_BUDGET_MS, DEFAULT_STREAM_IDLE_TIMEOUT,
PreviousResponseUnavailableReason, WebSocketFastPath,
execute_prepared_response_create_request_stream, post_send_ambiguous,
prepare_response_create_request_with_pool, websocket_audit_dir,
write_websocket_audit_artifact_from_env,
},
@@ -375,7 +379,10 @@ impl CodexBackendClient {
.map(|pool| (pool, pool_key, downstream_cancellation));
let fast_path_budget = match requirement {
TransportRequirement::PersistedContinuation | TransportRequirement::NewChain => {
Some(WEBSOCKET_FAST_PATH_BUDGET)
Some(self.websocket_pool.as_deref().map_or(
Duration::from_millis(DEFAULT_FAST_PATH_BUDGET_MS),
CodexWebSocketPool::fast_path_budget,
))
}
TransportRequirement::ExplicitWebSocketWarmup
| TransportRequirement::WebSocketNewChain
@@ -32,8 +32,6 @@ use super::{
pump::{PumpLogContext, PumpedWebSocket, transport_metric_reason},
};
pub(crate) const WEBSOCKET_FAST_PATH_BUDGET: Duration = Duration::from_millis(800);
/// WebSocket 快路径的控制流结果;预算未命中不代表连接失败
pub(crate) enum WebSocketFastPath<T> {
/// 在前台预算内获得结果
@@ -575,7 +573,7 @@ async fn wait_for_shared_connect(
wait_for_fast_path(waiter.started_at(), fast_path_budget, waiter.wait()).await
}
// 同一次 opening 的所有等待者共享截止时间;后来的请求不会重置 800ms 预算
// 同一次 opening 的所有等待者共享截止时间
async fn wait_for_fast_path<F: Future>(
started_at: TokioInstant,
budget: Option<Duration>,
@@ -35,7 +35,7 @@ use super::{
use super::control::WEBSOCKET_SEND_TIMEOUT;
const WEBSOCKET_EXTENSIONS: &str = "permessage-deflate; client_max_window_bits";
const WEBSOCKET_CONNECT_TIMEOUT: Duration = Duration::from_secs(15);
pub(crate) const WEBSOCKET_CONNECT_TIMEOUT: Duration = Duration::from_secs(15);
impl CodexWebSocketConnection {
/// 复用传输库的握手编码检查,不能在拨号后才发现插件输出不可表示
@@ -39,11 +39,11 @@ pub use self::{
};
pub(crate) use self::{
coordinator::{
PreparedWebSocket, WEBSOCKET_FAST_PATH_BUDGET, WebSocketFastPath,
execute_prepared_response_create_request_stream, post_send_ambiguous,
prepare_response_create_request_with_pool,
PreparedWebSocket, WebSocketFastPath, execute_prepared_response_create_request_stream,
post_send_ambiguous, prepare_response_create_request_with_pool,
},
error::WEBSOCKET_CLOSE_MESSAGE_TOO_BIG,
handshake::WEBSOCKET_CONNECT_TIMEOUT,
live::{connect_live_sideband, into_live_relay},
pool::DEFAULT_STREAM_IDLE_TIMEOUT,
pool::{DEFAULT_FAST_PATH_BUDGET_MS, DEFAULT_STREAM_IDLE_TIMEOUT},
};
@@ -37,6 +37,7 @@ pub(crate) use self::{
};
const DEFAULT_MAX_CONNECTING: usize = 16;
pub(crate) const DEFAULT_FAST_PATH_BUDGET_MS: u64 = 800;
const DEFAULT_MAX_AGE: Duration = Duration::from_mins(55);
const DEFAULT_MAINTENANCE_INTERVAL: Duration = Duration::from_secs(5);
const DEFAULT_IDLE_TIMEOUT: Duration = Duration::from_secs(300);
@@ -70,6 +71,8 @@ pub struct CodexWebSocketPoolConfig {
pub max_age: Duration,
/// 所有账号合计允许并发执行的 opening 数
pub max_connecting: usize,
/// 允许回退 HTTP 的请求在前台等待 WebSocket 建连的时长
pub fast_path_budget: Duration,
/// 后台维护间隔;`None` 表示不启动后台任务
pub maintenance_interval: Option<Duration>,
/// 未绑定下游 WS 的连接归池后可空闲的时间,不由 Ping/Pong 刷新
@@ -84,6 +87,7 @@ impl Default for CodexWebSocketPoolConfig {
enabled: true,
max_age: DEFAULT_MAX_AGE,
max_connecting: DEFAULT_MAX_CONNECTING,
fast_path_budget: Duration::from_millis(DEFAULT_FAST_PATH_BUDGET_MS),
maintenance_interval: Some(DEFAULT_MAINTENANCE_INTERVAL),
idle_timeout: DEFAULT_IDLE_TIMEOUT,
stream_idle_timeout: Some(DEFAULT_STREAM_IDLE_TIMEOUT),
@@ -117,6 +121,10 @@ impl CodexWebSocketPool {
pool
}
pub(crate) fn fast_path_budget(&self) -> Duration {
self.config.fast_path_budget
}
/// 等待下一条上游消息的空闲超时;`None` 或零值使用默认 300 秒
pub(crate) fn stream_idle_timeout(&self) -> Option<Duration> {
self.config.stream_idle_timeout
@@ -811,12 +811,6 @@ async fn openai_admin_provider_persists_the_full_pending_envelope_and_binds_owne
.get("mutation")
.and_then(Value::as_object)
.expect("pending mutation");
assert!(
payload
.expose_to_provider()
.get("reauthorization_credential_revision")
.is_none()
);
assert!(
payload
.expose_to_provider()
@@ -829,13 +823,8 @@ async fn openai_admin_provider_persists_the_full_pending_envelope_and_binds_owne
mutation.get("schema_version").and_then(Value::as_u64),
Some(3)
);
assert!(mutation.get("expected_config_revision").is_none());
assert!(
mutation
.get("target")
.and_then(Value::as_object)
.is_some_and(|target| target.get("expected_credential_revision").is_none())
);
assert_eq!(mutation["target"]["kind"], "create");
assert_eq!(mutation["target"]["name"], "OAuth account");
assert_eq!(
mutation.get("started_request_id").and_then(Value::as_str),
Some("request-start")
@@ -1037,11 +1026,6 @@ async fn openai_reauthorization_pending_payload_reuses_the_account_installation_
document.get("installation_id").and_then(Value::as_str),
Some(expected_installation_id.as_str())
);
assert!(
document
.get("reauthorization_credential_revision")
.is_none()
);
assert_eq!(
target.get("kind").and_then(Value::as_str),
Some("reauthorize")
@@ -1050,7 +1034,6 @@ async fn openai_reauthorization_pending_payload_reuses_the_account_installation_
target.get("account_id").and_then(Value::as_str),
Some("acct_pending_reauth")
);
assert!(target.get("expected_credential_revision").is_none());
}
#[tokio::test]
@@ -2942,7 +2925,6 @@ mod errors {
.prepare_refresh(command())
.await
.unwrap_err();
// 既有 transport 策略未认定此错误为安全重试,本次不能因展示更详细而放宽重试边界
assert_eq!(error.kind(), Kind::Ambiguous);
assert_eq!(
error.public_message(),
+40 -13
View File
@@ -96,26 +96,53 @@ fn openai_stream_retry_budget_uses_the_official_hard_cap() {
}
#[test]
fn websocket_pool_idle_timeout_accepts_existing_configs_and_explicit_overrides() {
for (idle_timeout_ms, expected) in [(None, 300_000), (Some(600_000), 600_000)] {
let mut document = serde_json::json!({
"ws_pool": {
fn websocket_pool_timeouts_accept_defaults_and_individual_overrides() {
for (settings, idle_ms, fast_ms) in [
(
serde_json::json!({
"enabled": true,
"max_age_ms": 3_300_000,
"max_connecting": 8,
"stream_idle_timeout_ms": 300_000
}
});
if let Some(idle_timeout_ms) = idle_timeout_ms {
document["ws_pool"]["idle_timeout_ms"] = serde_json::json!(idle_timeout_ms);
}
let mut config: OpenAiConfig = serde_json::from_value(document).unwrap();
}),
300_000,
800,
),
(
serde_json::json!({"idle_timeout_ms": 600_000}),
600_000,
800,
),
(serde_json::json!({"fast_path_budget_ms": 1}), 300_000, 1),
(
serde_json::json!({"fast_path_budget_ms": 15_000}),
300_000,
15_000,
),
] {
let mut config: OpenAiConfig =
serde_json::from_value(serde_json::json!({"ws_pool": settings})).unwrap();
config
.resolve_and_validate(Path::new("/srv/gateway"))
.unwrap();
assert_eq!(
config.websocket_pool_config().idle_timeout,
Duration::from_millis(expected)
let pool = config.websocket_pool_config();
assert_eq!(pool.idle_timeout, Duration::from_millis(idle_ms));
assert_eq!(pool.fast_path_budget, Duration::from_millis(fast_ms));
}
}
#[test]
fn websocket_fast_path_budget_must_fit_the_opening_timeout() {
for budget_ms in [0, 15_001] {
let mut config = valid_config();
config.ws_pool.fast_path_budget_ms = budget_ms;
let error = config
.resolve_and_validate(Path::new("/srv/gateway"))
.unwrap_err();
assert!(
error
.to_string()
.contains("openai.ws_pool.fast_path_budget_ms")
);
}
}
@@ -232,7 +232,6 @@ async fn warmup_uses_global_profile_and_lowest_reasoning_effort() {
zstd::stream::decode_all(requests[0].body.as_slice()).expect("zstd body should decode");
let body: serde_json::Value =
serde_json::from_slice(&decoded).expect("warmup body should be valid JSON");
// 上游按目录拒绝目录外的档位,none 曾让全部定时预热只留下 error 终态
assert_eq!(body["reasoning"]["effort"], "low");
*policy.0.lock().unwrap() = OpaqueProviderData::new(
json!({"mode":"custom","userAgent":"invalid"})
@@ -128,6 +128,9 @@ async fn upstream_codes_survive_http_and_websocket_opening_without_normalization
body,
);
let diagnostic = error.diagnostic().expect("safe diagnostic");
if expected_kind == ProviderErrorKind::ContinuationRecoveryRequired {
assert_eq!(diagnostic.as_str(), "上游找不到先前的响应");
}
assert!(!diagnostic.as_str().contains(original_code));
assert!(!diagnostic.as_str().contains("PRIVATE_UPSTREAM_DETAIL"));
assert!(!format!("{error:?} {error}").contains(original_code));
@@ -3559,7 +3559,7 @@ async fn assert_cross_endpoint_affinity(thread_id: Option<&str>) {
}
drop(same);
// 仍由旧租约流程报告繁忙并换号,亲和不绕过并发限制
// 亲和账号的并发租约已满时,请求应切换账号
leases
.busy_accounts
.lock()
@@ -8875,6 +8875,7 @@ async fn capacity_http_and_websocket_opening_rejections_use_bounded_business_ret
}
};
assert_eq!(error.kind(), ProviderErrorKind::UpstreamCapacityUnavailable);
assert_eq!(error.diagnostic().unwrap().as_str(), "上游模型容量不足");
assert_eq!(error.upstream_status(), Some(status));
assert!(error.replay_is_safe());
assert_eq!(error.retry_after(), Some(Duration::from_secs(129600)));
@@ -70,6 +70,78 @@ pub(super) async fn stream_failure(
}
}
#[tokio::test]
async fn bare_websocket_bad_request_offers_http_error_only_for_native_responses_sse() {
use ClientTransport::{HttpJson, HttpSse, WebSocket};
use gateway_protocol::openai::RESPONSES_PATH;
let detail = json!({
"type":"invalid_request_error", "code":"invalid_value", "message":"Invalid input.",
"param":"input[2].id", "extension":{"reason":"duplicate"}
});
let bad_request = json!({"type":"error", "status":400, "error":detail, "sequence_number":7});
let no_status = json!({"type":"error", "error":detail});
let response_failed = json!({"type":"response.failed", "status":400, "response":{"id":"resp_failed","error":detail}});
let capacity = json!({"status":400, "type":"error", "error":overload()["error"]});
for (endpoint, transport, frame, expects_http) in [
(RESPONSES_PATH, HttpSse, &bad_request, true),
(RESPONSES_PATH, WebSocket, &bad_request, false),
(RESPONSES_PATH, HttpJson, &bad_request, false),
("/v1/chat/completions", HttpSse, &bad_request, false),
(RESPONSES_PATH, HttpSse, &no_status, false),
(RESPONSES_PATH, HttpSse, &response_failed, false),
(RESPONSES_PATH, HttpSse, &capacity, false),
] {
let store = Arc::new(MemoryAccountStore::default());
create_account(&store, "acct_provider_contract").await;
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
let base_url = format!("http://{}", listener.local_addr().unwrap());
let raw = frame.to_string();
let server = tokio::spawn(async move {
let (socket, _) = listener.accept().await.unwrap();
let mut ws = accept_codex_test_websocket(socket).await;
ws.next().await.unwrap().unwrap();
ws.send(Message::Text(raw.into())).await.unwrap();
});
let request = RequestAttemptContext::new(
ModelRequestId::new("req_ws_bad_input").unwrap(),
ClientApiKeyId::new("key_openai_contract").unwrap(),
)
.with_middleware(None, Arc::from([]), endpoint.to_owned(), transport)
.with_request_location(Some(global_request_location()));
let mut stream = provider_with_base_url(&store, base_url)
.execute(
planned_request("openai", generate_operation()),
context_for_request(request, CancellationToken::new()),
)
.await
.unwrap();
let (events, mut error) = stream_failure(&mut stream).await;
assert!(events.iter().all(|event| !event.has_client_event()));
let response = error.client_visible_upstream_response();
assert_eq!(
response.is_some(),
expects_http,
"{endpoint} {transport:?} {frame}"
);
if let Some(response) = response {
assert_eq!(response.status(), 400);
assert_eq!(
response.content_type(),
Some(b"application/json".as_slice())
);
assert_eq!(
serde_json::from_slice::<Value>(response.body()).unwrap(),
json!({"error":detail})
);
}
let events = error.take_atomic_client_events();
assert_eq!(events.len(), 1);
assert_eq!(events[0].wire_event().unwrap().data(), frame);
server.await.unwrap();
}
}
#[tokio::test]
async fn large_preludes_are_forwarded_before_failure_on_http_and_websocket() {
for websocket in [false, true] {
@@ -341,6 +341,31 @@ async fn downstream_websocket_new_chain_should_preserve_continuation_after_slow_
#[tokio::test]
async fn external_continuation_should_wait_for_a_cold_websocket() {
assert_slow_opening_uses_websocket(
external_continuation_request("conversation-cross-account"),
CodexWebSocketPoolConfig::default(),
)
.await;
}
#[tokio::test]
async fn configured_fast_path_budget_should_allow_slow_websocket_openings() {
let config = CodexWebSocketPoolConfig {
fast_path_budget: Duration::from_secs(3),
..Default::default()
};
let mut persisted = new_chain_request("persisted");
persisted.set_previous_response_id(Some("resp_persisted".into()));
persisted.previous_response_scope = Some(PreviousResponseScope::Persisted);
for request in [new_chain_request("new-chain"), persisted] {
assert_slow_opening_uses_websocket(request, config).await;
}
}
async fn assert_slow_opening_uses_websocket(
request: CodexResponsesRequest,
config: CodexWebSocketPoolConfig,
) {
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
let addr = listener.local_addr().unwrap();
let server = tokio::spawn(async move {
@@ -350,12 +375,12 @@ async fn external_continuation_should_wait_for_a_cold_websocket() {
let _payload = websocket.next().await.unwrap().unwrap();
websocket
.send(Message::Text(
completed_websocket_response("resp_cross_account", 2, 1).into(),
completed_websocket_response("resp_slow_opening", 2, 1).into(),
))
.await
.unwrap();
});
let pool = Arc::new(CodexWebSocketPool::default());
let pool = Arc::new(CodexWebSocketPool::with_config(config));
let backend = CodexBackendClient::new(
reqwest::Client::builder().no_proxy().build().unwrap(),
format!("http://{addr}"),
@@ -363,13 +388,16 @@ async fn external_continuation_should_wait_for_a_cold_websocket() {
)
.with_websocket_pool(Arc::clone(&pool));
let response = backend
.create_response(
&external_continuation_request("conversation-cross-account"),
request_context("req_cross_account", Some("chatgpt-account-b")),
)
.await
.expect("external continuation should complete over WebSocket");
let response = timeout(
Duration::from_secs(5),
backend.create_response(
&request,
request_context("req_slow_opening", Some("chatgpt-account-b")),
),
)
.await
.expect("slow WebSocket opening should complete")
.unwrap();
server.await.unwrap();
assert_eq!(response.transport, CodexBackendTransport::WebSocket);
@@ -432,8 +432,7 @@ async fn lagged_profiles_track_observed_release_history() {
);
}
/// 重启后恢复缓存、首次检查即发现新版:恢复版本必须进入发布历史,
/// 滞后一档不能跳回启动种子(PR #339 审查反馈的触发序列)。
/// 重启后首次检查发现新版时,滞后一档应选中从缓存恢复的版本
#[tokio::test]
async fn restored_cache_release_should_stay_in_version_lag_history() {
use provider_openai::transport::profile::selection::ClientProfileSelection;
@@ -1,8 +1,6 @@
//! 验证 HTTP 与 WebSocket 的 TLS 握手特征
use std::collections::BTreeMap;
use std::path::Path;
use std::process::Stdio;
use bytes::{Buf as _, Bytes};
@@ -10,11 +8,8 @@ use super::*;
const CASE_ENV: &str = "CODEX_PROXY_TEST_HTTP_CLIENT_HELLO";
const CASE_COMPLETED: &str = "http-tls-client-hello-case-completed";
const REFERENCE_ENV: &str = "CODEX_PROXY_TEST_REFERENCE_BINARY";
// 基线来自官方 Codex 823ea830c0 的客户端源码,各路径重复采样五次
// HTTP 另与本机 Core 0.160.0 的采样核对,源码客户端与本项目还通过真实 models 请求验证
// HTTP/native-tls 的扩展顺序固定;WebSocket/rustls 会随机化扩展顺序和临时密钥
// 握手基线对应官方 Codex 823ea830c0,rustls 的扩展顺序和临时密钥按连接变化
#[derive(Debug, PartialEq, Eq)]
struct ClientHello {
legacy_version: u16,
@@ -57,81 +52,22 @@ fn http_client_hellos_should_match_official_tls_transports() {
return;
}
run_isolated_cases(
"transport::tls::http_client_hellos_should_match_official_tls_transports",
&["native", "custom-ca"],
);
}
#[test]
#[ignore = "requires CODEX_PROXY_TEST_REFERENCE_BINARY pointing to the official Codex executable"]
fn client_hellos_should_match_the_official_binary_on_this_platform() {
let reference = std::env::var_os(REFERENCE_ENV)
.map(std::path::PathBuf::from)
.expect("set CODEX_PROXY_TEST_REFERENCE_BINARY to the official Codex executable")
.canonicalize()
.expect("official Codex executable path");
if let Ok(case) = std::env::var(CASE_ENV) {
let runtime = tokio::runtime::Builder::new_current_thread()
.enable_all()
.build()
.unwrap();
runtime.block_on(async {
for sample in 0..3 {
let mut expected = capture_official_hello(&reference, case == "websocket").await;
let mut actual = if case == "websocket" {
capture_websocket_hello().await
} else {
capture_http_hello(provider_openai::transport::build_reqwest_client().unwrap())
.await
};
// rustls 随机排列扩展,其他字段及各自列表的顺序仍逐项核对
if case != "native" {
expected.extensions.sort_unstable();
actual.extensions.sort_unstable();
}
assert_eq!(actual, expected, "{case} ClientHello sample {sample}");
}
});
println!("\n{CASE_COMPLETED}");
return;
}
let version = Command::new(&reference)
.arg("--version")
.output()
.expect("read official Codex version");
assert!(version.status.success());
println!(
"TLS reference: {} on {}-{}",
String::from_utf8_lossy(&version.stdout).trim(),
std::env::consts::OS,
std::env::consts::ARCH,
);
run_isolated_cases(
"transport::tls::client_hellos_should_match_the_official_binary_on_this_platform",
&["native", "custom-ca", "websocket"],
);
}
fn run_isolated_cases(test_name: &str, cases: &[&str]) {
// Cargo 运行测试时可能注入 SSL_CERT_FILE,生产代码会把它视作自定义 CA 并切到 rustls;
// 因此在清理相关环境变量的子进程里验证默认路径
let current_exe = std::env::current_exe().expect("current test binary path");
let directory = tempfile::tempdir().unwrap();
let ca_path = directory.path().join("ca.pem");
std::fs::write(&ca_path, TEST_CA_PEM).unwrap();
for case in cases {
for case in ["native", "custom-ca"] {
let mut command = Command::new(&current_exe);
command
.arg("--exact")
.arg(test_name)
.arg("--include-ignored")
.arg("transport::tls::http_client_hellos_should_match_official_tls_transports")
.arg("--nocapture")
.env(CASE_ENV, case)
.env_remove(provider_openai::transport::tls::CODEX_CA_CERT_ENV)
.env_remove(provider_openai::transport::tls::SSL_CERT_FILE_ENV);
if *case == "custom-ca" {
if case == "custom-ca" {
command.env(provider_openai::transport::tls::CODEX_CA_CERT_ENV, &ca_path);
}
let output = command.output().expect("run isolated TLS ClientHello case");
@@ -153,70 +89,6 @@ fn run_isolated_cases(test_name: &str, cases: &[&str]) {
}
}
async fn capture_official_hello(reference: &Path, websocket: bool) -> ClientHello {
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
let endpoint = format!(
"https://localhost:{}/v1",
listener.local_addr().unwrap().port()
);
let directory = tempfile::tempdir().unwrap();
// 官方进程只访问本机采集端点,握手后即终止,认证使用无效测试值
let mut command = tokio::process::Command::new(reference);
command
.args([
"exec",
"--ignore-user-config",
"--ignore-rules",
"--ephemeral",
"--skip-git-repo-check",
"--sandbox",
"read-only",
"--json",
"--model",
"tls-probe",
])
.current_dir(directory.path())
.env("CPR_TLS_PROBE_API_KEY", "test-local-handshake-only")
.stdin(Stdio::null())
.stdout(Stdio::null())
.stderr(Stdio::null())
.kill_on_drop(true);
for name in [
"HTTP_PROXY",
"HTTPS_PROXY",
"ALL_PROXY",
"http_proxy",
"https_proxy",
"all_proxy",
] {
command.env_remove(name);
}
for setting in [
"model_provider=\"cpr_tls_probe\"".to_owned(),
"model_providers.cpr_tls_probe.name=\"CPR TLS Probe\"".to_owned(),
format!("model_providers.cpr_tls_probe.base_url=\"{endpoint}\""),
"model_providers.cpr_tls_probe.env_key=\"CPR_TLS_PROBE_API_KEY\"".to_owned(),
"model_providers.cpr_tls_probe.wire_api=\"responses\"".to_owned(),
format!("model_providers.cpr_tls_probe.supports_websockets={websocket}"),
"model_providers.cpr_tls_probe.request_max_retries=0".to_owned(),
"model_providers.cpr_tls_probe.stream_max_retries=0".to_owned(),
"project_doc_max_bytes=0".to_owned(),
] {
command.args(["--config", &setting]);
}
let mut child = command
.arg("TLS handshake capture")
.spawn()
.expect("start official Codex TLS reference");
let hello = timeout(Duration::from_secs(30), read_client_hello(listener)).await;
let _ = child.kill().await;
child
.wait()
.await
.expect("reap official Codex TLS reference");
hello.expect("official Codex ClientHello within timeout")
}
async fn capture_http_hello(client: reqwest::Client) -> ClientHello {
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
let url = format!(
@@ -237,19 +109,13 @@ async fn capture_http_hello(client: reqwest::Client) -> ClientHello {
#[tokio::test]
async fn websocket_client_hello_should_match_official_rustls_transport() {
let mut hello = capture_websocket_hello().await;
hello.extensions.sort_unstable();
assert_eq!(hello, official_websocket_hello());
}
async fn capture_websocket_hello() -> ClientHello {
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
let url = format!("wss://localhost:{}/", listener.local_addr().unwrap().port());
let connector =
provider_openai::transport::tls::maybe_build_rustls_client_config_with_custom_ca()
.unwrap()
.map(tokio_tungstenite::Connector::Rustls);
let (hello, response) = timeout(Duration::from_secs(10), async {
let (mut hello, response) = timeout(Duration::from_secs(10), async {
tokio::join!(
read_client_hello(listener),
tokio_tungstenite::connect_async_tls_with_config(url, None, false, connector)
@@ -261,7 +127,8 @@ async fn capture_websocket_hello() -> ClientHello {
response.is_err(),
"capture endpoint rejects TLS after ClientHello"
);
hello
hello.extensions.sort_unstable();
assert_eq!(hello, official_websocket_hello());
}
#[cfg(target_os = "linux")]
@@ -875,7 +875,6 @@ async fn websocket_execute_response_create_request_should_forward_typed_events_w
let (stream, _) = listener.accept().await.unwrap();
let mut websocket = accept_codex_test_websocket(stream).await;
let _message = websocket.next().await.unwrap().unwrap();
// 透明代理:缺官方必需字段的 delta 事件不再被丢弃,原样转发
websocket
.send(Message::Text(
json!({
@@ -982,8 +982,7 @@ async fn websocket_pool_should_release_slot_when_client_drops_stream() {
.contains("streaming has begun")
);
// 客户端断开:drop stream → rx 被 drop → tx.closed() 完成 →
// 代理丢弃上游连接并释放 slot(不再等 idle 超时)
// 客户端丢弃响应流会触发上游连接关闭,池槽位在空闲超时前释放
drop(stream);
tokio::time::sleep(Duration::from_millis(200)).await;
@@ -525,24 +525,7 @@ pub(super) fn map_transport_error_with_state(
allow_explicit_replay: bool,
) -> ProviderError {
let transport_kind = error.kind();
let kind = match transport_kind {
GrokInferenceTransportErrorKind::InvalidRequest => ProviderErrorKind::InvalidRequest,
GrokInferenceTransportErrorKind::Unsupported => ProviderErrorKind::Unsupported,
GrokInferenceTransportErrorKind::Unauthorized => ProviderErrorKind::Unauthorized,
GrokInferenceTransportErrorKind::PermissionDenied
| GrokInferenceTransportErrorKind::ModelAccessDenied
| GrokInferenceTransportErrorKind::PaymentRequired
| GrokInferenceTransportErrorKind::SafetyRejected => ProviderErrorKind::PermissionDenied,
GrokInferenceTransportErrorKind::RateLimited => ProviderErrorKind::RateLimited,
GrokInferenceTransportErrorKind::QuotaExhausted
| GrokInferenceTransportErrorKind::FreeQuotaExhausted
| GrokInferenceTransportErrorKind::ModelQuotaExhausted => ProviderErrorKind::QuotaExhausted,
GrokInferenceTransportErrorKind::Timeout => ProviderErrorKind::Timeout,
GrokInferenceTransportErrorKind::Transport => ProviderErrorKind::Transport,
GrokInferenceTransportErrorKind::Protocol => ProviderErrorKind::Protocol,
GrokInferenceTransportErrorKind::Unavailable => ProviderErrorKind::Unavailable,
GrokInferenceTransportErrorKind::Cancelled => ProviderErrorKind::Cancelled,
};
let kind = transport_kind.provider_kind();
let mut mapped = provider_error(
kind,
forced_send_state.unwrap_or_else(|| error.send_state()),
@@ -579,14 +562,8 @@ pub(super) fn map_transport_error_with_state(
mapped = mapped.with_client_visible_upstream_error(detail);
}
let diagnostic = error.diagnostic().cloned().unwrap_or_else(|| {
let status = error
.status()
.map_or_else(|| "none".to_owned(), |value| value.to_string());
ProviderDiagnostic::new(format!(
"xAI upstream failure: kind={}, status={status}",
kind.as_str()
))
.with_classification("upstream", "upstream_failure")
ProviderDiagnostic::new(transport_kind.diagnostic_message())
.with_classification("upstream", "upstream_failure")
});
mapped = mapped.with_diagnostic(diagnostic);
if error.requires_credential_recovery() {
@@ -4,7 +4,8 @@ use std::collections::{BTreeMap, BTreeSet};
use gateway_core::engine::provider::NativeResponseTranslator;
use gateway_core::error::{
ClientVisibleUpstreamError, OpaqueUpstreamValue, ProviderError, ProviderErrorKind,
ClientVisibleUpstreamError, OpaqueUpstreamValue, ProviderDiagnostic, ProviderError,
ProviderErrorKind,
};
use gateway_core::event::{
ContentItem, ContentKind, FinishReason, GatewayEvent, ProtocolWireEvent, ProviderEvent,
@@ -20,6 +21,7 @@ use gateway_protocol::openai::events::{TokenUsage, billable_usage_is_complete, e
use gateway_protocol::openai::sse::{SseEvent, SseEventDecoder};
use serde_json::Value;
use super::GrokInferenceTransportErrorKind;
use super::request::{GrokResponseTransform, GrokResponsesRequest};
use super::upstream_error::{classify_grok_quota_failure, scrub_account_fingerprints};
@@ -1207,19 +1209,24 @@ fn upstream_event_error(value: &Value) -> ProviderError {
.or_else(|| value.pointer("/response/error/type"))
.and_then(Value::as_str);
let message = upstream_error_field(value, "message");
let kind = if classify_grok_quota_failure(code, error_type, message).is_some() {
ProviderErrorKind::QuotaExhausted
let kind = if let Some(quota) = classify_grok_quota_failure(code, error_type, message) {
GrokInferenceTransportErrorKind::from_quota(quota)
} else {
match code {
Some("invalid_request" | "invalid_prompt") => ProviderErrorKind::InvalidRequest,
Some("unsupported" | "unsupported_feature") => ProviderErrorKind::Unsupported,
Some("unauthorized" | "invalid_token") => ProviderErrorKind::Unauthorized,
Some("permission_denied") => ProviderErrorKind::PermissionDenied,
Some("rate_limit_exceeded") => ProviderErrorKind::RateLimited,
_ => ProviderErrorKind::Unavailable,
Some("invalid_request" | "invalid_prompt") => {
GrokInferenceTransportErrorKind::InvalidRequest
}
Some("unsupported" | "unsupported_feature") => {
GrokInferenceTransportErrorKind::Unsupported
}
Some("unauthorized" | "invalid_token") => GrokInferenceTransportErrorKind::Unauthorized,
Some("permission_denied") => GrokInferenceTransportErrorKind::PermissionDenied,
Some("rate_limit_exceeded") => GrokInferenceTransportErrorKind::RateLimited,
_ => GrokInferenceTransportErrorKind::Unavailable,
}
};
let mut error = ProviderError::new(kind, UpstreamSendState::Sent)
let mut error = ProviderError::new(kind.provider_kind(), UpstreamSendState::Sent)
.with_diagnostic(ProviderDiagnostic::new(kind.diagnostic_message()))
.with_raw_upstream_error(gateway_core::error::RawUpstreamError::new(
value.to_string(),
))
@@ -9,13 +9,14 @@ use futures::Stream;
use gateway_core::engine::middleware::MiddlewareHeader;
use gateway_core::error::{
ClientVisibleUpstreamError, ErrorSource, OpaqueUpstreamValue, ProviderDiagnostic,
RawUpstreamError,
ProviderErrorKind, RawUpstreamError,
};
use gateway_core::event::UpstreamHttpVersion;
use gateway_core::upstream::UpstreamSendState;
use url::Url;
use zeroize::Zeroizing;
use super::upstream_error::GrokQuotaFailureKind;
use super::{GrokHeader, GrokSessionBinding};
/// 交给注入的 HTTP SSE transport 的自持有请求
@@ -352,6 +353,58 @@ pub enum GrokInferenceTransportErrorKind {
Cancelled,
}
impl GrokInferenceTransportErrorKind {
pub(crate) const fn from_quota(failure: GrokQuotaFailureKind) -> Self {
match failure {
GrokQuotaFailureKind::Account => Self::QuotaExhausted,
GrokQuotaFailureKind::FreeAccount => Self::FreeQuotaExhausted,
GrokQuotaFailureKind::FreeModelUsage => Self::ModelQuotaExhausted,
}
}
pub(crate) const fn provider_kind(self) -> ProviderErrorKind {
match self {
Self::InvalidRequest => ProviderErrorKind::InvalidRequest,
Self::Unsupported => ProviderErrorKind::Unsupported,
Self::Unauthorized => ProviderErrorKind::Unauthorized,
Self::PermissionDenied
| Self::ModelAccessDenied
| Self::PaymentRequired
| Self::SafetyRejected => ProviderErrorKind::PermissionDenied,
Self::RateLimited => ProviderErrorKind::RateLimited,
Self::QuotaExhausted | Self::FreeQuotaExhausted | Self::ModelQuotaExhausted => {
ProviderErrorKind::QuotaExhausted
}
Self::Timeout => ProviderErrorKind::Timeout,
Self::Transport => ProviderErrorKind::Transport,
Self::Protocol => ProviderErrorKind::Protocol,
Self::Unavailable => ProviderErrorKind::Unavailable,
Self::Cancelled => ProviderErrorKind::Cancelled,
}
}
pub(crate) const fn diagnostic_message(self) -> &'static str {
match self {
Self::InvalidRequest => "上游拒绝了请求参数",
Self::Unsupported => "上游不支持此请求",
Self::Unauthorized => "上游账号凭据无效",
Self::PermissionDenied => "上游账号无权执行此请求",
Self::ModelAccessDenied => "上游账号无权使用此模型",
Self::PaymentRequired => "上游要求付费",
Self::SafetyRejected => "请求被上游安全策略拦截",
Self::RateLimited => "上游请求频率受限",
Self::QuotaExhausted => "上游账号额度已用完",
Self::FreeQuotaExhausted => "上游账号免费额度已用完",
Self::ModelQuotaExhausted => "此模型的免费额度已用完",
Self::Timeout => "上游响应超时",
Self::Transport => "上游连接失败",
Self::Protocol => "上游协议处理失败",
Self::Unavailable => "上游服务暂不可用",
Self::Cancelled => "请求已取消",
}
}
}
/// 推理 transport 失败,公开分类与受控上游详情分别承载
#[derive(Clone)]
pub struct GrokInferenceTransportError {
@@ -1156,18 +1156,28 @@ async fn classify_inference_status(
if let Some(raw) = raw {
error = error.with_raw_upstream_error(raw);
}
let diagnostic_code = if status == StatusCode::BAD_REQUEST && reasoning_decode_failed(&metadata)
let (code, message) = if status == StatusCode::BAD_REQUEST && reasoning_decode_failed(&metadata)
{
"reasoning_decode_failed"
("reasoning_decode_failed", "上游无法解码加密的推理内容")
} else {
body_failure.map_or("upstream_failure", GrokBodyFailure::marker)
let message = match (body_failure, kind) {
(
Some(GrokBodyFailure::ModelCapacity),
GrokInferenceTransportErrorKind::RateLimited,
) => "上游模型容量不足",
(
Some(GrokBodyFailure::EmptyUpstream),
GrokInferenceTransportErrorKind::Unavailable,
) => "上游未返回模型响应",
_ => kind.diagnostic_message(),
};
(
body_failure.map_or("upstream_failure", GrokBodyFailure::marker),
message,
)
};
error = error.with_diagnostic(
ProviderDiagnostic::new(format!(
"xAI upstream rejected request: status={status_code}"
))
.with_classification("upstream", diagnostic_code),
);
error = error
.with_diagnostic(ProviderDiagnostic::new(message).with_classification("upstream", code));
error = error.with_upstream_failure_fields(gateway_core::upstream::UpstreamFailureFields {
status: Some(status_code),
code: metadata.original_code,
@@ -1221,7 +1231,7 @@ enum GrokBodyFailure {
impl GrokBodyFailure {
fn transport_kind(self) -> GrokInferenceTransportErrorKind {
match self {
Self::Quota(failure) => quota_transport_error_kind(failure),
Self::Quota(failure) => GrokInferenceTransportErrorKind::from_quota(failure),
Self::Billing => GrokInferenceTransportErrorKind::PaymentRequired,
Self::EmptyUpstream => GrokInferenceTransportErrorKind::Unavailable,
Self::ModelCapacity | Self::RateLimit => GrokInferenceTransportErrorKind::RateLimited,
@@ -1372,7 +1382,7 @@ fn first_string(object: &serde_json::Map<String, Value>, fields: &[&str]) -> Opt
fn classify_payment_required(metadata: &InferenceErrorMetadata) -> GrokInferenceTransportErrorKind {
quota_failure(metadata).map_or(
GrokInferenceTransportErrorKind::PaymentRequired,
quota_transport_error_kind,
GrokInferenceTransportErrorKind::from_quota,
)
}
@@ -1392,7 +1402,7 @@ fn classify_forbidden(
} else if let Some(failure) = body_failure {
failure.transport_kind()
} else if let Some(failure) = quota_failure(metadata) {
quota_transport_error_kind(failure)
GrokInferenceTransportErrorKind::from_quota(failure)
} else if model_access_denied(metadata) {
GrokInferenceTransportErrorKind::ModelAccessDenied
} else {
@@ -1405,7 +1415,7 @@ fn classify_too_many_requests(
) -> GrokInferenceTransportErrorKind {
quota_failure(metadata).map_or(
GrokInferenceTransportErrorKind::RateLimited,
quota_transport_error_kind,
GrokInferenceTransportErrorKind::from_quota,
)
}
@@ -1441,16 +1451,6 @@ fn quota_failure(metadata: &InferenceErrorMetadata) -> Option<GrokQuotaFailureKi
)
}
fn quota_transport_error_kind(failure: GrokQuotaFailureKind) -> GrokInferenceTransportErrorKind {
match failure {
GrokQuotaFailureKind::Account => GrokInferenceTransportErrorKind::QuotaExhausted,
GrokQuotaFailureKind::FreeAccount => GrokInferenceTransportErrorKind::FreeQuotaExhausted,
GrokQuotaFailureKind::FreeModelUsage => {
GrokInferenceTransportErrorKind::ModelQuotaExhausted
}
}
}
fn model_access_denied(metadata: &InferenceErrorMetadata) -> bool {
metadata.message.as_deref().is_some_and(|message| {
let message = message.to_ascii_lowercase();
+1 -14
View File
@@ -403,18 +403,7 @@ async fn xai_admin_provider_restores_full_pending_envelope_and_binds_owner() {
let flow_id = "pending-envelope";
let owner_ref = admin_session_owner_ref("admin-owner");
let payload = pending_payload(flow_id, &owner_ref);
pending.insert(flow_id, owner_ref, payload.clone());
let mutation = payload
.expose_to_provider()
.get("mutation")
.and_then(Value::as_object)
.expect("pending mutation");
assert_eq!(mutation.get("expected_config_revision"), None);
assert_eq!(
mutation.get("started_request_id").and_then(Value::as_str),
Some("request-start")
);
pending.insert(flow_id, owner_ref, payload);
let wrong_owner = bundle
.admin_provider()
@@ -610,8 +599,6 @@ async fn xai_admin_provider_projects_cached_quota_models_and_canonical_export()
assert_eq!(window_data["onDemandCapCents"], 500);
assert_eq!(window_data["onDemandUsedCents"], 100);
assert_eq!(window_data["prepaidBalanceCents"], -500);
assert!(!window_data.contains_key("monthlyLimitCents"));
assert!(!window_data.contains_key("includedUsedCents"));
let models = admin
.models(account.id(), false)
.await
@@ -26,7 +26,7 @@ fn repository() -> (Arc<MemoryProviderAccountStore>, GrokCredentialRepository) {
}
#[tokio::test]
async fn create_persists_plaintext_oauth_json_without_envelope_fields() {
async fn create_persists_oauth_method_and_tokens_in_provider_json() {
let (store, _) = repository();
let input = create_input("plain", "subject-plain");
seed_input(&store, &input).await.expect("create account");
@@ -47,8 +47,6 @@ async fn create_persists_plaintext_oauth_json_without_envelope_fields() {
object.get("refresh_token").and_then(|v| v.as_str()),
Some("refresh-plain")
);
assert!(!object.contains_key("secret_envelope"));
assert!(!object.contains_key("secret_key_id"));
}
#[tokio::test]
@@ -159,8 +159,7 @@ impl GrokEndpointPolicy for CatalogExitPolicy {
timeout: Option<Duration>,
proxy: Option<&OutboundProxy>,
) -> Result<reqwest::Client, GrokReqwestTransportBuildError> {
// “直连”也终止于本地 sink,旧实现漏代理时不会触达真实上游
// 显式代理分支仍使用生产构造器及官方 HTTPS/CONNECT 目标
// 直连请求落到本地监听器,显式代理请求通过生产构造器连接 HTTPS 目标
OfficialGrokEndpointPolicy
.build_inference_client(timeout, Some(proxy.unwrap_or(&self.direct_sink)))
}
@@ -1604,6 +1604,10 @@ fn decoder_should_classify_free_quota_failed_event() {
.push(body.as_bytes())
.expect_err("free quota failure must surface");
assert_eq!(
error.diagnostic().unwrap().as_str(),
"上游账号免费额度已用完"
);
assert_eq!(
error.kind(),
gateway_core::error::ProviderErrorKind::QuotaExhausted
@@ -405,7 +405,7 @@ async fn inference_proxy_client_is_built_once_for_concurrent_same_binding() {
for task in tasks {
assert!(task.await.unwrap().iter().all(Result::is_ok));
}
// 启动时的直连 client + 一个代理 client;不再先构建并丢弃另一个直连 client
// 一个启动时创建的直连客户端和一个并发请求共用的代理客户端
assert_eq!(builds.load(Ordering::SeqCst), 2);
assert!(origin_server.received_requests().await.unwrap().is_empty());
}
@@ -918,6 +918,10 @@ async fn inference_transport_should_classify_free_usage_429_as_account_free_quot
error.kind(),
GrokInferenceTransportErrorKind::FreeQuotaExhausted
);
assert_eq!(
error.diagnostic().unwrap().as_str(),
"上游账号免费额度已用完"
);
assert_eq!(error.status(), Some(429));
assert_eq!(
error.upstream_code().map(|code| code.as_str()),
@@ -1097,7 +1097,7 @@ fn history_sanitizer_should_only_strip_known_grok_injection_sites() {
.expect("history normalization");
let body = Value::Object(encoded.body().clone());
// 工具 schema 里恰好叫 phase 的属性与语义 null 不再被误删
// 工具 schema 内的属性名和 null 值属于用户数据
assert_eq!(
body.pointer("/input/0/tools/0/input_schema/properties/phase"),
Some(&json!({"type": "string"}))
@@ -1312,7 +1312,7 @@ fn unsupported_tools_should_be_filtered_with_their_orphaned_choice() {
}
#[test]
fn ambiguous_tool_contracts_should_fail_before_upstream_io() {
fn invalid_responses_requests_report_the_offending_field() {
for (body, field) in [
(
json!({"model": "client", "input": "x", "tools": [
@@ -1339,33 +1339,34 @@ fn ambiguous_tool_contracts_should_fail_before_upstream_io() {
json!({"model": "client", "input": [{"type": "compaction_trigger"}]}),
"input",
),
(
json!({"input": [{"type":"local_shell_call", "call_id":"call_shell",
"action":{"type":"exec", "command":["pwd"]}}]}),
"input",
),
(
json!({"input": [{"type":"local_shell_call_output", "call_id":"call_shell", "output":"ok"}]}),
"input",
),
(
json!({"input":"hello", "response_format":{"type":"json_object"}}),
"response_format",
),
(
json!({"input":"hello", "reasoning_effort":"high"}),
"reasoning_effort",
),
(
json!({"input":"hello", "reasoningEffort":"high"}),
"reasoningEffort",
),
] {
let request = raw_request(body);
assert_eq!(
GrokResponsesRequest::encode(&request, "grok-4.5", &client_key())
.expect_err("invalid tool contract"),
GrokRequestEncodeError::InvalidRequestField { field }
);
}
}
#[test]
fn retired_wire_formats_are_rejected_without_fallback() {
for field in ["response_format", "reasoning_effort", "reasoningEffort"] {
let mut body = json!({"input":"hello"});
body[field] = json!("high");
assert!(
GrokResponsesRequest::encode(&raw_request(body), "grok-4.6", &client_key()).is_err()
);
}
for kind in ["local_shell_call", "local_shell_call_output"] {
assert!(
GrokResponsesRequest::encode(
&raw_request(json!({"input":[{"type":kind,"call_id":"old"}]})),
"grok-4.6",
&client_key()
)
.is_err()
.expect_err("invalid Responses request"),
GrokRequestEncodeError::InvalidRequestField { field },
"{field}"
);
}
}
+7 -15
View File
@@ -1,10 +1,8 @@
# 数据库迁移
sqlx 在服务启动、监听请求之前按编号执行迁移,并把文件 checksum 记入 `_sqlx_migrations`。
已应用迁移的字节与记录不一致时,服务会拒绝启动
服务监听请求前,sqlx 按编号执行本目录的 SQL,并将文件校验和写入 `_sqlx_migrations`。已应用文件的校验和不匹配时,服务拒绝启动
迁移按递增编号组织,完整清单以本目录 SQL 文件和 `.frozen-sha256` 为准。
业务状态与存储职责见[状态所有权](../../docs/architecture.md#8-状态所有权),离线恢复见[部署文档](../../deploy/README.md#人工恢复数据库)
[状态所有权](../../docs/architecture.md#8-状态所有权) · [离线恢复](../../deploy/README.md#人工恢复数据库)
## 命名约定
@@ -15,7 +13,7 @@ sqlx 在服务启动、监听请求之前按编号执行迁移,并把文件 ch
## 冻结规则
- 同一大版本内,已合入 main 的迁移文件**按字节永久冻结**,包括注释和空白。schema 变更及错误修正都须新增编号迁移,使用 `alter` 或回填补偿;修改原文件会导致已部署实例重启时 checksum 失配,且没有自动恢复路径
- 同一大版本内,合入 `main` 的迁移文件**按字节永久冻结**,包括注释和空白。修改 schema 或修正错误须追加编号迁移,使用 `alter` 或数据回填
- 跨大版本不支持在线升级,目标版本必须使用全新数据目录部署;此时可将已完成升级的 schema 折叠为新的初始化基线
- 支持连续升级的预发行线从首次发布起同样冻结迁移。alpha、beta、rc 到对应正式版必须保留
已发布迁移的编号与字节;同一轮 exp 的后续发行也只能追加迁移。发布前以该发行线已发布版本
@@ -30,7 +28,7 @@ cd backend/migrations
sha256sum --check --strict .frozen-sha256
```
遇到 checksum 不一致,先核对运行版本和文件来源;不要修改数据库中的 checksum 来绕过校验
校验和不一致时无法自动恢复。核对运行版本与文件来源,不要改写数据库中的校验和
## 本地测试库
@@ -41,19 +39,13 @@ export CPR_TEST_DATABASE_URL='postgres://<user>:<password>@127.0.0.1:5432/<db>'
export CPR_TEST_REDIS_URL='redis://:<password>@127.0.0.1:6379'
```
插件 Runtime 的真实子进程与持久化测试优先使用 `CPR_PLUGIN_TEST_DATABASE_URL` 和
`CPR_PLUGIN_TEST_REDIS_URL`。设置插件数据库变量时必须同时提供对应 Redis 变量;未设置插件数据库变量时,
使用上述标准测试服务。两种配置遵守相同的密码与隔离要求;缺少服务时的跳过和 CI 失败规则也相同
插件 Runtime 的真实子进程与持久化测试可使用专用的 `CPR_PLUGIN_TEST_DATABASE_URL`,此时须同时设置 `CPR_PLUGIN_TEST_REDIS_URL`。省略插件数据库 URL 时使用上面的测试服务
测试自建随机 schema / key 前缀做隔离,但仍应使用专用开发或测试实例,不要连接生产库。
凭据从自己的部署配置或 CI Secret 中读取,不要粘贴未脱敏的 `docker inspect` 输出。
环境变量未设置导致的跳过不算数据库测试通过
使用专用开发或测试实例,测试通过随机 schema 和 Redis key 前缀隔离数据。凭据取自部署配置或 CI Secret,不要分享未脱敏的 `docker inspect` 输出
PostgreSQL 的临时 schema 测试连接使用异步提交,保留事务可见性、回滚和完整迁移检查
需要验证数据库崩溃后的持久性时,使用独立数据库与生产连接配置,不复用这类 fixture
运行包含 `StoreBundle` 初始化的完整集成测试时,两条测试 URL 都须包含密码,原始密码须满足
[Store 密码要求](../../deploy/README.md#手动安装),在测试 URL 中按 URL 规则编码。
仅能连接数据库并不代表该初始化合同通过。专用服务使用对应测试密码,
并在测试进程中清除 `CPR_DATABASE_URL`、`CPR_REDIS_URL`、`CPR_DATABASE_PASSWORD` 和
`CPR_REDIS_PASSWORD`,避免启动配置被部署环境覆盖
在测试进程中清除 `CPR_DATABASE_URL`、`CPR_REDIS_URL`、`CPR_DATABASE_PASSWORD` 和 `CPR_REDIS_PASSWORD`,避免部署环境覆盖测试配置
+53 -55
View File
@@ -1,8 +1,6 @@
# 部署与运维
首次安装可按 [快速开始](../README.md#快速开始) 操作。
本文补充客户端配置、权限、备份和升级;部署命令从安装目录 `codex-proxy-rs/` 执行,
其中 `deploy/` 存放 Compose 文件和配置,`.runtime/` 存放持久化数据
首次安装见[快速开始](../README.md#快速开始)。部署命令在安装目录 `codex-proxy-rs/` 执行。`deploy/` 存放 Compose 文件和配置,`.runtime/` 存放持久化数据
| 任务 | 入口 |
| --- | --- |
@@ -14,8 +12,6 @@
## 配置归属
配置按职责保存,不都在 YAML 中:
| 位置 | 内容 | 修改方式 |
| --- | --- | --- |
| `deploy/config.yaml` | 监听、数据库/Redis 连接、部署凭据、时区、日志与可选内存分配策略等启动配置 | 从模板创建,已有部署合并修改,不覆盖原文件 |
@@ -237,11 +233,29 @@ flowchart LR
网关端口默认只绑定本机;数据库和 Redis 不对公网开放。插件以网关同一系统身份运行,不能作为不可信代码沙箱
## 安装脚本选项
[一键安装](../README.md#快速开始)需要当前用户能访问 Docker,并可通过 `sudo` 或 root 设置目录权限。脚本会启动网关、PostgreSQL 和 Redis,首次安装完成后输出访问地址和管理员密码
运行 `bash install.sh` 时可设置以下环境变量:
| 变量 | 用途 | 默认值 |
| --- | --- | --- |
| `INSTALL_DIR` | 安装目录,建议使用绝对路径 | 当前目录下的 `codex-proxy-rs/` |
| `CPR_RELEASE_TAG` | 指定发布标签 | 最新正式版本 |
| `ADMIN_PASSWORD` | 管理员初始密码,至少 12 位,不含 `$` 或控制字符,不能使用常见弱口令 | 随机生成 |
例如,将服务安装到指定目录:
```bash
INSTALL_DIR="$HOME/services/codex-proxy-rs" bash install.sh
```
重复运行时使用同一安装目录。检测到 `deploy/config.yaml` 后,[脚本](install.sh)会保留现有配置与部署文件,忽略传入的管理员密码。版本升级见[镜像升级与源码构建](#镜像升级与源码构建)
## 手动安装
本节适用于 Linux amd64/arm64,需准备 Docker Engine、Docker Compose Plugin、curl 和 OpenSSL,
并确保当前用户能访问 Docker、可通过 `sudo` 或 root 设置目录权限。一键安装入口见
[快速开始](../README.md#一键安装),脚本会自动完成本节准备和服务启动
Linux amd64/arm64 需要 Docker Engine、Docker Compose Plugin、curl 和 OpenSSL。当前用户须可访问 Docker,并能通过 `sudo` 或 root 设置目录权限
下载同一正式 Release 的部署文件并设置目录权限:
@@ -390,11 +404,9 @@ PostgreSQL/Redis 启动密码。日常校验使用 `config --quiet`
### 安装管理端应用
使用 Chrome、Edge 等支持 PWA 的浏览器访问管理端,可通过地址栏或浏览器菜单安装应用,安装后以独立窗口打开站点首页,沿用现有登录流程
用 Chrome、Edge 等支持 PWA 的浏览器通过 HTTPS、`http://localhost` 或 `http://127.0.0.1` 访问管理端,从地址栏或浏览器菜单安装。入口是否显示取决于浏览器、访问交互及安装状态
首次在 Chrome 中安装时,系统标题栏可能显示应用名称。可用窗口右上角的标题栏按钮隐藏名称,隐藏后仍可拖动顶部空白区域移动窗口
安装入口要求 HTTPS,或本机的 `http://localhost`、`http://127.0.0.1`;普通 HTTP 局域网地址不满足条件。入口是否显示还取决于浏览器、访问交互及是否已安装。应用需要联网访问网关,不提供离线使用
应用在独立窗口打开首页,须联网并按原流程登录。Chrome 窗口右上角可隐藏标题栏名称,顶部空白区域仍可拖动窗口
### 启动后的运行设置
@@ -405,7 +417,7 @@ PostgreSQL/Redis 启动密码。日常校验使用 `config --quiet`
| 上游客户端身份 | “系统设置 → 上游配置 → 客户端身份”;Key 可按 Provider 覆盖,OpenAI Key 可独立配置[安装身份种子](../docs/api.md#key-客户端身份) |
| 并发与排队 | “系统设置 → 运行设置”;Key 与账号分别设置排队容量和超时,可选择账号排队失败后换号,见[排队规则](../docs/api.md#并发与排队) |
| 账号错误保护 | “系统设置 → 运行设置 → 错误保护”;默认关闭,按[自定义规则](../docs/api.md#账号错误保护)暂停账号调度 |
| 全局请求位置 | “系统设置 → 上游配置 → 请求位置覆盖”;默认关闭,不从 YAML 导入 |
| 全局请求位置 | “系统设置 → 上游配置 → 请求位置覆盖”,默认关闭 |
| 代理位置 | “代理管理”;优先于全局位置,全局关闭时仍可独立生效 |
位置覆盖只影响 OpenAI 请求中受支持的位置与时区信息,不改变上下文日期、真实出口 IP、epoch 时间戳或系统时区。
@@ -532,6 +544,9 @@ OpenAI Responses 上游 WebSocket 每 25 秒发送 Ping 保活,并回应上游
修改上限对后续请求生效,已存在的连接继续计数;调低上限不会强制中断在途或绑定下游 WS 的连接。
预算仅覆盖宿主原生 OpenAI Responses 连接,插件自建连接及其他 HTTP/WS 流量仍需预留容量
允许回退 HTTP 的 Responses 新链和持久化续接,由 `openai.ws_pool.fast_path_budget_ms` 控制前台等待上游 WS 建连的时长,默认 800 毫秒,可设为 1–15000 毫秒,重启应用后生效。
超出预算时,本次请求走 HTTP/SSE,已启动的池化建连在后台继续。高延迟出口可调大该值,代价是仍需回退的请求会等得更久
未绑定活跃客户端 WS 的池化连接,归池后按 `openai.ws_pool.idle_timeout_ms` 计时,默认 `300000`(5 分钟,必须大于零)。
Ping/Pong 不延长空闲期限;默认每 5 秒扫描,通常在空闲 300~305 秒开始回收,复用前也检查是否到期。
关闭先停止复用,最多等待 1 秒发送 Close,随后终止并等待 socket 释放,容量在物理连接释放后才归还。
@@ -598,7 +613,13 @@ Caddy 与应用同在容器网络时,将回源地址改为 `codex-proxy-rs:808
## 客户端配置
在管理端创建客户端密钥。Responses、Chat Completions 和 Anthropic Messages 客户端的 Base URL 见[客户端接入](../README.md#客户端接入);
在管理端创建客户端密钥,将其填入 API 客户端的 API Key 字段。根据客户端自动追加的请求路径选择 Base URL,远程接入时将 `http://127.0.0.1:8080` 替换为网关的 HTTPS 地址
| 客户端自动追加的路径 | Base URL(本机部署) |
| --- | --- |
| OpenAI Responses `/responses`、Chat Completions `/chat/completions` | `http://127.0.0.1:8080/v1` |
| Anthropic Messages `/v1/messages` | `http://127.0.0.1:8080` |
直接发送 HTTP 请求可参考 [Messages 示例](../docs/api.md#messages-请求)
使用 Codex 时,打开「使用密钥」,按操作系统复制 `config.toml`。
@@ -683,14 +704,12 @@ Codex OAuth 账号的上游传输方式默认 WS;固定为 SSE 的账号不承
### 语音通话
Codex 0.164.0 的 `/voice` 通过 Provider 的 `base_url` 创建通话,控制连接另用顶层
`experimental_realtime_ws_base_url`,不会自动继承 Provider 地址。两者应指向同一网关的 `/v1`,
使用相同的代理密钥,并确保反向代理允许 WebSocket Upgrade。此设置独立于 Responses 的
`supports_websockets` 开关
使用 `/voice` 时,将 Provider 的 `base_url`(创建通话)和顶层 `experimental_realtime_ws_base_url`(控制连接)
都设为同一网关的 `/v1`,使用同一把客户端密钥。若单独设置了 `experimental_realtime_webrtc_call_base_url`,也要指向该地址。
顶层设置写在第一个 TOML 表之前,保存后完全退出并重启 Codex
已有配置需把 `experimental_realtime_ws_base_url` 合并到第一个 TOML 表之前,修改后完全退出并重启
Codex。创建通话成功后仍报 `realtime websocket handshake failed` 时,先检查客户端日志中的
`connecting realtime websocket` 是否指向网关;若仍为 `api.openai.com`,说明控制连接未经过代理
反向代理须允许 WebSocket Upgrade,Responses 的 `supports_websockets` 开关不影响语音。
若通话已创建但报 `realtime websocket handshake failed`,检查客户端日志中 `connecting realtime websocket` 的目标是否为网关
语音使用具备上游权限的 OAuth 账号,音频流由客户端与上游直接传输,路由与限制见
[Codex Live 语音通话](../docs/api.md#codex-live-语音通话)
@@ -881,15 +900,9 @@ OAuth 恢复开关为 `host.logging.oauth_recovery`,默认关闭,与普通
## 密码语义
- `admin.default_password` 只在首次创建管理员时使用
- 已有管理员在「系统设置 → 安全与访问 → 管理员密码」修改登录密码,需要验证当前密码;修改后所有管理员会话失效,使用新密码重新登录
- PostgreSQL 官方镜像只在空数据目录初始化时使用 `database.password`
- Redis 在每次容器创建时使用 `redis.password`
已有 PostgreSQL 数据目录后,直接修改 `database.password` 不会修改数据库用户密码,只会导致
应用无法连接。轮换时必须先在 PostgreSQL 中修改用户密码,再同步更新 `config.yaml`。Redis
密码变更后需要用新配置重新创建 Redis 和应用容器,不需要删除 Redis 数据目录。
安排维护窗口,避免应用和 Redis 在过渡期间使用不同密码
- **管理员**:`admin.default_password` 只在创建首个管理员时使用。已有管理员在「系统设置 → 安全与访问 → 管理员密码」验证当前密码后修改,所有管理员会话须重新登录
- **PostgreSQL**:镜像只在空数据目录初始化时设置 `database.password`。轮换须先修改数据库用户密码,再同步更新 `config.yaml`,否则应用无法连接
- **Redis**:容器创建时读取 `redis.password`。在维护窗口更新配置并重新创建 Redis 和应用容器,保留数据目录
## 镜像升级与源码构建
@@ -927,15 +940,13 @@ docker compose -f deploy/compose.yaml build codex-proxy-rs
### 升级前检查
- OpenAI 或 xAI 授权使用已保存代理,且代理的 WebSocket 连接上限非零:升级或回退后,重新发起尚未完成的授权,不复用旧回调或授权码。上限为 `0` 的在途授权和已保存的账号、凭据不受影响
- Key 配置含 `installationId`:数据库自动转换为 `installationSeed`,API 调用方须使用[当前字段](../docs/api.md#key-客户端身份)。出站安装身份及关联的会话、缓存标识会变化,已有 WebSocket 精确续写需重发完整上下文
- 数据库或备份含 `accountAutoFreeze*` 设置:升级后错误保护关闭、规则为空,需在管理端重新配置并启用;API 调用方使用 [`accountErrorProtection`](../docs/api.md#账号错误保护)。已有冻结到当前冷却截止后解除,账号并发上限保留,需调整时手动设置
- OpenAI 或 xAI 的在途授权若因代理 WebSocket 连接上限与保存值不匹配而失败,须重新发起授权,使用新的回调和授权码
- Key 配置含 `installationId` 时,迁移会将其转为 `installationSeed`。API 调用方使用[安装身份种子](../docs/api.md#key-客户端身份)。这些 Key 的安装身份、会话与缓存标识会变化,WebSocket 精确续写须重发完整上下文
- 数据库或备份含 `accountAutoFreeze*` 设置时,迁移后错误保护默认关闭、规则为空。需要保护的部署须配置并启用 [`accountErrorProtection`](../docs/api.md#账号错误保护)。已有冻结到期解除,账号并发上限保留原值
### 版本命名与升级规则
管理端「系统更新」可临时选择通道检查更新,不保存选择,不会自动下载或安装。
每次打开弹窗按当前运行版本匹配通道:正式版为 Stable,预发行按版本后缀匹配。
升级并重启后按新运行版本匹配;侧栏更新提示始终使用当前运行通道。预发行编号 `N` 从 1 开始递增
侧栏按运行通道提示更新。「系统更新」弹窗默认使用该通道,可临时切换,检查不会触发下载或安装。预发行编号 `N` 从 1 开始递增
| 通道 | 命名示例 | 接收的版本 |
| --- | --- | --- |
@@ -945,9 +956,7 @@ docker compose -f deploy/compose.yaml build codex-proxy-rs
| Alpha | `X.Y.Z-alpha.N` | Alpha、Beta、RC、正式版 |
| Exp | `X.Y.Z-exp.N` | 同一轮实验中编号更高的 exp,仅实验实例可选 |
普通通道在同一大版本内持续接收更高版本,包括后续小版本和补丁版本的预发行。
切换通道不会降级,Stable 候选也必须高于当前运行版本。
下载、安装或待重启期间不能切换通道
普通通道只接收同一大版本内高于运行版本的候选,包括表中允许的小版本和补丁预发行。下载、安装或待重启期间不能切换通道
更新器读取更新仓库 `main` 分支的 `release/version.yaml`。`version` 是源码构建版本,只有 `published` 中当前大版本和通道对应的版本才参与更新检查
@@ -960,10 +969,7 @@ docker compose -f deploy/compose.yaml build codex-proxy-rs
exp 不进入正式版、alpha、beta 或 rc,普通实例也不能选择 Exp。
从 exp 切换正式版时需先备份,在目标版本的独立数据库中迁移业务数据,不能直接复用或整库还原实验数据库
版本大小遵循 [SemVer](https://semver.org/),构建元数据 `+...` 不参与比较。未知预发行标识不提供在线更新。
更新器先过滤不允许的目标,再选择版本最高的候选;其他通道或更高大版本领先,不影响当前发行线的更新。
只有当前官方构建满足在线更新条件且存在允许安装的新版本时,才返回“有可用更新”。否则不显示更新标记、
其他通道的版本及发布说明,手动检查显示“当前没有可用更新”。检查失败单独报告,不能当作没有更新
更新器按 [SemVer](https://semver.org/) 选取允许的最高版本,忽略构建元数据 `+...`。未知预发行标识不支持在线更新。无候选时,手动检查显示“当前没有可用更新”,检查失败单独提示
alpha、beta、rc、exp 在 GitHub 标记为 Pre-release,不覆盖 GitHub Latest 或镜像 `latest`。
升级前确认 PostgreSQL 满足目标版本的[部署要求](#部署结构)。可连续升级的发行线与约束见[迁移冻结规则](../backend/migrations/README.md#冻结规则)
@@ -1031,27 +1037,21 @@ Release 必须提供当前 OS/架构的 `codex-proxy-rs_<version>_<os>_<arch>.ta
| `plugins/official/plugin-release-manifest.json` | 随平台安装包和镜像分发,记录宿主版本、提交与支持的插件合同 |
| 可执行文件同目录的 `plugins/official` | 随受信宿主发行物部署的只读目录,与二进制、Web 资源成套更新或恢复 |
- 下载更新时校验发行身份,插件合同不兼容不阻止安装。点击重启时检查已安装目标版本,列出不兼容插件的名称和原因;确认后重启,不兼容实例保持未启动,启用配置、绑定、密钥和私有数据保留
- 回滚同样在重启前提示插件兼容风险,启动时重新检查,不改写持久启用配置。更新或回滚期间的并发配置变更会阻止切换,文件替换失败或取消时恢复整组文件
- 更新和回滚时校验发行身份。插件版本不兼容仍可安装,重启前列出受影响的插件和原因,由管理员确认。并发配置变更阻止切换,文件替换失败或取消时恢复整组文件
- 非空官方清单中的包经身份、平台和摘要校验后幂等导入;导入不确认信任、不创建配置、不启用,也不删除旧包。管理员确认信任后才执行默认配置流程;重复摘要保留首次安装出处
- `sealed` 是构建封口标记,不是密码学签名。普通上传、URL 或 GitHub 安装不能获得 `builtin` 身份,独立教学示例也不例外
宿主启动检查覆盖管理页更新、Docker 与手工替换二进制。不兼容实例不挂载任何能力或故障占位,其额外认证和拦截停止生效,宿主原生认证继续执行。
宿主范围或能力版本不匹配时,可在插件页确认风险后尝试本次启动;清单、RPC、平台或包完整性错误不能绕过。具体操作见[插件故障处理](../docs/plugins.md#故障处理)
所有部署在启动时检查插件兼容性。不兼容实例保持未启动,保留配置、绑定、密钥和私有数据。原生认证继续执行,插件提供的认证和拦截不生效。可确认的版本风险与须更换包的错误见[插件故障处理](../docs/plugins.md#故障处理)
部署须保留完整的二进制、Web 资源与官方插件目录;不要手动修改制品元数据或迁移 checksum 绕过校验。
插件安装包必须匹配宿主 OS 和架构,部署前需验证目标平台的插件运行与上游调用,不能只以打包成功判断可用
## 备份与恢复
管理端 S3/R2 提供业务备份;需要完整请求历史时,另做 PostgreSQL 整库备份或基础备份与 WAL 归档
不要在 PostgreSQL 写入期间直接复制数据目录作为一致性备份
| 需要保留的内容 | 备份方式 |
| --- | --- |
| 账号、Key、设置、插件、已用额度与用量汇总 | 管理端 S3/R2 业务备份 |
| 完整请求、诊断和审计历史 | 独立整库备份,或停库后备份 `.runtime/postgres` |
| 完整请求、诊断和审计历史 | PostgreSQL 整库备份、基础备份与 WAL 归档,或停库后备份 `.runtime/postgres` |
| 部署配置与凭据 | 单独备份 `deploy/config.yaml` 及 Compose 自定义配置 |
| 应用日志与已启用的 OAuth 恢复记录 | 单独备份 `.runtime/logs`,不包含在数据库归档中 |
| 会话锚点与节点运行文件 | 按需备份 `.runtime/data` |
@@ -1064,9 +1064,7 @@ OpenAI 主动额度重置卡及消费结果由上游持有,不属于本地备
### 备份内容与限制
业务归档为 `.sql.gz`,保留完整数据库结构和迁移记录,但不包含请求明细、诊断与审计日志、
逐请求费用去重记录和可重建的统计明细。Key 当前日、周的边界与已用额度独立保留。
恢复后,已有窗口可继续使用;更改边界时不能重算恢复前的消费,以恢复后开始的新周期接续即可。
从未记录费用历史完整范围的版本升级时,宿主以库中最早留存的费用判断可重算范围;没有费用事件时采用升级时间
逐请求费用去重记录和可重建的统计明细。归档保留 Key 当前日、周的窗口边界与已用额度。恢复后可沿用原窗口,更改边界须从恢复后的新周期开始
原生用量按 UTC 小时保留全局请求数、成功/失败数、Token 和实际费用,每小时至多一行;
插件维护的用量贡献按其原维度保留。原生汇总只覆盖备份快照中已发布且尚未被历史清理撤销的统计,
+2 -1
View File
@@ -85,11 +85,12 @@ openai:
residency: us
# 账号路由参考值:us、us_cr
account_routing_override: null
# 可选:完整的 Responses 上游 WS 池配置;省略整段使用以下默认值。
# Responses 上游 WS 池配置,可单独覆盖下列默认值
# ws_pool:
# enabled: true
# max_age_ms: 3300000
# max_connecting: 8
# fast_path_budget_ms: 800 # 回退 HTTP 前等待 WS 建连的时长,范围 1–15000 毫秒
# idle_timeout_ms: 300000 # 仅回收未绑定活跃客户端 WS 的空闲连接,必须大于零。
# stream_idle_timeout_ms: 300000
+59 -71
View File
@@ -1,8 +1,6 @@
# Codex Proxy RS 接口
本文描述当前源码的公开 HTTP 合同,路由以 `backend/crates/gateway-api/src` 中的 router 为准
配置客户端见[部署文档](../deploy/README.md#客户端配置),内部职责见[系统架构](architecture.md),部署实例的功能以实际运行版本和 revision 为准
公开 HTTP 路由位于 `backend/crates/gateway-api/src`。客户端接入见[部署文档](../deploy/README.md#客户端配置),模块职责见[系统架构](architecture.md)
| 查找内容 | 入口 |
| --- | --- |
@@ -26,8 +24,7 @@
Authorization: Bearer sk_...
```
自动生成的 Key 保持 `sk_` 格式;迁入的自定义 Key 使用保存时的原值,不限制前缀或固定长度。
无论格式如何,只有已保存且启用的 Client Key 能通过鉴权
自动生成的 Key 以 `sk_` 开头,自定义 Key 按原值鉴权,无固定前缀或长度。仅已保存且启用的 Key 有效
`/v1/messages`、`/v1/messages/count_tokens`、`/v1/models` 和 `/v1/models/{model_id}` 也接受 `x-api-key: <Client Key>`。
同时提供两个认证头时优先使用 `Authorization`;客户端提交的是网关 Client Key,上游密钥由选中的账号提供
@@ -55,6 +52,10 @@ Client Key 通过账号分组限定路由范围:未绑定分组时可使用全
`codex_python_sdk`、`codex-app-server`、`codex-app-server-sdk` 与 `codex_mcp_server`
名称按完整标识匹配且不区分大小写,括号后缀中的应用或 SDK 版本不能替代 Core 版本
TUI 连接共享 App Server 时,User-Agent 可以是 `Codex Desktop/<Core 版本> … (codex-tui; <TUI 版本>)`。
这种请求按 CLI 门槛检查前缀中的 Core 版本,`version` 头可以省略或与 Core 版本相同。
若该头提供不同的值,或 UA 另含 Desktop 应用版本后缀,则按 Desktop 规则校验
Desktop 应用版本优先取 `version` 头,未提供时取 User-Agent 中的 `(Codex Desktop; <版本>)`。
ChatGPT 远程控制使用 `(codex_chatgpt_<平台>_remote; <版本>)` 形式的 User-Agent 后缀,已知平台包括
`android` 和 `ios`。网关按该命名格式识别非空的平台名,后缀须完整,平台名和版本均不能含空白、括号或分号。
@@ -168,7 +169,7 @@ Codex PAT 验证服务不可用和身份响应无效分别返回 `50301`、`5020
`YYYY-MM-DD HH:mm:ss`,短时间、相对时间和图表标签按对应视图返回;缺失时间的展示字段为 `null` 或占位文本。
调用者直接显示文本,使用原始时间点进行排序、比较和输入,不把展示文本转回请求时间
账号、模型用量和 Key 列表的最近使用时间由前端根据原始 RFC3339 时间点,通过 VueUse `useTimeAgoIntl` 按界面语言显示短相对时间,并随时间更新;悬停的完整日期仍使用后端 `lastUsedAtFullDisplay`,不使用浏览器本地时区重算
账号、模型用量和 Key 列表使用 RFC3339 时间点 `lastUsedAt` 显示随时间更新的本地化相对时间,悬停时显示服务端返回的 `lastUsedAtFullDisplay`
Dashboard 的 `lastUsedRelative` 和账号额度的 `refreshedAtRelative` 由后端确定时间语义,
分别以查询锚点和服务端当前时间计算,随接口刷新更新。前端只翻译分类与单位,不使用浏览器时钟或时区重算
@@ -178,7 +179,7 @@ Dashboard 的 `lastUsedRelative` 和账号额度的 `refreshedAtRelative` 由后
- `kind=elapsed` 包含整数 `value` 和 `unit=minute|hour|day`,分钟不足 60、小时不足 24,之后始终用天;数值向下取整
- `kind=absolute` 的 `value` 是后端按部署 `host.timezone` 生成的完整日期文本,用于按整秒判断的未来时间点
原始 RFC3339 `lastUsedAt`、`quota.refreshedAt` 与兼容展示字段保持可用,不用于前端重新决定上述展示方式
账号额度的原始刷新时间为 RFC3339 字段 `quota.refreshedAt`
账号冷却返回 RFC3339 `rateLimitedUntil` 和 `rateLimitRecoveryDisplay`,后者包含剩余时长、
到期时间或等待恢复探测的提示,随账号数据刷新;前端不解析展示文本或自行计算恢复提示
@@ -302,9 +303,8 @@ print(completion.choices[0].message.content)
`logit_bias` 和 `prediction` 没有对应的 Responses 控制语义,接受后忽略,不保证生效。
消息的 `reasoning_content` 和 `reasoning` 作为辅助历史忽略,不转为用户正文
本地保留以下限制:`n` 只能为 `1`,`store` 和 `background` 只能为 `false`,
`modalities` 只能为 `["text"]`,旧式 `functions` 只能为空数组;这些字段也可省略或为 `null`。
非空旧式函数定义、`function_call`、旧式 `function` 角色、音频输出以及无法映射的内容类型会被拒绝。
`n`、`store`、`background`、`modalities` 和 `functions` 可省略或为 `null`。非空值仅接受 `n: 1`、`store: false`、`background: false`、`modalities: ["text"]` 和 `functions: []`。
网关拒绝 `function_call`、`function` 消息角色、音频输出和无法映射的内容类型。
入口不接收 `input`、`previous_response_id` 或 `conversation`;需要服务端续接时使用 `/v1/responses`
未知客户端附加字段在协议包装对象中忽略,不据名称自动转交 Responses;schema、metadata、工具参数和
@@ -351,11 +351,10 @@ Responses 上游使用 `$.input`,Messages 上游使用 `$.messages`
转向 OpenAI Responses 上游时,`max_tokens` 仍为入站必填字段,但不限制实际输出。
消息角色为 `user`、`assistant` 或 `system`,`content` 为字符串或内容块数组;初始系统指令放在顶层 `system`,
会话中的 `system` 消息保留其位置,具体模型支持情况由上游校验。
`stream` 缺省或 `false` 返回 JSON,`true` 返回 SSE。每轮由客户端携带所需的完整上下文。Claude Code 用 `--resume` 恢复本地会话后,仍通过 `messages` 发送上下文;网关不缓存对话正文用于下一轮。
Messages 没有服务端历史续接或 WebSocket 入口
`stream` 缺省或为 `false` 时返回 JSON,`true` 返回 SSE。每轮须通过 `messages` 发送完整上下文,包括 Claude Code 用 `--resume` 恢复的本地会话。此入口不支持服务端续接或 WebSocket
Messages 生成请求通过 OpenAI Provider 选号时,优先使用 `x-claude-code-session-id` 识别 Claude Code 会话,
缺少有效头部时读取 `metadata.user_id` JSON 字符串中的 `session_id` 或旧格式 `_session_<id>` 后缀。
缺少有效头部时,从 `metadata.user_id` 的 JSON 字符串读取 `session_id`,或读取字符串的 `_session_<id>` 后缀(此处 ID 只接受十六进制字符与连字符)。
会话标识最长 256 字节,不接受控制字符;普通用户标识和对话内容不用于绑定账号。
同一 Client Key 下的会话沿用[账号亲和与换号](#账号亲和与换号)设置,转向 Responses 上游时也适用
@@ -668,19 +667,14 @@ OpenAI Responses 上游 WS 按握手响应头 `x-codex-websocket-max-message-byt
此规则适用于所有客户端。下一步请求应在新连接上发送完整输入,省略 `previous_response_id`。
已接收的后续请求按序处理,若增量先到,仍按上述 400 合同恢复。启用 WS 帧中间件时保留连接
已建立模型执行的 HTTP 响应(生成请求、Messages 输入计数、Images 和 Search)按以下规则返回关联 ID:
`x-gateway-request-id` 为模型执行 ID;`x-request-id` 保留有效上游值,只有上游
`x-oai-request-id` 时复用其值,没有上游 ID 时使用模型执行 ID。`x-oai-request-id` 不是必需字段,
也不要求客户端识别它;OpenAI 与 xAI 路由使用相同规则。失败响应的关联 ID 不采用会话 opening ID,
错误正文读取失败时仍返回已知上游 ID;已采集的 turn state 等允许的会话头继续按原合同交付。
尚未建立执行的入口拒绝继续使用 middleware 的入口关联
生成请求、Messages 输入计数、Images 和 Search 的 HTTP 响应在建立模型执行后返回两个关联 ID,OpenAI 与 xAI 规则相同:
WebSocket 在尚未交付上游业务事件时合成的错误,除下述容量恢复合同外,保留已确认的失败状态,
以及 Provider 提取的结构化 message/type/code;没有结构化错误时使用稳定安全文案,不把原始
HTML 或截断正文当作 message。
合成错误自身的 `headers` 携带允许下发的响应头:优先保留实际失败的上游 request ID,无上游 ID 时
提供网关关联 ID,并用 `x-gateway-request-id` 独立标识网关请求。除下述客户端错误兼容与原生续写额度恢复外,
已经取得的原始上游错误帧不重写
- `x-gateway-request-id` 为模型执行 ID
- `x-request-id` 优先取有效的上游同名头,其次取上游 `x-oai-request-id`,最后取模型执行 ID
错误正文读取失败时仍返回已知上游 ID 与允许下发的会话头(如 turn state)。只有在建立执行前拒绝请求时才使用中间件的入口关联
WebSocket 在交付业务事件前合成的错误保留已确认的失败状态和结构化 `message/type/code`,容量恢复按[重试规则](#容量拒绝与重试)处理。缺少结构化错误时使用安全提示。错误的 `headers` 携带允许下发的响应头,优先返回失败的上游 request ID,缺失时使用网关关联 ID。`x-gateway-request-id` 单独标识网关请求
### 模型目录
@@ -722,11 +716,8 @@ OpenAI 聚合当前 Key 范围内合格 OAuth 和 API Key 账号的目录。每
服务启动时批量恢复账号目录;目录读取只检查本地账号资格和 Client Key 范围,不等待上游查询。
成功目录响应带 `Cache-Control: private, no-store`,不借用上游 ETag 标识经过选择/别名/聚合后的正文
`service_tiers` 的 `name` 用于生成 `/fast` 等命令,`id` 是请求使用的 `service_tier` 值,二者不能互换。
上游未声明或明确返回空数组时不补档位,也不根据模型名推断 Fast。
该合同对齐
[官方 Codex 0.154.0 的模型元数据](https://github.com/openai/codex/blob/6b9826e3aa83b1a5947db50f4332cb9c65f1b340/codex-rs/protocol/src/openai_models.rs)
与其动态服务档位命令;客户端需重新加载模型目录才能使用更新后的档位信息
`service_tiers` 中的 `name` 用于生成 `/fast` 等命令,`id` 用作请求的 `service_tier` 值。
上游未声明档位或返回空数组时,网关不补充档位。档位更新后,客户端需重新加载模型目录
Codex 专用目录中的 `context_window` 与 `max_context_window` 分别表示默认上下文窗口和客户端本地
覆盖的上限。OpenAI Provider 原样保留上游对应字段,缺失与 `null` 不互相转换;网关不通过部署配置
@@ -789,6 +780,9 @@ HTTP 瞬时建连失败(含 TLS 握手 EOF),或 WebSocket 新请求在发
`turn_rate_limit_exceeded` 保留原始错误和 `Retry-After`,由客户端按自身重试预算等待。
代理不因此写入账号冷却、换号或透明重试,其他会话仍可使用该账号
`/v1/responses` 流式请求尚未发出数据或心跳时,若上游 WS `error` 明确返回 400,
且网关判定为普通请求参数错误,客户端收到 HTTP 400 和原始 `error` 对象。
已发出数据或心跳时,同一错误通过 SSE `response.failed` 和 `[DONE]` 结束。
上游 WS `error` 转为 SSE `response.failed` 时,事件级的有效 `Retry-After` 同时放入
`response.error.headers`,供客户端读取;错误对象已有有效重试头时优先保留
@@ -1144,12 +1138,12 @@ call 与账号的绑定保存在网关进程内,未连接时一小时过期;
普通业务请求和状态轮询不会续期。管理员访问凭据到期后,仍可通过续期 Cookie 恢复登录;续期成功会轮换两种凭据,
并重新计算不活动期限,但不能超过登录时确定的最长有效期。访问凭据仍有效时,refresh 返回同一组凭据和期限。
轮换后 30 秒内重试上一代续期凭据返回同一组新凭据;超出窗口再次使用已识别的上一代凭据会撤销该会话。
续期已过期或会话已撤销时不会重新创建;未认证返回 `{ authenticated: false, session: null }`,不写 Cookie;依赖故障返回 503。
续期过期或会话已撤销时返回未认证状态,不重建会话或写入 Cookie。依赖故障返回 503。
退出可以只携带续期 Cookie,并清除两种 Cookie。Key 登录清除续期 Cookie,密钥身份会话保持固定期限。
期限配置见[部署配置](../deploy/README.md#手动安装)
每次恢复密钥会话时重新确认 Key 存在且启用;停用或删除后会话失效,重新启用不会恢复已撤销会话。
依赖不可用时返回 503,不返回已认证或假装未登录。预算耗尽不妨碍登录
密钥校验依赖不可用时返回 503。预算耗尽不妨碍登录
密钥会话访问管理接口返回 403,不清除仍然有效的会话。
浏览器会话不能替代 `/v1/*` 的 Client Key,Client Key 也不能替代浏览器会话
@@ -1523,7 +1517,7 @@ API 的 `autoLocation` 默认为 `false`;开启时使用已检测位置,测
导入请求可以携带顶层 `outboundProxyId`,在令牌交换前解析为默认出口;文件中显式的代理配置优先。
文件及 AT/RT 导入从凭据交换到落库期间保护所选代理;此时修改、删除或写入测试结果返回 409,
避免已轮换的凭据因代理状态变化而丢失。完成导入或请求取消后自动释放保护。
OAuth 等待回调期间不持有保护;提交仍拒绝已删除或连接配置改变的代理
OAuth 等待回调期间允许修改代理。提交时若代理已删除、停用,或地址、WebSocket 连接上限与授权开始时不匹配,须使用有效代理重新发起授权
### 账号连接测试 SSE
@@ -1797,7 +1791,7 @@ OpenAI 授权码交换与令牌刷新请求的连接超时为 30 秒,单次上
`quota_exhausted`。额度观测不会清除凭据过期、无效或封禁事实;这些事实统一投影为 `error`,并由
`errorReason` 区分。额度接口的 401/403 也不足以判定 refresh token 永久失效,credential 终态只由
OAuth refresh 的明确永久错误写入
- xAI 额度百分比只读取 `creditUsagePercent`,缺失时保持未知,不由旧月额度与用量计算。
- xAI 额度百分比取自 `creditUsagePercent`,缺失时为未知。
预付余额保留上游账本符号,非零余额及剩余按量额度可独立证明可用;窗口已过期或缺少可用证据时,
不凭旧快照恢复账号
- 正常 Responses 请求会解析上游响应的 rate-limit headers,合并进同一 quota 快照并同步状态。Free、
@@ -2060,15 +2054,14 @@ OpenAI Key 的 `installationSeed` 接受带连字符的 UUID,保存时规范
- 种子不发送给上游,也不改写账号凭据;更改或清除种子使生效身份变化时,WebSocket 精确续写须重发完整上下文
兼容字段 `openaiClientProfileOverride` 和 `xaiClientProfileOverride` 分别对应上述映射中的 `openai`、`xai`。
创建时省略或 `null` 表示无覆盖;更新时省略保留、`null` 清除。与通用字段同时提交时必须一致,否则拒绝整个请求;
响应中的兼容字段从同一映射派生,不是第二份配置
创建时省略或为 `null` 表示无覆盖。更新时省略保留,`null` 清除。与通用字段同时提交时须一致,否则整次请求被拒绝
### 名称与密钥值
密钥列表的 `search` 仅匹配名称和标签,不匹配密钥值或可见前缀;搜索不区分大小写,使用字面量包含匹配,`%`、`_` 和 `\` 按普通字符处理。
创建和更新时去除名称首尾空白,并按忽略大小写、首尾空格的名称查重,重复返回 `409`。
更新排除当前记录,并发写入同样执行查重;失败不会留下审计或配置版本变更。
历史重名数据不自动改名,已有凭据继续有效;再次保存时需使用未被其他密钥占用的名称
已有同名 Key 的凭据有效,编辑时须使用未被其他 Key 占用的名称
`customKey` 仅用于创建:省略、`null` 或空字符串时继续自动生成;非空时按原值保存,不追加前缀、
不截断、不修剪空白,也不要求固定长度。Key 须为 HTTP Bearer 可传输的非空可见 ASCII 字符,
@@ -2385,7 +2378,8 @@ Chat Completions 和 Responses 通过原生 OpenAI Provider 选号时,缺少
缺少必填系数、系数为 `null`、未知字段及无效数值均返回 `422`,不写入配置。读取设置额外返回只读
`smartSchedulingDefaults`,内容为上述默认对象,用于恢复默认与自定义状态比较,不可提交到更新接口
`resetWeight` 控制重置分在总评分中的比重。`resetWindowWeights` 中的 `fiveHour`、`weekly`、`monthly` 分别表示 5 小时、周和月的相对系数。三项均为 0~10、最多一位小数。默认均为 0,旧配置省略整个字段时也取 0;全部为 0 时不计重置分。设为 `{"fiveHour":0,"weekly":1,"monthly":0}` 可只按周重置评分。只计算账号通用窗口,未知、缺失或已过期的周期贡献为零
`resetWeight` 控制重置分在总评分中的比重。`resetWindowWeights` 的 `fiveHour`、`weekly`、`monthly` 分别是 5 小时、周和月的相对系数,取值为 0~10,最多一位小数。省略整个字段时三项均为 0。
全部为 0 时不计重置分。设为 `{"fiveHour":0,"weekly":1,"monthly":0}` 可只按周重置评分。只计算账号通用窗口,未知、缺失或已过期的周期贡献为零
`queueWeight` 只在没有可立即使用的账号、需要选择等待队列时参与评分,越大越偏向等待人数少的账号。
设为 `0` 时沿用最短队列规则;启用后结合其余五项评分选择队列。队列人数限于当前进程,只有开启账号排队才会生效,
@@ -2460,16 +2454,14 @@ models.dev 同步只导入可表示为当前文本 Token 计价的 OpenAI/xAI
更新时省略某项保留原值,对象替换该项,`null` 删除显式选择并使用 Provider 默认值;不清除其他 Provider 的配置。
配置内容由对应 Provider 校验,不包含账号凭据。Key 可通过 `providerRequestProfileOverrides` 整体覆盖所属 Provider 的选择
`openaiClientProfile` 与 `xaiClientProfile` 是同一映射的兼容字段:省略保留,不能显式提交 `null`;
与通用字段同时提供时必须一致,否则整次更新拒绝。读取响应从映射派生这两个字段,不维护平行状态
`openaiClientProfile` 与 `xaiClientProfile` 读写同一映射中的对应项。省略保留,显式提交 `null` 或与通用字段冲突时拒绝整次更新
直接读取 `openai` 或 `xai` 的选项与预览。OpenAI 选项返回六个 `presets` 与 `maxVersionLag`,xAI 返回 `defaults`;
响应均包含 `globalConfiguration`
### OpenAI 上游客户端身份
`openaiClientProfile` 保存通用选择,首次默认 `MacOS · Desktop · 自动最新`。
兼容字段的更新语义见上节。初始化不读取 YAML 身份字段。
OpenAI 通用身份默认使用 `MacOS · Desktop · 自动最新`。
该配置作用于 Client Key 的 OpenAI 模型请求,适用于 HTTP/SSE、WebSocket、Images 和 Search,
也用于账号模型目录的后台发现、手动刷新、导出及定时预热;下次执行时采用当前全局选择,不使用单个 Key 的覆盖。
不改变 xAI、入站客户端版本门禁、账号认证或后台 Desktop 专属操作
@@ -2538,9 +2530,7 @@ WebSocket 精确续写沿用所属连接;安装身份配置与变更限制见
### xAI 上游客户端身份
`xaiClientProfile` 保存 Grok CLI 的通用身份选择;首次使用内置 `grok-shell / headless / linux / x86_64`
并采用自动更新版本。初始化不读取 YAML 身份字段,数据库已有选择时不覆盖。
更新设置省略该字段保留现值,不能提交 `null`
Grok CLI 通用身份默认使用 `grok-shell / headless / linux / x86_64`,版本自动更新
| 字段 | 取值与语义 |
| --- | --- |
@@ -2743,8 +2733,7 @@ Dashboard 的当前账号摘要包含 `upstream`,结构与账号列表一致
| `GET` | `/api/admin/operations/errors` | 运维错误分页列表 |
| `GET` | `/api/admin/diagnostics/export` | 按 `requestId` 或 `errorId` 下载诊断 ZIP 附件 |
用量汇总的 `averageLatencyMsValue` 为可空毫秒数,前端按持续时长格式化;无延迟样本时为 `null`,
`averageLatencyMs` 保留为兼容展示字段
用量汇总的 `averageLatencyMsValue` 为平均延迟毫秒数,无样本时为 `null`。`averageLatencyMs` 提供格式化文本
### Dashboard 趋势指标
@@ -2782,7 +2771,7 @@ Dashboard 的 `capacityInfo` 统计普通容量,不含独立审批池;`maxCo
Dashboard 的 `accountUsage[]` 返回稳定指标 `metric=requests|tokens`、可空原始数值 `metricValueRaw` 和
可空 RFC3339 `lastUsedAt`;前端负责指标名称和数字本地化,相对时间按[页面时间合同](#页面时间合同)翻译 `lastUsedRelative`。
`requests` 使用代表性额度窗口的本地请求数,`tokens` 使用今日 Token;未知数值为 `null`,零值保留 `0`。
`metricLabel`、`metricValue` 和 `lastUsed` 保留给兼容调用方,当前管理端不解析或显示这些字段
`metricLabel`、`metricValue` 和 `lastUsed` 提供兼容的展示文本
`accountUsage[].notes` 为账号当前备注,无备注时为 `null`
@@ -2796,7 +2785,7 @@ Dashboard 的 `accountUsage[]` 返回稳定指标 `metric=requests|tokens`、可
Dashboard 默认 `period=today`,用量、诊断和错误查询默认 `period=7d`,范围参数遵循[页面时间合同](#页面时间合同)。
Dashboard 返回原始 `asOf` 及 `asOfDisplay`,作为当前数据的查询锚点
请求明细列表接受 `currentPage`、`pageSize`、时间范围、`provider`、`clientApiKeyName`、`accountSearch`、`model` 和 `status`。
请求明细列表接受 `currentPage`、`pageSize`、时间范围、`provider`、`clientApiKeyName`、`accountSearch`、`model`、`status` 和 `errorOrigin`。
汇总和洞察接受时间范围与 `provider`;性能和成本另要求 `metric`,诊断另接受 `dimension`、`model` 和 `statusCode`。
各接口拒绝未知参数,明细筛选不改变顶部统计范围
@@ -2806,7 +2795,11 @@ Dashboard 返回原始 `asOf` 及 `asOfDisplay`,作为当前数据的查询锚
重试中间错误不改变请求最终分类;`logicalOutcome` 保留真实结果。状态筛选只影响明细列表,
不改变顶部统计,独立运维事件仍通过 `/api/admin/operations/errors` 查询
请求列表的 `errorCode` / `errorMessage` 提供最终请求的错误码与错误信息,未记录时为 `null`。
当 `status=error` 时,可传 `errorOrigin=upstream|proxy|connection|unknown` 筛选错误来源。
省略时包含全部来源。筛选与列表、详情共用下述来源规则,并在统计总数和分页前与其他明细条件一同生效。
其他状态携带 `errorOrigin` 或来源值无效时返回 `400`
请求列表的 `errorCode` 保留已记录的错误码,`errorMessage` 是最终失败的安全摘要,例如账号额度耗尽或模型容量不足。两者各自缺失时为 `null`。
`clientStatusCode` / `upstreamStatusCode` 分别提供已记录的客户端与上游状态码,未记录时为 `null`。
HTTP SSE 请求可能在返回 HTTP 200 后流内失败;WebSocket 已升级时,客户端错误状态码不代表 HTTP 握手状态或 WebSocket 关闭码。
两侧状态码不互相替代,也不覆盖 `logicalOutcome`
@@ -3068,30 +3061,25 @@ Provider metadata 分别保留 `requestedServiceTier` 与 `upstreamServiceTier`
| `GET` | `/api/admin/system/restart/check` | 无 | 只读检查重启目标与启用插件 |
| `POST` | `/api/admin/system/restart` | `{ confirmation? }` | 复核兼容性风险确认并重启,保留插件启用配置 |
在线更新遵循[版本命名与升级规则](../deploy/README.md#版本命名与升级规则)。版本接口的
`updateChannel` 由当前版本推导,取值为 `stable`、`alpha`、`beta`、`rc`、`exp`,无法识别时为 `unknown`。
详情接口的可选 `channel` 仅作用于本次查询,不保存实例偏好;省略时按当前运行版本推导。
响应的 `policy` 包含本次 `channel` 与 `availableChannels`,普通实例可选 `stable`、`rc`、`beta`、`alpha`,
实验实例仅允许 `exp`。不可用通道返回 `40901`,未知枚举值返回参数错误。
执行时应同时发送页面确认的 `channel` 与 `targetVersion`,服务端冻结该通道并重新复核远端目标;
省略通道时按运行版本推导。版本接口只读本地构建和已有运行通道摘要,缓存未就绪时 `updateCached=false`,不会发起网络请求。
检查与执行使用同一规则,禁止的通道转换、跨实验线、跨大版本、降级或同版本重装均以 `40901` 拒绝。
`hasUpdate=true` 仅表示当前构建支持在线更新,且存在允许的更高版本;`latestVersion`、`releaseUrl` 和
`notes` 对应这个候选。没有可升级候选时,`hasUpdate=false`、`latestVersion` 为当前版本,
`releaseUrl` 和 `notes` 保留当前版本的已发布 Release 信息;找不到匹配当前版本的 Release 时为空。
当前构建不支持在线更新时不查询 Release,`hasUpdate=false`、`latestVersion` 为当前版本,
`releaseUrl` 和 `notes` 为空,不支持原因通过 `updateSupported=false`、`unsupportedReason` 返回。
版本接口只读本地构建和通道摘要,缓存未就绪时返回 `updateCached=false`。`updateChannel` 按运行版本推导,为 `stable`、`alpha`、`beta`、`rc`、`exp` 或 `unknown`
详情与安装接口的 `channel` 只对本次操作有效,省略时取运行通道。响应的 `policy` 包含 `channel` 和 `availableChannels`。普通实例可选 `stable`、`rc`、`beta`、`alpha`,实验实例仅可选 `exp`。
未知枚举值返回参数错误。禁用通道、跨实验线、跨大版本、降级或同版本重装返回 `40901`。安装时同时提交已确认的 `channel` 和 `targetVersion`,服务端按[升级规则](../deploy/README.md#版本命名与升级规则)复核目标
| 详情查询结果 | `hasUpdate` | `latestVersion` | `releaseUrl`、`notes` |
| --- | --- | --- | --- |
| 有可安装的更高版本 | `true` | 候选版本 | 候选 Release 信息 |
| 无可升级候选 | `false` | 当前版本 | 当前 Release 信息,未找到时为空 |
| 构建不支持在线更新 | `false` | 当前版本 | 为空。跳过 Release 查询,通过 `updateSupported=false` 与 `unsupportedReason` 返回原因 |
`summaryOnly=true` 优先于 `refresh`,按发布索引检查版本,仅对更高候选核对公开 Release 和当前平台附件;`notes`、`releaseUrl` 为空。详情或摘要检查失败时返回 `warning` 和 `hasUpdate=false`,此时 `latestVersion` 不代表已确认的通道版本。GitHub 限流时,`retryAt` 为最早可重试的 RFC 3339 时间,`retryAtDisplay` 按部署时区展示;其他情况两者均为 `null`。
普通查询缓存 20 分钟,手动刷新最短间隔为 60 秒;临时错误缓存 60 秒,限流按来源退避。
后台安装重新核对通道和目标版本,目标变化须再次检查并确认;下载与校验流程见[在线更新](../deploy/README.md#管理端在线更新)
目标变化须重新检查并确认。下载与校验见[在线更新](../deploy/README.md#管理端在线更新)
更新 POST 在本地校验目标版本并持久化任务后返回 `202`,数据包含 `operationId`、`targetVersion`、
`deploymentMode` 和 `message`,只表示已受理。Release 查询、远端目标复核、下载、校验及文件替换在后台
执行,结果通过 `/update/status` 的 `operation` 查询:`status` 为 `idle`、`running`、`succeeded` 或 `failed`,
终态包含 `finishedAt`,失败原因在 `error` 中。SSE 的 `operationId` 用于关联进度;终态事件发出前状态已落盘。
连接中断不取消已受理任务;响应丢失时先查询状态,不自动重复提交。打开更新页面时也会恢复最近一次任务。
下载并解包后校验发行身份,插件版本不匹配不阻止更新或回滚,兼容性风险在重启前提示。
两条路径在文件交换前后复核全局配置版本,文件替换失败或取消时成组恢复二进制、Web 资源和官方插件目录
更新 POST 在本地校验目标版本、保存任务后返回 `202`,含 `operationId`、`targetVersion`、`deploymentMode` 和 `message`。后台负责复核 Release、下载、校验及替换文件。
通过 SSE 的 `operationId` 跟踪进度,或查询 `/update/status` 的 `operation`。`status` 取 `idle`、`running`、`succeeded` 或 `failed`。终态含 `finishedAt`,失败原因在 `error`,状态落盘后发送终态事件。
断开连接不取消任务。响应丢失时先查询状态,重新打开更新页面可查看最近任务。
更新和回滚均校验发行身份,在文件交换前后复核全局配置版本。失败或取消时成组恢复二进制、Web 和官方插件目录。插件兼容风险在重启前确认
客户端重启前调用 `restart/check`,返回 `targetVersion`、`releaseManifestSha256`、`configRevision` 和 `incompatiblePlugins`,
每项包含 `instanceId`、`name`、`reason`,检查不修改插件状态。源码运行的目标版本与发行摘要为空,检查当前宿主兼容性。
+15 -28
View File
@@ -1,8 +1,6 @@
# Codex Proxy RS 架构
本文说明模块职责、请求流程、状态存储和必须保持的约束。
具体 HTTP 字段见 [接口文档](api.md),部署参数见 [部署文档](../deploy/README.md);上游 URL、超时、
重试间隔和 UI 布局属于源码或配置,不在架构文档重复维护
HTTP 字段见[接口文档](api.md),部署参数见[部署文档](../deploy/README.md)
| 阅读目标 | 章节 |
| --- | --- |
@@ -26,9 +24,7 @@ Codex Proxy RS 是单进程、单副本运行的多 Provider AI 网关,同时
Responses、Chat Completions 和 Messages 共用生成执行链,API Key 账号可选择 Responses 或 Messages 上游协议,
仍由 OpenAI Provider 管理。Chat 在 API 层转为 Responses,Provider 在选定账号后处理 Messages 与 Responses 的转换。
系统不存在 Provider Instance 层,也不支持通过复制应用容器进行多副本扩容。
Client Key 限定账号分组,而不是绑定某个 Provider;一次请求的
Provider 候选由账号范围、模型能力和运行时健康共同决定
Client Key 限定账号分组,账号范围、模型能力与运行时健康决定候选 Provider。网关没有独立的 Provider Instance 层
| 概念 | 所有者与含义 |
| --- | --- |
@@ -37,8 +33,7 @@ Provider 候选由账号范围、模型能力和运行时健康共同决定
| 认证方式 | Provider 解释账号 credential schema,并生成对应上游认证材料 |
| 上游协议 | Provider 根据所选账号的配置与能力决定实际发送格式,调用协议层转换器 |
Provider 注册名与协议标识分别维护,即使字符串相同也不互相代替。
`providers/openai` 执行兼容 API Key 账号的 Messages 请求,表示该适配器支持此账号与协议组合,不代表入站协议决定 Provider 身份
Provider 注册名与协议标识分别维护,同名也不能互换
## 2. 运行拓扑
@@ -218,7 +213,7 @@ flowchart LR
协议与容量见 [SDK 通信边界](../backend/crates/gateway-plugin/sdk/README.md#通信边界)
- **主动 HTTP 请求复用总路由**:Runtime 通过 Core 的 `http::Dispatcher` 调用 API 已组装的路由,SDK 的 `dispatch_http` 与 `next` 共用正文资源池。
子调用持有父子关联、冻结计划和取消信号,跳过祖先发起实例;模型 request 与 attempt 延续该集合。内部管理请求使用宿主签发的插件身份,审计记录插件与调用来源,普通客户端不能用 headers 声明此身份。
正文转交延续真实交付寿命,EOF、显式关闭或父级取消释放资源;组合根保活 Dispatcher,Runtime 只保存 Weak,不增加逐接口注册清单
正文转交后存续至 EOF、显式关闭或父调用取消。组合根持有 Dispatcher,Runtime 只保存弱引用
- **主动服务调用在注册表统一组合**:Admin 按类型登记操作,Core 组合器只负责续体,Runtime 搬运跨进程调用。
插件与 CLI 主动调用公开服务时进入 `service` 中间件一次;原生 HTTP 接口由总入口包裹,业务方法及其内部调用不重复组合。
主动子调用继承冻结计划、父子关联和取消信号,无 service 绑定时也保留空计划快照;调用结束回收资源。
@@ -568,7 +563,7 @@ OpenAI 模型目录用于发现与原生 Responses 账号资格筛选。
同协议业务响应使用原始 wire,跨协议才调用转换器;客户端错误兼容与原生续写额度恢复按明确例外处理,见 [OpenAI 透传](api.md#openai-透传)。
`transport/correlation` 在出站副本上按本次安装身份统一映射关联标识。
Responses 的账号归属判断及换号头部清理由 Provider 统一执行,各传输消费同一出站请求。
原生安装身份由 OpenAI Provider 按 Key 种子、Key ID 与选中账号 ID 确定性派生,无需额外映射表;未配置种子时取自账号,与 UA 继承方式无关。Live 后续阶段使用引导时冻结的种子;插件的身份生成、持久化及关联字段改写通过既有中间件链路自行完成
安装身份独立于 UA,派生规则见 [Key 客户端身份](api.md#key-客户端身份)。Live 沿用引导时冻结的种子。插件通过中间件生成并保存身份、改写关联字段
内部选号、亲和、连接池与本地诊断继续读取原始身份;具体字段边界见 [API 协议](api.md#请求头与身份)
canonical facts 从同一数据旁路提取,用于路由、恢复判断、观测和计费。
WebSocket transport 按完整文本消息交付,wire 同时保留原文与可选解析视图;同协议出口使用原文,
@@ -602,7 +597,7 @@ OpenAI 模型目录用于发现与原生 Responses 账号资格筛选。
- OpenAI 与 xAI 用户身份选择由 PostgreSQL 保存,Core 在 `FrozenAccountScope` 中按 Key 整体覆盖通用选择,
以 Provider-owned 不透明对象沿路由计划传递;执行会话复用首次解析结果,使重试不受发布更新影响。
各 Provider 唯一负责默认值、校验、版本来源及 UA 生成,Admin 提供管理和生效预览。
首次初始化只写入内置默认选择;YAML 不定义客户端身份,也不作为数据库初始化或请求解析的来源。
首次初始化使用 Provider 内置默认值。
官方发布资料与用户选择分开:OpenAI 在 Redis 按 Provider、客户端、平台、架构隔离可重建版本缓存,
离线版本、制品身份及预设环境默认值集中在
[`transport/profile/baseline.rs`](../backend/crates/providers/openai/src/transport/profile/baseline.rs),由发布检查与预设解析共用。
@@ -615,7 +610,7 @@ OpenAI 模型目录用于发现与原生 Responses 账号资格筛选。
其余后台账号和 Desktop 专属操作使用独立官方 Desktop 画像。
管理端连接测试从本次发布快照携带全局画像,经 Provider 解析后冻结为探测身份。
xAI 以内置画像为版本检查基线,在进程内更新 Grok CLI 发布资料;模型与压缩请求使用已保存的用户选择,
OAuth、后台目录和额度查询使用内置官方画像。两者均不回写 `config.yaml`
OAuth、后台目录和额度查询使用内置官方画像
xAI Provider 负责 Codex custom 工具与 Grok function 工具的双向转换,保持工具类型、item ID 与
`call_id` 配对;超限或转换失败终止流。默认 `store: false` 的续接由现有会话 owner 重放完整历史;
@@ -669,8 +664,7 @@ OpenAI Provider 的账号资格模块统一解释请求类型、认证与套餐
其余原生 OpenAI 请求按来源账号、凭据版本和套餐匹配最近一次成功的目录,排除未列出的模型。大池可在读取账号时按目录摘要筛选,白名单和受管适配器由选号时单独判断。
xAI 按套餐读取有效期内的目录缓存。两者在没有对应目录时保留上游验证,选号不请求上游目录
原生 OpenAI Responses 按[官方 Codex 0.166.0](https://github.com/openai/codex/blob/6ff1e1ca3b30fc8b914720681fcf5fe62e95f856/codex-rs/codex-api/src/error.rs#L73)的结构化 `model_not_found` 错误码与状态合同识别模型拒绝,
不从消息或任意正文推断模型权限;通过既有模型级冷却端口记录账号、凭据版本与上游模型,30 分钟内不再选用该组合。
原生 OpenAI Responses 按结构化错误码 `model_not_found` 识别模型拒绝。状态码缺失或为 400、403、404 时,将账号、凭据版本与上游模型的组合冷却 30 分钟。错误消息文本不参与判断。
该反馈不冻结整个账号,不改写管理员模型政策,也不占用 WS 传输恢复预算;重试仍遵守交付边界与原生续写固定账号约束。
管理员诊断旁路目录资格与模型拒绝冷却,OpenAI 的受管上游适配器不继承这两项原生限制
@@ -863,9 +857,8 @@ Arc 随 RoutingPlan 冻结并进入所有 attempt,不在推理请求中读取
整份价目。Provider 按当前 attempt 实际发送的上游模型查价,响应声明的模型只作观测,费用明细复用同一口径;
自定义倍率只作用于本地计算费用,上游报告金额不变
本地计算费用携带当次拆分、有效单价和倍率,终态观测将其写入版本化费用快照。查询优先还原快照,
不使用新配置解释历史;无快照的旧记录保留总额核对后补充拆分的路径。Client Key 账本使用同一费用
结果沿既有幂等结算流程累计,不依赖请求明细写入成功
终态观测将本地费用拆分、有效单价和倍率写入版本化快照。查询优先展示快照,缺少快照时仅在按内置规则核算的总额与记录一致时补充拆分。
Client Key 账本按同一费用幂等结算,独立于请求明细写入
## 7. 控制面与 revision
@@ -1099,7 +1092,7 @@ Admin 集中校验与裁剪公开能力,展示和调度消费同一份观测
Admin 为账号聚合设置独立并发上限,满额立即返回可重试的限流响应;模型展开按响应字节预算提前拒绝必然超限的组合,批量投影定期让出执行时间,避免重查询占满共享数据库与执行资源
Admin 的 `peer_link` 分别拥有共享导出与上游消费用例;上游消费统一处理发现、协议校验、同步、展示和调度投影。
Provider 声明可连接的认证种类,并从本轮凭据中提取连接材料;当前 OpenAI API Key 提供该适配,xAI 原生账号继续参与共享导出。
Provider 声明可互联的认证类型并提取连接信息。OpenAI 支持从 API Key 账号接入,xAI 原生账号可参与共享导出。
Host 执行有界 HTTP 请求,复用组合根注入的证书策略和账号出口;Store 通过通用账号额度端口保存不透明观测,不解释互联或 Provider 协议。
互联与原生额度共用 `provider_quota_json`、`quota_observed_at`、凭据版本和额度访问事实,每个账号仅保存当前来源的观测。
Admin 将明确不支持互联的结果绑定连接身份保存于同一观测,不伪造额度快照或改变额度访问状态。
@@ -1113,7 +1106,7 @@ OAuth 额度解析属于 Provider,CPR 发现、解析与投影属于 Admin;
额度时间戳支持轻量缓存校验,普通账号和凭据查询不加载额度正文,完整观测分批读取
共享端按 Core 的预算规则从本地账本生成明确的访问状态,与本地准入共用口径;金额字段只供接入端展示。
接入端 Admin 的独立额度模块解释默认公开的访问状态,展示、调度投影与同步共用,不要求公开账号池额度;未知或过期事实保留已有状态,Provider 不新增 CPR 错误码分类。
共享端默认公开访问状态,无需公开账号池额度。接入端 Admin 统一解释该状态,供展示、调度和同步使用,未知或过期时保留已有状态。
通用额度写入按凭据版本和查询开始时间提交快照,并独立保护访问事实的观察时间;网络查询可附带连接校验,在同一事务核对出口与启用状态。
互联账号重新授权或出口变更使旧快照及互联识别记录失效,正常 token 续期保留额度;授权撤销提交不含共享内容的观测和时间屏障,阻止更早响应重新发布旧内容。
互联解析只提交有效且明确的预算访问事实,额度同步不改变凭据或独立冷却
@@ -1427,15 +1420,11 @@ Store 在同一可重复读快照下导出业务表和已发布小时汇总,
导出进程、快照事务和压缩文件由同一次任务持有;取消、15 分钟超时或失败会终止子进程并删除部分文件。
压缩后限额和 SHA-256 覆盖实际上传字节,完整 schema 与迁移记录保留在归档内
PostgreSQL 备份恢复属于人工维护操作。当前没有部署级维护模式开关,需要先停止应用,
离线处理快照中的非终态任务、计划游标和到期清理条件,再重新验证对象存储并恢复计划。
关闭计划开关只阻止新计划任务,不会停止 Worker 的任务恢复和删除流程。
未经核对就启动旧快照,可能触发远端对象删除;操作步骤见 [部署文档](../deploy/README.md#人工恢复数据库)
恢复 PostgreSQL 前须停止应用。关闭计划只阻止新任务,Worker 仍可恢复任务并删除远端对象。
离线核对非终态任务、计划游标和到期清理条件,再验证对象存储并恢复计划。步骤见[人工恢复数据库](../deploy/README.md#人工恢复数据库)
## 12. 修改与验收
变更按事实与资源的所有者分配,不能仅按“协议”或“生命周期”等宽泛标签决定目录:
| 改动内容 | 所属边界 |
| --- | --- |
| 入口解码与规范化、客户端连接和协议交付 | API |
@@ -1447,9 +1436,7 @@ PostgreSQL 备份恢复属于人工维护操作。当前没有部署级维护模
| 进程启动关闭、受管资源与后台任务监督 | Host |
| 插件 RPC、调用关联与调用资源回收 | Runtime |
Chat 兼容入口在 API 中规范化为 Responses;Provider 在选号后按账号协议调用 `gateway-protocol` 的 Responses/Messages 转换器。
请求、连接和 RPC 的寿命由各自所有者管理。
状态归属与失败后的保证见[状态所有权](#8-状态所有权)。不以兼容 shim、第二套状态机或跨层旁路绕开已有合同
协议转换见 [Provider 与协议边界](#5-provider-与协议边界),资源生命周期与失败保证见[状态所有权](#8-状态所有权)。扩展现有合同,避免增设平行状态机或跨层旁路
### 后端自审
+12 -49
View File
@@ -1,8 +1,6 @@
# 开发与源码联调
本文说明开发环境、服务启动与跨仓库联调,命令均从宿主仓库根目录执行
协作与检查要求见 [贡献与审查](../CONTRIBUTING.md),部署实例的配置与数据维护见 [部署与运维](../deploy/README.md)
除克隆仓库外,命令均在宿主仓库根目录执行。协作与验收见 [贡献与审查](../CONTRIBUTING.md),部署配置与数据维护见 [部署与运维](../deploy/README.md)
| 任务 | 入口 |
| --- | --- |
@@ -14,12 +12,8 @@
## 环境与依赖
需要 Node.js 26.13.1、pnpm、[Rust 工具链](architecture.md#验证命令)、PostgreSQL 和 Redis
各前端的 `packageManager` 固定 pnpm 版本,宿主 CI 和 Docker 从 `frontend/package.json` 读取
Rust 工具链声明位于 `backend/rust-toolchain.toml`,从仓库根目录运行 Cargo 时显式选择该工具链;
`--manifest-path` 只选择 manifest,不切换 rustup 按当前目录选定的工具链
使用 Node.js 26.13.1、PostgreSQL、Redis 和各前端 `packageManager` 指定的 pnpm。宿主 CI 与 Docker 读取 `frontend/package.json`。
在仓库根目录运行 Cargo 时,用 `+版本号` 选择 `backend/rust-toolchain.toml` 指定的[工具链](architecture.md#验证命令)
```bash
git clone https://github.com/zyycn/codex-proxy-rs.git
@@ -27,11 +21,11 @@ cd codex-proxy-rs
pnpm --dir frontend install --frozen-lockfile
```
前端依赖、锁文件与 ESLint 配置由 `frontend/` 管理,根目录不维护 Node 包
宿主前端的依赖、锁文件与 ESLint 配置位于 `frontend/`
- **版本固定**:`@codex-proxy/ui` 使用固定 GitHub 标签或提交,锁文件记录实际提交、源码归档地址及完整性摘要
- **安装与构建**:pnpm 按 UI 自身锁文件准备依赖,执行 `prepack` 生成 JS、CSS 和类型声明,普通 `dev`、`build`、发行 CI 和 Docker 使用编译产物,无需初始化子模块
- **构建许可**:`frontend/pnpm-workspace.yaml` 的 `allowBuilds` 按仓库放行自有 UI 包脚本,升级时核对源码并更新锁文件,无需逐次修改许可,不开放全部依赖脚本
- **构建许可**:`frontend/pnpm-workspace.yaml` 的 `allowBuilds` 按仓库放行自有 UI 包脚本。升级时核对源码并更新锁文件
## 启动宿主
@@ -60,10 +54,7 @@ pnpm --dir frontend dev
## 源码入口
后端职责和依赖方向见 [Workspace 边界](architecture.md#3-workspace-边界),页面与共享逻辑见 [前端模块职责](architecture.md#34-前端模块职责)。
先按所属模块定位,再跟踪请求、状态与展示的调用关系
共享 UI 的命名与目录见[组件架构](../modules/ui/playground/guide/architecture.md)
[后端 Workspace 边界](architecture.md#3-workspace-边界) · [前端模块职责](architecture.md#34-前端模块职责) · [共享 UI 组件架构](../modules/ui/playground/guide/architecture.md)
Messages 与 Responses 的纯协议转换位于 `backend/crates/gateway-protocol/src/anthropic/`,
HTTP 入口位于 `backend/crates/gateway-api/src/openai/messages.rs`,
@@ -75,31 +66,7 @@ HTTP 入口位于 `backend/crates/gateway-api/src/openai/messages.rs`,
再核对工具往返、取消、错误和输入计数;请求格式及六种组合见 [模型数据面](api.md#3-模型数据面与模型目录)。
Messages 账号只配置 HTTP;本地计数估算不能替代上游计费核对
TLS 指纹在发布目标对应的操作系统和架构上核验,参考程序使用同机运行的官方 Codex CLI 可执行文件。
`CODEX_PROXY_TEST_REFERENCE_BINARY` 指向实际二进制,Windows 使用 `.exe`,npm 安装时使用平台包中的二进制。
macOS / Linux 可设置:
```bash
export CODEX_PROXY_TEST_REFERENCE_BINARY=/absolute/path/to/codex
export RUST_MIN_STACK=16777216
```
Windows PowerShell 可设置:
```powershell
$env:CODEX_PROXY_TEST_REFERENCE_BINARY = 'C:\path\to\codex.exe'
$env:RUST_MIN_STACK = '16777216'
```
随后在仓库根目录执行:
```text
cargo +1.99.1 test --manifest-path backend/Cargo.toml --locked -p provider-openai --test main transport::tls:: -- --include-ignored --nocapture --test-threads=1
```
对照用例记录官方版本及运行平台,分别采样默认 HTTP、自定义 CA 的 HTTP 和 WebSocket,各重复三次。
默认 HTTP 保留扩展顺序逐项比较;rustls 路径对随机扩展顺序排序后比较,算法列表、密钥交换组和 ALPN 仍核对原有顺序。
采集在本机 TLS 握手阶段结束,使用测试认证值,无需真实账号。普通测试默认忽略官方二进制对照用例,须以上述命令显式执行
OpenAI 的 `transport::tls::` 测试在本机回环地址采集 ClientHello,覆盖默认 HTTP、自定义 CA 的 HTTP 和 WebSocket。运行方式见[后端验证命令](architecture.md#验证命令)
## 源码联调
@@ -111,7 +78,7 @@ cargo +1.99.1 test --manifest-path backend/Cargo.toml --locked -p provider-opena
| `modules/ui` | `codex-proxy-ui`,共用组件与主题 |
| `modules/plugins` | `codex-proxy-plugins`,官方插件示例 |
各仓库的常规 CI 验证自身代码和锁定依赖。源码模式用于按需联调,运行前确认所选版本或提交组合及其公开合同兼容
各仓库的 CI 使用锁定依赖。联调前确认所选提交的公开接口兼容
### 检出与安装
@@ -122,7 +89,7 @@ git clone --recurse-submodules https://github.com/zyycn/codex-proxy-rs.git
cd codex-proxy-rs
```
已有仓库运行 `git submodule update --init --recursive`。子模块固定到具体提交;拉取宿主更新后,同样用此命令对齐。执行前先保存子模块中的改动,避免切换正在开发的分支
在已有仓库中,先保存子模块改动,再用 `git submodule update --init --recursive` 检出宿主指定的提交。拉取宿主更新后也用此命令对齐
在宿主根目录安装各项目依赖:
@@ -177,12 +144,8 @@ pnpm --dir modules/plugins/examples/workbench/frontend build:source
## 编辑与提交
直接打开宿主目录即可开发,分别在对应仓库目录操作 Git
1. 在要修改的子模块内先创建分支,例如 `git -C modules/ui switch -c feat/select`。初次初始化的子模块通常处于 detached HEAD
2. 在子模块运行自身检查,并在宿主根目录运行所需联调检查
3. 分别提交、推送并合并组件库或插件 PR。宿主只记录子模块提交号,不能替代子仓库的提交与推送
4. 管理端与插件页面按需升级 UI 依赖,各自固定标签或提交并维护锁文件,无需与 `modules/ui` 同步版本
5. 提交宿主改动及 `modules/ui`、`modules/plugins` 指针。指针必须指向远程可取得的提交,不能只存在于开发机
更新子模块指针不会自动升级消费方依赖。正式依赖不能写成开发机路径或浮动分支;SDK 仍由插件仓库固定到包含所需合同的宿主提交
3. 在对应仓库提交、推送并合并组件库或插件 PR
4. 需要升级依赖时,在管理端或插件仓库固定 UI 标签或提交并更新锁文件。插件 SDK 固定到提供所需合同的宿主提交
5. 在宿主仓库提交代码和子模块指针。指针须可从远程检出,更新指针不会升级消费方依赖
Binary file not shown.

After

Width:  |  Height:  |  Size: 6.5 KiB

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 16 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 173 KiB

+18 -31
View File
@@ -5,17 +5,6 @@
[安装](#安装) · [完整信任](#完整信任) · [配置与启用](#配置与启用) · [使用](#使用) · [更新与卸载](#更新回退与卸载)
```mermaid
flowchart LR
A[选择来源] --> B[校验包并确认来源]
B --> C[确认安装并接受制品]
C --> D[生成默认配置]
D -->|配置完整且兼容| E[启用并发布]
D -->|缺少必填项或版本不匹配| F[补充配置或确认风险后启用]
```
安装包须通过结构、目标平台和进程协议校验;宿主版本范围或能力版本不匹配时提示兼容风险,处理方式见[故障处理](#故障处理)
## 安装
在“插件管理”点击安装图标,选择来源:
@@ -27,8 +16,7 @@ flowchart LR
公开来源无需认证。私有来源可选择或创建独立下载认证;认证按来源和用途限制,不会交给插件进程。
下载代理独立选择,未指定时使用部署默认出口,代理失败不会回退直连。SHA-256 用于固定内容,不证明发布者身份
“下一步”只解析和校验包,不保存制品。检查名称、发布者、版本、平台和摘要后确认安装。随宿主发行物导入的官方制品会显示为“待接受”,也必须先确认信任来源,
未接受的制品不能创建或编辑配置。相同摘要的确认可安全重试
点击“下一步”预检。核对名称、发布者、版本、平台与摘要后确认安装。随宿主导入的官方制品显示“待接受”,确认来源后才能创建或编辑配置。相同摘要可重复确认
确认安装后,若该插件还没有任何配置,宿主会:
@@ -36,13 +24,11 @@ flowchart LR
2. 为需要实例范围的贡献项生成默认绑定;模型目录、管理页面、命令行和自动维护按声明注册,入口认证不自动绑定
3. 配置完整且版本兼容时直接启用并发布;缺少必填项或版本不匹配时保存为停用,补充配置或确认风险后再启用
类型错误、非法 schema 或把敏感值混入普通配置会直接拒绝,不会伪装成“待配置”。更新已有插件时不会创建另一套配置,
管理端在包安装完成后提示确认切换,检查通过后应用目标版本,不兼容时保留原版本并打开待调整的设置
类型错误、schema 无效或普通配置含敏感值时,安装被拒绝。更新已有配置须[确认切换版本](#版本与设置),配置不兼容时保留原版本并打开待调整的设置
### 完整信任
插件以网关的系统身份访问数据、凭据、配置和网络,宿主不提供安全沙箱或权限清单隔离。
安装即信任全部代码与行为,安全由安装者承担;包格式、摘要和兼容性校验不证明安全。只安装可信来源,升级前确认目标版本
插件以网关的系统身份访问数据、凭据、配置和网络,没有沙箱或权限清单隔离。包格式、摘要和兼容性校验无法验证代码安全。安装前确认来源,升级前确认目标版本
## 配置与启用
@@ -54,8 +40,7 @@ flowchart LR
模型请求阶段支持 Key、分组、模型等作用范围;HTTP、WebSocket 消息和服务调用全局生效,具体匹配由插件处理。
客户端 Key、账号分组、Provider 和模型等范围同时满足才生效,同一范围内任一值匹配即可
“事件观察”分别设置“请求完成与用量”和“上游 WebSocket 事件”;关闭其中一类不影响另一类。
观察用于接收事实;请求、响应或消息改写使用对应的中间件
“事件观察”可独立开关“请求完成与用量”和“上游 WebSocket 事件”。改写请求、响应或消息须使用对应中间件
范围数组为空表示不限制该维度。自动创建的默认绑定不预先绑定 Client Key;普通网关请求仍使用实际请求的 Key。
管理页面和命令行调用模型时另行选择 Client Key,沿用该 Key 的启用状态、范围和预算,计入普通请求用量
@@ -63,16 +48,20 @@ flowchart LR
`frontend_authentication` 不会随安装自动接管入口。启用它时必须明确配置外部 principal 到既有 Client Key 的映射;
已停用或删除的 Key 不会因此恢复访问
存在多套配置时,可在“历史配置”中选择并确认替换当前配置,管理端只维护一个当前配置,不提供新增配置入口
若同一插件已有多个启用实例,需先整理为一套才能继续启用或更新,宿主不会自动停用实例或删除配置、密钥与私有数据
管理端为每个插件维护一套当前配置。可在“历史配置”中选择另一套,确认后替换当前配置。
若有多套配置同时启用,先手动停用多余配置,再启用或更新插件。停用会保留配置、密钥和私有数据
声明自动维护的插件可自行准备分组和 Key,无需提供管理员密码。停用会停止维护,但保留这些资源及其原生启用状态;
删除插件配置也不自动删除资源。需要撤销 Key 访问时,在 Key 管理中停用或删除相应 Key
“已启用”表示配置匹配且宿主观察到会话就绪,不是插件业务或外部服务的健康证明。“等待生效”表示候选仍在准备或等待发布;“需要处理”会显示发布或运行失败原因。
“运行状态未知”表示暂时没有运行诊断,启用配置保持不变。详情中的“运行负载”展示当前发布会话的在途调用、执行、排队、恢复等待、驻留回调和活动流;计数可能重叠,不包含其他正在排空的旧版本
并发编辑冲突时应重新加载最新配置后确认,不能覆盖另一窗口的修改
| 状态 | 含义 |
| --- | --- |
| 已启用 | 配置匹配且宿主会话就绪,业务与外部服务健康需单独确认 |
| 等待生效 | 配置正在准备或等待发布 |
| 需要处理 | 发布或运行失败,详情显示原因 |
| 运行状态未知 | 暂无运行诊断,保留启用配置 |
“运行负载”只统计当前发布会话的在途调用、执行、排队、恢复等待、驻留回调和活动流,各项计数可能重叠。编辑冲突时重新载入配置再确认
## 使用
@@ -101,8 +90,7 @@ flowchart LR
- **切换版本**:在版本列表中选择已安装版本,确认当前版本与目标版本后执行。若该版本已有恢复设置,使用它上次启用时提交的参数、密钥与功能范围;否则从当前设置生成草稿。切换保持启停状态,目标制品必须已接受。停用的历史配置引用旧版本时显示“历史配置”,不表示该版本正在运行
- **回退版本**:只列出同一插件已安装、已接受且保留恢复设置的较早版本,恢复对应设置后重新执行兼容检查
没有目标版本快照时,草稿保留当前显式值并补充缺失的 schema 默认值。停用草稿不覆盖最近启用时的恢复点;
未保存或已丢失的设置无法通过快照恢复
没有目标快照时,草稿保留显式值并补齐 schema 默认值。停用草稿不覆盖最近启用时的恢复点
宿主更新的检查与恢复要求见[插件兼容与发行目录](../deploy/README.md#插件兼容与发行目录)
@@ -116,11 +104,10 @@ flowchart LR
### 故障处理
宿主启动时检查插件清单、RPC、平台、宿主范围和已声明能力版本。不兼容实例保持未启动,不挂载能力或故障占位,启用配置、绑定、密钥与私有数据保留;这同样适用于 Docker 与手工升级
不兼容的插件不会自动启动或挂载能力,已保存的启用配置、绑定、密钥和私有数据均保留。宿主继续执行原生认证
宿主范围或能力版本不匹配时,页面以黄色三角感叹号标记,悬浮或点击显示“未启动:版本不兼容”及原因。在插件详情点击启动,确认“启动不兼容版本可能导致系统不稳定”后可尝试;确认只适用于当前宿主、插件包和配置版本的本次启动,下次宿主启动重新检查。配置或目标变化后需要重新确认,成功启动后仍保留兼容性提醒
包损坏、清单或 RPC 格式不兼容、平台不符时显示具体原因,不能强行启动,需更换兼容包。未启动插件提供的额外认证、拦截与其他能力不生效,宿主原生认证继续执行。版本要求见 [SDK](../backend/crates/gateway-plugin/sdk/README.md),重启检查见[部署说明](../deploy/README.md#插件兼容与发行目录)
- **宿主范围或能力版本不匹配**:黄色三角标记显示原因。可在详情中确认风险并尝试启动。确认仅对当前宿主、插件包和配置版本的本次启动有效。启动成功后仍显示提醒
- **包损坏、清单或 RPC 格式不兼容、平台不符**:按提示更换兼容包。版本要求见 [SDK](../backend/crates/gateway-plugin/sdk/README.md),重启检查见[部署说明](../deploy/README.md#插件兼容与发行目录)
通过兼容检查后,RPC 握手失败或运行中进程崩溃、帧边界、调用关联或传输错误会使对应实例未就绪,
显示红色三角感叹号及脱敏错误详情,保留启用配置,可在详情中重新启动或切换版本。连续故障受重启次数限制
+8 -26
View File
@@ -11,16 +11,8 @@
</div>
在管理端「主题」中调整颜色、字号、圆角和组件样式,保存后应用到当前浏览器。
设置保存在浏览器本地,不会同步到服务器或其他设备。只想换配色时,选择品牌色预置即可
下文说明实现和扩展方式。颜色使用 Ant Design 十阶色板与项目的明暗角色规则,
中性表面从当前底色和文字基色派生;Vue 组件通过 CSS Variables 与 Tailwind CSS 4 使用这些值。
项目不依赖 Ant Design 组件库或 CSS-in-JS
> [!IMPORTANT]
> 主题的目标是调整颜色、密度、圆角与层级,不改变现有页面结构和产品语义。默认主题保留既有表面层级,并满足正常文字的可读性约束;
> 成功、警告、错误和业务数据色不会因为品牌色变化而失去原有含义
在管理端「主题」选择预置配色,或调整颜色、字号、圆角和组件样式。设置仅保存在当前浏览器。
Vue 组件通过 CSS Variables 和 Tailwind CSS 4 使用主题,无需 Ant Design 组件库或 CSS-in-JS
## 设计原则
@@ -29,7 +21,7 @@
- **主色与表面分离**:品牌色负责交互和强调,页面、容器与浮层使用预设底色或自定义背景,文字由文本 Seed 派生
- **语义独立**:成功、警告、错误、信息和链接色各自派生,不随品牌色改变
- **无边设计**:默认依靠表面色差、间距和轻阴影表达层级;边框只用于焦点、错误和必要分隔
- **运行时可定制**:用户输入在浏览器中实时派生,因此使用 CSS Variables,不使用构建时 SCSS 变量
- **运行时可定制**:浏览器按用户设置实时生成 CSS Variables
- **单一事实源**:Store 只保存最小配置,所有 Map、Alias 与未覆盖的 Component Token 均由纯函数生成
- **行为透明**:任意自定义 Seed 都进入统一算法,页面只选择角色。功能色 `text` 与 `on-container` 分别依据中性
Surface 和自身 Container 三态做对比度保护,不使用固定色相的文字锚点覆盖自定义 Seed;交互仍尊重
@@ -37,15 +29,10 @@
## 界面文案与信息层级
管理端以查看状态和完成操作为主,延续紧凑的信息布局、清楚的主次关系,以及表面色差、间距和轻阴影构成的层级
- **先沿用已有设计**:先看原页面和最接近的同类实现,复用布局、控件、操作位置与状态展示,新增能力优先融入原有操作路径
只有现有设计无法承载本次任务时才改变结构,并说明具体问题,不以个人审美或设计技能中的通用建议为由重做页面
- **沿用已有设计**:参考原页面和同类实现,复用布局、控件、操作位置与状态展示。只有现有结构无法承载需求时才调整,并说明具体问题
- **按作用范围摆放操作**,例如单行操作沿用表格已有的行操作区,整表操作沿用列表工具栏。同层内容沿用相邻区域的对齐边线,同组控件保持一致的间距,换行后仍能看出标签、控件与操作的对应关系
- **页面文案言简意赅**,控件含义清楚就省去说明。必要的限制、失败原因和操作后果就近简述,用法和示例放在文档中
- **文案不使用句号和分号**:自行编写的标题、标签、按钮、表单帮助、空状态、提示和错误文案不使用 `。`、句末 `.`、`;` 或 `;`,优先写成短语或简短分句
需要表达多个要点时,按内容关系拆成字段、短行或列表,不把长段落机械替换成逗号串
这项约定针对界面文案,URL、版本号、小数、代码、原始日志和用户输入保留原样
- **界面文案省去句号和分号**:标题、标签、按钮、帮助、空状态、提示和错误文案使用短语或短句。多个要点拆成字段、短行或列表。URL、版本号、小数、代码、原始日志和用户输入保留原样
- **按内容选择提示方式**:Tooltip 用于短名称或单句补充,Popover 用于需要阅读、多段说明或含链接的内容,复用项目现有组件
帮助入口需可识别、可通过键盘和触屏打开,图标提供可访问名称,不依赖悬停才能读到必要内容
- **避免大字报**:不堆叠超大标题、口号、整屏介绍、重复副标题或大段说明卡片,页面尽快进入数据、筛选和操作
@@ -53,8 +40,6 @@
- **按任务组织空间**:优先使用紧凑的工具栏、表格、表单和必要的指标卡,卡片承担独立的信息或操作职责,不为每段说明单独套卡
密度以可读、可点击为边界,保留窄屏换行和必要的控件间距
开发时按任务选择参考入口,复用其职责和信息层级,具体布局仍以当前任务为准:
| 场景 | 参考入口 | 关注点 |
| --- | --- | --- |
| 页面头部 | `@codex-proxy/ui` 的 `ZPageHeader`、[系统概览](../frontend/src/views/dashboard/components/DashboardContent.vue) | 简短标题、必要的统计范围或状态、就近操作 |
@@ -69,7 +54,7 @@
应用使用 Vue I18n Composition API,语言标识为 `en`、`zh-Hans`、`zh-Hant`。资源按领域存放在 `frontend/src/i18n/locales/`,使用 `领域.功能.用途` 的语义 key,例如 `accounts.connectionTest.description`,三种语言保持相同 key 和具名参数
默认语言为简体中文,浏览器本地保存的有效语言选择优先;未保存选择、保存值无效或存储不可用时使用简体中文
优先使用浏览器本地保存的有效语言,其他情况使用简体中文
业务语言包及对应 UI 文案按语言加载,首次只加载当前语言,加载成功后缓存资源。缺失消息显示为空,不回退到其他语言或显示 key;切换时语言包加载失败则保留当前语言
@@ -101,8 +86,6 @@ flowchart LR
J --> K[首页画板 / 组件概览]
```
核心职责保持分离:
| 层 | 入口 | 职责 |
| --- | --- | --- |
| 基础组件 | `@codex-proxy/ui` | 稳定组件与通用函数,不承载业务状态 |
@@ -210,9 +193,8 @@ Input、阴影与其他 Component Token 从 Fill、Surface、Primary 和 Semanti
正常文字同时检查 Layout、Container、Elevated、文字交互背景、三级 Fill,以及控件透明填充在各宿主上的合成色
和浅色的选中 / 选中 Hover 背景。正文、标题和 Secondary 至少 7:1,
Tertiary 至少 5.5:1,Quaternary 至少 4.5:1;这些是相对全部上述表面的最低目标,对 Container 的实测比值通常更高。
Disabled 保留独立的弱化颜色,不承担正常信息。控件填充由文字 Seed 和透明度派生,placeholder 继续消费
Quaternary;主按钮白字与功能色文字遵循各自的容器配对规则
Tertiary 至少 5.5:1,Quaternary 至少 4.5:1。
Disabled 使用独立的弱化颜色,不承担正常信息。控件填充由文字 Seed 和透明度派生,placeholder 使用 Quaternary。主按钮白字与功能色文字遵循各自的容器配对规则
### Alias Token
+1
View File
@@ -428,6 +428,7 @@ type UsagePageQuery = UsageRangeQuery & PageQuery & {
accountSearch?: string
model?: string
status?: UsageRecordStatus
errorOrigin?: UsageErrorOrigin
}
interface UsageDetailQuery {
+1 -1
View File
@@ -123,7 +123,7 @@ function responseHeader(
: undefined
}
function httpFallback(status: number) {
export function httpFallback(status: number) {
switch (status) {
case 400:
return t('common.errors.invalidParameters')
+2 -2
View File
@@ -1,6 +1,6 @@
import type { RawResponse, RawResponseMeta, RequestContext, RequestNext } from '../types'
import { t } from '@/i18n'
import { ApiError, normalizeApiResponseError } from './error'
import { ApiError, httpFallback, normalizeApiResponseError } from './error'
export async function rawPlugin(context: RequestContext, next: RequestNext) {
const options = context.raw
@@ -54,7 +54,7 @@ export async function rawPlugin(context: RequestContext, next: RequestNext) {
throw normalized
throw new ApiError(
response.status >= 400
? t('common.errors.http', { status: response.status })
? httpFallback(response.status)
: t('common.errors.unsupportedResponse'),
response.status,
undefined,

Some files were not shown because too many files have changed in this diff Show More