chore(release): prepare v3.7.2

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

.agents/skills/dev-guide/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: dev-guide
+description: 当前仓库开发指南。修改或排查本仓库的 Rust 网关、Vue 管理端、账号与出站代理、接口协议、部署、CI、发布或文档时使用，定位权威规范和验证入口。Use for development in the repository containing this skill; not for generic Rust/Vue questions in unrelated repositories.
+---
+
+# 开发指南
+
+先读根目录的 [AGENTS.md](../../../AGENTS.md) 和 [CONTRIBUTING.md](../../../CONTRIBUTING.md)。
+本技能只组织工作入口，架构、协议和视觉规则从下列权威文档读取，不维护第二份副本。
+
+## 按任务读取
+
+| 任务 | 技能与文档入口 |
+| --- | --- |
+| 用户能力、快速开始 | [README](../../../README.md) |
+| 模块职责、调用链、状态归属 | [系统架构](../../../docs/architecture.md) |
+| Rust 开发 | 加载并使用 `$rust-best-practices`，结合 [系统架构](../../../docs/architecture.md) 与 [项目约定](../../../CONTRIBUTING.md#项目约定) |
+| HTTP 路由、请求与响应、导入导出 | [API 文档](../../../docs/api.md) |
+| 前端开发、管理端组件、主题 Token、视觉验证 | 加载并使用 `$frontend-design`，结合 [管理端主题](../../../docs/theme.md) 与 [界面验证](../../../CONTRIBUTING.md#界面验证) |
+| 常规文档更新 | [文档职责与更新条件](../../../CONTRIBUTING.md#文档职责与更新条件)：维护当前说明，在原章节就地修订，不记录变更历史 |
+| 部署、客户端配置、备份与恢复 | [部署说明](../../../deploy/README.md) |
+| 数据迁移、冻结清单与本地测试库 | [迁移说明](../../../backend/migrations/README.md) |
+| 验证命令与提交规范 | [贡献与审查](../../../CONTRIBUTING.md) |
+| 创建或审查 PR | [github-pr](../github-pr/SKILL.md) |
+| 整理或提交 Issue | [github-issue](../github-issue/SKILL.md) |
+| 发布说明、版本规划与发版 | [release](../release/SKILL.md) |
+
+## 执行顺序
+
+1. 从仓库根目录确认工作区、当前任务范围和相关运行实例；保留已有改动。
+2. 按 `AGENTS.md` 的 CodeGraph 约定定位入口、调用链和职责归属，再阅读相关实现。
+3. 按 [问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据) 核实触发条件、问题发生版本与目标分支现状，
+   优先依据适用的官方源码确定方案。结合上表读取所需文档，先找可复用的同类实现，再修改所属模块。
+4. 文档和运行结果不一致时，追查当前源码、配置与版本，区分实现缺陷和文档过期；
+   按 [文档职责与更新条件](../../../CONTRIBUTING.md#文档职责与更新条件) 判断是否修订，不为每次改动追加文档或发布说明。
+5. 按 `CONTRIBUTING.md` 验证并报告结果。后端 Cargo 命令从 `backend/` 执行，或显式指定该目录的 manifest。
+
+发布任务按 `release` 技能读取当前版本、发布入口和工作流，发布说明语言遵循 `CONTRIBUTING.md`。

.agents/skills/dev-guide/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "dev-guide"
+  short_description: "从仓库规范与架构文档定位实现、验证和交付的正确入口"
+  default_prompt: "使用 $dev-guide 按当前仓库规范与架构完成开发、验证或发布。"

.agents/skills/github-issue/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: github-issue
+description: 整理与提交 GitHub Issue（问题反馈 / 功能建议）。用于“提个 Issue”“把这个问题反馈到仓库”“帮我报个 bug”“整理成 Issue”，以及通过 Issue 提议功能或协作规则的场景；区分草拟正文和实际提交。Use for drafting or filing bug reports and feature requests; not for debugging-only, editing Issue Forms/templates, or skill-authoring requests.
+---
+
+# 整理与提交 Issue
+
+本仓库流程见 [贡献与审查](../../../CONTRIBUTING.md)，问题反馈使用当前的
+[YAML Issue Form](../../../.github/ISSUE_TEMPLATE/bug_report.yml)。从表单读取字段与必填项，不在技能中复制一份字段清单。
+用户指定其他仓库时，使用该仓库当前的贡献规则与 Issue 模板，不能把这里的表单套过去。
+
+## 确定目标和动作
+
+- 根据用户 URL、仓库上下文和 remote 确认接收 Issue 的仓库。fork 场景核对用户要反馈给自己的 fork 还是上游。
+- “写一份、整理内容、草拟 Issue”只准备正文；明确要求“提交、创建 Issue”才发布。
+  已经授权提交且信息足够时直接完成，不重复索要确认；仅自动选中技能不能授权发布。
+- “有个 bug”“这个报错怎么修”本身是排障语境，不能推断要发 Issue；结合已有反馈任务识别省略的目标和动作。
+- 缺少无法推断的目标或关键复现事实时，只问必要信息，并先整理其余已有证据。
+- 使用可用的 GitHub 连接器或 `gh`。不要为提交 Issue 安装新工具、修改仓库配置或启用额外服务。
+
+## 证据与去重
+
+1. 读取目标仓库实际 Issue 模板和配置，区分缺陷、功能建议与协作规则提案。
+   本仓库后两类允许普通 Issue；其他仓库按其配置选择入口。
+2. 先搜索 open 和 closed Issues，结合关键词、错误信息与触发条件检查重复，而不只比较标题。
+   同时核对相关 PR 与发布记录，关联已有修复及其发布版本；仅主分支已修复时明确尚未发布。
+   同一问题已有记录且没有新增证据时返回已有链接；用户仍明确要求新建时按其要求处理。
+   不因发现重复而擅自评论、重开或关闭已有 Issue。
+3. 从用户描述、当前版本与已有诊断中整理事实：区分实际结果、预期结果、稳定复现条件和未经证实的推测。
+   不把本地开发版本当作发生问题的部署版本；无法复现时如实说明已知条件。
+   引用官方行为或提出实现方案时，按 [问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据) 注明来源、版本与缺口；
+   不把找到官方源码或证明根因作为提交症状反馈的前提。
+4. 只收集定位所需信息。正文、日志片段和附件去除密钥、Cookie、令牌、代理认证、私人请求内容等敏感信息；
+   不直接附完整配置或请求转储。记录与复现相关的代理、TUN、证书条件，不擅自修改这些环境来收集材料。
+
+## 编写正文
+
+- 标题写具体症状或所需行为，不预先断言尚未证明的根因。语言与目标仓库及用户要求一致。
+- YAML Issue Form 按字段顺序使用 `attributes.label` 作为 Markdown 小标题，填写相应答案。
+  `gh issue create --body-file` 直接提交正文，不会替你完成网页表单校验；手动核对必填字段、选项和必选确认项。
+  不把原始 YAML、占位文字或尚未确认的勾选项当成答案提交。
+- 无法获知的信息明确写未提供或不适用，并说明理由；如果该事实关系到能否理解或复现问题，发布前补齐。
+  功能或规则提案说明当前场景、缺少的能力、建议结果和必要取舍，不强行填写缺陷复现步骤。
+- 附件只使用用户授权发布且实际可访问的地址；本机 `/tmp/...` 路径不能作为 GitHub 附件。
+  没有可用附件时保留操作描述并说明缺口，不声称截图已上传。
+- 使用模板规定或用户要求的 labels、assignees；先确认它们在目标仓库存在，不自行猜测。
+
+## 提交与收尾
+
+把核对后的 UTF-8 正文写入临时文件，或直接传给连接器的结构化字段。CLI 变量先从已确认的目标与正文赋值：
+
+```bash
+gh issue create --repo "$issue_repo" --title "$issue_title" --body-file "$issue_body_file"
+```
+
+发布前快速复核目标、必填内容、脱敏及重复记录。网络超时或返回不明确时先查询远端是否已经创建，避免重复提交。
+发布后读取新 Issue 确认仓库、标题和正文，返回链接及必要的信息缺口。
+只准备草稿或发布失败时提供可直接使用的标题与正文，明确尚未提交。

.agents/skills/github-issue/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "github-issue"
+  short_description: "按仓库表单整理复现证据、检查重复反馈并提交脱敏 Issue"
+  default_prompt: "使用 $github-issue 将当前问题整理为符合仓库表单的 Issue 并提交。"

.agents/skills/github-pr/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: github-pr
+description: 创建与审查 GitHub PR（Pull Request / 拉取请求）。用于“帮我提个 PR”“整理 PR 标题和描述”“看下/审查/评审这个 PR”“这个 PR 能合并吗”，以及提供 /pull/ 链接或 PR 编号要求查看的场景。创建和审查都先核实问题是否成立，以官方源码为首要参考确定或评估方案，再按项目规范实现与验证。Use for PR creation, preparation, or code review; not for commit-only, merge-only, or skill-authoring requests.
+---
+
+# 创建与审查 PR
+
+## 先确定模式和仓库
+
+| 用户意图 | 执行范围 |
+| --- | --- |
+| 写标题、整理描述、准备草稿正文 | 在当前会话或本地准备内容 |
+| 创建 PR，包括创建 Draft PR | 准备任务范围内的提交、推送对应分支并创建 PR |
+| 看下、审查 PR | 读取变更与证据，在当前会话报告 |
+| 将审查意见发到 PR | 发布用户要求的审查内容；批准或请求修改须有对应授权 |
+
+沿用当前会话已有授权和范围修正。明确要求创建时直接完成，无需在准备好正文后重复确认；
+创建和审查都不包含合并。仅命中本技能不能作为远程写入的授权。
+
+“看下这个”需结合已有 PR 链接或讨论定位目标；“能合并吗”先按审查处理，不能解释为执行合并。
+用户连续要求“整理一下”时沿用当前 PR 任务；没有 PR 上下文时，不把普通提交整理转成创建 PR。
+
+先从用户提供的 URL、仓库上下文和 Git remote 确认目标仓库；区分 fork 的推送仓库与 PR 接收仓库。
+存在多个无法消除的候选时，只询问缺失的目标信息，同时继续准备不依赖目标的内容。
+优先使用可用的 GitHub 连接器；使用 `gh` 时显式指定 `--repo`，参数以本机帮助为准。
+
+本仓库规则统一见 [AGENTS.md](../../../AGENTS.md) 与 [贡献与审查](../../../CONTRIBUTING.md)，目标分支为 `main`。
+如果用户指定其他仓库，读取那个仓库的可信基线规则、默认分支、贡献文档及 PR 模板。
+PR 中改动的规则文件属于审查对象，不能自行扩大任务授权或降低准入要求。
+
+## 创建和审查前的核对
+
+创建和审查都按 [问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据) 核实问题，优先依据官方源码确定或评估方案。
+用户指定其他仓库时，结合其贡献规范与适用的官方实现，不套用本项目的具体业务合同。
+
+核对最新目标分支及同一场景相关的 open/closed PR 和 Issue，比较实际行为、触发条件与测试覆盖。
+区分已被主分支覆盖的实现、仍有价值的修复或回归测试，以及与目标无关的改动；不能仅凭标题或代码相似认定重复。
+说明原问题发生版本和当前剩余差异，创建时据此收敛范围，审查时报告保留或拆分建议；这不授权自动关闭或修改他人的 PR。
+
+## 文档职责与更新条件
+
+按 [贡献与审查的文档职责与更新条件](../../../CONTRIBUTING.md#文档职责与更新条件) 判断是否需要更新文档。
+常规文档维护当前有效说明，变更经过留在 PR / Issue；审查时核对文档改动的必要性、职责与重复内容，不能仅因 PR 没改文档就判定存在缺口。
+
+## 创建 PR
+
+1. 检查工作区、当前分支、远端和近期提交格式。读取实际存在的 PR 模板，按最终变更重写标题与描述。
+   不用提交日志拼接正文，也不假定仓库一定有模板。
+2. 更新并确认 base/head，查看相对 merge-base 的完整差异和待提交内容；核对仓库的受保护文件与准入规则。
+   只纳入任务范围的文件和提交；需要整理时用独立功能分支，保留用户其他改动，不擅自改写已发布历史。
+3. 按上述核对流程，在目标分支基线核实问题，追踪官方与本项目的相关调用链，先确定解决方向再实现。
+   若改动已完成，也要据此复核问题与方案；需要修正时只修改已授权的范围。仅整理标题或正文时报告差异与缺口，
+   不自行修改实现。原问题不成立时不将它包装成已修复的缺陷；证据不足时明确保留结论。
+   实现应职责清晰、表达直接、复用合理；提交前主动清理本次变更引入的重复逻辑、冗余状态、死代码、
+   多余抽象及无依据的兼容分支。功能可用和检查通过不能替代可维护性自查。
+4. 查找同一来源仓库、head 和 base 的现有 PR；已存在则复用其链接，不重复创建。
+   更新现有标题或正文须在本次整理/更新请求范围内。
+5. 按贡献文档执行适用检查。记录实际验证的提交或工作区状态，区分通过、失败、跳过和未执行。
+   前端改动提供实际界面证据或预览步骤；缺少证据时写明，不用构建成功替代视觉验收。
+6. 将任务范围内的提交推送到正确远端，核对远端 head。标题遵循项目约定，正文先说明问题成立的依据和最终行为，
+   再给必要的设计取舍、验证与遗留事项。涉及官方行为时，写明官方源码位置与版本或提交、官方处理方式、
+   本次实现与它的关系及必要的偏离原因；区分源码推断和实际复现，不用检查通过替代方案论证。按规模压缩，不强填无关章节。
+7. 明确要求草稿或仍有阻塞项时创建 Draft PR，并解释原因；具备审查条件且未要求草稿时创建普通 PR。
+   GitHub Draft 状态与“只写本地草稿正文”不同，后者不创建远程对象。
+8. 创建后核对链接、base、head、草稿状态和最新检查结果。网络超时或结果不确定时先查询远端，再决定是否重试。
+
+CLI 示例中的变量必须先根据上述检查赋值；`pr_body_file` 是精确写入 UTF-8 正文的临时文件：
+
+```bash
+gh pr create --repo "$pr_repo" --base "$pr_base" --head "$pr_head" \
+  --title "$pr_title" --body-file "$pr_body_file"
+```
+
+按需添加 `--draft`。不要用 `gh pr create --dry-run` 做只读预览，它仍可能推送 Git 变更。
+多行正文通过文件或连接器的结构化字段传递，不把未转义正文拼进 shell 命令。
+创建完成返回链接、目标分支和验证摘要；不要称为已合并或已获维护者批准。
+
+## 审查 PR
+
+1. 获取 PR 的 base/head SHA、描述、文件差异、已有讨论及 CI 状态。记录实际审查的 head，使用 merge-base 差异。
+   需要源码上下文时先遵守目标仓库的定位规则；需检出时使用隔离工作区，保留用户当前分支和运行环境。
+2. 先核实 PR 要解决的问题是否成立：提取触发场景、预期行为和声称的原因，在目标分支基线检查实际行为。
+   按上述核对流程收集一手证据，区分原有问题、环境或配置差异与 PR 新引入的问题，说明主分支已覆盖的部分。
+3. 从官方方案评估解决方向：说明官方如何处理同一场景，检查 PR 是否遵循其协议语义和职责归属、
+   是否复用已有能力或正确传递官方合同；核对偏离官方方案的理由与运行证据。
+4. 按贡献文档的审查维度追踪完整调用链，找到共享业务事实、同类实现及已有验证。
+   对既有特殊分支查清服务的场景，再判断本次改动是否引入或加重问题。
+   主动检查本次变更新引入或加重的冗余与代码异味，说明具体位置、维护成本或行为影响及最小修复方向；
+   不能仅因功能可用、CI 通过而略过，也不把个人写法偏好判为缺陷。
+5. UI 改动同时对照主题、共用组件、数据展示逻辑和同类页面。浏览器可用时检查相关交互及状态；
+   未运行的页面检查列为验证缺口，不从截图或源码推断所有状态都正确。
+6. 核对 CI 与本地证据是否覆盖当前 head；根据风险补充必要验证，不触发无关部署或真实账号业务请求。
+   工具不可用、集成测试跳过或环境不足时具体说明影响范围。
+7. 按 [审查标准](../../../CONTRIBUTING.md#审查标准) 用中文先回答原问题是否成立、解决方向是否合理，
+   再列出实现问题与验证缺口，结论附具体依据。
+   实现问题区分必须修复项、可选建议和验证缺口；没有的类别可省略。
+   每个问题给变更中的文件位置、触发条件或规范依据、影响和最小修复方向。
+   复用建议指出具体已有实现，不把个人偏好写成缺陷；未发现问题时直接说明并交代覆盖范围。
+8. 结束前核对 head 是否变化。发生变化时检查新增差异并更新结论，或明确结论只适用于原 SHA。
+
+审查本身不修改源码、不发表评论、不提交 GitHub 的批准或请求修改状态。
+用户明确要求发布时，先复核当前 head 和重复评论，再通过结构化字段或 `--body-file` 发布对应内容；
+需要绑定具体提交时使用支持 commit ID 的审查接口。不要在旧提交结论上批准新的 head。

.agents/skills/github-pr/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "github-pr"
+  short_description: "创建与审查拉取请求，先核实问题，以官方源码为首要依据确定或评估实现方案"
+  default_prompt: "使用 $github-pr 按当前请求创建或审查 PR，先核实问题是否成立，以官方源码为首要参考确定或评估解决方案，说明源码依据及必要的偏离原因，并按仓库规范实现与验证或报告审查结论。"

.agents/skills/release/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: release
+description: 准备或执行当前仓库发版，维护中文发布说明。用于“发版”“发个新版本”“准备 vX.Y.Z”“推荐版本号”“整理更新日志/发布说明”“更新 release/notes.md”“打版本 tag”等发行任务。Use for version planning, release notes, and publishing a repository release; not for deploying/restarting an instance, publishing application data, or authoring a release skill.
+---
+
+# 发版
+
+## 识别任务范围
+
+| 用户意图 | 执行范围 |
+| --- | --- |
+| 推荐版本号 | 根据本次变更与已有版本给出建议及理由 |
+| 整理更新日志、写 note、准备发版 | 核对变更、编写说明、检查发布条件；未要求提交时保留本地改动 |
+| 正式发布、发布指定版本、打版本 tag | 在已授权范围内执行对应步骤；仅打 tag 的请求不自动扩展为完整发版 |
+| 重试失败的发版 | 核对上次执行状态，从未完成的步骤恢复 |
+
+沿用当前会话明确的版本、范围与授权；用户已要求正式发版且条件满足时直接执行，不重复确认。
+“准备好了”“可以发版吗”属于准备或检查，不能解释成正式发布；创建本技能也不触发发版。
+发行版发布与运行实例升级分开判断，“上线”需结合上下文确定用户指哪一种。
+
+## 读取当前流程
+
+先读 [AGENTS.md](../../../AGENTS.md) 与 [贡献与审查](../../../CONTRIBUTING.md)，再按任务检查：
+
+| 事实 | 权威入口 |
+| --- | --- |
+| 当前版本 | [release/version.yaml](../../../release/version.yaml) |
+| 本次发布说明及语言约定 | [release/notes.md](../../../release/notes.md)、贡献文档的项目约定 |
+| 版本提交、tag、推送与工作流触发 | [release/publish](../../../release/publish) |
+| 构建、检查、GitHub Release 和镜像发布 | [发布工作流](../../../.github/workflows/release.yml) |
+| 平台与产物清单 | [release/platforms.yaml](../../../release/platforms.yaml) |
+
+命令从仓库根目录执行；每次以当前脚本和工作流为准，不另写发布脚本或绕过已有质量检查。
+用户明确指定其他仓库时先读取其发布流程，不能直接套用这里的路径和命令。
+
+## 准备版本与说明
+
+1. 确认发布分支、upstream、目标仓库、工作区和完整待推送范围。本仓库沿用 `main`；
+   未提交或未跟踪内容分别核对，不因脚本只检查已跟踪文件就认定所有内容都已纳入发布。
+2. 读取版本文件、已有 tag 和实际发行记录，确认上一发布基线与本次目标提交。
+   根据基线到目标的提交和最终差异归纳变更，剔除回退、重复和未进入发布范围的内容。
+   不能只用当前版本文件或最近几条提交判断“本次更新”。
+3. 使用用户指定或当前会话已确定的目标版本；需要建议时按兼容性、能力新增和修复范围说明理由。
+   目标 tag 必须未被占用；遇到已有同名版本先判断是重试还是新发版，不自动递增版本掩盖冲突。
+4. 按贡献文档维护 `release/notes.md`。正文写中文，保留版本号和必要技术标识；
+   按用户可感知的最终行为归并，不逐条翻译 commit，也不把排查过程或未验证承诺写入说明。
+   可按新增功能、问题修复、体验优化、升级说明组织，省略没有内容的章节。
+5. 替换为本次版本说明，首行与目标 tag 一致且正文非空。升级事项应能追溯到实际迁移、配置或兼容变化；
+   敏感信息脱敏，未合入功能不宣称已发布。已有准确说明仅需翻译时保持其事实和范围。
+6. 按贡献规范检查变更与现有 CI 证据，明确通过、失败、跳过和未执行。
+   只修改说明时无需重建前后端；正式发版仍要跟踪发布工作流针对目标提交的检查与产物。
+
+## 执行正式发版
+
+调用入口前重新核对当前脚本的副作用、目标版本和待推送提交，保留无关工作区内容，不自动清理或暂存用户文件。
+先编辑 `release/notes.md`，保留为未提交改动（已暂存或未暂存均可）；其他已跟踪文件的改动应先单独提交。
+脚本会更新 `release/version.yaml`，将它与最终工作区中的发布说明一起提交为 `chore(release): prepare vX.Y.Z`。
+不要提前单独提交说明或把版本文件改成目标版本；脚本要求说明相对 HEAD 有改动，并自行更新版本号。
+本任务需要的提交按贡献文档保留英文 Conventional Commits 与相应署名。
+
+在准备完成且用户已授权正式发布后，将 `release_version` 设为已确定的版本，执行：
+
+```bash
+release/publish "$release_version"
+```
+
+该命令会创建包含版本号和发布说明的单次提交与 annotated tag，原子推送分支和 tag，再从长期分支手动触发 `release.yml`。
+它没有只读预演模式；不能为了检查或演练而执行。发布工作流读取 tag 中的说明，修改 tag 之后的本地文件不会改变该次构建。
+
+## 恢复与验收
+
+- 脚本中断或网络超时时，先核对本地提交与 tag、远端分支与 tag、对应工作流 run 及 Release，确定已完成到哪一步。
+  若本地已创建版本提交或 tag，不直接重跑入口，也不通过删 tag、回退版本或强推来消除报错。
+- 提交和 tag 已推送但工作流未触发时，核对目标后使用脚本提示的 dispatch 命令补触发；
+  工作流已存在则跟踪或恢复对应 run，避免重复发布。发现 tag 指向不同提交时报告冲突，不移动已发布 tag。
+- 跟踪与本次 tag 对应的 run ID，核对工作流解析的目标提交。触发工作流成功只表示已开始，不能当作发布完成。
+- 发布完成后核对 GitHub Release 的版本、正式版/预发行状态和中文变更正文；对照平台清单与工作流确认归档、校验和及镜像产物。
+  工作流附加的安装说明和自动提交列表按其当前配置处理，不用它们替代手写的中文变更说明。
+- 返回版本、tag 对应提交、Release/工作流链接及实际结果。失败、仍在构建或缺失产物时明确说明，不能称为发布成功；
+  Release 和镜像已生成也不表示用户的运行实例已经升级。

.agents/skills/release/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "release"
+  short_description: "按仓库流程整理中文发布说明、核对版本并完成发行与验证"
+  default_prompt: "使用 $release 准备下一个版本的中文发布说明，并核对发版条件。"

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,120 @@
+name: 问题反馈
+description: 提交可复现的问题，帮助定位和修复
+body:
+  - type: markdown
+    attributes:
+      value: |
+        请提供最小复现信息。请求、日志和截图发布前请移除密钥、令牌、Cookie、代理认证及私人内容。
+
+  - type: dropdown
+    id: issue-type
+    attributes:
+      label: 问题类型
+      options:
+        - 接口请求或响应异常
+        - 页面或交互异常
+        - 配置或部署异常
+        - 其他问题
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: 问题描述
+      description: 说明发生了什么、实际结果以及出现的频率。
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: 服务版本
+      description: 填写具体版本号；从源码运行时填写提交号。
+      placeholder: 版本号或提交号
+    validations:
+      required: true
+
+  - type: dropdown
+    id: deployment
+    attributes:
+      label: 部署方式
+      options:
+        - Docker Compose
+        - 其他容器部署
+        - 二进制运行
+        - 源码运行
+        - 其他方式（请在环境信息中说明）
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: 环境信息
+      description: 填写操作系统与版本；页面问题同时填写浏览器与版本。
+      placeholder: |
+        操作系统与版本：
+        浏览器与版本（页面问题）：
+    validations:
+      required: true
+
+  - type: textarea
+    id: account-client
+    attributes:
+      label: 账号与客户端
+      description: 接口问题请填写平台、认证类型、模型和客户端信息，不要提供账号凭据。
+      placeholder: |
+        平台与认证类型：
+        模型名称：
+        客户端名称与版本：
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: 复现步骤
+      description: 描述触发问题的操作；无法稳定复现时，说明已知触发条件。
+      placeholder: |
+        1. 使用什么配置或输入
+        2. 执行什么操作
+        3. 出现什么结果
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: 预期行为
+      description: 说明原本期望得到的结果。
+    validations:
+      required: true
+
+  - type: textarea
+    id: request-response
+    attributes:
+      label: 请求与响应
+      description: |
+        接口问题请提供脱敏后的最小请求、网关实际状态/响应片段和客户端终端显示，区分两者。
+        优先附管理端默认诊断包并检查其缺失说明；原始错误与日志片段需另行审阅脱敏。
+        先按部署文档的“请求错误排查”检查关联 ID、错误详情与 application 日志，不默认开启完整 dump。
+      placeholder: |
+        发生时间与时区：
+        传输（HTTP JSON / SSE / WebSocket）：
+        网关关联 ID（x-gateway-request-id / 配置的入口头）：
+        上游关联 ID（x-request-id / x-oai-request-id，注明来源）：
+        网关实际状态与响应片段：
+        客户端终端显示：
+        诊断包或无法取得的信息：
+      render: text
+
+  - type: textarea
+    id: screenshots
+    attributes:
+      label: 截图或录屏
+      description: 页面或交互问题可在此拖入相关截图、录屏，并说明对应的操作。
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: 补充信息
+      description: 最近的升级或配置变更；网络问题补充系统代理、TUN 和自定义证书等相关环境。

.github/dependabot.yml

@@ -21,11 +21,27 @@ updates:
       day: monday
       time: '09:10'
       timezone: Asia/Shanghai
-    # 固定官方 Codex Desktop 的 TLS 指纹；升级前必须抓取握手并比对扩展顺序。
+    # 按官方 Codex 锁文件、协议指纹或已审计 fork 固定；完成对应核对与实测后再手动升级。
     ignore:
+      - dependency-name: aws-lc-rs
+      - dependency-name: hyper
       - dependency-name: hyper-rustls
+      - dependency-name: hyper-tls
+      - dependency-name: hyper-util
+      - dependency-name: native-tls
+      - dependency-name: openssl
+      - dependency-name: openssl-src
+      - dependency-name: openssl-sys
       - dependency-name: reqwest
       - dependency-name: rustls
+      - dependency-name: rustls-native-certs
+      - dependency-name: rustls-pki-types
+      - dependency-name: tokio
+      - dependency-name: tokio-native-tls
+      - dependency-name: tokio-rustls
+      - dependency-name: tokio-tungstenite
+      - dependency-name: tungstenite
+      - dependency-name: zstd
     groups:
       minor-and-patch:
         update-types:

.github/workflows/_quality.yml

@@ -159,7 +159,7 @@ jobs:
           ref: ${{ inputs.ref }}
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
         with:
           version: 11.7.0
 
@@ -205,3 +205,6 @@ jobs:
           rhysd/actionlint:1.7.7@sha256:887a259a5a534f3c4f36cb02dca341673c6089431057242cdc931e9f133147e9
           -color
           .github/workflows/*.yml
+
+      - name: Check release script syntax
+        run: bash -n release/publish

.github/workflows/agents-md-guard.yml

@@ -0,0 +1,75 @@
+name: Agent Instructions Guard
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - edited
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: agents-md-guard-${{ github.event.pull_request.number }}
+  cancel-in-progress: false
+
+jobs:
+  guard:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      # 只查询 PR 元数据，禁止检出或执行贡献分支中的代码。
+      - name: Enforce agent instructions policy
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const { owner, repo } = context.repo;
+            const pr = context.payload.pull_request;
+            const params = { owner, repo, pull_number: pr.number };
+            const files = await github.paginate(github.rest.pulls.listFiles, {
+              ...params,
+              per_page: 100,
+            });
+            const isInstructions = path => typeof path === 'string'
+              && (path === 'AGENTS.md' || path.endsWith('/AGENTS.md'));
+
+            // 同时检查重命名前后的路径，避免通过移走规则文件绕过检查。
+            if (!files.some(file => isInstructions(file.filename) || isInstructions(file.previous_filename))) {
+              core.info('No agent instruction changes detected.');
+              return;
+            }
+
+            // 旧事件不处理后续提交，也不重复处理已关闭的 PR。
+            const { data: current } = await github.rest.pulls.get(params);
+            if (current.state !== 'open' || current.head.sha !== pr.head.sha) {
+              core.info('Pull request state has changed; skipping this event.');
+              return;
+            }
+
+            const marker = '<!-- agents-md-guard -->';
+            const body = [
+              marker,
+              '此 PR 修改了 `AGENTS.md`，已按贡献规则关闭。',
+              '',
+              'PR 不接受根目录或子目录中 `AGENTS.md` 的新增、修改、删除或重命名。',
+              '请撤销相关变更后重新打开 PR；如需调整协作规则，请先提交 Issue 说明原因和建议，由维护者处理。',
+            ].join('\n');
+
+            try {
+              const comments = await github.paginate(github.rest.issues.listComments, {
+                owner, repo, issue_number: pr.number, per_page: 100,
+              });
+              const notified = comments.some(comment => comment.user?.login === 'github-actions[bot]'
+                && comment.body?.includes(marker));
+              if (!notified) {
+                await github.rest.issues.createComment({ owner, repo, issue_number: pr.number, body });
+              }
+            } catch (error) {
+              core.warning(`Unable to post policy explanation: ${error.message}`);
+            }
+
+            await github.rest.pulls.update({ ...params, state: 'closed' });
+            core.setFailed('Pull requests must not change AGENTS.md.');

.github/workflows/ci.yml

@@ -6,6 +6,7 @@ on:
       - main
     paths-ignore:
       - 'release/version.yaml'
+      - 'release/notes.md'
   pull_request:
     branches:
       - main

.github/workflows/release.yml

@@ -88,6 +88,13 @@ jobs:
           fail("Release tag #{release_tag} does not match #{version_path} tag #{expected_tag}") unless release_tag == expected_tag
           fail("#{version_path}: version #{version} is not a valid semver") unless version.match?(SEMVER)
 
+          notes_path = "release/notes.md"
+          fail("#{notes_path}: release notes are required") unless File.file?(notes_path)
+          notes = File.readlines(notes_path)
+          unless notes.first&.strip == "# #{release_tag}" && !notes.drop(1).join.strip.empty?
+            fail("#{notes_path}: expected non-empty notes starting with '# #{release_tag}'")
+          end
+
           platforms = platforms_data["platforms"]
           fail("#{platforms_path}: platforms must be a non-empty array") unless platforms.is_a?(Array) && !platforms.empty?
 
@@ -308,6 +315,7 @@ jobs:
         shell: bash
         env:
           VERSION: ${{ needs.release-info.outputs.version }}
+          DOCKER_VERSION: ${{ needs.release-info.outputs.docker_version }}
         run: |
           set -euo pipefail
           ruby <<'RUBY' > release-platforms.json
@@ -342,7 +350,18 @@ jobs:
 
           shutil.rmtree(release_dir, ignore_errors=True)
           release_dir.mkdir(parents=True)
-          archives = []
+          config_template = pathlib.Path("deploy/config.example.yaml")
+          shutil.copy2(config_template, release_dir / config_template.name)
+          compose = pathlib.Path("deploy/compose.yaml").read_text()
+          image = f"{os.environ['REGISTRY']}/{os.environ['IMAGE_NAME']}"
+          default_image = "${CPR_IMAGE:-" + image + ":latest}"
+          if compose.count(default_image) != 1:
+              raise SystemExit("Expected exactly one default application image in deploy/compose.yaml")
+          # 发布附件固定镜像版本，防止后续 pull 与随包配置模板脱节。
+          versioned_image = "${CPR_IMAGE:-" + f"{image}:{os.environ['DOCKER_VERSION']}" + "}"
+          compose = compose.replace(default_image, versioned_image)
+          (release_dir / "compose.yaml").write_text(compose)
+          assets = [release_dir / config_template.name, release_dir / "compose.yaml"]
 
           for platform in platforms:
               platform_name = f"{platform['os']}-{platform['arch']}"
@@ -360,6 +379,9 @@ jobs:
               shutil.copy2(binary_src, binary_dest)
               binary_dest.chmod(0o755)
               shutil.copytree(frontend_dir, web_dist, dirs_exist_ok=True)
+              deploy_dir = package_root / "deploy"
+              deploy_dir.mkdir()
+              shutil.copy2(config_template, deploy_dir / config_template.name)
 
               archive_name = f"{APP_NAME}_{version}_{platform['os']}_{platform['arch']}.{platform['archive']}"
               archive_path = release_dir / archive_name
@@ -368,12 +390,12 @@ jobs:
                       archive.add(package_root, arcname=APP_NAME)
               else:
                   raise SystemExit(f"Unsupported archive format: {platform['archive']}")
-              archives.append(archive_path)
+              assets.append(archive_path)
 
           checksum_path = release_dir / "checksums.txt"
           with checksum_path.open("w", encoding="utf-8") as file:
-              for archive in archives:
-                  file.write(f"{sha256(archive)}  {archive.name}\n")
+              for asset in assets:
+                  file.write(f"{sha256(asset)}  {asset.name}\n")
           PY
 
       - name: Generate release asset provenance
@@ -643,6 +665,43 @@ jobs:
 
           cosign sign --yes "${images[@]}"
 
+      - name: Prepare release notes
+        shell: bash
+        env:
+          INSTALLATION_NOTES: |
+            > [!WARNING]
+            > **跨大版本升级：** 不支持跨大版本在线升级。请使用全新的 `.runtime/` 数据目录重新部署，再重新导入或重新授权服务商账号，并重新导入客户端密钥。详见[升级说明](https://github.com/${{ github.repository }}/blob/${{ needs.release-info.outputs.tag }}/deploy/README.md#镜像升级与源码构建)。
+
+            ## 📥 安装
+
+            **Docker 部署：**
+            ```bash
+            # 从 GitHub 容器镜像仓库拉取
+            docker pull ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ needs.release-info.outputs.docker_version }}
+            ```
+
+            请从本版本附件下载 `compose.yaml` 和 `config.example.yaml`。Compose 默认固定到本版本镜像；升级前请对比模板与已有配置。
+
+            **手动下载：**
+            请从下方附件中下载适合当前平台的归档包。
+
+            发布归档提供 GitHub 构建产物证明。Docker 镜像附带软件物料清单（SBOM）、构建来源证明和 cosign 无密钥签名。
+
+            ## 📚 文档
+
+            - [GitHub 仓库](https://github.com/${{ github.repository }})
+            - [部署指南](https://github.com/${{ github.repository }}/blob/${{ needs.release-info.outputs.tag }}/deploy/README.md)
+        run: |
+          python3 <<'PY'
+          import os
+          from pathlib import Path
+
+          notes = "\n".join(Path("release/notes.md").read_text().splitlines()[1:]).strip()
+          installation = os.environ["INSTALLATION_NOTES"].strip()
+          output = Path(os.environ["RUNNER_TEMP"]) / "release-notes.md"
+          output.write_text(f"{notes}\n\n{installation}\n")
+          PY
+
       - name: Publish GitHub Release
         uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3.0.3
         with:
@@ -651,27 +710,7 @@ jobs:
           previous_tag: ${{ needs.release-info.outputs.previous_tag }}
           prerelease: ${{ needs.release-info.outputs.prerelease == 'true' }}
           make_latest: ${{ needs.release-info.outputs.prerelease == 'true' && 'false' || 'true' }}
-          body: |
-            > [!WARNING]
-            > **Upgrading across major versions?** Online upgrades across major versions are not supported. Deploy the new major fresh with a new `.runtime/` data directory, then re-import or re-authorize provider accounts and client keys. See the [upgrade notes](https://github.com/${{ github.repository }}/blob/main/deploy/README.md#镜像升级与源码构建).
-
-            ## 📥 Installation
-
-            **Docker:**
-            ```bash
-            # GitHub Container Registry
-            docker pull ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ needs.release-info.outputs.docker_version }}
-            ```
-
-            **Manual download:**
-            Download the appropriate archive for your platform from the assets below.
-
-            Release archives are covered by GitHub artifact attestations. Docker images are published with SBOM/provenance attestations and keyless cosign signatures.
-
-            ## 📚 Documentation
-
-            - [GitHub Repository](https://github.com/${{ github.repository }})
-            - [Installation Guide](https://github.com/${{ github.repository }}/blob/main/deploy/README.md)
+          body_path: ${{ runner.temp }}/release-notes.md
           fail_on_unmatched_files: true
           files: |
             dist/release/*

.github/workflows/security-scan.yml

@@ -40,7 +40,16 @@ jobs:
 
       - name: Run cargo audit
         working-directory: backend
-        run: cargo audit
+        shell: bash
+        run: |
+          # 临时接受此中危风险以保持 Codex 0.154.0 的 TLS 指纹；直接升级会新增 ML-DSA 签名算法。
+          # 仅豁免本条公告，2026-09-21 UTC 起恢复阻断；兼容升级验证完成后应提前删除豁免。
+          # https://github.com/rustls/rustls/security/advisories/GHSA-2mjx-qc3c-rqvc
+          audit_advisory_args=()
+          if [[ "$(date -u +%F)" < "2026-09-21" ]]; then
+            audit_advisory_args+=(--ignore RUSTSEC-2026-0285)
+          fi
+          cargo audit "${audit_advisory_args[@]}"
 
   frontend-security:
     runs-on: ubuntu-latest
@@ -52,7 +61,7 @@ jobs:
           ref: ${{ github.event.pull_request.head.sha || github.sha }}
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
         with:
           version: 11.7.0
 

.gitignore

@@ -33,7 +33,6 @@ Thumbs.db
 # Local tools and worktrees
 /.codegraph/
 /.codex-ws-audit/
-/.agents/
 /.reasonix/
 /.claude
 /.worktrees/

AGENTS.md

@@ -0,0 +1,47 @@
+# 项目协作约定
+
+开发和审查先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，使用其中的协作流程和审查标准。
+模块职责以 [系统架构](docs/architecture.md) 为准，界面约定以 [管理端主题](docs/theme.md) 为准；
+没有明确约定时保持与相邻实现一致，不把单次页面反馈扩展成全仓规则。
+
+<!-- CODEGRAPH_START -->
+## CodeGraph
+
+In repositories indexed by CodeGraph (a `.codegraph/` directory exists at the repo root), reach for it BEFORE grep/find or reading files when you need to understand or locate code:
+
+- **MCP tools** (when available): `codegraph_explore` answers most code questions in one call — the relevant symbols' verbatim source plus the call paths between them. `codegraph_node` returns one symbol's source + callers, or reads a whole file with line numbers. If the tools are listed but deferred, load them by name via tool search.
+- **Shell** (always works): `codegraph explore "<symbol names or question>"` and `codegraph node <symbol-or-file>` print the same output.
+
+If there is no `.codegraph/` directory, skip CodeGraph entirely — indexing is the user's decision.
+<!-- CODEGRAPH_END -->
+
+## 工作方式
+
+- 开发和审查按 [问题与方案依据](CONTRIBUTING.md#问题与方案依据) 先核实问题，以官方源码为首要参考确定或评估方案。
+- 先定位变更所属模块、同类实现和上下游调用关系，再选择最小合理改动。复用已有能力，也避免为尚不存在的需求增加抽象。
+- 代码注释使用中文，解释原因与边界；提交信息使用英文，沿用历史中的 Conventional Commits 格式。
+- 按变更范围执行验证，记录命令、结果和缺口。跳过的测试不算通过；界面与集成行为需要对应运行证据，构建通过不能替代实际验收。
+- 审查请求默认只读。修复、提交、推送和合并按用户当前授权执行；“本地验证通过”不等于用户已经审阅批准。
+- 不读取或输出无关凭据，不把真实密钥、代理认证、账号令牌或请求转储放入提交、截图及审查报告。
+
+## Code Review Rules
+
+### 审查范围
+
+- 确认目标分支与当前变更范围，结合调用方、被调用方及已有测试审查；结论对应实际审查的提交或工作区状态。
+- 按 CONTRIBUTING.md 的维度检查设计、正确性、安全、复杂度、性能、可读性、验证、界面和文档，深度与变更风险相称。
+- 重点核对现有架构和数据合同：共享业务事实是否重复解释，异步与并发操作是否破坏状态，权限和敏感数据是否越界，协议适配是否影响兼容性。
+- 修改既有特殊分支时先查场景和历史；放宽检查、修改测试或新增例外需要业务依据，不能仅以让检查通过为理由。
+
+### 代码与界面一致性
+
+- 对重复逻辑、冗余状态和多余抽象给出具体位置及影响；建议复用时指出已有实现，不能仅凭行数或语法相似判定质量。
+- UI 变更对照项目基础组件、主题和同类页面，检查交互、状态、响应式与可访问性。局部问题是否应在共用组件修复，按职责判断，不一律禁止局部样式。
+- 核对截图、预览和实际交互证据；未检查的状态明确列为验证缺口，不推断视觉验收已经通过。
+
+### 审查输出
+
+- 用中文先回答原问题是否成立、解决方向是否合理，依据与判断标准见 [贡献与审查](CONTRIBUTING.md#审查标准)，再报告实现问题和验证缺口。
+- 实现问题聚焦本次变更新引入或加重的、可定位的问题，包含文件位置、触发场景或规范依据、影响和最小修复方向。
+- 区分必须修复的问题、可选建议和验证缺口。个人偏好标为建议，不作为必须修复项；没有问题时不要凑数。
+- 严重程度按实际影响判断，不为绕过工具的优先级过滤而升级普通规范问题。说明审查和验证的实际覆盖范围，AI 未报告问题不等于维护者批准。

CONTRIBUTING.md

@@ -0,0 +1,145 @@
+# 贡献与审查
+
+贡献应解决明确的问题，并保持或改善项目的可维护性。提交者、自动检查和审查者使用同一套标准，让重复问题在提交和初审阶段得到处理。
+
+本文定义协作流程与审查标准；模块职责以 [系统架构](docs/architecture.md) 为准，视觉规则以 [管理端主题](docs/theme.md) 为准。没有明确约定时遵循相邻实现；具体页面的布局决定不自动成为全项目限制。
+
+## 提交 Issue
+
+问题反馈使用仓库的 [Issue 表单](.github/ISSUE_TEMPLATE/bug_report.yml)，填写问题类型、描述、版本与环境、复现步骤和预期结果。接口问题补充平台与认证类型、模型、客户端，以及脱敏后的请求、响应和请求 ID；页面问题附相关截图或录屏。
+
+日志和配置只提供定位所需片段，不上传真实凭据或完整请求转储。功能建议与协作规则调整可直接提交 Issue，说明场景、原因和建议方案。
+
+## 问题与方案依据
+
+开发、创建 PR 和审查都先核实待解决的问题、触发条件与预期行为，再确定或评估实现。区分问题发生版本、目标分支现状和本次变更后的行为，不把需求描述、PR 描述或第三方项目的做法直接当成事实。目标分支已修复的问题，应说明当前仍需补齐的差异，不能据此否定旧版本中的问题。
+
+涉及上游协议、客户端行为或兼容性时，以对应版本的官方源码为首要资料。优先读取用户提供或本机已有的官方源码，核对仓库来源、版本或提交；本地资料不足时查官方仓库的对应版本源码，再结合官方测试、文档、发布说明和运行证据。第三方资料只作线索或补充。引用具体文件、符号或行号，对外引用优先使用固定提交的源码链接；源码不可得或版本不匹配时说明证据缺口，不把最新实现当成当前部署行为。无上游依赖的内部变更，以本项目代码、合同和运行证据为依据。
+
+官方已有同一场景的处理方式时，优先沿用其协议语义、职责归属和解决路径，检查是否只需复用已有能力或正确传递官方合同。新增覆盖配置、补偿逻辑或采用第三方兼容方案，应说明官方路径为何不足；偏离官方方案需有本项目的实际约束和验证依据，不机械照搬源码，也不默认接受已有提案。
+
+反馈 Issue 时区分观察到的症状、根因假设和方案建议，关联已有 Issue、PR 及包含修复的发布版本。能说明问题的反馈可以先提交，不要求报告者先找到官方源码或证明根因；引用官方行为或提出实现方案时，按上述原则注明依据与缺口。
+
+## PR 流程
+
+1. **准备变更。** 按上述依据核实问题与方案，找到所属模块、相关调用链和最接近的现有实现，在功能分支完成修改与自查。涉及架构、公开合同或较大交互变化时，先说明方案与取舍。
+2. **发起 PR。** 目标分支使用 `main`。说明问题成立的依据、触发场景、改动后的行为和实际验证结果；涉及官方行为时注明源码位置、版本和方案关系。界面改动提供截图、录屏或可复现的预览方式。一个 PR 围绕一个明确目标，必要重构说明关联原因。
+3. **自动检查与初审。** CI 执行适用的格式、静态分析、测试和构建检查；启用 AI 审查后，由它按本规范辅助检查语义、复用和一致性。提交者先处理明确问题，维护者重点审阅方案、风险与用户体验。
+4. **修改与合并。** 更新代码后重新执行受影响的检查，确认审查意见已处理，验证证据对应当前变更。维护者审阅批准后再合并；需要升级说明的变更同步相关文档。
+
+AI 开发和审查入口是根目录的 [AGENTS.md](AGENTS.md)。在仓库上下文中要求“审查 PR #编号”时，应按下列标准执行，无需再次列举要求。
+
+### 项目技能
+
+仓库技能位于 `.agents/skills/`，随代码共享。技能提供执行流程，协作与审查标准仍以本文和 `AGENTS.md` 为准。
+
+| 技能 | 用途 | 调用示例 |
+| --- | --- | --- |
+| [dev-guide](.agents/skills/dev-guide/SKILL.md) | 项目开发与文档导航 | `$dev-guide 修复当前问题` |
+| [github-pr](.agents/skills/github-pr/SKILL.md) | 创建或审查 PR | `$github-pr 创建当前分支的 PR` / `$github-pr 审查 PR #编号` |
+| [github-issue](.agents/skills/github-issue/SKILL.md) | 整理或提交 Issue | `$github-issue 提交当前问题` |
+| [release](.agents/skills/release/SKILL.md) | 准备发布说明或正式发版 | `$release 整理本次发布说明` / `$release 发布 vX.Y.Z` |
+
+审查请求默认在当前会话报告；明确要求创建 PR、提交 Issue 或正式发版时才执行对应远程操作。技能安装不等于启用 GitHub 自动审查。
+
+### 规则文件保护
+
+PR 不接受根目录或子目录中 `AGENTS.md` 的新增、修改、删除或重命名。调整这些文件时先提交 Issue 说明原因和建议，由维护者处理；[规则保护工作流](.github/workflows/agents-md-guard.yml) 会提示并关闭包含此类变更的 PR。撤销相关变更后可以重新打开 PR，继续正常检查。
+
+源码变更遵守现有架构边界与迁移冻结规则，由对应 CI 检查执行；不额外设立整块业务目录的 PR 禁改清单。构建、测试和安全扫描复用现有工作流。
+
+## 审查标准
+
+按改动涉及的范围选择检查深度，无需为每个 PR 填写所有维度的报告。
+
+结论先回答原问题是否成立（成立、部分成立、不成立或证据不足），说明触发条件和依据；再判断解决方向是否合理，交代适用的官方方案、本次实现与它的关系及必要调整，最后报告实现问题与验证缺口。原问题是否成立与 PR 实现是否正确分别判断。源码推断、实际复现和检查结果分别说明，CI 通过不能代替问题与方案的论证。
+
+| 维度 | 检查重点 |
+| --- | --- |
+| 设计与架构 | 职责归属、依赖方向、公开接口是否合理；是否融入已有体系，有无绕过边界的旁路 |
+| 正确性与兼容性 | 正常、异常和边界输入；并发、取消、重试与副作用；是否改变既有 API、协议或数据合同 |
+| 安全与数据 | 权限、输入校验、敏感信息、状态隔离和持久化一致性；日志与诊断是否符合脱敏边界 |
+| 简洁性与复用 | 重复业务规则、冗余状态、无效代码和过早抽象；能否用更直接的实现解决当前问题 |
+| 性能与资源 | 实际数据规模下的查询、请求、内存与连接成本；资源释放、背压和异常时的生命周期 |
+| 可读性与风格 | 命名是否准确，控制流是否易懂，格式是否一致；注释解释约束与原因而非复述代码 |
+| 测试与验证 | 是否覆盖真实触发条件和结果，能否发现回归；证据是否对应本次变更，有无跳过或缺失项 |
+| 界面与交互 | 共用组件和主题、信息层级、状态反馈、响应式、键盘操作及可访问性；是否有实际页面证据 |
+| 文档与升级 | 行为、配置、API 和部署说明是否同步；数据迁移和兼容影响是否交代清楚 |
+
+审查意见区分三类：
+
+- **必须修复：** 有具体触发条件的缺陷、违反现有合同或明确项目规范的问题。说明位置、依据、影响和最小修复方向。
+- **建议：** 不影响合同或规范的替代实现、命名偏好和局部优化。个人偏好不能单独阻止合并，也不应强求与本次目标无关的重构。
+- **验证缺口：** 尚未检查的行为、状态或运行环境。说明缺少什么证据，由维护者评估是否需要补齐，不能把未验证当作已通过或已发现缺陷。
+
+复杂度不按行数判断，复用不只看语法相似。建议合并重复逻辑时应指出共享的业务含义；建议保留特殊分支时应能说明它服务的场景。例外应有依据，不能仅为绕过检查而放宽规则。
+
+## 项目约定
+
+- AI 进行 Rust 开发时，加载并使用 `$rust-best-practices` 技能。模块、可见性、依赖方向和测试目录按架构文档执行，使用现有 Rustfmt 与 Clippy 配置。
+- Vue 使用 TypeScript、`<script setup>` 和现有 ESLint 配置；API 请求通过已有模块及 `request` 封装，沿用逐行请求配置格式。
+- 业务数据的解析、校验和展示优先复用已有逻辑。新增抽象放在拥有该职责的模块，避免重复事实源或无实际需求的通用层。
+- 新增代码注释使用中文。提交信息使用英文 Conventional Commits，参考近期历史，按完整功能归并；确由 Codex 参与的提交保留 `Co-authored-by: Codex <noreply@openai.com>`。
+- 发布说明写入 `release/notes.md`，标题首行为目标版本的 `# vX.Y.Z`，章节标题和正文使用中文；命令、配置键、协议名等保留原文。只说明本次版本的实际变化，按影响交代升级事项。
+- PR 聚焦目标；无关格式化、重构和依赖升级单独处理。
+
+## 文档职责与更新条件
+
+常规文档说明当前有效的用法、接口合同、模块职责和维护约束，不承担变更历史。
+只有改动使对应说明失真、缺少必要信息，或改变读者需要执行的操作与判断时，才更新文档。
+内部修复、重构和界面微调不默认附带文档改动；审查时不能仅因 PR 没改文档就判定存在缺口。
+
+- 按 [开发指南的文档入口](.agents/skills/dev-guide/SKILL.md#按任务读取) 找到内容所属文档，在原有章节就地修订，
+  不按每次变更追加说明。同一事实只保留一处完整说明，其他文档按读者任务提供必要摘要和链接。
+- API 文档保留调用所需的字段、状态、语义和限制；架构文档保留职责与不变量；部署文档保留配置、操作和排障。
+  不把界面布局、内部锁或索引实现写进接口说明，也不把前端库的实现选择写进部署说明。
+- 改动原因、前后对比、排查经过和本次验证结果放在 PR / Issue 或任务报告。版本变更与升级影响按维护者的发版安排维护
+  `release/notes.md`，不为普通开发任务或 PR 自动追加发布说明。
+- 仍影响实际升级、恢复或兼容使用的限制与操作应保留，并注明适用条件；不能仅因涉及旧版就删除。
+  审查文档改动时核对必要性、所属职责与重复内容，区分当前使用说明和仅解释此次修复的内容。
+
+## 界面验证
+
+AI 进行前端开发时，加载并使用 `$frontend-design` 技能。设计方案以本项目的用户任务、[管理端主题](docs/theme.md) 和已有组件为依据，在任务范围内改进布局、视觉与交互。
+
+开发前查找同类页面及 `components/base` 中的基础组件，优先使用已有主题 Token、交互和数据展示逻辑。需要扩展时在对应职责层修改；局部样式的适用范围遵循主题文档，不一律禁止，也不靠页面覆盖掩盖共用组件的问题。
+
+列表列宽、序号、按钮、分页和弹窗尺寸由实际任务与数据规模决定，以同类页面为参照。新增或调整交互时说明用户需要完成什么操作，不把某个页面的取舍推广成全局禁令。
+
+提交者在浏览器中验证受影响路径，提供前后截图、录屏或预览步骤，并标明实际覆盖的状态。按变更选择浅色/深色、窄窗口、空/加载/错误状态、大量数据及键盘操作；共用主题或基础组件变更按主题文档扩大验证范围。模拟数据与预览材料不包含真实凭据。
+
+涉及浏览器能力或访问环境差异时，按项目支持的部署方式核对相关 HTTP/HTTPS、localhost/实际部署地址与浏览器版本，记录实际覆盖的条件；本地预览正常不能替代部署环境中的交互验收。
+
+## 验证
+
+选择与变更相关的检查，纯文档修改无需重建前后端。行为修复补充能覆盖触发条件和结果的测试，不增加仅复述实现的断言。
+
+| 范围 | 现有检查 | 仍需提供的证据 |
+| --- | --- | --- |
+| Rust | Rustfmt、严格 Clippy、后端测试、架构边界检查 | 相关失败场景和集成行为 |
+| 前端 | ESLint、类型检查与构建 | 页面一致性、交互和实际数据状态 |
+| 数据库迁移 | 冻结清单校验与 PR 基线比对 | 升级行为及兼容说明 |
+| 依赖安全 | Cargo Audit、pnpm Audit | 本次变更的权限、数据与信任边界 |
+| 工作流与容器 | Actionlint、相关容器检查 | 改动涉及的运行行为 |
+
+前端从仓库根目录执行：
+
+```bash
+pnpm --dir frontend format:check
+pnpm --dir frontend build
+git diff --check
+```
+
+`build` 已包含类型检查；不维护独立前端测试代码。后端的工具链、命令与线程栈设置统一见 [修改与验收](docs/architecture.md#12-修改与验收)。
+
+依赖 PostgreSQL / Redis 的测试使用 [专用测试环境](backend/migrations/README.md#本地测试库)，未配置导致跳过时明确记录。CI 中已有对应服务和检查，见 [质量工作流](.github/workflows/_quality.yml) 与 [安全扫描](.github/workflows/security-scan.yml)。
+
+集成变更应验证实际业务路径及结果，不能只凭健康检查或探测成功认定全链路正常。协议和网络改动按需核对认证、证书、代理、流式交付及客户端结果；记录影响复现的环境条件。缺少运行条件时说明缺口，不用模拟结果代替真实集成结论。
+
+## 自动检查与合并条件
+
+[CI](.github/workflows/ci.yml) 已按变更范围调用现有质量检查。新增自动规则优先使用现有工具，要求依据明确、结果稳定、误报可控；无法可靠判定的设计与视觉问题保留审查判断，避免把具体源码写法锁成测试。
+
+AI 自动审查需要在所用工具中单独启用。其支持的检查范围和优先级过滤以工具说明为准；即使能读取 `AGENTS.md`，也不能保证所有可维护性和视觉问题都会被报告。配置参考 [Codex GitHub 审查文档](https://learn.chatgpt.com/docs/third-party/github)。
+
+要由 GitHub 强制执行合并条件，维护者需配置对应分支的必需状态检查、审阅批准和讨论解决要求，并按需要设置新提交后的重新审阅。配置前核对实际检查名称与触发范围，见 [GitHub 分支保护](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)。规则文档本身不会启用 AI 服务或更改分支设置。

README.md

@@ -5,59 +5,47 @@
 
 # Codex Proxy RS
 
-面向 Codex 的自托管多账号 AI 网关。
+面向 Codex 的自托管多账号 AI 网关
 
 [![CI](https://github.com/zyycn/codex-proxy-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/zyycn/codex-proxy-rs/actions/workflows/ci.yml)
 [![Release](https://img.shields.io/github/v/release/zyycn/codex-proxy-rs?display_name=tag&sort=semver&style=flat-square)](https://github.com/zyycn/codex-proxy-rs/releases)
 [![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)
 
-[功能](#功能) · [快速开始](#快速开始) · [客户端接入](#客户端接入) · [文档](#文档) · [社区](#社区) · [许可证](#许可证)
+[快速开始](#快速开始) · [客户端接入](#客户端接入) · [文档](#文档) · [社区](#社区) · [许可证](#许可证)
 
 </div>
 
-将 OpenAI、xAI 账号接入同一个服务，通过网页管理账号、分配客户端密钥和查看使用情况。
-客户端使用统一的访问地址与代理密钥，上游账号凭据由服务端管理。
-
-## 功能
-
-- **账号管理**：OAuth 授权、账号导入、凭据刷新与额度查看；支持独立出站代理及 sub2api OpenAI 账号代理导入。
-- **访问控制**：通过账号分组分配密钥权限，设置日/周 USD 限额、并发和请求频率。
-- **客户端接入**：支持 Codex CLI、桌面端与 Responses API 客户端，提供 HTTP 流式响应和 WebSocket。
-- **请求诊断**：查看请求记录、用量、费用、延迟和错误详情。
-- **部署运维**：Docker Compose 部署、S3/R2 数据库备份、同大版本在线更新与回滚。
-
-图片生成、编辑和 Codex 独立搜索由 OpenAI 账号提供；模型与功能的可用性取决于上游账号权限。
-
 > [!NOTE]
 > 本项目提供 Responses API，不支持 `/v1/chat/completions`。接入前请确认客户端支持 Responses 协议。
 
 ## 快速开始
 
-使用 Docker Compose 部署发布镜像 `ghcr.io/zyycn/codex-proxy-rs:latest`，同时启动 PostgreSQL 和 Redis。
+使用 Docker Compose 部署版本固定的发布镜像，同时启动 PostgreSQL 和 Redis。
 以下命令适用于 Linux amd64/arm64，需要 Docker Engine、Docker Compose Plugin、curl 和 OpenSSL。已有部署请先看
 [升级说明](deploy/README.md#镜像升级与源码构建)，不要覆盖原配置。
 
 ### 1. 下载部署文件并配置
 
 ```bash
-mkdir -p codex-proxy-rs/deploy
-cd codex-proxy-rs
+mkdir -p codex-proxy-rs/deploy && cd codex-proxy-rs
 
-curl -fsSL https://raw.githubusercontent.com/zyycn/codex-proxy-rs/main/deploy/compose.yaml \
+# 只解析一次最新正式版本，确保两个文件来自同一 Release。
+CPR_RELEASE_URL="$(curl -fsSL -o /dev/null -w '%{url_effective}' https://github.com/zyycn/codex-proxy-rs/releases/latest)"
+CPR_RELEASE_TAG="${CPR_RELEASE_URL##*/}"
+curl -fsSL "https://github.com/zyycn/codex-proxy-rs/releases/download/${CPR_RELEASE_TAG}/compose.yaml" \
   -o deploy/compose.yaml
-curl -fsSL https://raw.githubusercontent.com/zyycn/codex-proxy-rs/main/deploy/config.example.yaml \
+curl -fsSL "https://github.com/zyycn/codex-proxy-rs/releases/download/${CPR_RELEASE_TAG}/config.example.yaml" \
   -o deploy/config.example.yaml
 
-mkdir -p .runtime/data .runtime/logs
 install -d -m 0750 .runtime/postgres .runtime/redis
-cp deploy/config.example.yaml deploy/config.yaml
-sudo chown "$(id -u):10001" deploy/config.yaml
-chmod 0640 deploy/config.yaml
-sudo chown -R "$(id -u):10001" .runtime/data .runtime/logs
-chmod 0770 .runtime/data .runtime/logs
+sudo install -d -m 0770 -o "$(id -u)" -g 10001 .runtime/data .runtime/logs
+sudo install -m 0640 -o "$(id -u)" -g 10001 deploy/config.example.yaml deploy/config.yaml
 ```
 
+也可将 `CPR_RELEASE_TAG` 设置为指定的发布标签。Release 附带的 `compose.yaml` 默认使用该版本镜像，
+配置模板和部署文件均包含在 `checksums.txt` 中；不要混用 `main` 分支模板与已发布镜像。
+
 分别生成数据库和 Redis 密码：
 
 ```bash
@@ -73,8 +61,6 @@ openssl rand -hex 24
 | `store.redis.password` | 第二个生成的 48 位十六进制密码 |
 | `admin.default_password` | 管理员初始密码，至少 12 位，不能包含 `$` |
 
-不需要创建 `.env`。管理员初始密码只在首次创建账号时使用。
-
 ### 2. 启动服务
 
 ```bash
@@ -92,7 +78,7 @@ curl -i http://127.0.0.1:8080/healthz
 
 ### 3. 添加账号与客户端密钥
 
-1. 在「账号」中添加 OpenAI 或 xAI 账号，完成授权或导入。
+1. 在「账号」中添加账号，完成授权或导入。
 2. 按需建立账号分组，再创建客户端密钥并选择可用分组。**不选分组表示可使用全部账号**。
 3. 打开密钥的「使用密钥」，复制客户端配置。
 
@@ -106,7 +92,7 @@ curl -i http://127.0.0.1:8080/healthz
 | 配置 | 值 |
 | --- | --- |
 | Base URL | `http://127.0.0.1:8080/v1`；远程接入使用服务器的 HTTPS 地址 |
-| API Key | 管理端创建的 `sk_...` 客户端密钥 |
+| API Key | 管理端创建的客户端密钥 |
 
 可用模型以该密钥查询到的模型列表为准：
 
@@ -123,6 +109,7 @@ curl http://127.0.0.1:8080/v1/models \
 - [系统架构](docs/architecture.md)
 - [管理端主题](docs/theme.md)
 - [数据库迁移](backend/migrations/README.md)
+- [贡献与审查](CONTRIBUTING.md)
 
 ## 社区
 

backend/Cargo.lock

@@ -116,7 +116,7 @@ checksum = "82f6aeea286b8eb4dd3431a1be1b59d290ace00f5bfd8e2a159bc2a05e2c1667"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.4",
+ "syn 3.0.5",
 ]
 
 [[package]]
@@ -154,9 +154,9 @@ dependencies = [
 
 [[package]]
 name = "aws-lc-rs"
-version = "1.18.1"
+version = "1.16.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b281d307588d634de920874890732659e2e7672f72b5e10e81badc1a8a83621e"
+checksum = "a054912289d18629dc78375ba2c3726a3afe3ff71b4edba9dedfca0e3446d1fc"
 dependencies = [
  "aws-lc-sys",
  "untrusted 0.7.1",
@@ -165,22 +165,21 @@ dependencies = [
 
 [[package]]
 name = "aws-lc-sys"
-version = "0.45.0"
+version = "0.39.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9bff6c3b54fad79a2e60b8102caf565819711497c1f5f092f49508e2f5c31b27"
+checksum = "1fa7e52a4c5c547c741610a2c6f123f3881e409b714cd27e6798ef020c514f0a"
 dependencies = [
  "cc",
  "cmake",
  "dunce",
  "fs_extra",
- "pkg-config",
 ]
 
 [[package]]
 name = "aws-runtime"
-version = "1.9.1"
+version = "1.9.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c9007227e10b5fed2f3e0a2beff489211e2b5604c400b7a9d5d81ca9d64c24bb"
+checksum = "ef47857a1d4488b528f4a5d5715fa7c3300820897824152234d3fa22b1426657"
 dependencies = [
  "aws-credential-types",
  "aws-sigv4",
@@ -206,9 +205,9 @@ dependencies = [
 
 [[package]]
 name = "aws-sdk-s3"
-version = "1.144.0"
+version = "1.146.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "30dc8bf6baaf7d46336a0ca2c69f223d9b90d7a801fb3e28f7ea17b00dc6b1de"
+checksum = "37b5ffaae346b9bd486ebdc3eb7053ec8ab8a1ad0f19a332eefeff036ed559e6"
 dependencies = [
  "arc-swap",
  "aws-credential-types",
@@ -479,9 +478,9 @@ dependencies = [
 
 [[package]]
 name = "aws-types"
-version = "1.5.0"
+version = "1.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "eec1cd5469f328c782dc3e33d4153cf118a54e33cbb3356d60d16f89883e1f94"
+checksum = "209f3a6d82a6e9e5f94abbed94c7a26e1c052341002bf57a5fb5481f625896fc"
 dependencies = [
  "aws-credential-types",
  "aws-smithy-async",
@@ -709,6 +708,7 @@ checksum = "a6139a8597ed92cf816dfb33f5dd6cf0bb93a6adc938f11039f371bc5bcd26c3"
 dependencies = [
  "chrono",
  "phf 0.12.1",
+ "serde",
 ]
 
 [[package]]
@@ -740,17 +740,18 @@ dependencies = [
  "provider-xai",
  "serde",
  "serde_json",
- "syn 3.0.4",
+ "syn 3.0.5",
  "tempfile",
  "thiserror",
  "tokio",
+ "tokio-rustls",
 ]
 
 [[package]]
 name = "combine"
-version = "4.6.7"
+version = "4.6.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ba5a308b75df32fe02788e748662718f03fde005016435c444eea572398219fd"
+checksum = "cfc320937d09e6de266b31b9afb480f197d7a861be86be7cb2ea7e5d1bfffc5e"
 dependencies = [
  "bytes",
  "futures-core",
@@ -807,6 +808,16 @@ dependencies = [
  "url",
 ]
 
+[[package]]
+name = "core-foundation"
+version = "0.9.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91e195e091a93c46f7102ec7818a2aa394e1e1771c3ab4825963fa03e45afb8f"
+dependencies = [
+ "core-foundation-sys",
+ "libc",
+]
+
 [[package]]
 name = "core-foundation"
 version = "0.10.1"
@@ -1191,7 +1202,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
 dependencies = [
  "libc",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -1290,6 +1301,21 @@ version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb"
 
+[[package]]
+name = "foreign-types"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f6f339eb8adc052cd2ca78910fda869aefa38d22d5cb648e6485e4d3fc06f3b1"
+dependencies = [
+ "foreign-types-shared",
+]
+
+[[package]]
+name = "foreign-types-shared"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "00b0228411908ca8685dba7fc2cdd70ec9990a6e753e89b6ac91a84c40fbaf4b"
+
 [[package]]
 name = "form_urlencoded"
 version = "1.2.2"
@@ -1382,7 +1408,7 @@ checksum = "9fb9654ba8355388abeb8dcb4fc62f511300867002afc858860463bdd9fe0c44"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.4",
+ "syn 3.0.5",
 ]
 
 [[package]]
@@ -1433,6 +1459,7 @@ dependencies = [
  "cron",
  "futures",
  "gateway-core",
+ "heck",
  "hex",
  "rand_core 0.6.4",
  "secrecy",
@@ -1456,6 +1483,7 @@ dependencies = [
  "base64 0.23.1",
  "bytes",
  "chrono",
+ "flate2",
  "futures",
  "gateway-admin",
  "gateway-core",
@@ -1471,6 +1499,7 @@ dependencies = [
  "tracing",
  "url",
  "uuid",
+ "zstd",
 ]
 
 [[package]]
@@ -1875,6 +1904,22 @@ dependencies = [
  "tower-service",
 ]
 
+[[package]]
+name = "hyper-tls"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "70206fc6890eaca9fde8a0bf71caa2ddfc9fe045ac9e5c70df101a7dbde866e0"
+dependencies = [
+ "bytes",
+ "http-body-util",
+ "hyper",
+ "hyper-util",
+ "native-tls",
+ "tokio",
+ "tokio-native-tls",
+ "tower-service",
+]
+
 [[package]]
 name = "hyper-util"
 version = "0.1.20"
@@ -1892,9 +1937,11 @@ dependencies = [
  "percent-encoding",
  "pin-project-lite",
  "socket2",
+ "system-configuration",
  "tokio",
  "tower-service",
  "tracing",
+ "windows-registry",
 ]
 
 [[package]]
@@ -2232,6 +2279,23 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "native-tls"
+version = "0.2.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "87de3442987e9dbec73158d5c715e7ad9072fda936bb03d19d7fa10e00520f0e"
+dependencies = [
+ "libc",
+ "log",
+ "openssl",
+ "openssl-probe 0.1.6",
+ "openssl-sys",
+ "schannel",
+ "security-framework 2.11.1",
+ "security-framework-sys",
+ "tempfile",
+]
+
 [[package]]
 name = "new_debug_unreachable"
 version = "1.0.6"
@@ -2287,12 +2351,66 @@ version = "1.21.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 
+[[package]]
+name = "openssl"
+version = "0.10.75"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08838db121398ad17ab8531ce9de97b244589089e290a384c900cb9ff7434328"
+dependencies = [
+ "bitflags",
+ "cfg-if",
+ "foreign-types",
+ "libc",
+ "once_cell",
+ "openssl-macros",
+ "openssl-sys",
+]
+
+[[package]]
+name = "openssl-macros"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a948666b637a0f465e8564c73e89d4dde00d72d4d473cc972f390fc3dcee7d9c"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "openssl-probe"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d05e27ee213611ffe7d6348b942e8f942b37114c00cc03cec254295a4a17852e"
+
 [[package]]
 name = "openssl-probe"
 version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7c87def4c32ab89d880effc9e097653c8da5d6ef28e6b539d313baaacfbafcbe"
 
+[[package]]
+name = "openssl-src"
+version = "300.6.1+3.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "46eb8fb9fb3b61ce1c0f8a026c4c1a0714d3a9e138e7fbde78753ce2babc3846"
+dependencies = [
+ "cc",
+]
+
+[[package]]
+name = "openssl-sys"
+version = "0.9.111"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "82cab2d520aa75e3c58898289429321eb788c3106963d0dc886ec7a5f4adc321"
+dependencies = [
+ "cc",
+ "libc",
+ "openssl-src",
+ "pkg-config",
+ "vcpkg",
+]
+
 [[package]]
 name = "outref"
 version = "0.5.2"
@@ -2600,6 +2718,7 @@ dependencies = [
  "base64 0.23.1",
  "bytes",
  "chrono",
+ "chrono-tz",
  "cookie",
  "flate2",
  "futures",
@@ -2611,6 +2730,9 @@ dependencies = [
  "hyper",
  "hyper-rustls",
  "hyper-util",
+ "native-tls",
+ "openssl",
+ "openssl-sys",
  "reqwest",
  "roxmltree",
  "rustls",
@@ -2737,7 +2859,7 @@ dependencies = [
  "once_cell",
  "socket2",
  "tracing",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -2836,9 +2958,9 @@ dependencies = [
 
 [[package]]
 name = "redis"
-version = "1.6.0"
+version = "1.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e37a4ca5c6ca42aa3e6df2fd32b987a65d32a4c2159a6f3fe0fd1df306a2658f"
+checksum = "2acbc41a996f7652b2ddd9dfd98cc4ff602cfd742ae35382f07f608405ab50ed"
 dependencies = [
  "arc-swap",
  "arcstr",
@@ -2915,6 +3037,7 @@ dependencies = [
  "bytes",
  "cookie",
  "cookie_store",
+ "encoding_rs",
  "futures-core",
  "futures-util",
  "h2",
@@ -2923,9 +3046,12 @@ dependencies = [
  "http-body-util",
  "hyper",
  "hyper-rustls",
+ "hyper-tls",
  "hyper-util",
  "js-sys",
  "log",
+ "mime",
+ "native-tls",
  "percent-encoding",
  "pin-project-lite",
  "quinn",
@@ -2937,6 +3063,7 @@ dependencies = [
  "serde_urlencoded",
  "sync_wrapper",
  "tokio",
+ "tokio-native-tls",
  "tokio-rustls",
  "tokio-util",
  "tower",
@@ -3007,7 +3134,7 @@ dependencies = [
  "errno",
  "libc",
  "linux-raw-sys",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -3028,21 +3155,21 @@ dependencies = [
 
 [[package]]
 name = "rustls-native-certs"
-version = "0.8.4"
+version = "0.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dab5152771c58876a2146916e53e35057e1a4dfa2b9df0f0305b07f611fdea4d"
+checksum = "612460d5f7bea540c490b2b6395d8e34a953e52b491accd6c86c8164c5932a63"
 dependencies = [
- "openssl-probe",
+ "openssl-probe 0.2.1",
  "rustls-pki-types",
  "schannel",
- "security-framework",
+ "security-framework 3.7.0",
 ]
 
 [[package]]
 name = "rustls-pki-types"
-version = "1.15.1"
+version = "1.14.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2f4925028c7eb5d1fcdaf196971378ed9d2c1c4efc7dc5d011256f76c99c0a96"
+checksum = "be040f8b0a225e40375822a563fa9524378b9d63112f53e19ffff34df5d33fdd"
 dependencies = [
  "web-time",
  "zeroize",
@@ -3126,6 +3253,19 @@ dependencies = [
  "zeroize",
 ]
 
+[[package]]
+name = "security-framework"
+version = "2.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "897b2245f0b511c87893af39b033e5ca9cce68824c4d7e7630b5a1d339658d02"
+dependencies = [
+ "bitflags",
+ "core-foundation 0.9.4",
+ "core-foundation-sys",
+ "libc",
+ "security-framework-sys",
+]
+
 [[package]]
 name = "security-framework"
 version = "3.7.0"
@@ -3133,7 +3273,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b7f4bc775c73d9a02cde8bf7b2ec4c9d12743edf609006c7facc23998404cd1d"
 dependencies = [
  "bitflags",
- "core-foundation",
+ "core-foundation 0.10.1",
  "core-foundation-sys",
  "libc",
  "security-framework-sys",
@@ -3201,7 +3341,7 @@ checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.4",
+ "syn 3.0.5",
 ]
 
 [[package]]
@@ -3659,9 +3799,9 @@ dependencies = [
 
 [[package]]
 name = "syn"
-version = "3.0.4"
+version = "3.0.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e6275cddf4610d1775e6d1fe9469b2e77d0f39fd98fb7450901b821e0c53649f"
+checksum = "12df2e0110f65b775f769bb17ef989067a1d931b2eb822bd4346631eeada89f9"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -3688,6 +3828,27 @@ dependencies = [
  "syn 2.0.119",
 ]
 
+[[package]]
+name = "system-configuration"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a13f3d0daba03132c0aa9767f98351b3488edc2c100cda2d2ec2b04f3d8d3c8b"
+dependencies = [
+ "bitflags",
+ "core-foundation 0.9.4",
+ "system-configuration-sys",
+]
+
+[[package]]
+name = "system-configuration-sys"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e1d1b10ced5ca923a1fcb8d03e96b8d3268065d724548c0211415ff6ac6bac4"
+dependencies = [
+ "core-foundation-sys",
+ "libc",
+]
+
 [[package]]
 name = "tar"
 version = "0.4.46"
@@ -3709,7 +3870,7 @@ dependencies = [
  "getrandom 0.4.3",
  "once_cell",
  "rustix",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -3738,7 +3899,7 @@ checksum = "bc04cd3e1236dd4a98afca4569f2deb3f120e5422a4023be2cb683f8486292af"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.4",
+ "syn 3.0.5",
 ]
 
 [[package]]
@@ -3807,9 +3968,9 @@ checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
 
 [[package]]
 name = "tokio"
-version = "1.53.1"
+version = "1.52.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "202caea871b69668250d242070849eb495be178ed697a3e98aebce5bc81a0bed"
+checksum = "8fc7f01b389ac15039e4dc9531aa973a135d7a4135281b12d7c1bc79fd57fffe"
 dependencies = [
  "bytes",
  "libc",
@@ -3832,6 +3993,16 @@ dependencies = [
  "syn 2.0.119",
 ]
 
+[[package]]
+name = "tokio-native-tls"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbae76ab933c85776efabc971569dd6119c580d8f5d448769dec1764bf796ef2"
+dependencies = [
+ "native-tls",
+ "tokio",
+]
+
 [[package]]
 name = "tokio-rustls"
 version = "0.26.4"
@@ -4180,9 +4351,9 @@ checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
 
 [[package]]
 name = "uuid"
-version = "1.26.0"
+version = "1.26.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b5772d71c9be8a8a6ac2117d949c5b224c1b72241bb611d9a3012edcf8af7812"
+checksum = "2ef6dac1e96601b4fb3acccccff2139741fcb757cb9a36089bf5be91cfb285ce"
 dependencies = [
  "getrandom 0.4.3",
  "js-sys",
@@ -4415,6 +4586,17 @@ version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
 
+[[package]]
+name = "windows-registry"
+version = "0.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "02752bf7fbdcce7f2a27a742f798510f3e5ad88dbe84871e5168e2120c3d5720"
+dependencies = [
+ "windows-link",
+ "windows-result",
+ "windows-strings",
+]
+
 [[package]]
 name = "windows-result"
 version = "0.4.1"

backend/apps/gateway/Cargo.toml

@@ -28,6 +28,7 @@ config = { version = "0.15.23", default-features = false, features = ["yaml"] }
 serde_json = "1"
 syn = { version = "3.0.3", features = ["full", "visit"] }
 tempfile = "3.27.0"
+tokio-rustls = { version = "=0.26.4", default-features = false }
 
 [lints]
 workspace = true

backend/apps/gateway/src/bootstrap.rs

@@ -78,7 +78,10 @@ pub async fn run() -> Result<(), BootstrapError> {
         store.admin_ports(),
         vec![openai.admin_provider(), xai.admin_provider()],
         core.snapshot_control(),
-        core.account_probe(),
+        (
+            core.account_probe(),
+            host.proxy_probe(provider_openai::build_reqwest_client_with_custom_ca),
+        ),
         host.client_distribution_resolver(),
         host.system_operations(),
     )

backend/apps/gateway/tests/architecture.rs

@@ -182,6 +182,7 @@ const ADAPTER_PUBLIC_MODULES: &[(&str, &[&str])] = &[
         &[
             "client_distribution",
             "config",
+            "proxy_probe",
             "serve",
             "system_update",
             "workers",

backend/apps/gateway/tests/bootstrap.rs

@@ -9,6 +9,151 @@ const REDIS_PASSWORD: &str = "222222222222222222222222222222222222222222222222";
 const ADMIN_PASSWORD: &str = "test-admin-password";
 const TOPOLOGY_CHILD_ENV: &str = "CPR_TEST_TOPOLOGY_CHILD";
 
+#[tokio::test]
+async fn proxy_probe_should_use_provider_custom_ca_for_https_proxies() {
+    use gateway_admin::ports::proxy::ProxyProbe;
+    use gateway_core::account::OutboundProxy;
+    use gateway_host::proxy_probe::HttpProxyProbe;
+    use std::{sync::Arc, time::Duration};
+    use tokio::io::{AsyncReadExt as _, AsyncWriteExt as _};
+    use tokio_rustls::{
+        TlsAcceptor,
+        rustls::{
+            ServerConfig,
+            pki_types::{CertificateDer, PrivateKeyDer, pem::PemObject as _},
+        },
+    };
+
+    const CHILD_ENV: &str = "CPR_TEST_PROXY_TLS_DIRECTORY";
+    let Ok(directory) = std::env::var(CHILD_ENV) else {
+        let directory = tempfile::tempdir().unwrap();
+        generate_proxy_test_certificates(directory.path());
+        // 使用子进程隔离环境变量，避免并行测试读取到临时 CA 配置。
+        for ca_env in ["CODEX_CA_CERTIFICATE", "SSL_CERT_FILE"] {
+            let mut child = Command::new(std::env::current_exe().unwrap());
+            child
+                .args([
+                    "--exact",
+                    "bootstrap::proxy_probe_should_use_provider_custom_ca_for_https_proxies",
+                    "--nocapture",
+                ])
+                .env(CHILD_ENV, directory.path())
+                .env_remove("CODEX_CA_CERTIFICATE")
+                .env_remove("SSL_CERT_FILE")
+                .env(ca_env, directory.path().join("ca.pem"));
+            if ca_env == "CODEX_CA_CERTIFICATE" {
+                child.env(
+                    "SSL_CERT_FILE",
+                    directory.path().join("missing-fallback.pem"),
+                );
+            }
+            let output = child.output().unwrap();
+            assert!(
+                output.status.success(),
+                "{ca_env}: {}\n{}",
+                String::from_utf8_lossy(&output.stdout),
+                String::from_utf8_lossy(&output.stderr)
+            );
+        }
+        return;
+    };
+    provider_openai::ensure_rustls_provider();
+    let directory = std::path::Path::new(&directory);
+    let certificate = CertificateDer::from_pem_file(directory.join("server.pem")).unwrap();
+    let key = PrivateKeyDer::from_pem_file(directory.join("server.key")).unwrap();
+    let acceptor = TlsAcceptor::from(Arc::new(
+        ServerConfig::builder()
+            .with_no_client_auth()
+            .with_single_cert(vec![certificate], key)
+            .unwrap(),
+    ));
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let proxy =
+        OutboundProxy::parse(&format!("https://{}", listener.local_addr().unwrap())).unwrap();
+    let server = tokio::spawn(async move {
+        let (socket, _) = listener.accept().await.unwrap();
+        let mut stream = acceptor.accept(socket).await.unwrap();
+        let mut request = Vec::new();
+        while !request.ends_with(b"\r\n\r\n") {
+            assert!(request.len() < 8192);
+            request.push(stream.read_u8().await.unwrap());
+        }
+        assert!(request.starts_with(b"GET http://unresolvable.invalid/ip "));
+        let body = "{\"ip\":\"203.0.113.8\"}";
+        stream.write_all(format!("HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}", body.len()).as_bytes()).await.unwrap();
+        stream.shutdown().await.unwrap();
+    });
+    let probe = HttpProxyProbe::new("http://unresolvable.invalid/ip")
+        .with_client_builder(provider_openai::build_reqwest_client_with_custom_ca);
+    let result = probe.test(&proxy).await;
+    assert!(result.success, "{}", result.message);
+    assert_eq!(result.exit_ip.unwrap().to_string(), "203.0.113.8");
+    tokio::time::timeout(Duration::from_secs(5), server)
+        .await
+        .unwrap()
+        .unwrap();
+}
+
+fn generate_proxy_test_certificates(directory: &std::path::Path) {
+    let openssl = |args: &[&str]| {
+        let output = Command::new("openssl")
+            .args(args)
+            .current_dir(directory)
+            .output()
+            .unwrap();
+        assert!(
+            output.status.success(),
+            "{}",
+            String::from_utf8_lossy(&output.stderr)
+        );
+    };
+    openssl(&[
+        "req",
+        "-x509",
+        "-newkey",
+        "rsa:2048",
+        "-nodes",
+        "-keyout",
+        "ca.key",
+        "-out",
+        "ca.pem",
+        "-days",
+        "1",
+        "-subj",
+        "/CN=Proxy Test CA",
+    ]);
+    openssl(&[
+        "req",
+        "-newkey",
+        "rsa:2048",
+        "-nodes",
+        "-keyout",
+        "server.key",
+        "-out",
+        "server.csr",
+        "-subj",
+        "/CN=localhost",
+    ]);
+    fs::write(directory.join("extensions"), "subjectAltName=IP:127.0.0.1\nbasicConstraints=critical,CA:FALSE\nkeyUsage=digitalSignature,keyEncipherment\nextendedKeyUsage=serverAuth\n").unwrap();
+    openssl(&[
+        "x509",
+        "-req",
+        "-in",
+        "server.csr",
+        "-CA",
+        "ca.pem",
+        "-CAkey",
+        "ca.key",
+        "-CAcreateserial",
+        "-out",
+        "server.pem",
+        "-days",
+        "1",
+        "-extfile",
+        "extensions",
+    ]);
+}
+
 #[test]
 fn config_loader_should_load_complete_terminal_example() {
     parse_config(&valid_config()).expect("terminal config example");
@@ -165,6 +310,39 @@ fn config_loader_should_reject_invalid_desktop_profile_fields() {
     assert_rejected(valid_config().replace("desktop_build: '8109'", "desktop_build: 'build'"));
 }
 
+#[test]
+fn config_loader_should_accept_empty_and_custom_request_locations() {
+    let original = valid_config();
+    let omitted = original
+        .lines()
+        .filter(|line| !line.trim_start().starts_with("location:"))
+        .collect::<Vec<_>>()
+        .join("\n");
+    assert_ne!(original, omitted);
+    parse_config(&omitted).expect("location passthrough when omitted");
+    let location_line = original
+        .lines()
+        .find(|line| line.trim_start().starts_with("location:"))
+        .expect("example location");
+    for empty in ["    location:", "    location: null", "    location: ~"] {
+        parse_config(&original.replace(location_line, empty)).expect("empty YAML location");
+    }
+    let custom = original.replace(
+        "location: { country: 'US', region: 'Ohio', city: 'Piketon', timezone: 'America/New_York' }",
+        "location: { country: 'NZ', region: 'Auckland', city: 'Auckland', timezone: 'Pacific/Auckland' }",
+    );
+    assert_ne!(original, custom);
+    parse_config(&custom).expect("custom location from YAML");
+}
+
+#[test]
+fn config_loader_should_reject_invalid_request_location_timezones() {
+    let original = valid_config();
+    let invalid = original.replace("timezone: 'America/New_York'", "timezone: 'Not/A_Timezone'");
+    assert_ne!(original, invalid);
+    assert_rejected(invalid);
+}
+
 fn assert_rejected(config: String) {
     assert!(parse_config(&config).is_err());
 }

backend/apps/gateway/tests/main.rs

@@ -1,6 +1,9 @@
 mod architecture;
 mod bootstrap;
 
+// 组合根是否混入业务策略由代码审查判断，行数和标识符/注释关键词不能证明职责越界。
+// 依赖 DAG、公开模块面和模块镜像继续由 architecture 检查，源码纪律由下方测试维护。
+
 use std::{
     collections::BTreeSet,
     fs,
@@ -75,28 +78,6 @@ fn workspace_production_files_have_no_hidden_modules_or_test_hooks() {
     }
 }
 
-#[test]
-fn bootstrap_owns_only_bundle_wiring() {
-    let root = Path::new(env!("CARGO_MANIFEST_DIR")).join("src");
-    let bootstrap = fs::read_to_string(root.join("bootstrap.rs")).expect("read bootstrap");
-    for forbidden in [
-        "sqlx::",
-        "redis::",
-        "Repository",
-        "impl Provider",
-        "impl ExecutionService",
-        "tokio::spawn",
-        "access_token",
-        "refresh_token",
-    ] {
-        assert!(
-            !bootstrap.contains(forbidden),
-            "bootstrap owns `{forbidden}`"
-        );
-    }
-    assert!(bootstrap.lines().count() <= 300);
-}
-
 fn rust_files(root: &Path) -> BTreeSet<PathBuf> {
     let mut result = BTreeSet::new();
     collect_rust_files(root, root, &mut result);

backend/crates/gateway-admin/Cargo.toml

@@ -19,6 +19,7 @@ bytes = "1.11.1"
 chrono = "0.4.45"
 futures = "0.3.32"
 gateway-core = { path = "../gateway-core" }
+heck = "0.5.0"
 hex = "0.4.3"
 rand_core = { version = "0.6.4", features = ["getrandom"] }
 serde = { version = "1.0.228", features = ["derive"] }

backend/crates/gateway-admin/src/lib.rs

@@ -25,7 +25,7 @@ pub use use_case::{
     account_groups::AccountGroupService, accounts::AccountsService, auth::AuthService,
     backup::BackupService, client_distribution::ClientDistributionService,
     client_keys::ClientKeyService, observability::ObservabilityService, openai::OpenAiService,
-    settings::SettingsService, system::SystemService, xai::XaiService,
+    proxies::ProxiesService, settings::SettingsService, system::SystemService, xai::XaiService,
 };
 
 use model::{AdminError, AdminErrorKind};
@@ -149,6 +149,7 @@ pub enum AdminConfigError {
 /// 字段全部私有；调用方经 accessor 直接调用能力，不需要命名内部 `use_case` 模块。
 #[derive(Clone)]
 pub struct AdminServices {
+    proxies: Arc<dyn ProxiesService>,
     auth: Arc<dyn AuthService>,
     accounts: Arc<dyn AccountsService>,
     account_groups: Arc<dyn AccountGroupService>,
@@ -163,6 +164,11 @@ pub struct AdminServices {
 }
 
 impl AdminServices {
+    #[must_use]
+    pub fn proxies(&self) -> &dyn ProxiesService {
+        self.proxies.as_ref()
+    }
+
     #[must_use]
     pub fn auth(&self) -> &dyn AuthService {
         self.auth.as_ref()
@@ -247,10 +253,11 @@ pub async fn initialize(
     store: AdminStorePorts,
     providers: Vec<Arc<dyn ProviderAdmin>>,
     snapshot: Arc<dyn SnapshotControl>,
-    probe: Arc<dyn AccountProbe>,
+    probes: (Arc<dyn AccountProbe>, Arc<dyn ports::proxy::ProxyProbe>),
     client_distribution: Arc<dyn ClientDistributionResolver>,
     system: Arc<dyn SystemOperations>,
 ) -> Result<AdminBundle, AdminError> {
+    let (probe, proxy_probe) = probes;
     config
         .resolve_and_validate(Path::new("."))
         .map_err(|error| AdminError::invalid(error.to_string()))?;
@@ -290,6 +297,12 @@ pub async fn initialize(
         backup_ports.object_store(),
     );
     let services = AdminServices {
+        proxies: Arc::new(use_case::proxies::DefaultProxiesService::new(
+            store.proxies(),
+            proxy_probe,
+            snapshot.clone(),
+            registry.clone(),
+        )),
         auth,
         accounts,
         account_groups: Arc::new(DefaultAccountGroupService::new(
@@ -316,11 +329,13 @@ pub async fn initialize(
         openai: Arc::new(DefaultOpenAiService::new(
             openai,
             store.accounts(),
+            store.proxies(),
             snapshot.clone(),
         )),
         xai: Arc::new(DefaultXaiService::new(
             xai,
             store.accounts(),
+            store.proxies(),
             snapshot.clone(),
         )),
         backups,

backend/crates/gateway-admin/src/model/accounts.rs

@@ -221,7 +221,7 @@ pub struct UpdateAccount {
     pub concurrency_limit: Option<AccountConcurrencyLimit>,
     pub weight: AccountWeight,
     pub group_ids: Vec<gateway_core::routing::AccountGroupId>,
-    pub outbound_proxy: Option<Option<gateway_core::account::OutboundProxy>>,
+    pub outbound_proxy: Option<super::proxies::AccountProxySelection>,
 }
 
 /// 账号更新结果。
@@ -239,7 +239,7 @@ pub struct BatchUpdateAccounts {
     pub concurrency_limit: Option<AccountConcurrencyLimit>,
     pub weight: AccountWeight,
     pub group_ids: Vec<gateway_core::routing::AccountGroupId>,
-    pub outbound_proxy: Option<Option<gateway_core::account::OutboundProxy>>,
+    pub outbound_proxy: Option<super::proxies::AccountProxySelection>,
 }
 
 /// 批量账号更新结果。

backend/crates/gateway-admin/src/model/client_keys.rs

@@ -6,7 +6,7 @@ use chrono::{DateTime, Utc};
 
 use gateway_core::{
     engine::budget::{ClientBudgetLimits, ClientBudgetStatus},
-    policy::{ClientApiKeyId, RateLimits},
+    policy::{ClientApiKeyId, PlaintextClientApiKey, RateLimits},
     routing::{AccountGroupId, ProviderKind},
 };
 
@@ -144,6 +144,7 @@ impl fmt::Debug for ClientKeySecret {
 /// API 提交的 Client Key 创建命令。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CreateClientKey {
+    pub custom_key: Option<PlaintextClientApiKey>,
     pub name: String,
     pub label: Option<String>,
     pub group_ids: Vec<AccountGroupId>,
@@ -223,19 +224,3 @@ pub struct ClientKeyMutation {
     pub record: Option<ClientKeyRecord>,
     pub id: ClientApiKeyId,
 }
-
-#[derive(Debug, Clone)]
-pub struct UnresolvedClientCharge {
-    pub request_id: String,
-    pub started_at: DateTime<Utc>,
-    pub completed_at: Option<DateTime<Utc>>,
-    pub state: String,
-}
-
-#[derive(Debug, Clone)]
-pub struct ReconcileClientCharge {
-    pub key_id: ClientApiKeyId,
-    pub request_id: String,
-    pub amount_usd: gateway_core::metering::Decimal,
-    pub reason: String,
-}

backend/crates/gateway-admin/src/model/mod.rs

@@ -10,6 +10,9 @@ pub mod client_distribution;
 pub mod client_keys;
 pub mod observability;
 pub mod provider_credentials;
+pub mod proxies;
+pub mod quota_forecast;
+pub mod quota_forecast_sampling;
 pub mod settings;
 pub mod system;
 

backend/crates/gateway-admin/src/model/provider_credentials.rs

@@ -15,7 +15,7 @@ use serde_json::{Map, Value};
 use uuid::Uuid;
 
 use super::{
-    AdminError, MutationActor, MutationContext, PageSize, Revision,
+    AdminError, MutationActor, MutationContext, Revision,
     accounts::{
         AccountImportSettings, AccountRecord, AccountSummary, AccountUsage, CredentialState,
     },
@@ -49,56 +49,6 @@ impl fmt::Debug for ProviderDocument {
     }
 }
 
-/// Credential 列表稳定游标。
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct CredentialCursor {
-    pub created_at: DateTime<Utc>,
-    pub account_id: ProviderAccountId,
-}
-
-/// Provider credential 列表查询。
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct CredentialListQuery {
-    pub credential_state: Option<CredentialStateFilter>,
-    pub enabled: Option<bool>,
-    pub window: CredentialListWindow,
-}
-
-/// Credential 状态筛选。
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub enum CredentialStateFilter {
-    Exact(CredentialState),
-    AnyOf(Vec<CredentialState>),
-}
-
-impl CredentialStateFilter {
-    #[must_use]
-    pub fn matches(&self, credential_state: CredentialState) -> bool {
-        match self {
-            Self::Exact(expected) => *expected == credential_state,
-            Self::AnyOf(expected) => expected.contains(&credential_state),
-        }
-    }
-}
-
-/// Credential 目录的集合窗口；完整列表与游标分页互斥。
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub enum CredentialListWindow {
-    All,
-    Page {
-        cursor: Option<CredentialCursor>,
-        page_size: PageSize,
-    },
-}
-
-/// Provider credential 列表。
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct CredentialPage {
-    pub config_revision: Revision,
-    pub items: Vec<AccountRecord>,
-    pub next_cursor: Option<CredentialCursor>,
-}
-
 /// Provider credential 详情。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CredentialDetails {
@@ -108,6 +58,7 @@ pub struct CredentialDetails {
 
 /// Provider 正式文档批量导入命令。
 pub struct ImportCredentials {
+    pub outbound_proxy_id: Option<String>,
     pub settings: Option<AccountImportSettings>,
     pub context: MutationContext,
     pub document: ProviderDocument,
@@ -132,6 +83,7 @@ pub struct CredentialImportResult {
 
 /// Provider 解析导入文档时只接收不透明文档，不接触 revision 或审计上下文。
 pub struct PrepareCredentialImport {
+    pub default_outbound_proxy: Option<gateway_core::account::OutboundProxy>,
     pub document: ProviderDocument,
 }
 
@@ -175,6 +127,7 @@ pub struct PreparedCredentialImport {
 /// Admin 交给 Store 的导入事务命令。
 #[derive(Debug, Clone, PartialEq)]
 pub struct CredentialImportCommit {
+    pub outbound_proxy: Option<super::proxies::ImportProxyBinding>,
     pub settings: Option<AccountImportSettings>,
     pub prepared: PreparedCredentialImport,
 }
@@ -255,6 +208,7 @@ pub struct PendingAuthorizationMutation {
     target: AuthorizationMutationTarget,
     owner_binding: AuthorizationOwnerBinding,
     outbound_proxy: Option<gateway_core::account::OutboundProxy>,
+    outbound_proxy_id: Option<String>,
 }
 
 impl PendingAuthorizationMutation {
@@ -269,6 +223,7 @@ impl PendingAuthorizationMutation {
             target,
             owner_binding,
             outbound_proxy: None,
+            outbound_proxy_id: None,
         }
     }
 
@@ -299,6 +254,16 @@ impl PendingAuthorizationMutation {
     pub fn outbound_proxy(&self) -> Option<&gateway_core::account::OutboundProxy> {
         self.outbound_proxy.as_ref()
     }
+
+    #[must_use]
+    pub fn with_outbound_proxy_id(mut self, id: Option<String>) -> Self {
+        self.outbound_proxy_id = id;
+        self
+    }
+
+    pub fn outbound_proxy_id(&self) -> Option<&str> {
+        self.outbound_proxy_id.as_deref()
+    }
 }
 
 impl PendingAuthorizationMutation {
@@ -338,6 +303,9 @@ impl PendingAuthorizationMutation {
                 Value::String(proxy.expose_url().to_owned()),
             );
         }
+        if let Some(id) = &self.outbound_proxy_id {
+            document.insert("outbound_proxy_id".to_owned(), Value::String(id.clone()));
+        }
         document
     }
 
@@ -382,7 +350,8 @@ impl PendingAuthorizationMutation {
                 started_request_id: document.started_request_id,
             },
         )
-        .with_outbound_proxy(proxy))
+        .with_outbound_proxy(proxy)
+        .with_outbound_proxy_id(document.outbound_proxy_id))
     }
 }
 
@@ -395,6 +364,8 @@ struct StoredAuthorizationMutationV1 {
     started_request_id: String,
     #[serde(default)]
     outbound_proxy_url: Option<String>,
+    #[serde(default)]
+    outbound_proxy_id: Option<String>,
 }
 
 #[derive(Deserialize)]
@@ -418,7 +389,7 @@ pub struct StartAuthorization {
     pub context: MutationContext,
     pub name: String,
     pub reauthorization: Option<ProviderAccountId>,
-    pub outbound_proxy: Option<gateway_core::account::OutboundProxy>,
+    pub outbound_proxy: Option<super::proxies::AccountProxySelection>,
 }
 
 /// OAuth 流程启动结果。
@@ -750,6 +721,13 @@ pub struct ProviderQuotaWindow {
     pub provider_data: Option<ProviderDocument>,
 }
 
+/// 账号用量统计周期，按周优先、月次之选择；短期限流窗口不参与统计面板。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum AccountUsagePeriod {
+    Weekly,
+    Monthly,
+}
+
 /// Provider 解释 quota 所需的公共请求事实。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProviderQuotaRequest {
@@ -779,6 +757,24 @@ pub(crate) fn explicit_plan_type(value: Option<&str>) -> Option<&str> {
     })
 }
 
+/// 按需查询的订阅周期，不参与额度或账号可用性判断。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProviderSubscription {
+    pub starts_at: Option<DateTime<Utc>>,
+    pub expires_at: DateTime<Utc>,
+    pub will_renew: Option<bool>,
+    pub billing_period: Option<String>,
+    pub billing_currency: Option<String>,
+    pub observed_at: DateTime<Utc>,
+}
+
+/// 按需汇聚的个人信息；资料查询失败不丢弃可用的订阅结果。
+#[derive(Debug, Clone, PartialEq)]
+pub struct AccountPersonalInfo {
+    pub profile: Result<ProviderProfileStatistics, AdminError>,
+    pub subscription: Option<ProviderSubscription>,
+}
+
 /// Provider 官方个人资料中的累计摘要。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProviderProfileStatisticsSummary {
@@ -900,23 +896,37 @@ impl ProviderQuota {
         }
     }
 
-    /// 返回账号展开面板使用的当前额度窗口用量。
+    /// 选择账号用量统计的周/月窗口，同时返回展示所需的周期事实。
     ///
-    /// Provider 已提供账号级本地用量时，固定窗口和无固定重置点的滚动窗口
-    /// 都可作为代表用量；优先级与 Dashboard 代表性额度窗口一致，
-    /// 同一优先级保持 Provider 投影顺序。
+    /// 只使用边界完整、可归属到整个账号的窗口；周优先于月，同周期保持
+    /// Provider 投影顺序。没有符合条件的窗口时不回退到短期或历史累计。
     #[must_use]
-    pub fn representative_window_usage(&self) -> Option<&AccountUsage> {
-        self.windows
-            .iter()
-            .enumerate()
-            .filter(|(_, window)| {
-                window.local_usage_attribution == QuotaLocalUsageAttribution::AccountWide
-                    && window.window_seconds.is_some()
-                    && window.local_usage.is_some()
-            })
-            .min_by_key(|(index, window)| (quota_usage_priority(window), *index))
-            .and_then(|(_, window)| window.local_usage.as_ref())
+    pub fn usage_window(&self) -> Option<(&ProviderQuotaWindow, AccountUsagePeriod)> {
+        self.usage_windows()
+            .filter(|(window, _)| window.local_usage.is_some())
+            .min_by_key(|(_, period)| *period)
+    }
+
+    /// 统计与预测共用窗口归属规则，避免把模型专属桶或短期限流当作账号容量。
+    pub(crate) fn usage_windows(
+        &self,
+    ) -> impl Iterator<Item = (&ProviderQuotaWindow, AccountUsagePeriod)> {
+        self.windows.iter().filter_map(|window| {
+            if window.local_usage_attribution != QuotaLocalUsageAttribution::AccountWide
+                || window.reset_at.is_none()
+            {
+                return None;
+            }
+            let seconds = window.window_seconds?;
+            let period = if is_week_window(seconds) {
+                AccountUsagePeriod::Weekly
+            } else if window.group == "monthly" && seconds >= 7 * 24 * 60 * 60 {
+                AccountUsagePeriod::Monthly
+            } else {
+                return None;
+            };
+            Some((window, period))
+        })
     }
 
     /// 返回 Dashboard 使用的代表性额度比例。

backend/crates/gateway-admin/src/model/proxies.rs

@@ -0,0 +1,105 @@
+//! 可复用的账号出口配置，以及脱敏后的连通性测试结果。
+
+use chrono::{DateTime, Utc};
+use gateway_core::account::OutboundProxy;
+
+use super::{PageSize, Revision, account_groups::AccountGroupRef};
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum AccountProxySelection {
+    Direct,
+    Url(OutboundProxy),
+    Saved(String),
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ImportProxyBinding {
+    pub id: String,
+    pub proxy: OutboundProxy,
+}
+
+#[derive(Debug, Clone)]
+pub struct ProxyListQuery {
+    pub page: u32,
+    pub page_size: PageSize,
+    pub search: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProxyAccountRef {
+    pub id: String,
+    pub name: String,
+    pub email: Option<String>,
+    pub provider_kind: String,
+    pub authentication_kind: String,
+    pub plan_type: Option<String>,
+    pub plan_type_display: Option<String>,
+    pub groups: Vec<AccountGroupRef>,
+    pub enabled: bool,
+}
+
+/// 按代理查询关联账号，分页与搜索均在存储层执行。
+#[derive(Debug, Clone)]
+pub struct ProxyAccountListQuery {
+    pub proxy_id: String,
+    pub page: u32,
+    pub page_size: PageSize,
+    pub search: String,
+}
+
+#[derive(Debug, Clone)]
+pub struct ProxyAccountPage {
+    pub items: Vec<ProxyAccountRef>,
+    pub total: u64,
+    pub page: u32,
+    pub page_size: u16,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProxyTestResult {
+    pub success: bool,
+    pub latency_ms: u64,
+    pub exit_ip: Option<std::net::IpAddr>,
+    pub message: String,
+}
+
+#[derive(Debug, Clone)]
+pub struct ProxyRecord {
+    pub id: String,
+    pub name: String,
+    pub proxy: OutboundProxy,
+    pub revision: Revision,
+    pub account_count: u64,
+    pub last_test_at: Option<DateTime<Utc>>,
+    pub last_test: Option<ProxyTestResult>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone)]
+pub struct ProxyPage {
+    pub items: Vec<ProxyRecord>,
+    pub total: u64,
+    pub page: u32,
+    pub page_size: u16,
+}
+
+#[derive(Debug, Clone)]
+pub struct NewProxy {
+    pub name: String,
+    pub proxy: OutboundProxy,
+}
+
+#[derive(Debug, Clone)]
+pub struct UpdateProxy {
+    pub id: String,
+    pub revision: Revision,
+    pub name: String,
+    pub proxy: Option<OutboundProxy>,
+}
+
+#[derive(Debug, Clone)]
+pub struct ProxyMutation {
+    pub config_revision: Revision,
+    pub record: ProxyRecord,
+}

backend/crates/gateway-admin/src/model/quota_forecast.rs

@@ -0,0 +1,204 @@
+//! 账号额度的只读容量估算，不参与金额结算或账号调度。
+
+use chrono::{DateTime, Duration, Utc};
+
+use super::provider_credentials::{AccountUsagePeriod, ProviderQuota, ProviderQuotaWindow};
+use super::quota_forecast_sampling::{QuotaForecastMethod, QuotaForecastSample};
+
+const DAY_SECONDS: u64 = 86_400;
+const MIN_USED_PERCENT: f64 = 5.0;
+const LOW_SAMPLE_PERCENT: f64 = 10.0;
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct AccountQuotaForecastReport {
+    pub account_id: String,
+    pub generated_at: DateTime<Utc>,
+    pub forecasts: [AccountQuotaForecast; 2],
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct AccountQuotaForecast {
+    pub period: AccountUsagePeriod,
+    pub target_seconds: u64,
+    pub extrapolated: bool,
+    pub source: Option<QuotaForecastSource>,
+    pub unavailable_reason: Option<&'static str>,
+    pub low_sample: bool,
+    pub incomplete_cost: bool,
+    pub incomplete_tokens: bool,
+    pub estimated_tokens: Option<u64>,
+    pub estimated_usd: Option<f64>,
+    /// 剩余估算始终属于源窗口，不随目标周期折算。
+    pub remaining_tokens: Option<u64>,
+    pub remaining_usd: Option<f64>,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct QuotaForecastSource {
+    pub label: String,
+    pub used_percent: Option<f64>,
+    pub observed_at: Option<DateTime<Utc>>,
+    pub reset_at: DateTime<Utc>,
+    pub tokens: Option<u64>,
+    pub usd: Option<f64>,
+}
+
+/// 优先预测真实的对应窗口；缺少对应周期时只给出明确标识的 7/30 天容量折算。
+/// 本地日志不能证明站外消耗或完整留存，因此即使样本充足也不声称官方额度。
+#[must_use]
+pub fn account_quota_forecasts(
+    quota: &ProviderQuota,
+    account_added_at: DateTime<Utc>,
+    now: DateTime<Utc>,
+    samples: &[QuotaForecastSample],
+) -> [AccountQuotaForecast; 2] {
+    [AccountUsagePeriod::Weekly, AccountUsagePeriod::Monthly].map(|period| {
+        let selected = quota
+            .usage_windows()
+            .find(|(_, source_period)| *source_period == period)
+            .or_else(|| quota.usage_windows().min_by_key(|(_, period)| *period));
+        let mut forecast = AccountQuotaForecast {
+            period,
+            target_seconds: match period {
+                AccountUsagePeriod::Weekly => 7 * DAY_SECONDS,
+                AccountUsagePeriod::Monthly => 30 * DAY_SECONDS,
+            },
+            extrapolated: false,
+            source: None,
+            unavailable_reason: Some("没有可统计的周/月额度窗口，请先刷新账号额度。"),
+            low_sample: false,
+            incomplete_cost: false,
+            incomplete_tokens: false,
+            estimated_tokens: None,
+            estimated_usd: None,
+            remaining_tokens: None,
+            remaining_usd: None,
+        };
+        if let Some((window, source_period)) = selected {
+            forecast.project(
+                window,
+                source_period,
+                quota.observed_at,
+                account_added_at,
+                now,
+                samples.iter().find(|sample| sample.key == window.key),
+            );
+        }
+        forecast
+    })
+}
+
+impl AccountQuotaForecast {
+    fn project(
+        &mut self,
+        window: &ProviderQuotaWindow,
+        source_period: AccountUsagePeriod,
+        observed_at: Option<DateTime<Utc>>,
+        account_added_at: DateTime<Utc>,
+        now: DateTime<Utc>,
+        sample: Option<&QuotaForecastSample>,
+    ) {
+        let (Some(seconds), Some(reset_at)) = (window.window_seconds, window.reset_at) else {
+            return;
+        };
+        self.extrapolated = source_period != self.period;
+        if !self.extrapolated {
+            self.target_seconds = seconds;
+        }
+        let percent = window
+            .used_percent
+            .filter(|p| p.is_finite() && (0.0..=100.0).contains(p));
+        let usage = sample.map(|sample| &sample.usage);
+        let usd = usage
+            .filter(|usage| usage.known_cost_count > 0)
+            .map(|usage| usage.usd)
+            .filter(|value| value.is_finite() && *value >= 0.0);
+        let start = i64::try_from(seconds)
+            .ok()
+            .and_then(Duration::try_seconds)
+            .and_then(|duration| reset_at.checked_sub_signed(duration));
+        self.source = Some(QuotaForecastSource {
+            label: window.label.clone(),
+            used_percent: percent,
+            observed_at,
+            reset_at,
+            tokens: usage.map(|usage| usage.tokens),
+            usd,
+        });
+        self.incomplete_cost = usage.is_none_or(|usage| {
+            usage.unavailable_cost_count > 0
+                || usage.known_cost_count == 0
+                || usage.known_cost_count != usage.request_count
+        });
+        self.incomplete_tokens = usage.is_some_and(|usage| usage.missing_token_count > 0);
+        let method = sample.map_or(QuotaForecastMethod::Cumulative, |sample| sample.method);
+        let Some(start) = start.filter(|start| *start <= now && now < reset_at) else {
+            self.unavailable_reason = Some("额度窗口已过期或边界无效，请刷新账号额度后重试。");
+            return;
+        };
+        if !observed_at.is_some_and(|observed| start <= observed && observed <= now) {
+            self.unavailable_reason = Some("缺少本周期的额度快照，请先刷新账号额度。");
+            return;
+        }
+        if sample.is_some_and(|sample| sample.discontinuous) {
+            self.unavailable_reason =
+                Some("额度观测出现回落或累计记录不连续，正在重新积累配对样本。");
+            return;
+        }
+        if account_added_at > start && method == QuotaForecastMethod::Cumulative {
+            self.unavailable_reason = Some(
+                "本周期开始时的记录不完整，正在积累至少 5 个百分点的配对观测，无需等待下次重置。",
+            );
+            return;
+        }
+        let Some(percent) = percent else {
+            self.unavailable_reason = Some("已用比例未知，请刷新额度后查看预测。");
+            return;
+        };
+        let Some(usage) = usage.filter(|usage| usage.request_count > 0) else {
+            self.unavailable_reason = Some("本周期没有网关用量记录，暂时无法预测额度。");
+            return;
+        };
+        let Some(sample) = sample.filter(|sample| {
+            sample.end_at == observed_at.unwrap_or(now)
+                && start <= sample.start_at
+                && sample.start_at <= sample.end_at
+                && sample.sampled_percent.is_finite()
+                && sample.sampled_percent >= MIN_USED_PERCENT
+                && sample.sampled_percent <= percent
+        }) else {
+            self.unavailable_reason =
+                Some("有效额度进度不足 5 个百分点或采样边界无效，请继续积累用量。");
+            return;
+        };
+        self.low_sample = sample.sampled_percent < LOW_SAMPLE_PERCENT
+            || (method == QuotaForecastMethod::Incremental && sample.block_count < 2);
+        // 漏记和个别缺失只影响精度，仍按已记录数值估算，不按请求数补齐未知消耗。
+        // 预测是近似展示值；不复用为账单金额，也不把月折算当成自然月或额外余额。
+        let capacity_factor = 100.0 / sample.sampled_percent;
+        let factor = capacity_factor * self.target_seconds as f64 / seconds as f64;
+        let tokens = Some(usage.tokens).filter(|tokens| *tokens > 0);
+        self.estimated_tokens = tokens.and_then(|value| estimate_tokens(value, factor));
+        self.estimated_usd = usd.and_then(|value| estimate(value, factor));
+        let remaining_factor = (100.0 - percent) / sample.sampled_percent;
+        self.remaining_tokens = tokens.and_then(|value| estimate_tokens(value, remaining_factor));
+        self.remaining_usd = usd.and_then(|value| estimate(value, remaining_factor));
+        self.unavailable_reason = if self.estimated_tokens.is_none() && self.estimated_usd.is_none()
+        {
+            Some("本周期暂无可用于估算的 Token 或费用数据，请积累用量后重试。")
+        } else {
+            None
+        };
+    }
+}
+
+fn estimate(value: f64, factor: f64) -> Option<f64> {
+    let estimate = value * factor;
+    (estimate.is_finite() && estimate >= 0.0).then_some(estimate)
+}
+
+fn estimate_tokens(value: u64, factor: f64) -> Option<u64> {
+    estimate(value as f64, factor)
+        .filter(|value| value.round() < u64::MAX as f64)
+        .map(|value| value.round() as u64)
+}

backend/crates/gateway-admin/src/model/quota_forecast_sampling.rs

@@ -0,0 +1,190 @@
+//! 预测专用的配对采样；不改变完整交付用量或费用账本的统计口径。
+
+use chrono::{DateTime, Utc};
+
+use super::provider_credentials::ProviderDocument;
+
+/// 限制带 Provider 文档的历史点数量；累计用量仍覆盖整个查询区间。
+pub const MAX_FORECAST_HISTORY_POINTS: usize = 128;
+const MIN_BLOCK_PERCENT: f64 = 5.0;
+const RECENT_BLOCKS: usize = 3;
+
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct QuotaForecastUsage {
+    pub request_count: u64,
+    pub tokens: u64,
+    pub input_tokens: u64,
+    pub output_tokens: u64,
+    pub cached_tokens: u64,
+    pub missing_token_count: u64,
+    pub known_cost_count: u64,
+    pub unavailable_cost_count: u64,
+    pub usd: f64,
+    pub excluded_request_count: u64,
+}
+
+impl QuotaForecastUsage {
+    /// 累计计数倒退表示不能配对，不用饱和减法掩盖数据断点。
+    fn difference(&self, baseline: &Self) -> Option<Self> {
+        let usd = self.usd - baseline.usd;
+        if !usd.is_finite() || usd < -1e-9 {
+            return None;
+        }
+        Some(Self {
+            request_count: self.request_count.checked_sub(baseline.request_count)?,
+            tokens: self.tokens.checked_sub(baseline.tokens)?,
+            input_tokens: self.input_tokens.checked_sub(baseline.input_tokens)?,
+            output_tokens: self.output_tokens.checked_sub(baseline.output_tokens)?,
+            cached_tokens: self.cached_tokens.checked_sub(baseline.cached_tokens)?,
+            missing_token_count: self
+                .missing_token_count
+                .checked_sub(baseline.missing_token_count)?,
+            known_cost_count: self
+                .known_cost_count
+                .checked_sub(baseline.known_cost_count)?,
+            unavailable_cost_count: self
+                .unavailable_cost_count
+                .checked_sub(baseline.unavailable_cost_count)?,
+            usd: usd.max(0.0),
+            excluded_request_count: self
+                .excluded_request_count
+                .checked_sub(baseline.excluded_request_count)?,
+        })
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct QuotaForecastHistoryPoint {
+    pub started_at: DateTime<Utc>,
+    pub completed_at: DateTime<Utc>,
+    pub usage: QuotaForecastUsage,
+    pub provider_observation: ProviderDocument,
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct QuotaForecastHistory {
+    pub points: Vec<QuotaForecastHistoryPoint>,
+    pub usage: QuotaForecastUsage,
+    pub pending_request_count: u64,
+}
+
+/// 具体 Provider 从自己的历史文档解释出的额度事实。
+#[derive(Debug, Clone, PartialEq)]
+pub struct QuotaForecastObservation {
+    pub used_percent: f64,
+    pub reset_at: DateTime<Utc>,
+    pub plan_type: Option<String>,
+}
+
+#[derive(Debug, Clone)]
+pub struct QuotaForecastPoint {
+    pub observed_at: DateTime<Utc>,
+    pub used_percent: f64,
+    pub usage: QuotaForecastUsage,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum QuotaForecastMethod {
+    Cumulative,
+    Incremental,
+}
+
+#[derive(Debug, Clone)]
+pub struct QuotaForecastSample {
+    pub key: String,
+    pub method: QuotaForecastMethod,
+    pub start_at: DateTime<Utc>,
+    pub end_at: DateTime<Utc>,
+    pub baseline_percent: f64,
+    pub sampled_percent: f64,
+    pub block_count: usize,
+    pub observation_count: usize,
+    pub pending_request_count: u64,
+    pub discontinuous: bool,
+    pub usage: QuotaForecastUsage,
+}
+
+/// 对同一额度段的累计点形成至少 5 个百分点的连续块，使用最近三个完整块及尾部。
+/// 不平均逐请求比值；重复百分比不增加块数，5/10 个百分点仅是量化噪声门槛。
+#[must_use]
+pub fn select_forecast_sample(
+    key: String,
+    start_at: DateTime<Utc>,
+    current: QuotaForecastPoint,
+    mut history: Vec<QuotaForecastPoint>,
+    pending_request_count: u64,
+) -> QuotaForecastSample {
+    history.retain(|point| {
+        start_at <= point.observed_at
+            && point.observed_at < current.observed_at
+            && point.used_percent.is_finite()
+            && (0.0..100.0).contains(&point.used_percent)
+    });
+    history.sort_by_key(|point| point.observed_at);
+    let mut sample = QuotaForecastSample {
+        key,
+        method: QuotaForecastMethod::Cumulative,
+        start_at,
+        end_at: current.observed_at,
+        baseline_percent: 0.0,
+        sampled_percent: current.used_percent,
+        block_count: 0,
+        observation_count: history.len(),
+        pending_request_count,
+        discontinuous: false,
+        usage: current.usage.clone(),
+    };
+    history.push(current);
+    let mut anchors: Vec<&QuotaForecastPoint> = Vec::new();
+    let mut high_water: Option<&QuotaForecastPoint> = None;
+    for point in &history {
+        if let Some(previous) = high_water {
+            if point.observed_at <= previous.observed_at {
+                continue;
+            }
+            if point.used_percent < previous.used_percent {
+                // 一个百分点内的回落可能是量化/并发乱序；更大的回落不能跨越。
+                if previous.used_percent - point.used_percent <= 1.0 {
+                    continue;
+                }
+                sample.discontinuous = true;
+                anchors.clear();
+            }
+        }
+        high_water = Some(point);
+        if anchors
+            .last()
+            .is_none_or(|anchor| point.used_percent - anchor.used_percent >= MIN_BLOCK_PERCENT)
+        {
+            anchors.push(point);
+        }
+    }
+    let Some(current) = history.last() else {
+        return sample;
+    };
+    if anchors.len() < 2 {
+        return sample;
+    }
+    let baseline_index = anchors.len().saturating_sub(RECENT_BLOCKS + 1);
+    let baseline = anchors[baseline_index];
+    let progress = current.used_percent - baseline.used_percent;
+    if !progress.is_finite() || progress < MIN_BLOCK_PERCENT {
+        return sample;
+    }
+    let Some(usage) = current.usage.difference(&baseline.usage) else {
+        sample.discontinuous = true;
+        return sample;
+    };
+    if usage.request_count == 0 {
+        return sample;
+    }
+    sample.method = QuotaForecastMethod::Incremental;
+    sample.start_at = baseline.observed_at;
+    sample.baseline_percent = baseline.used_percent;
+    sample.sampled_percent = progress;
+    sample.block_count = anchors.len() - baseline_index - 1;
+    sample.usage = usage;
+    // 断点后的新基线已有足够进度时，只消费新段；旧段从不参与本次估算。
+    sample.discontinuous = false;
+    sample
+}

backend/crates/gateway-admin/src/ports/mod.rs

@@ -3,5 +3,6 @@
 pub mod backup;
 pub mod client_distribution;
 pub mod provider;
+pub mod proxy;
 pub mod store;
 pub mod system;

backend/crates/gateway-admin/src/ports/provider.rs

@@ -8,6 +8,7 @@ use gateway_core::{
     operation::Operation,
     routing::{ProviderKind, UpstreamModelId},
 };
+use heck::ToUpperCamelCase;
 
 use crate::model::observability::{
     CalculatedBillingBreakdown, DashboardWireProfile, ProviderBillingInput,
@@ -18,7 +19,11 @@ use crate::model::provider_credentials::{
     PrepareCredentialRotation, PreparedAuthorizationCommit, PreparedCredentialImport,
     PreparedCredentialRotation, ProviderExport, ProviderExportCredentialInput, ProviderModels,
     ProviderProfileAvatar, ProviderProfileStatistics, ProviderQuota, ProviderQuotaRequest,
-    ProviderResetCreditResult, ProviderResetCredits, explicit_plan_type,
+    ProviderResetCreditResult, ProviderResetCredits, ProviderSubscription, explicit_plan_type,
+};
+use crate::model::{
+    provider_credentials::{ProviderDocument, ProviderQuotaWindow},
+    quota_forecast_sampling::QuotaForecastObservation,
 };
 
 /// Provider 管理失败的稳定分类。
@@ -170,7 +175,24 @@ pub trait ProviderAdmin: Send + Sync {
         request: ProviderQuotaRequest,
     ) -> Result<ProviderQuota, ProviderAdminError>;
 
+    /// 历史观测的协议字段仅由具体 Provider 解释；不支持时保留累计估算。
+    fn quota_forecast_observation(
+        &self,
+        _document: &ProviderDocument,
+        _window: &ProviderQuotaWindow,
+    ) -> Option<QuotaForecastObservation> {
+        None
+    }
+
     /// 查询 Provider 官方个人资料统计；不支持该能力的 Provider 使用默认拒绝。
+    /// 只由个人信息显式查询，不在额度刷新或后台任务中预取。
+    async fn subscription(
+        &self,
+        _account_id: &ProviderAccountId,
+    ) -> Result<Option<ProviderSubscription>, ProviderAdminError> {
+        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
+    }
+
     async fn profile_statistics(
         &self,
         _account_id: &ProviderAccountId,
@@ -251,7 +273,20 @@ impl ProviderAdminRegistry {
             .ok_or_else(|| ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
     }
 
-    /// 账号页和 Dashboard 共用的套餐展示投影，不修改持久化的原始套餐值。
+    /// 账号目录与关联列表共用套餐补全和展示规则，已知账号套餐优先于额度快照。
+    pub(crate) fn resolve_account_plan(
+        &self,
+        provider_kind: &str,
+        plan_type: &mut Option<String>,
+        quota: Option<&ProviderQuota>,
+    ) -> Option<String> {
+        if let Some(quota) = quota {
+            quota.fill_missing_plan_type(plan_type);
+        }
+        self.plan_type_display(provider_kind, plan_type.as_deref())
+    }
+
+    /// 账号页和 Dashboard 共用的大驼峰套餐展示名称，不修改原始套餐值。
     pub(crate) fn plan_type_display(
         &self,
         provider_kind: &str,
@@ -261,10 +296,12 @@ impl ProviderAdminRegistry {
         let provider = ProviderKind::new(provider_kind.to_owned())
             .ok()
             .and_then(|kind| self.providers.get(&kind));
-        Some(provider.map_or_else(
+        let display = provider.map_or_else(
             || plan_type.to_owned(),
             |provider| provider.plan_type_display(plan_type),
-        ))
+        );
+        // 所有 Provider 及未知套餐统一排版，保留 Plus 后缀的含义。
+        Some(display.replace('+', " Plus ").to_upper_camel_case())
     }
 
     /// 返回所有已注册 Provider 的 Dashboard 上游身份画像。

backend/crates/gateway-admin/src/ports/proxy.rs

@@ -0,0 +1,66 @@
+use async_trait::async_trait;
+use gateway_core::account::{OutboundProxy, ProviderAccountId};
+
+use super::store::AdminStoreResult;
+use crate::model::{
+    MutationContext, Revision,
+    proxies::{
+        ImportProxyBinding, NewProxy, ProxyAccountListQuery, ProxyAccountPage, ProxyListQuery,
+        ProxyMutation, ProxyPage, ProxyRecord, ProxyTestResult, UpdateProxy,
+    },
+};
+
+#[async_trait]
+pub trait ProxyStore: Send + Sync {
+    /// 在凭据交换到提交期间保护选定代理的连接配置和测试结果。
+    async fn reserve_import(&self, id: &str) -> AdminStoreResult<ProxyImportReservation>;
+    async fn list(&self, query: ProxyListQuery) -> AdminStoreResult<ProxyPage>;
+    async fn list_accounts(
+        &self,
+        query: ProxyAccountListQuery,
+    ) -> AdminStoreResult<ProxyAccountPage>;
+    async fn get(&self, id: &str) -> AdminStoreResult<ProxyRecord>;
+    /// 仅在账号仍绑定指定代理时解除关联，并清除账号保存的连接地址。
+    async fn remove_account(
+        &self,
+        proxy_id: &str,
+        account_id: &ProviderAccountId,
+        context: &MutationContext,
+    ) -> AdminStoreResult<Revision>;
+    async fn create(
+        &self,
+        command: NewProxy,
+        context: &MutationContext,
+    ) -> AdminStoreResult<ProxyMutation>;
+    async fn update(
+        &self,
+        command: UpdateProxy,
+        context: &MutationContext,
+    ) -> AdminStoreResult<ProxyMutation>;
+    async fn delete(
+        &self,
+        id: &str,
+        revision: Revision,
+        context: &MutationContext,
+    ) -> AdminStoreResult<Revision>;
+    async fn record_test(
+        &self,
+        id: &str,
+        revision: Revision,
+        result: ProxyTestResult,
+        context: &MutationContext,
+    ) -> AdminStoreResult<ProxyRecord>;
+}
+
+/// 离开作用域时释放保护，错误返回和请求取消也遵循相同规则。
+pub trait ProxyImportGuard: Send + Sync {}
+
+pub struct ProxyImportReservation {
+    pub binding: ImportProxyBinding,
+    pub guard: Box<dyn ProxyImportGuard>,
+}
+
+#[async_trait]
+pub trait ProxyProbe: Send + Sync {
+    async fn test(&self, proxy: &OutboundProxy) -> ProxyTestResult;
+}

backend/crates/gateway-admin/src/ports/store.rs

@@ -32,9 +32,9 @@ use crate::model::{
     },
     provider_credentials::{
         AuthorizationCommit, CredentialDetails, CredentialImportCommit, CredentialImportResult,
-        CredentialListQuery, CredentialMutationResult, CredentialPage, CredentialRotationCommit,
-        ProviderExportCredentialInput,
+        CredentialMutationResult, CredentialRotationCommit, ProviderExportCredentialInput,
     },
+    quota_forecast_sampling::QuotaForecastHistory,
     settings::{AdminApiKey, AdminApiKeyMutation, ReplaceRuntimeSettings, RuntimeSettings},
 };
 
@@ -44,6 +44,7 @@ pub enum AdminStoreErrorKind {
     Invalid,
     NotFound,
     StaleRevision,
+    DuplicateName,
     Conflict,
     Unavailable,
 }
@@ -110,11 +111,11 @@ pub trait AccountStore: Send + Sync {
         windows: &[AccountUsageWindowQuery],
     ) -> AdminStoreResult<Vec<AccountUsageWindowResult>>;
 
-    async fn list_credentials(
+    /// 从同一数据库语句取得截止快照的累计用量和有界历史观测。
+    async fn load_quota_forecast_history(
         &self,
-        provider_kind: &gateway_core::routing::ProviderKind,
-        query: CredentialListQuery,
-    ) -> AdminStoreResult<CredentialPage>;
+        window: &AccountUsageWindowQuery,
+    ) -> AdminStoreResult<QuotaForecastHistory>;
 
     async fn credential_details(
         &self,
@@ -220,29 +221,6 @@ pub trait AuthStore: Send + Sync {
 /// Client API Key 管理写入。
 #[async_trait]
 pub trait ClientKeyStore: Send + Sync {
-    async fn unresolved_charges(
-        &self,
-        _id: &gateway_core::policy::ClientApiKeyId,
-    ) -> AdminStoreResult<Vec<crate::model::client_keys::UnresolvedClientCharge>> {
-        Err(AdminStoreError::new(
-            AdminStoreErrorKind::Unavailable,
-            "client budget",
-            "unsupported",
-        ))
-    }
-
-    async fn reconcile_charge(
-        &self,
-        _command: crate::model::client_keys::ReconcileClientCharge,
-        _context: &MutationContext,
-    ) -> AdminStoreResult<()> {
-        Err(AdminStoreError::new(
-            AdminStoreErrorKind::Unavailable,
-            "client budget",
-            "unsupported",
-        ))
-    }
-
     async fn list_client_keys(&self, query: ClientKeyListQuery) -> AdminStoreResult<ClientKeyPage>;
 
     async fn reveal_client_key(
@@ -405,6 +383,7 @@ pub struct AdminAccountStorePorts {
     accounts: Arc<dyn AccountStore>,
     runtime: Arc<dyn AccountRuntimeStore>,
     groups: Arc<dyn AccountGroupStore>,
+    proxies: Arc<dyn super::proxy::ProxyStore>,
 }
 
 impl AdminAccountStorePorts {
@@ -413,11 +392,13 @@ impl AdminAccountStorePorts {
         accounts: Arc<dyn AccountStore>,
         runtime: Arc<dyn AccountRuntimeStore>,
         groups: Arc<dyn AccountGroupStore>,
+        proxies: Arc<dyn super::proxy::ProxyStore>,
     ) -> Self {
         Self {
             accounts,
             runtime,
             groups,
+            proxies,
         }
     }
 }
@@ -470,6 +451,11 @@ impl AdminStorePorts {
         self.accounts.groups.clone()
     }
 
+    #[must_use]
+    pub fn proxies(&self) -> Arc<dyn super::proxy::ProxyStore> {
+        self.accounts.proxies.clone()
+    }
+
     #[must_use]
     pub fn auth(&self) -> Arc<dyn AuthStore> {
         self.auth.clone()

backend/crates/gateway-admin/src/use_case/accounts.rs

@@ -22,12 +22,14 @@ use crate::{
         },
         observability::TimeRange,
         provider_credentials::{
-            AccountDirectoryItem, AccountDirectoryPage, AccountExportBundle, AccountRefreshResult,
-            ConsumeProviderResetCredit, PrepareCredentialRefresh, ProviderModels,
-            ProviderProfileAvatar, ProviderProfileStatistics, ProviderQuota, ProviderQuotaRequest,
+            AccountDirectoryItem, AccountDirectoryPage, AccountExportBundle, AccountPersonalInfo,
+            AccountRefreshResult, ConsumeProviderResetCredit, PrepareCredentialRefresh,
+            ProviderModels, ProviderProfileAvatar, ProviderQuota, ProviderQuotaRequest,
             ProviderQuotaWindow, ProviderResetCreditResult, ProviderResetCredits,
             QuotaLocalUsageAttribution,
         },
+        quota_forecast::{AccountQuotaForecastReport, account_quota_forecasts},
+        quota_forecast_sampling::{QuotaForecastPoint, select_forecast_sample},
     },
     ports::{
         provider::ProviderAdminRegistry,
@@ -83,11 +85,16 @@ pub trait AccountsService: Send + Sync {
         refresh: bool,
     ) -> Result<AccountDirectoryItem, AdminError>;
 
-    async fn profile_statistics(
+    async fn quota_forecast(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Result<AccountQuotaForecastReport, AdminError>;
+
+    async fn personal_info(
         &self,
         _account_id: &ProviderAccountId,
-    ) -> Result<ProviderProfileStatistics, AdminError> {
-        Err(AdminError::invalid("当前 Provider 不支持账号统计"))
+    ) -> Result<AccountPersonalInfo, AdminError> {
+        Err(AdminError::invalid("当前 Provider 不支持个人信息"))
     }
 
     async fn profile_avatar(
@@ -213,6 +220,7 @@ impl DefaultAccountsService {
                 quota
                     .windows
                     .iter()
+                    .filter(|window| window.local_usage.is_none())
                     .filter_map(|window| quota_usage_window(&item.account.id, window))
             })
             .collect::<Vec<_>>();
@@ -279,12 +287,14 @@ impl DefaultAccountsService {
             std::slice::from_mut(&mut quota),
         )
         .await?;
-        let usage = quota.representative_window_usage().cloned();
-        quota.fill_missing_plan_type(&mut stored.account.plan_type);
+        let usage = quota
+            .usage_window()
+            .and_then(|(window, _)| window.local_usage.clone());
         Ok(AccountDirectoryItem {
-            plan_type_display: self.providers.plan_type_display(
+            plan_type_display: self.providers.resolve_account_plan(
                 stored.account.provider_kind.as_str(),
-                stored.account.plan_type.as_deref(),
+                &mut stored.account.plan_type,
+                Some(&quota),
             ),
             projection: stored.projection,
             usage,
@@ -372,12 +382,14 @@ impl AccountsService for DefaultAccountsService {
             .into_iter()
             .zip(quotas)
             .map(|(mut item, quota)| {
-                let usage = quota.representative_window_usage().cloned();
-                quota.fill_missing_plan_type(&mut item.account.plan_type);
+                let usage = quota
+                    .usage_window()
+                    .and_then(|(window, _)| window.local_usage.clone());
                 AccountDirectoryItem {
-                    plan_type_display: self.providers.plan_type_display(
+                    plan_type_display: self.providers.resolve_account_plan(
                         item.account.provider_kind.as_str(),
-                        item.account.plan_type.as_deref(),
+                        &mut item.account.plan_type,
+                        Some(&quota),
                     ),
                     usage,
                     account: item.account,
@@ -577,15 +589,127 @@ impl AccountsService for DefaultAccountsService {
         self.load_directory_item(account_id, refresh).await
     }
 
-    async fn profile_statistics(
+    async fn quota_forecast(
         &self,
         account_id: &ProviderAccountId,
-    ) -> Result<ProviderProfileStatistics, AdminError> {
-        let (_, provider) = self.provider_for_account(account_id).await?;
-        provider
-            .profile_statistics(account_id)
+    ) -> Result<AccountQuotaForecastReport, AdminError> {
+        let (stored, provider) = self.provider_for_account(account_id).await?;
+        let quota = provider
+            .quota(ProviderQuotaRequest {
+                account_id: account_id.clone(),
+                refresh: false,
+                rolling_usage: None,
+            })
             .await
-            .map_err(|error| map_provider_error(error, "provider profile statistics"))
+            .map_err(|error| map_provider_error(error, "forecast quota snapshot"))?;
+        let now = Utc::now();
+        let mut samples = Vec::new();
+        for (window, _) in quota.usage_windows() {
+            let (Some(mut query), Some(observed), Some(percent)) = (
+                quota_usage_window(account_id.as_str(), window),
+                quota.observed_at,
+                window.used_percent,
+            ) else {
+                continue;
+            };
+            query.range.start = query.range.start.max(stored.account.created_at);
+            if query.range.start >= observed
+                || observed > now
+                || now >= query.range.end
+                || !percent.is_finite()
+                || !(0.0..=100.0).contains(&percent)
+            {
+                continue;
+            }
+            let reset_at = query.range.end;
+            query.range.end = observed;
+            let history = self
+                .accounts
+                .load_quota_forecast_history(&query)
+                .await
+                .map_err(|error| map_store_error(error, "forecast paired usage"))?;
+            let mut points = Vec::new();
+            let mut interrupted = false;
+            for point in history.points {
+                let Some(fact) =
+                    provider.quota_forecast_observation(&point.provider_observation, window)
+                else {
+                    continue;
+                };
+                let same_plan = quota
+                    .plan_type
+                    .as_deref()
+                    .zip(fact.plan_type.as_deref())
+                    .is_some_and(|(current, previous)| current.eq_ignore_ascii_case(previous));
+                // 仅容纳已观测到的秒级量化抖动，不用宽时间容差合并实际重置。
+                // 不匹配的段截断基线；之后的有效观测可以重新积累。
+                if !same_plan || (fact.reset_at - reset_at).abs() > Duration::seconds(2) {
+                    points.clear();
+                    interrupted = true;
+                    continue;
+                }
+                points.push(QuotaForecastPoint {
+                    observed_at: point.completed_at,
+                    used_percent: fact.used_percent,
+                    usage: point.usage,
+                });
+            }
+            let mut sample = select_forecast_sample(
+                window.key.clone(),
+                query.range.start,
+                QuotaForecastPoint {
+                    observed_at: observed,
+                    used_percent: percent,
+                    usage: history.usage,
+                },
+                points,
+                history.pending_request_count,
+            );
+            if interrupted
+                && sample.method
+                    == crate::model::quota_forecast_sampling::QuotaForecastMethod::Cumulative
+            {
+                sample.discontinuous = true;
+            }
+            samples.push(sample);
+        }
+        Ok(AccountQuotaForecastReport {
+            account_id: account_id.to_string(),
+            generated_at: now,
+            forecasts: account_quota_forecasts(&quota, stored.account.created_at, now, &samples),
+        })
+    }
+
+    async fn personal_info(
+        &self,
+        account_id: &ProviderAccountId,
+    ) -> Result<AccountPersonalInfo, AdminError> {
+        let (initial, provider) = self.provider_for_account(account_id).await?;
+        // 两项读取相互独立；不因其中一项失败而取消另一项，也不触发凭据或额度刷新。
+        let (profile, subscription) = futures::join!(
+            provider.profile_statistics(account_id),
+            provider.subscription(account_id),
+        );
+        let profile =
+            profile.map_err(|error| map_provider_error(error, "provider profile statistics"));
+        let subscription = subscription
+            .map_err(|error| map_provider_error(error, "provider subscription"))
+            .ok()
+            .flatten();
+
+        // 汇聚等待期间发生重新授权、换绑或删除时，不返回混合身份的数据。
+        let current = self.load_account(account_id).await?;
+        if current.account.provider_kind != initial.account.provider_kind
+            || current.account.credential_revision != initial.account.credential_revision
+            || current.account.upstream_user_id != initial.account.upstream_user_id
+            || current.account.upstream_account_id != initial.account.upstream_account_id
+        {
+            return Err(AdminError::conflict("账号身份已变化，请刷新信息后重试"));
+        }
+        Ok(AccountPersonalInfo {
+            profile,
+            subscription,
+        })
     }
 
     async fn profile_avatar(
@@ -758,14 +882,12 @@ fn quota_usage_window(
     account_id: &str,
     window: &ProviderQuotaWindow,
 ) -> Option<AccountUsageWindowQuery> {
-    if window.local_usage.is_some()
-        || window.local_usage_attribution != QuotaLocalUsageAttribution::AccountWide
-    {
+    if window.local_usage_attribution != QuotaLocalUsageAttribution::AccountWide {
         return None;
     }
     let reset_at = window.reset_at?;
     let seconds = i64::try_from(window.window_seconds?).ok()?;
-    let start = reset_at.checked_sub_signed(Duration::seconds(seconds))?;
+    let start = reset_at.checked_sub_signed(Duration::try_seconds(seconds)?)?;
     let range = TimeRange::new(start, reset_at).ok()?;
     // 上游百分比以该 reset 边界定义；以当前时间回推会让本地 Token 属于另一窗口。
     Some(AccountUsageWindowQuery {

backend/crates/gateway-admin/src/use_case/client_keys.rs

@@ -18,7 +18,7 @@ use crate::{
             DeleteClientKey, NewClientKey, SetClientKeyEnabled, UpdateClientKey,
         },
     },
-    ports::store::ClientKeyStore,
+    ports::store::{AdminStoreError, AdminStoreErrorKind, ClientKeyStore},
 };
 
 use super::{map_store_error, publish_committed};
@@ -26,19 +26,6 @@ use super::{map_store_error, publish_committed};
 /// API 消费的 Client Key 管理服务。
 #[async_trait]
 pub trait ClientKeyService: Send + Sync {
-    async fn unresolved_charges(
-        &self,
-        _id: &ClientApiKeyId,
-    ) -> Result<Vec<crate::model::client_keys::UnresolvedClientCharge>, AdminError> {
-        Err(AdminError::unavailable("client budget unavailable"))
-    }
-    async fn reconcile_charge(
-        &self,
-        _context: &MutationContext,
-        _command: crate::model::client_keys::ReconcileClientCharge,
-    ) -> Result<(), AdminError> {
-        Err(AdminError::unavailable("client budget unavailable"))
-    }
     async fn list(&self, query: ClientKeyListQuery) -> Result<ClientKeyPage, AdminError>;
     async fn reveal(&self, id: &ClientApiKeyId) -> Result<ClientKeySecret, AdminError>;
     async fn create(
@@ -77,34 +64,6 @@ impl DefaultClientKeyService {
 
 #[async_trait]
 impl ClientKeyService for DefaultClientKeyService {
-    async fn unresolved_charges(
-        &self,
-        id: &ClientApiKeyId,
-    ) -> Result<Vec<crate::model::client_keys::UnresolvedClientCharge>, AdminError> {
-        self.store
-            .unresolved_charges(id)
-            .await
-            .map_err(|error| map_store_error(error, "client budget"))
-    }
-
-    async fn reconcile_charge(
-        &self,
-        context: &MutationContext,
-        command: crate::model::client_keys::ReconcileClientCharge,
-    ) -> Result<(), AdminError> {
-        if command.request_id.is_empty()
-            || command.request_id.len() > 128
-            || command.reason.trim().is_empty()
-            || command.reason.len() > 1024
-            || command.reason.chars().any(char::is_control)
-        {
-            return Err(AdminError::invalid("invalid charge reconciliation"));
-        }
-        self.store
-            .reconcile_charge(command, context)
-            .await
-            .map_err(|error| map_store_error(error, "client budget"))
-    }
     async fn list(&self, query: ClientKeyListQuery) -> Result<ClientKeyPage, AdminError> {
         validate_cursor(&query)?;
         self.store
@@ -128,9 +87,13 @@ impl ClientKeyService for DefaultClientKeyService {
     ) -> Result<CreatedClientKey, AdminError> {
         let id = ClientApiKeyId::new(format!("key_{}", Uuid::now_v7().simple()))
             .map_err(|_| AdminError::internal("创建 Client API Key ID 失败"))?;
-        let mut bytes = [0_u8; 32];
-        OsRng.fill_bytes(&mut bytes);
-        let plaintext = format!("sk_{}", URL_SAFE_NO_PAD.encode(bytes));
+        let plaintext = if let Some(key) = command.custom_key {
+            key.expose_for_auth().to_owned()
+        } else {
+            let mut bytes = [0_u8; 32];
+            OsRng.fill_bytes(&mut bytes);
+            format!("sk_{}", URL_SAFE_NO_PAD.encode(bytes))
+        };
         let (config_revision, record) = self
             .store
             .create_client_key(
@@ -146,7 +109,7 @@ impl ClientKeyService for DefaultClientKeyService {
                 context,
             )
             .await
-            .map_err(|error| map_store_error(error, "client API key"))?;
+            .map_err(map_client_key_write_error)?;
         publish_committed(self.snapshot.as_ref(), config_revision).await?;
         Ok(CreatedClientKey {
             config_revision,
@@ -164,7 +127,7 @@ impl ClientKeyService for DefaultClientKeyService {
             .store
             .update_client_key(command, context)
             .await
-            .map_err(|error| map_store_error(error, "client API key"))?;
+            .map_err(map_client_key_write_error)?;
         publish_committed(self.snapshot.as_ref(), config_revision).await?;
         Ok(ClientKeyMutation {
             config_revision,
@@ -212,6 +175,14 @@ 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"),
+    }
+}
+
 fn validate_cursor(query: &ClientKeyListQuery) -> Result<(), AdminError> {
     let Some(cursor) = &query.cursor else {
         return Ok(());

backend/crates/gateway-admin/src/use_case/mod.rs

@@ -8,10 +8,13 @@ pub mod client_distribution;
 pub mod client_keys;
 pub mod observability;
 pub mod openai;
+pub mod proxies;
 pub mod settings;
 pub mod system;
 pub mod xai;
 
+use std::sync::Arc;
+
 use crate::{
     model::{
         AdminError, AdminErrorKind, MutationContext,
@@ -21,7 +24,7 @@ use crate::{
             CredentialDetails, CredentialMutationResult, CredentialRotationCommit,
             PendingAuthorizationMutation, PreparedAuthorizationCommit,
             PreparedAuthorizationCredential, PreparedCredentialImport, PreparedCredentialRotation,
-            StartAuthorization,
+            ProviderQuotaRequest, StartAuthorization,
         },
     },
     ports::{
@@ -39,9 +42,9 @@ 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::Conflict => {
-            AdminErrorKind::Conflict
-        }
+        AdminStoreErrorKind::StaleRevision
+        | AdminStoreErrorKind::DuplicateName
+        | AdminStoreErrorKind::Conflict => AdminErrorKind::Conflict,
         AdminStoreErrorKind::Unavailable => AdminErrorKind::Unavailable,
     };
     tracing::warn!(resource, error_kind = ?error.kind(), "admin store operation failed");
@@ -96,6 +99,43 @@ async fn publish_committed(
     Ok(())
 }
 
+async fn publish_credentials_and_observe_quota(
+    provider: &Arc<dyn ProviderAdmin>,
+    snapshot: &dyn SnapshotControl,
+    revision: crate::model::Revision,
+    account_ids: &[ProviderAccountId],
+    request_id: &str,
+) -> Result<(), AdminError> {
+    provider.account_facts_changed(account_ids).await;
+    publish_committed(snapshot, revision).await?;
+
+    // 凭据已经提交；额度只是可重建的观察，不能拖住管理请求或回滚提交结果。
+    let provider = Arc::clone(provider);
+    let account_ids = account_ids.to_vec();
+    let request_id = request_id.to_owned();
+    tokio::spawn(async move {
+        for account_id in account_ids {
+            if let Err(error) = provider
+                .quota(ProviderQuotaRequest {
+                    account_id: account_id.clone(),
+                    refresh: true,
+                    rolling_usage: None,
+                })
+                .await
+            {
+                tracing::warn!(
+                    request_id,
+                    provider = %provider.provider_kind().as_str(),
+                    account_id = %account_id.as_str(),
+                    quota_error = ?error.kind(),
+                    "initial quota observation failed"
+                );
+            }
+        }
+    });
+    Ok(())
+}
+
 async fn required_credential(
     accounts: &dyn AccountStore,
     provider_kind: &ProviderKind,
@@ -109,13 +149,27 @@ async fn required_credential(
         .ok_or_else(|| AdminError::not_found("Provider 凭据不存在"))
 }
 
+async fn import_proxy_binding(
+    proxies: &dyn crate::ports::proxy::ProxyStore,
+    id: Option<&str>,
+) -> Result<Option<crate::ports::proxy::ProxyImportReservation>, AdminError> {
+    let Some(id) = id else { return Ok(None) };
+    let reservation = proxies
+        .reserve_import(id)
+        .await
+        .map_err(|error| map_store_error(error, "proxy"))?;
+    Ok(Some(reservation))
+}
+
 async fn pending_authorization(
     accounts: &dyn AccountStore,
+    proxies: &dyn crate::ports::proxy::ProxyStore,
     provider_kind: &ProviderKind,
     command: &StartAuthorization,
     resource: &'static str,
 ) -> Result<PendingAuthorizationMutation, AdminError> {
-    let mut proxy = command.outbound_proxy.clone();
+    let proxy;
+    let mut proxy_id = None;
     let target = match &command.reauthorization {
         Some(account_id) => {
             proxy = required_credential(accounts, provider_kind, account_id, resource)
@@ -126,9 +180,27 @@ async fn pending_authorization(
                 account_id: account_id.clone(),
             }
         }
-        None => AuthorizationMutationTarget::Create {
-            name: command.name.clone(),
-        },
+        None => {
+            use crate::model::proxies::AccountProxySelection;
+            proxy = match &command.outbound_proxy {
+                Some(AccountProxySelection::Url(value)) => Some(value.clone()),
+                Some(AccountProxySelection::Saved(id)) => {
+                    let record = proxies
+                        .get(id)
+                        .await
+                        .map_err(|error| map_store_error(error, "proxy"))?;
+                    if !record.last_test.is_some_and(|test| test.success) {
+                        return Err(AdminError::conflict("请先测试代理连接"));
+                    }
+                    proxy_id = Some(record.id);
+                    Some(record.proxy)
+                }
+                Some(AccountProxySelection::Direct) | None => None,
+            };
+            AuthorizationMutationTarget::Create {
+                name: command.name.clone(),
+            }
+        }
     };
     Ok(PendingAuthorizationMutation::new(
         provider_kind.clone(),
@@ -137,7 +209,8 @@ async fn pending_authorization(
             &command.context,
         ),
     )
-    .with_outbound_proxy(proxy))
+    .with_outbound_proxy(proxy)
+    .with_outbound_proxy_id(proxy_id))
 }
 
 fn validate_prepared_import(

backend/crates/gateway-admin/src/use_case/openai.rs

@@ -3,17 +3,16 @@
 use std::sync::Arc;
 
 use async_trait::async_trait;
-use gateway_core::{account::ProviderAccountId, runtime::SnapshotControl};
+use gateway_core::runtime::SnapshotControl;
 
 use crate::{
     model::{
         AdminError,
         provider_credentials::{
             AuthorizationStarted, CompleteAuthorization, CredentialDeletion,
-            CredentialDeletionResult, CredentialDetails, CredentialImportCommit,
-            CredentialImportResult, CredentialListQuery, CredentialMutationResult, CredentialPage,
-            ImportCredentials, PrepareCredentialImport, PrepareCredentialRotation,
-            ProviderQuotaRequest, RotateCredential, StartAuthorization,
+            CredentialDeletionResult, CredentialImportCommit, CredentialImportResult,
+            CredentialMutationResult, ImportCredentials, PrepareCredentialImport,
+            PrepareCredentialRotation, RotateCredential, StartAuthorization,
         },
     },
     ports::{provider::ProviderAdmin, store::AccountStore},
@@ -21,18 +20,14 @@ use crate::{
 
 use super::{
     commit_authorization, commit_credential_rotation, delete_credentials, map_provider_error,
-    map_store_error, pending_authorization, publish_committed, required_credential,
-    validate_authorization_commit, validate_prepared_import, validate_prepared_rotation,
+    map_store_error, pending_authorization, publish_committed,
+    publish_credentials_and_observe_quota, required_credential, validate_authorization_commit,
+    validate_prepared_import, validate_prepared_rotation,
 };
 
 /// OpenAI 固定管理路由消费的服务。
 #[async_trait]
 pub trait OpenAiService: Send + Sync {
-    async fn list(&self, query: CredentialListQuery) -> Result<CredentialPage, AdminError>;
-    async fn details(
-        &self,
-        account_id: &ProviderAccountId,
-    ) -> Result<CredentialDetails, AdminError>;
     async fn import_document(
         &self,
         command: ImportCredentials,
@@ -58,6 +53,7 @@ pub trait OpenAiService: Send + Sync {
 pub(crate) struct DefaultOpenAiService {
     provider: Arc<dyn ProviderAdmin>,
     accounts: Arc<dyn AccountStore>,
+    proxies: Arc<dyn crate::ports::proxy::ProxyStore>,
     snapshot: Arc<dyn SnapshotControl>,
 }
 
@@ -66,71 +62,39 @@ impl DefaultOpenAiService {
     pub(crate) fn new(
         provider: Arc<dyn ProviderAdmin>,
         accounts: Arc<dyn AccountStore>,
+        proxies: Arc<dyn crate::ports::proxy::ProxyStore>,
         snapshot: Arc<dyn SnapshotControl>,
     ) -> Self {
         Self {
             provider,
             accounts,
+            proxies,
             snapshot,
         }
     }
-
-    fn observe_initial_quotas(&self, account_ids: &[ProviderAccountId], request_id: &str) {
-        let provider = Arc::clone(&self.provider);
-        let account_ids = account_ids.to_vec();
-        let request_id = request_id.to_owned();
-        tokio::spawn(async move {
-            for account_id in account_ids {
-                if let Err(error) = provider
-                    .quota(ProviderQuotaRequest {
-                        account_id: account_id.clone(),
-                        refresh: true,
-                        rolling_usage: None,
-                    })
-                    .await
-                {
-                    tracing::warn!(
-                        request_id,
-                        account_id = %account_id.as_str(),
-                        quota_error = ?error.kind(),
-                        "OpenAI initial quota observation failed"
-                    );
-                }
-            }
-        });
-    }
 }
 
 #[async_trait]
 impl OpenAiService for DefaultOpenAiService {
-    async fn list(&self, query: CredentialListQuery) -> Result<CredentialPage, AdminError> {
-        self.accounts
-            .list_credentials(self.provider.provider_kind(), query)
-            .await
-            .map_err(|error| map_store_error(error, "OpenAI credential"))
-    }
-
-    async fn details(
-        &self,
-        account_id: &ProviderAccountId,
-    ) -> Result<CredentialDetails, AdminError> {
-        required_credential(
-            self.accounts.as_ref(),
-            self.provider.provider_kind(),
-            account_id,
-            "OpenAI credential",
-        )
-        .await
-    }
-
     async fn import_document(
         &self,
         command: ImportCredentials,
     ) -> Result<CredentialImportResult, AdminError> {
         let context = command.context;
+        let proxy_reservation = super::import_proxy_binding(
+            self.proxies.as_ref(),
+            command.outbound_proxy_id.as_deref(),
+        )
+        .await?;
+        let outbound_proxy = proxy_reservation
+            .as_ref()
+            .map(|reservation| reservation.binding.clone());
         let prepared = self
             .provider
             .prepare_import(PrepareCredentialImport {
+                default_outbound_proxy: outbound_proxy
+                    .as_ref()
+                    .map(|binding| binding.proxy.clone()),
                 document: command.document,
             })
             .await
@@ -144,6 +108,7 @@ impl OpenAiService for DefaultOpenAiService {
             .accounts
             .commit_credential_import(
                 CredentialImportCommit {
+                    outbound_proxy,
                     prepared,
                     settings: command.settings,
                 },
@@ -151,12 +116,15 @@ impl OpenAiService for DefaultOpenAiService {
             )
             .await
             .map_err(|error| map_store_error(error, "OpenAI credential import"))?;
-        self.provider
-            .account_facts_changed(&result.credential_ids)
-            .await;
-        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
-        // 导入完成后立即做一次观察；失败不回滚已经提交的 credential。
-        self.observe_initial_quotas(&result.credential_ids, &context.request_id);
+        drop(proxy_reservation);
+        publish_credentials_and_observe_quota(
+            &self.provider,
+            self.snapshot.as_ref(),
+            result.config_revision,
+            &result.credential_ids,
+            &context.request_id,
+        )
+        .await?;
         Ok(result)
     }
 
@@ -166,6 +134,7 @@ impl OpenAiService for DefaultOpenAiService {
     ) -> Result<AuthorizationStarted, AdminError> {
         let pending = pending_authorization(
             self.accounts.as_ref(),
+            self.proxies.as_ref(),
             self.provider.provider_kind(),
             &command,
             "OpenAI credential",
@@ -203,14 +172,14 @@ impl OpenAiService for DefaultOpenAiService {
             "OpenAI authorization",
         )
         .await?;
-        self.provider
-            .account_facts_changed(std::slice::from_ref(&result.account_id))
-            .await;
-        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
-        self.observe_initial_quotas(
+        publish_credentials_and_observe_quota(
+            &self.provider,
+            self.snapshot.as_ref(),
+            result.config_revision,
             std::slice::from_ref(&result.account_id),
             &context.request_id,
-        );
+        )
+        .await?;
         Ok(result)
     }
 

backend/crates/gateway-admin/src/use_case/proxies.rs

@@ -0,0 +1,261 @@
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use futures::{StreamExt, stream};
+use gateway_core::{
+    account::{OutboundProxy, ProviderAccountId},
+    routing::ProviderKind,
+    runtime::SnapshotControl,
+};
+use tokio::sync::Semaphore;
+
+use super::{map_store_error, publish_committed};
+use crate::{
+    model::{
+        AdminError, AdminErrorKind, MutationContext, Revision,
+        provider_credentials::{ProviderQuotaRequest, explicit_plan_type},
+        proxies::*,
+    },
+    ports::{
+        provider::ProviderAdminRegistry,
+        proxy::{ProxyProbe, ProxyStore},
+        store::AdminStoreErrorKind,
+    },
+};
+
+#[async_trait]
+pub trait ProxiesService: Send + Sync {
+    async fn list(&self, query: ProxyListQuery) -> Result<ProxyPage, AdminError>;
+    async fn list_accounts(
+        &self,
+        query: ProxyAccountListQuery,
+    ) -> Result<ProxyAccountPage, AdminError>;
+    async fn remove_account(
+        &self,
+        proxy_id: &str,
+        account_id: &str,
+        context: &MutationContext,
+    ) -> Result<Revision, AdminError>;
+    async fn create(
+        &self,
+        command: NewProxy,
+        context: &MutationContext,
+    ) -> Result<ProxyMutation, AdminError>;
+    async fn update(
+        &self,
+        command: UpdateProxy,
+        context: &MutationContext,
+    ) -> Result<ProxyMutation, AdminError>;
+    async fn delete(
+        &self,
+        id: &str,
+        revision: Revision,
+        context: &MutationContext,
+    ) -> Result<Revision, AdminError>;
+    async fn test(
+        &self,
+        id: &str,
+        revision: Revision,
+        context: &MutationContext,
+    ) -> Result<ProxyRecord, AdminError>;
+    /// 探测未保存的连接地址，不写入代理记录或修改账号绑定。
+    async fn probe(&self, proxy: &OutboundProxy) -> Result<ProxyTestResult, AdminError>;
+}
+
+pub(crate) struct DefaultProxiesService {
+    store: Arc<dyn ProxyStore>,
+    probe: Arc<dyn ProxyProbe>,
+    snapshot: Arc<dyn SnapshotControl>,
+    providers: ProviderAdminRegistry,
+    test_slots: Semaphore,
+}
+
+impl DefaultProxiesService {
+    pub(crate) fn new(
+        store: Arc<dyn ProxyStore>,
+        probe: Arc<dyn ProxyProbe>,
+        snapshot: Arc<dyn SnapshotControl>,
+        providers: ProviderAdminRegistry,
+    ) -> Self {
+        Self {
+            store,
+            probe,
+            snapshot,
+            providers,
+            test_slots: Semaphore::new(4),
+        }
+    }
+}
+
+#[async_trait]
+impl ProxiesService for DefaultProxiesService {
+    async fn remove_account(
+        &self,
+        proxy_id: &str,
+        account_id: &str,
+        context: &MutationContext,
+    ) -> Result<Revision, AdminError> {
+        if proxy_id.is_empty() || proxy_id.len() > 128 || proxy_id.chars().any(char::is_control) {
+            return Err(AdminError::invalid("代理 ID 不合法"));
+        }
+        let account_id = ProviderAccountId::new(account_id.to_owned())
+            .map_err(|_| AdminError::invalid("账号 ID 不合法"))?;
+        let revision = self
+            .store
+            .remove_account(proxy_id, &account_id, context)
+            .await
+            .map_err(|error| {
+                if error.kind() == AdminStoreErrorKind::Conflict {
+                    AdminError::conflict("账号的代理绑定已变化，请刷新后重试")
+                } else {
+                    map_store_error(error, "proxy account")
+                }
+            })?;
+        publish_committed(self.snapshot.as_ref(), revision).await?;
+        Ok(revision)
+    }
+
+    async fn list_accounts(
+        &self,
+        query: ProxyAccountListQuery,
+    ) -> Result<ProxyAccountPage, AdminError> {
+        if query.proxy_id.is_empty()
+            || query.proxy_id.len() > 128
+            || query.proxy_id.chars().any(char::is_control)
+            || query.page == 0
+            || query.search.len() > 256
+            || query.search.chars().any(char::is_control)
+        {
+            return Err(AdminError::invalid("关联账号查询参数不合法"));
+        }
+        let mut page = self
+            .store
+            .list_accounts(query)
+            .await
+            .map_err(|error| map_store_error(error, "proxy"))?;
+        page.items = stream::iter(page.items)
+            .map(|mut account| async {
+                // 与账号目录一致，缺失套餐时读取已有额度快照；限制并发且不触发上游刷新。
+                let mut cached_quota = None;
+                if explicit_plan_type(account.plan_type.as_deref()).is_none()
+                    && let Ok(kind) = ProviderKind::new(account.provider_kind.clone())
+                    && let Ok(provider) = self.providers.require(&kind)
+                    && let Ok(account_id) = ProviderAccountId::new(account.id.clone())
+                    && let Ok(quota) = provider
+                        .quota(ProviderQuotaRequest {
+                            account_id,
+                            refresh: false,
+                            rolling_usage: None,
+                        })
+                        .await
+                {
+                    cached_quota = Some(quota);
+                }
+                account.plan_type_display = self.providers.resolve_account_plan(
+                    &account.provider_kind,
+                    &mut account.plan_type,
+                    cached_quota.as_ref(),
+                );
+                account
+            })
+            .buffered(8)
+            .collect()
+            .await;
+        Ok(page)
+    }
+
+    async fn list(&self, query: ProxyListQuery) -> Result<ProxyPage, AdminError> {
+        if query.page == 0 || query.search.len() > 256 || query.search.chars().any(char::is_control)
+        {
+            return Err(AdminError::invalid("代理查询参数不合法"));
+        }
+        self.store
+            .list(query)
+            .await
+            .map_err(|error| map_store_error(error, "proxy"))
+    }
+
+    async fn create(
+        &self,
+        mut command: NewProxy,
+        context: &MutationContext,
+    ) -> Result<ProxyMutation, AdminError> {
+        command.name = validate_name(&command.name)?;
+        let result = self
+            .store
+            .create(command, context)
+            .await
+            .map_err(|error| map_store_error(error, "proxy"))?;
+        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+        Ok(result)
+    }
+
+    async fn update(
+        &self,
+        mut command: UpdateProxy,
+        context: &MutationContext,
+    ) -> Result<ProxyMutation, AdminError> {
+        command.name = validate_name(&command.name)?;
+        let result = self
+            .store
+            .update(command, context)
+            .await
+            .map_err(|error| map_store_error(error, "proxy"))?;
+        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+        Ok(result)
+    }
+
+    async fn delete(
+        &self,
+        id: &str,
+        revision: Revision,
+        context: &MutationContext,
+    ) -> Result<Revision, AdminError> {
+        let result = self
+            .store
+            .delete(id, revision, context)
+            .await
+            .map_err(|error| map_store_error(error, "proxy"))?;
+        publish_committed(self.snapshot.as_ref(), result).await?;
+        Ok(result)
+    }
+
+    async fn probe(&self, proxy: &OutboundProxy) -> Result<ProxyTestResult, AdminError> {
+        let _permit = self.test_slots.try_acquire().map_err(|_| {
+            AdminError::new(AdminErrorKind::RateLimited, "代理测试繁忙，请稍后重试")
+        })?;
+        Ok(self.probe.test(proxy).await)
+    }
+
+    async fn test(
+        &self,
+        id: &str,
+        revision: Revision,
+        context: &MutationContext,
+    ) -> Result<ProxyRecord, AdminError> {
+        let _permit = self.test_slots.try_acquire().map_err(|_| {
+            AdminError::new(AdminErrorKind::RateLimited, "代理测试繁忙，请稍后重试")
+        })?;
+        let record = self
+            .store
+            .get(id)
+            .await
+            .map_err(|error| map_store_error(error, "proxy"))?;
+        if record.revision != revision {
+            return Err(AdminError::conflict("代理已被修改，请刷新后重新测试"));
+        }
+        let result = self.probe.test(&record.proxy).await;
+        self.store
+            .record_test(id, revision, result, context)
+            .await
+            .map_err(|error| map_store_error(error, "proxy"))
+    }
+}
+
+fn validate_name(value: &str) -> Result<String, AdminError> {
+    let value = value.trim();
+    if value.is_empty() || value.chars().count() > 100 || value.chars().any(char::is_control) {
+        return Err(AdminError::invalid("代理名称需要 1 至 100 个字符"));
+    }
+    Ok(value.to_owned())
+}

backend/crates/gateway-admin/src/use_case/xai.rs

@@ -11,8 +11,8 @@ use crate::{
         provider_credentials::{
             AuthorizationStarted, CompleteAuthorization, CredentialDeletion,
             CredentialDeletionResult, CredentialImportCommit, CredentialImportResult,
-            CredentialListQuery, CredentialMutationResult, CredentialPage, ImportCredentials,
-            PrepareCredentialImport, ProviderQuotaRequest, StartAuthorization,
+            CredentialMutationResult, ImportCredentials, PrepareCredentialImport,
+            StartAuthorization,
         },
     },
     ports::{provider::ProviderAdmin, store::AccountStore},
@@ -20,14 +20,13 @@ use crate::{
 
 use super::{
     commit_authorization, delete_credentials, map_provider_error, map_store_error,
-    pending_authorization, publish_committed, validate_authorization_commit,
-    validate_prepared_import,
+    pending_authorization, publish_committed, publish_credentials_and_observe_quota,
+    validate_authorization_commit, validate_prepared_import,
 };
 
 /// xAI 固定管理路由消费的服务。
 #[async_trait]
 pub trait XaiService: Send + Sync {
-    async fn list(&self, query: CredentialListQuery) -> Result<CredentialPage, AdminError>;
     async fn import_document(
         &self,
         command: ImportCredentials,
@@ -49,6 +48,7 @@ pub trait XaiService: Send + Sync {
 pub(crate) struct DefaultXaiService {
     provider: Arc<dyn ProviderAdmin>,
     accounts: Arc<dyn AccountStore>,
+    proxies: Arc<dyn crate::ports::proxy::ProxyStore>,
     snapshot: Arc<dyn SnapshotControl>,
 }
 
@@ -57,11 +57,13 @@ impl DefaultXaiService {
     pub(crate) fn new(
         provider: Arc<dyn ProviderAdmin>,
         accounts: Arc<dyn AccountStore>,
+        proxies: Arc<dyn crate::ports::proxy::ProxyStore>,
         snapshot: Arc<dyn SnapshotControl>,
     ) -> Self {
         Self {
             provider,
             accounts,
+            proxies,
             snapshot,
         }
     }
@@ -69,21 +71,25 @@ impl DefaultXaiService {
 
 #[async_trait]
 impl XaiService for DefaultXaiService {
-    async fn list(&self, query: CredentialListQuery) -> Result<CredentialPage, AdminError> {
-        self.accounts
-            .list_credentials(self.provider.provider_kind(), query)
-            .await
-            .map_err(|error| map_store_error(error, "xAI credential"))
-    }
-
     async fn import_document(
         &self,
         command: ImportCredentials,
     ) -> Result<CredentialImportResult, AdminError> {
         let context = command.context;
+        let proxy_reservation = super::import_proxy_binding(
+            self.proxies.as_ref(),
+            command.outbound_proxy_id.as_deref(),
+        )
+        .await?;
+        let outbound_proxy = proxy_reservation
+            .as_ref()
+            .map(|reservation| reservation.binding.clone());
         let prepared = self
             .provider
             .prepare_import(PrepareCredentialImport {
+                default_outbound_proxy: outbound_proxy
+                    .as_ref()
+                    .map(|binding| binding.proxy.clone()),
                 document: command.document,
             })
             .await
@@ -97,6 +103,7 @@ impl XaiService for DefaultXaiService {
             .accounts
             .commit_credential_import(
                 CredentialImportCommit {
+                    outbound_proxy,
                     prepared,
                     settings: command.settings,
                 },
@@ -104,18 +111,15 @@ impl XaiService for DefaultXaiService {
             )
             .await
             .map_err(|error| map_store_error(error, "xAI credential import"))?;
-        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
-        // 导入已经提交，额度属于可重建观察事实；单个账号查询失败由周期任务重试。
-        for account_id in &result.credential_ids {
-            let _ = self
-                .provider
-                .quota(ProviderQuotaRequest {
-                    account_id: account_id.clone(),
-                    refresh: true,
-                    rolling_usage: None,
-                })
-                .await;
-        }
+        drop(proxy_reservation);
+        publish_credentials_and_observe_quota(
+            &self.provider,
+            self.snapshot.as_ref(),
+            result.config_revision,
+            &result.credential_ids,
+            &context.request_id,
+        )
+        .await?;
         Ok(result)
     }
 
@@ -125,6 +129,7 @@ impl XaiService for DefaultXaiService {
     ) -> Result<AuthorizationStarted, AdminError> {
         let pending = pending_authorization(
             self.accounts.as_ref(),
+            self.proxies.as_ref(),
             self.provider.provider_kind(),
             &command,
             "xAI credential",
@@ -162,7 +167,14 @@ impl XaiService for DefaultXaiService {
             "xAI authorization",
         )
         .await?;
-        publish_committed(self.snapshot.as_ref(), result.config_revision).await?;
+        publish_credentials_and_observe_quota(
+            &self.provider,
+            self.snapshot.as_ref(),
+            result.config_revision,
+            std::slice::from_ref(&result.account_id),
+            &context.request_id,
+        )
+        .await?;
         Ok(result)
     }
 

backend/crates/gateway-admin/tests/main.rs

@@ -157,7 +157,7 @@ fn representative_quota_should_prefer_account_wide_window_over_model_specific_wi
 }
 
 #[test]
-fn representative_window_usage_should_accept_account_wide_rolling_window_without_reset() {
+fn usage_window_should_not_use_daily_rolling_usage_for_weekly_statistics() {
     let usage = AccountUsage {
         account_id: "acct_xai".to_owned(),
         request_count: 5,
@@ -194,14 +194,14 @@ fn representative_window_usage_should_accept_account_wide_rolling_window_without
             used_percent: None,
             reset_at: None,
             limit_reached: false,
-            local_usage: Some(usage.clone()),
+            local_usage: Some(usage),
             provider_data: None,
         }],
         limit_reached: false,
         provider_data: None,
     };
 
-    assert_eq!(quota.representative_window_usage(), Some(&usage));
+    assert_eq!(quota.usage_window(), None);
 }
 
 #[test]

backend/crates/gateway-admin/tests/model/mod.rs

@@ -2,3 +2,5 @@
 
 mod backup;
 mod provider_credentials;
+mod quota_forecast;
+mod quota_forecast_sampling;

backend/crates/gateway-admin/tests/model/provider_credentials.rs

@@ -1,12 +1,135 @@
 use gateway_admin::model::provider_credentials::{
-    AuthorizationMutationTarget, AuthorizationOwnerBinding, PendingAuthorizationMutation,
-    ProviderQuota, ProviderQuotaWindow, ProviderQuotaWindowRole, QuotaLocalUsageAttribution,
+    AccountUsagePeriod, AuthorizationMutationTarget, AuthorizationOwnerBinding,
+    PendingAuthorizationMutation, ProviderQuota, ProviderQuotaWindow, ProviderQuotaWindowRole,
+    QuotaLocalUsageAttribution,
 };
 use gateway_admin::model::{MutationActor, MutationContext};
 use gateway_core::account::ProviderAccountId;
 use gateway_core::routing::ProviderKind;
 use serde_json::{Value, json};
 
+#[test]
+fn usage_window_should_prefer_weekly_without_changing_dashboard_selection() {
+    let quota = usage_quota(vec![
+        usage_window("short", "shortTerm", 18_000),
+        usage_window("month", "monthly", 30 * 86_400),
+        usage_window("week", "shortTerm", 7 * 86_400),
+    ]);
+
+    assert_eq!(
+        selected_usage_window(&quota),
+        Some(("week", AccountUsagePeriod::Weekly))
+    );
+    assert_eq!(
+        quota
+            .representative_window()
+            .map(|window| window.key.as_str()),
+        Some("short")
+    );
+}
+
+#[test]
+fn usage_window_should_use_monthly_when_weekly_is_unavailable() {
+    let mut model_week = usage_window("model-week", "shortTerm", 7 * 86_400);
+    model_week.local_usage_attribution = QuotaLocalUsageAttribution::Unavailable;
+    let mut incomplete_week = usage_window("incomplete-week", "shortTerm", 7 * 86_400);
+    incomplete_week.reset_at = None;
+    let mut unknown_usage = usage_window("unknown-week", "shortTerm", 7 * 86_400);
+    unknown_usage.local_usage = None;
+    let quota = usage_quota(vec![
+        model_week,
+        incomplete_week,
+        unknown_usage,
+        usage_window("month", "monthly", 30 * 86_400),
+    ]);
+
+    assert_eq!(
+        selected_usage_window(&quota),
+        Some(("month", AccountUsagePeriod::Monthly))
+    );
+}
+
+#[test]
+fn usage_window_should_not_fallback_to_short_daily_or_incomplete_windows() {
+    let mut missing_duration = usage_window("unknown-month", "monthly", 30 * 86_400);
+    missing_duration.window_seconds = None;
+    let quota = usage_quota(vec![
+        usage_window("short", "shortTerm", 18_000),
+        usage_window("day", "shortTerm", 86_400),
+        usage_window("invalid-month", "monthly", 86_400),
+        missing_duration,
+    ]);
+
+    assert_eq!(quota.usage_window(), None);
+}
+
+#[test]
+fn usage_window_should_preserve_provider_order_for_equal_periods() {
+    let quota = usage_quota(vec![
+        usage_window("first-week", "shortTerm", 7 * 86_400),
+        usage_window("second-week", "shortTerm", 7 * 86_400),
+    ]);
+
+    assert_eq!(
+        selected_usage_window(&quota),
+        Some(("first-week", AccountUsagePeriod::Weekly))
+    );
+}
+
+fn selected_usage_window(quota: &ProviderQuota) -> Option<(&str, AccountUsagePeriod)> {
+    quota
+        .usage_window()
+        .map(|(window, period)| (window.key.as_str(), period))
+}
+
+fn usage_quota(windows: Vec<ProviderQuotaWindow>) -> ProviderQuota {
+    ProviderQuota {
+        plan_type: None,
+        observed_at: None,
+        refresh_token_expires_at: None,
+        windows,
+        limit_reached: false,
+        provider_data: None,
+    }
+}
+
+fn usage_window(key: &str, group: &str, seconds: u64) -> ProviderQuotaWindow {
+    ProviderQuotaWindow {
+        key: key.to_owned(),
+        group: group.to_owned(),
+        label: key.to_owned(),
+        limit_id: None,
+        limit_name: None,
+        role: None,
+        local_usage_attribution: QuotaLocalUsageAttribution::AccountWide,
+        window_seconds: Some(seconds),
+        used_percent: Some(50.0),
+        reset_at: Some(chrono::Utc::now()),
+        limit_reached: false,
+        local_usage: Some(gateway_admin::model::accounts::AccountUsage {
+            account_id: "acct_test".to_owned(),
+            request_count: 0,
+            success_count: 0,
+            input_tokens: None,
+            output_tokens: None,
+            cached_tokens: None,
+            cache_write_tokens: None,
+            reasoning_tokens: None,
+            image_input_tokens: None,
+            image_output_tokens: None,
+            image_request_count: 0,
+            image_request_failed_count: 0,
+            total_tokens: None,
+            cost_coverage: Default::default(),
+            costs: Vec::new(),
+            last_used_at: None,
+            request_buckets: Vec::new(),
+            models: Vec::new(),
+        }),
+        provider_data: None,
+    }
+}
+
 #[test]
 fn dashboard_quota_should_preserve_unknown_and_actual_window_facts() {
     let mut quota = ProviderQuota {
@@ -97,7 +220,21 @@ fn pending_mutation_v1_should_round_trip_all_targets_and_owners() {
                     PendingAuthorizationMutation::from_storage_v1(Value::Object(
                         expected.to_storage_v1()
                     )),
-                    Ok(expected),
+                    Ok(expected.clone()),
+                );
+                let with_proxy = expected
+                    .with_outbound_proxy(Some(
+                        gateway_core::account::OutboundProxy::parse(
+                            "http://user:secret@proxy.example:8080",
+                        )
+                        .unwrap(),
+                    ))
+                    .with_outbound_proxy_id(Some("proxy_saved".to_owned()));
+                assert_eq!(
+                    PendingAuthorizationMutation::from_storage_v1(Value::Object(
+                        with_proxy.to_storage_v1()
+                    )),
+                    Ok(with_proxy)
                 );
             }
         }

backend/crates/gateway-admin/tests/model/quota_forecast.rs

@@ -0,0 +1,382 @@
+use chrono::{DateTime, Duration, Utc};
+use gateway_admin::model::{
+    accounts::{AccountCost, AccountUsage},
+    observability::CostCoverage,
+    provider_credentials::{ProviderQuota, ProviderQuotaWindow, QuotaLocalUsageAttribution},
+    quota_forecast::{AccountQuotaForecast, account_quota_forecasts},
+    quota_forecast_sampling::{QuotaForecastMethod, QuotaForecastSample, QuotaForecastUsage},
+};
+
+fn now() -> DateTime<Utc> {
+    "2026-09-12T00:00:00Z".parse().unwrap()
+}
+
+fn window(key: &str, days: u64) -> ProviderQuotaWindow {
+    ProviderQuotaWindow {
+        key: key.to_owned(),
+        group: if days > 7 { "monthly" } else { "shortTerm" }.to_owned(),
+        label: key.to_owned(),
+        limit_id: None,
+        limit_name: None,
+        role: None,
+        local_usage_attribution: QuotaLocalUsageAttribution::AccountWide,
+        window_seconds: Some(days * 86_400),
+        used_percent: Some(20.0),
+        reset_at: Some(now() + Duration::days(1)),
+        limit_reached: false,
+        local_usage: Some(AccountUsage {
+            account_id: "acct_forecast".to_owned(),
+            request_count: 10,
+            success_count: 10,
+            input_tokens: Some(900),
+            output_tokens: Some(100),
+            cached_tokens: Some(800),
+            cache_write_tokens: None,
+            reasoning_tokens: None,
+            image_input_tokens: None,
+            image_output_tokens: None,
+            image_request_count: 0,
+            image_request_failed_count: 0,
+            total_tokens: Some(1_000),
+            cost_coverage: CostCoverage {
+                calculated_count: 10,
+                ..Default::default()
+            },
+            costs: vec![AccountCost {
+                currency: "USD".to_owned(),
+                amount: "2".parse().unwrap(),
+            }],
+            last_used_at: Some(now()),
+            request_buckets: Vec::new(),
+            models: Vec::new(),
+        }),
+        provider_data: None,
+    }
+}
+
+fn quota(windows: Vec<ProviderQuotaWindow>) -> ProviderQuota {
+    ProviderQuota {
+        plan_type: None,
+        observed_at: Some(now()),
+        refresh_token_expires_at: None,
+        windows,
+        limit_reached: false,
+        provider_data: None,
+    }
+}
+
+fn forecast(quota: &ProviderQuota) -> [AccountQuotaForecast; 2] {
+    account_quota_forecasts(quota, now() - Duration::days(60), now(), &samples(quota))
+}
+
+fn samples(quota: &ProviderQuota) -> Vec<QuotaForecastSample> {
+    quota
+        .windows
+        .iter()
+        .filter_map(|window| {
+            let usage = window.local_usage.as_ref()?;
+            let usd = usage.costs.iter().find(|cost| cost.currency == "USD");
+            Some(QuotaForecastSample {
+                key: window.key.clone(),
+                method: QuotaForecastMethod::Cumulative,
+                start_at: window.reset_at?.checked_sub_signed(Duration::try_seconds(
+                    i64::try_from(window.window_seconds?).ok()?,
+                )?)?,
+                end_at: quota.observed_at.unwrap_or(now()),
+                baseline_percent: 0.0,
+                sampled_percent: window.used_percent.unwrap_or(0.0),
+                block_count: 0,
+                observation_count: 0,
+                pending_request_count: 0,
+                discontinuous: false,
+                usage: QuotaForecastUsage {
+                    request_count: usage.request_count,
+                    tokens: usage.total_tokens.unwrap_or(0),
+                    input_tokens: usage.input_tokens.unwrap_or(0),
+                    output_tokens: usage.output_tokens.unwrap_or(0),
+                    cached_tokens: usage.cached_tokens.unwrap_or(0),
+                    missing_token_count: u64::from(usage.total_tokens.is_none()),
+                    known_cost_count: if usd.is_some() {
+                        usage.cost_coverage.known_count()
+                    } else {
+                        0
+                    },
+                    unavailable_cost_count: usage.cost_coverage.partial_count
+                        + usage.cost_coverage.unavailable_count,
+                    usd: usd.map_or(0.0, |cost| cost.amount.as_str().parse().unwrap()),
+                    excluded_request_count: 0,
+                },
+            })
+        })
+        .collect()
+}
+
+#[test]
+fn forecasts_use_actual_periods_and_do_not_extrapolate_remaining_capacity() {
+    let [week, month] = forecast(&quota(vec![window("week", 7)]));
+    assert_eq!(week.estimated_tokens, Some(5_000));
+    assert_eq!(week.estimated_usd, Some(10.0));
+    assert_eq!(week.remaining_tokens, Some(4_000));
+    assert_eq!(week.remaining_usd, Some(8.0));
+    assert!(!week.extrapolated);
+    assert!(month.extrapolated);
+    assert_eq!(month.estimated_tokens, Some(21_429));
+    assert!((month.estimated_usd.unwrap() - 10.0 * 30.0 / 7.0).abs() < 1e-10);
+    assert_eq!(month.remaining_tokens, week.remaining_tokens);
+    assert_eq!(month.remaining_usd, week.remaining_usd);
+}
+
+#[test]
+fn corresponding_actual_window_takes_priority_and_retains_its_duration() {
+    let [week, month] = forecast(&quota(vec![window("month", 31), window("week", 7)]));
+    assert_eq!(week.source.unwrap().label, "week");
+    assert_eq!(month.source.unwrap().label, "month");
+    assert!(!month.extrapolated);
+    assert_eq!(month.target_seconds, 31 * 86_400);
+    assert_eq!(month.estimated_tokens, Some(5_000));
+    let [week, _] = forecast(&quota(vec![window("month", 31)]));
+    assert!(week.extrapolated);
+    assert_eq!(week.estimated_tokens, Some(1_129));
+}
+
+#[test]
+fn short_or_model_specific_windows_are_not_account_capacity() {
+    let mut model = window("model", 7);
+    model.local_usage_attribution = QuotaLocalUsageAttribution::Unavailable;
+    for item in forecast(&quota(vec![window("day", 1), model])) {
+        assert!(item.source.is_none());
+        assert!(item.unavailable_reason.is_some());
+        assert!(item.estimated_tokens.is_none());
+    }
+}
+
+#[test]
+fn invalid_or_tiny_percentages_cannot_produce_estimates() {
+    for percent in [
+        None,
+        Some(f64::NAN),
+        Some(f64::INFINITY),
+        Some(-1.0),
+        Some(101.0),
+        Some(0.0),
+        Some(0.5),
+        Some(1.0),
+        Some(4.9),
+    ] {
+        let mut sample = window("week", 7);
+        sample.used_percent = percent;
+        let [week, _] = forecast(&quota(vec![sample]));
+        assert!(week.unavailable_reason.is_some(), "{percent:?}");
+        assert!(week.estimated_tokens.is_none());
+        assert!(week.estimated_usd.is_none());
+    }
+}
+
+#[test]
+fn low_samples_warn_and_exhaustion_uses_raw_not_display_percentages() {
+    let mut sample = window("week", 7);
+    sample.used_percent = Some(5.0);
+    sample.limit_reached = true;
+    let mut source = quota(vec![sample]);
+    source.limit_reached = true;
+    let [week, _] = forecast(&source);
+    assert!(week.low_sample);
+    assert_eq!(week.estimated_tokens, Some(20_000));
+    source.windows[0].used_percent = Some(100.0);
+    let [week, _] = forecast(&source);
+    assert!(!week.low_sample);
+    assert_eq!(week.remaining_tokens, Some(0));
+    assert_eq!(week.remaining_usd, Some(0.0));
+}
+
+#[test]
+fn stale_future_or_missing_snapshots_do_not_predict() {
+    for observed in [
+        None,
+        Some(now() - Duration::days(8)),
+        Some(now() + Duration::seconds(1)),
+    ] {
+        let mut source = quota(vec![window("week", 7)]);
+        source.observed_at = observed;
+        assert!(forecast(&source)[0].unavailable_reason.is_some());
+    }
+    let mut sample = window("week", 7);
+    sample.reset_at = Some(now());
+    assert!(
+        forecast(&quota(vec![sample]))[0]
+            .unavailable_reason
+            .is_some()
+    );
+}
+
+#[test]
+fn partial_account_history_or_missing_usage_keep_diagnostics_without_estimates() {
+    let source = quota(vec![window("week", 7)]);
+    let [week, _] =
+        account_quota_forecasts(&source, now() - Duration::days(1), now(), &samples(&source));
+    assert!(week.unavailable_reason.unwrap().contains("记录不完整"));
+    assert!(week.estimated_tokens.is_none());
+    let mut sample = window("week", 7);
+    sample.local_usage = None;
+    let [week, _] = forecast(&quota(vec![sample]));
+    assert!(week.source.is_some());
+    assert!(
+        week.unavailable_reason
+            .unwrap()
+            .contains("没有网关用量记录")
+    );
+}
+
+#[test]
+fn incremental_sample_supports_mid_cycle_accounts_and_remaining_uses_current_percent() {
+    let source = quota(vec![window("week", 7)]);
+    let mut sample = samples(&source).remove(0);
+    sample.method = QuotaForecastMethod::Incremental;
+    sample.start_at = now() - Duration::hours(6);
+    sample.baseline_percent = 10.0;
+    sample.sampled_percent = 10.0;
+    sample.block_count = 2;
+    let [week, month] =
+        account_quota_forecasts(&source, now() - Duration::days(1), now(), &[sample]);
+    assert_eq!(week.estimated_tokens, Some(10_000));
+    assert_eq!(week.remaining_tokens, Some(8_000));
+    assert_eq!(month.remaining_tokens, Some(8_000));
+    assert!(week.unavailable_reason.is_none());
+    assert!(!week.low_sample);
+}
+
+#[test]
+fn missing_tokens_keep_estimates_from_recorded_usage() {
+    let source = quota(vec![window("week", 7)]);
+    let mut sample = samples(&source).remove(0);
+    sample.usage.missing_token_count = 1;
+    let [week, _] = account_quota_forecasts(&source, now() - Duration::days(60), now(), &[sample]);
+    assert!(week.incomplete_tokens);
+    assert!(week.unavailable_reason.is_none());
+    assert_eq!(week.estimated_tokens, Some(5_000));
+    assert_eq!(week.remaining_tokens, Some(4_000));
+    assert_eq!(week.estimated_usd, Some(10.0));
+    assert_eq!(week.source.unwrap().tokens, Some(1_000));
+}
+
+#[test]
+fn discontinuous_samples_never_fall_back_to_cumulative_predictions() {
+    let source = quota(vec![window("week", 7)]);
+    let mut sample = samples(&source).remove(0);
+    sample.discontinuous = true;
+    let [week, _] = account_quota_forecasts(&source, now() - Duration::days(60), now(), &[sample]);
+    assert!(week.unavailable_reason.unwrap().contains("不连续"));
+    assert!(week.estimated_tokens.is_none());
+}
+
+#[test]
+fn partial_costs_keep_estimates_from_known_amounts() {
+    for coverage in [
+        CostCoverage {
+            calculated_count: 9,
+            partial_count: 1,
+            ..Default::default()
+        },
+        CostCoverage {
+            calculated_count: 9,
+            unavailable_count: 1,
+            ..Default::default()
+        },
+    ] {
+        let mut sample = window("week", 7);
+        sample.local_usage.as_mut().unwrap().cost_coverage = coverage;
+        let [week, _] = forecast(&quota(vec![sample]));
+        assert!(week.incomplete_cost);
+        assert!(week.unavailable_reason.is_none());
+        assert_eq!(week.estimated_usd, Some(10.0));
+        assert_eq!(week.remaining_usd, Some(8.0));
+        assert_eq!(week.estimated_tokens, Some(5_000));
+    }
+}
+
+#[test]
+fn missing_tokens_and_costs_do_not_block_recorded_capacity_or_remaining_estimates() {
+    let source = quota(vec![window("week", 7)]);
+    let mut sample = samples(&source).remove(0);
+    // 完整请求之外混有缺少计量的成功请求，不把已有用量和费用一并作废。
+    sample.usage.request_count += 2;
+    sample.usage.missing_token_count = 2;
+    sample.usage.unavailable_cost_count = 2;
+    sample.usage.excluded_request_count = 1;
+    sample.pending_request_count = 1;
+    let [week, month] =
+        account_quota_forecasts(&source, now() - Duration::days(60), now(), &[sample]);
+    assert!(week.incomplete_tokens);
+    assert!(week.incomplete_cost);
+    assert!(week.unavailable_reason.is_none());
+    assert_eq!(week.estimated_tokens, Some(5_000));
+    assert_eq!(week.estimated_usd, Some(10.0));
+    assert_eq!(week.remaining_tokens, Some(4_000));
+    assert_eq!(week.remaining_usd, Some(8.0));
+    assert_eq!(month.estimated_tokens, Some(21_429));
+    assert_eq!(month.remaining_tokens, week.remaining_tokens);
+    assert_eq!(month.remaining_usd, week.remaining_usd);
+}
+
+#[test]
+fn entirely_unknown_costs_leave_only_money_estimates_unavailable() {
+    let mut sample = window("week", 7);
+    let usage = sample.local_usage.as_mut().unwrap();
+    usage.cost_coverage = CostCoverage {
+        unavailable_count: usage.request_count,
+        ..Default::default()
+    };
+    usage.costs.clear();
+    let [week, _] = forecast(&quota(vec![sample]));
+    assert!(week.incomplete_cost);
+    assert!(week.unavailable_reason.is_none());
+    assert_eq!(week.estimated_tokens, Some(5_000));
+    assert_eq!(week.estimated_usd, None);
+    assert_eq!(week.remaining_usd, None);
+}
+
+#[test]
+fn entirely_unknown_tokens_and_costs_do_not_invent_zero_estimates() {
+    let source = quota(vec![window("week", 7)]);
+    let mut sample = samples(&source).remove(0);
+    sample.usage = QuotaForecastUsage {
+        request_count: 2,
+        missing_token_count: 2,
+        unavailable_cost_count: 2,
+        ..Default::default()
+    };
+    let [week, _] = account_quota_forecasts(&source, now() - Duration::days(60), now(), &[sample]);
+    assert!(week.unavailable_reason.is_some());
+    assert_eq!(week.estimated_tokens, None);
+    assert_eq!(week.estimated_usd, None);
+    assert_eq!(week.remaining_tokens, None);
+    assert_eq!(week.remaining_usd, None);
+}
+
+#[test]
+fn zero_known_cost_is_valid_but_missing_usd_is_not_invented() {
+    let mut sample = window("week", 7);
+    sample.local_usage.as_mut().unwrap().costs[0].amount = "0".parse().unwrap();
+    assert_eq!(
+        forecast(&quota(vec![sample.clone()]))[0].estimated_usd,
+        Some(0.0)
+    );
+    sample.local_usage.as_mut().unwrap().costs[0].currency = "EUR".to_owned();
+    assert_eq!(forecast(&quota(vec![sample]))[0].estimated_usd, None);
+}
+
+#[test]
+fn oversized_window_or_estimate_is_unavailable_without_panics_or_saturation() {
+    let mut sample = window("month", 30);
+    sample.window_seconds = Some(i64::MAX as u64);
+    assert!(
+        forecast(&quota(vec![sample]))[1]
+            .unavailable_reason
+            .is_some()
+    );
+    let mut sample = window("week", 7);
+    sample.local_usage.as_mut().unwrap().total_tokens = Some(u64::MAX);
+    let [week, _] = forecast(&quota(vec![sample]));
+    assert!(week.estimated_tokens.is_none());
+    assert_eq!(week.estimated_usd, Some(10.0));
+}

backend/crates/gateway-admin/tests/model/quota_forecast_sampling.rs

@@ -0,0 +1,124 @@
+use chrono::{DateTime, Duration, Utc};
+use gateway_admin::model::quota_forecast_sampling::{
+    QuotaForecastMethod, QuotaForecastPoint, QuotaForecastSample, QuotaForecastUsage,
+    select_forecast_sample,
+};
+
+fn time(minutes: i64) -> DateTime<Utc> {
+    "2026-09-12T00:00:00Z".parse::<DateTime<Utc>>().unwrap() + Duration::minutes(minutes)
+}
+
+fn point(minute: i64, percent: f64, tokens: u64) -> QuotaForecastPoint {
+    QuotaForecastPoint {
+        observed_at: time(minute),
+        used_percent: percent,
+        usage: QuotaForecastUsage {
+            request_count: minute as u64,
+            tokens,
+            input_tokens: tokens,
+            known_cost_count: minute as u64,
+            usd: tokens as f64 / 1_000.0,
+            ..Default::default()
+        },
+    }
+}
+
+fn select(points: Vec<QuotaForecastPoint>, current: QuotaForecastPoint) -> QuotaForecastSample {
+    select_forecast_sample("week".to_owned(), time(0), current, points, 2)
+}
+
+#[test]
+fn repeated_readings_do_not_make_independent_blocks_or_shift_the_baseline() {
+    let points = (1..100)
+        .map(|minute| point(minute, 20.0, minute as u64 * 100))
+        .collect();
+    let sample = select(points, point(100, 25.0, 10_000));
+    assert_eq!(sample.method, QuotaForecastMethod::Incremental);
+    assert_eq!(sample.block_count, 1);
+    assert_eq!(sample.start_at, time(1));
+    assert_eq!(sample.sampled_percent, 5.0);
+    assert_eq!(sample.usage.tokens, 9_900);
+    assert_eq!(sample.pending_request_count, 2);
+}
+
+#[test]
+fn recent_blocks_and_tail_replace_old_workload_without_averaging_individual_ratios() {
+    let points = vec![
+        point(1, 0.0, 0),
+        point(2, 5.0, 100),
+        point(3, 10.0, 200),
+        point(4, 15.0, 400),
+        point(5, 20.0, 600),
+        point(6, 25.0, 800),
+    ];
+    let sample = select(points, point(7, 27.0, 900));
+    assert_eq!(sample.baseline_percent, 10.0);
+    assert_eq!(sample.sampled_percent, 17.0);
+    assert_eq!(sample.usage.tokens, 700);
+    assert_eq!(sample.block_count, 3);
+}
+
+#[test]
+fn snapshot_at_a_block_boundary_keeps_only_three_recent_blocks() {
+    let points = (0..6)
+        .map(|i| point(i + 1, i as f64 * 5.0, i as u64 * 100))
+        .collect();
+    let sample = select(points, point(7, 30.0, 600));
+    assert_eq!(sample.baseline_percent, 15.0);
+    assert_eq!(sample.sampled_percent, 15.0);
+    assert_eq!(sample.usage.tokens, 300);
+}
+
+#[test]
+fn large_percentage_reversal_restarts_sampling_without_crossing_old_consumption() {
+    let sample = select(
+        vec![point(1, 40.0, 100), point(2, 50.0, 200), point(3, 1.0, 210)],
+        point(4, 8.0, 280),
+    );
+    assert_eq!(sample.baseline_percent, 1.0);
+    assert_eq!(sample.usage.tokens, 70);
+    assert_eq!(sample.sampled_percent, 7.0);
+    assert!(!sample.discontinuous);
+    let waiting = select(
+        vec![point(1, 40.0, 100), point(2, 50.0, 200)],
+        point(3, 2.0, 210),
+    );
+    assert!(waiting.discontinuous);
+}
+
+#[test]
+fn one_point_reversal_is_skipped_without_counting_an_extra_block() {
+    let sample = select(
+        vec![
+            point(1, 10.0, 100),
+            point(2, 15.0, 200),
+            point(3, 14.0, 210),
+        ],
+        point(4, 20.0, 300),
+    );
+    assert_eq!(sample.block_count, 2);
+    assert_eq!(sample.usage.tokens, 200);
+    assert!(!sample.discontinuous);
+}
+
+#[test]
+fn missing_token_and_cost_counts_are_local_to_the_selected_interval() {
+    let mut baseline = point(1, 30.0, 1_000);
+    baseline.usage.missing_token_count = 2;
+    baseline.usage.unavailable_cost_count = 3;
+    let mut end = point(3, 40.0, 2_000);
+    end.usage.missing_token_count = 2;
+    end.usage.unavailable_cost_count = 4;
+    let sample = select(vec![baseline], end);
+    assert_eq!(sample.usage.missing_token_count, 0);
+    assert_eq!(sample.usage.unavailable_cost_count, 1);
+}
+
+#[test]
+fn counter_regressions_fail_closed_and_future_points_are_not_used() {
+    let invalid = select(vec![point(1, 10.0, 1_000)], point(2, 20.0, 500));
+    assert!(invalid.discontinuous);
+    let future = select(vec![point(10, 1.0, 1)], point(2, 20.0, 500));
+    assert_eq!(future.method, QuotaForecastMethod::Cumulative);
+    assert_eq!(future.observation_count, 0);
+}

backend/crates/gateway-admin/tests/use_case/accounts.rs

@@ -33,16 +33,18 @@ use gateway_admin::{
             AuthorizationCommit, AuthorizationCommitGuard, AuthorizationCredentialCommit,
             AuthorizationMutationTarget, AuthorizationStarted, CompleteAuthorization,
             ConsumeProviderResetCredit, CredentialCommitGuard, CredentialDetails,
-            CredentialImportCommit, CredentialImportResult, CredentialListQuery,
-            CredentialMutationResult, CredentialPage, CredentialRotationCommit,
-            PendingAuthorizationMutation, PrepareCredentialImport, PrepareCredentialRefresh,
-            PrepareCredentialRotation, PreparedAuthorizationCommit,
+            CredentialImportCommit, CredentialImportResult, CredentialMutationResult,
+            CredentialRotationCommit, PendingAuthorizationMutation, PrepareCredentialImport,
+            PrepareCredentialRefresh, PrepareCredentialRotation, PreparedAuthorizationCommit,
             PreparedAuthorizationCredential, PreparedCredentialCreate, PreparedCredentialImport,
             PreparedCredentialRotation, PreparedCredentialRotationFacts, ProviderDocument,
-            ProviderExport, ProviderExportCredentialInput, ProviderModels, ProviderQuota,
-            ProviderQuotaRequest, ProviderQuotaWindow, ProviderResetCreditResult,
+            ProviderExport, ProviderExportCredentialInput, ProviderModels,
+            ProviderProfileActivityInsights, ProviderProfileStatistics,
+            ProviderProfileStatisticsSummary, ProviderQuota, ProviderQuotaRequest,
+            ProviderQuotaWindow, ProviderResetCreditResult, ProviderSubscription,
             QuotaLocalUsageAttribution,
         },
+        quota_forecast_sampling::{QuotaForecastHistory, QuotaForecastUsage},
         settings::{
             AdminApiKey, AdminApiKeyMutation, ReplaceRuntimeSettings, RotationStrategy,
             RuntimeSettings,
@@ -71,10 +73,15 @@ pub(super) struct FakeProviderAdmin {
     export_inputs: Mutex<Vec<ProviderExportCredentialInput>>,
     import_account_ids: Mutex<Vec<String>>,
     quota_requests: Mutex<Vec<ProviderQuotaRequest>>,
+    quota_started: tokio::sync::Notify,
+    quota_gate: Mutex<Option<tokio::sync::oneshot::Receiver<()>>>,
     quota: Mutex<ProviderQuota>,
     quota_refresh_account: Mutex<Option<(Arc<FakeAccountStore>, AccountRecord)>>,
     current_credential_revision: Mutex<Revision>,
     reset_credit_commands: Mutex<Vec<ConsumeProviderResetCredit>>,
+    profile_result: Mutex<Result<ProviderProfileStatistics, ProviderAdminErrorKind>>,
+    subscription_result: Mutex<Result<Option<ProviderSubscription>, ProviderAdminErrorKind>>,
+    personal_info_barrier: Mutex<Option<Arc<tokio::sync::Barrier>>>,
 }
 
 impl FakeProviderAdmin {
@@ -89,10 +96,15 @@ impl FakeProviderAdmin {
             export_inputs: Mutex::new(Vec::new()),
             import_account_ids: Mutex::new(vec!["acct_prepared".to_owned()]),
             quota_requests: Mutex::new(Vec::new()),
+            quota_started: tokio::sync::Notify::new(),
+            quota_gate: Mutex::new(None),
             quota: Mutex::new(empty_quota()),
             quota_refresh_account: Mutex::new(None),
             current_credential_revision: Mutex::new(revision(1)),
             reset_credit_commands: Mutex::new(Vec::new()),
+            profile_result: Mutex::new(Ok(empty_profile_statistics())),
+            subscription_result: Mutex::new(Ok(None)),
+            personal_info_barrier: Mutex::new(None),
         })
     }
 
@@ -100,6 +112,14 @@ impl FakeProviderAdmin {
         *self.failure.lock().expect("provider failure") = Some(ProviderAdminError::new(kind));
     }
 
+    async fn wait_personal_info_queries(&self) {
+        let barrier = self.personal_info_barrier.lock().unwrap().clone();
+        if let Some(barrier) = barrier {
+            barrier.wait().await;
+            barrier.wait().await;
+        }
+    }
+
     fn fail_next_with_message(&self, kind: ProviderAdminErrorKind, message: &str) {
         *self.failure.lock().expect("provider failure") =
             Some(ProviderAdminError::new(kind).with_message(message));
@@ -138,6 +158,26 @@ impl FakeProviderAdmin {
             .clone()
     }
 
+    pub(super) fn pause_next_quota(&self) -> tokio::sync::oneshot::Sender<()> {
+        let (sender, receiver) = tokio::sync::oneshot::channel();
+        *self.quota_gate.lock().expect("quota gate") = Some(receiver);
+        sender
+    }
+
+    pub(super) async fn wait_for_quota_requests(&self, expected: usize) {
+        tokio::time::timeout(std::time::Duration::from_secs(5), async {
+            loop {
+                let notified = self.quota_started.notified();
+                if self.quota_requests().len() >= expected {
+                    return;
+                }
+                notified.await;
+            }
+        })
+        .await
+        .expect("quota observation started");
+    }
+
     fn reset_credit_commands(&self) -> Vec<ConsumeProviderResetCredit> {
         self.reset_credit_commands
             .lock()
@@ -213,6 +253,32 @@ impl ProviderAdmin for FakeProviderAdmin {
         &self.kind
     }
 
+    async fn profile_statistics(
+        &self,
+        _: &ProviderAccountId,
+    ) -> Result<ProviderProfileStatistics, ProviderAdminError> {
+        self.record("provider.profile_statistics");
+        self.wait_personal_info_queries().await;
+        self.profile_result
+            .lock()
+            .unwrap()
+            .clone()
+            .map_err(ProviderAdminError::new)
+    }
+
+    async fn subscription(
+        &self,
+        _: &ProviderAccountId,
+    ) -> Result<Option<ProviderSubscription>, ProviderAdminError> {
+        self.record("provider.subscription");
+        self.wait_personal_info_queries().await;
+        self.subscription_result
+            .lock()
+            .unwrap()
+            .clone()
+            .map_err(ProviderAdminError::new)
+    }
+
     fn plan_type_display(&self, plan_type: &str) -> String {
         format!("{} display: {plan_type}", self.kind)
     }
@@ -377,6 +443,11 @@ impl ProviderAdmin for FakeProviderAdmin {
             .lock()
             .expect("provider quota requests")
             .push(request);
+        self.quota_started.notify_one();
+        let gate = self.quota_gate.lock().expect("quota gate").take();
+        if let Some(gate) = gate {
+            gate.await.expect("release paused quota");
+        }
         if let Some(kind) = self
             .quota_failure
             .lock()
@@ -404,6 +475,21 @@ impl ProviderAdmin for FakeProviderAdmin {
         })
     }
 
+    fn quota_forecast_observation(
+        &self,
+        document: &ProviderDocument,
+        _: &ProviderQuotaWindow,
+    ) -> Option<gateway_admin::model::quota_forecast_sampling::QuotaForecastObservation> {
+        let fields = document.expose_to_provider().expose_to_provider();
+        Some(
+            gateway_admin::model::quota_forecast_sampling::QuotaForecastObservation {
+                used_percent: fields.get("percent")?.as_f64()?,
+                reset_at: fields.get("reset")?.as_str()?.parse().ok()?,
+                plan_type: fields.get("plan")?.as_str().map(str::to_owned),
+            },
+        )
+    }
+
     async fn models(
         &self,
         _: &ProviderAccountId,
@@ -444,6 +530,7 @@ pub(super) struct FakeAccountStore {
     import_settings: Mutex<Vec<Option<gateway_admin::model::accounts::AccountImportSettings>>>,
     quota_window_usage: Mutex<Vec<AccountUsageWindowResult>>,
     quota_window_queries: Mutex<Vec<AccountUsageWindowQuery>>,
+    quota_forecast_history: Mutex<QuotaForecastHistory>,
 }
 
 impl FakeAccountStore {
@@ -461,6 +548,7 @@ impl FakeAccountStore {
             import_settings: Mutex::new(Vec::new()),
             quota_window_usage: Mutex::new(Vec::new()),
             quota_window_queries: Mutex::new(Vec::new()),
+            quota_forecast_history: Mutex::new(QuotaForecastHistory::default()),
         })
     }
 
@@ -612,21 +700,15 @@ impl AccountStore for FakeAccountStore {
             .clone())
     }
 
-    async fn list_credentials(
+    async fn load_quota_forecast_history(
         &self,
-        provider_kind: &ProviderKind,
-        _: CredentialListQuery,
-    ) -> AdminStoreResult<CredentialPage> {
-        self.record("store.list_credentials");
-        let accounts = self.accounts.lock().expect("accounts").clone();
-        Ok(CredentialPage {
-            config_revision: revision(1),
-            items: accounts
-                .into_iter()
-                .filter(|account| &account.provider_kind == provider_kind)
-                .collect(),
-            next_cursor: None,
-        })
+        window: &AccountUsageWindowQuery,
+    ) -> AdminStoreResult<QuotaForecastHistory> {
+        self.quota_window_queries
+            .lock()
+            .unwrap()
+            .push(window.clone());
+        Ok(self.quota_forecast_history.lock().unwrap().clone())
     }
 
     async fn credential_details(
@@ -1391,7 +1473,7 @@ async fn accounts_list_should_return_complete_directory_semantics() {
         ),
         (
             Some("  self_serve_business_prolite  "),
-            Some("openai display: self_serve_business_prolite"),
+            Some("OpenaiDisplaySelfServeBusinessProlite"),
         )
     );
 
@@ -1409,16 +1491,27 @@ async fn accounts_list_should_return_complete_directory_semantics() {
 
 #[tokio::test]
 async fn accounts_should_fill_missing_plan_from_quota_without_overriding_known_subtypes() {
-    for (stored_plan, quota_plan, expected) in [
-        (None, Some("free"), Some("free")),
-        (Some("  "), Some("free"), Some("free")),
-        (Some("unknown"), Some("free"), Some("free")),
+    for (stored_plan, quota_plan, expected, expected_display) in [
+        (None, Some("free"), Some("free"), Some("OpenaiDisplayFree")),
+        (
+            Some("  "),
+            Some("free"),
+            Some("free"),
+            Some("OpenaiDisplayFree"),
+        ),
+        (
+            Some("unknown"),
+            Some("free"),
+            Some("free"),
+            Some("OpenaiDisplayFree"),
+        ),
         (
             Some("self_serve_business_prolite"),
             Some("team"),
             Some("self_serve_business_prolite"),
+            Some("OpenaiDisplaySelfServeBusinessProlite"),
         ),
-        (None, None, None),
+        (None, None, None, None),
     ] {
         let provider = FakeProviderAdmin::new("openai", events());
         provider.set_quota(ProviderQuota {
@@ -1444,10 +1537,7 @@ async fn accounts_should_fill_missing_plan_from_quota_without_overriding_known_s
             .expect("account list");
         let account = page.items.first().expect("account item");
         assert_eq!(account.account.plan_type.as_deref(), expected);
-        assert_eq!(
-            account.plan_type_display,
-            expected.map(|plan| format!("openai display: {plan}"))
-        );
+        assert_eq!(account.plan_type_display.as_deref(), expected_display);
         for refresh in [false, true] {
             let detail = services
                 .accounts()
@@ -1692,6 +1782,172 @@ async fn accounts_list_should_not_derive_exhaustion_from_provider_quota_view() {
     );
 }
 
+#[tokio::test]
+async fn quota_forecast_reads_raw_snapshot_and_limits_usage_to_observation_time() {
+    let provider = FakeProviderAdmin::new("openai", events());
+    let now = Utc::now();
+    let observed = now - TimeDelta::hours(1);
+    let reset = now + TimeDelta::days(1);
+    provider.set_quota(ProviderQuota {
+        observed_at: Some(observed),
+        limit_reached: true,
+        windows: vec![ProviderQuotaWindow {
+            key: "week".to_owned(),
+            group: "shortTerm".to_owned(),
+            label: "周额度".to_owned(),
+            limit_id: None,
+            limit_name: None,
+            role: None,
+            local_usage_attribution: QuotaLocalUsageAttribution::AccountWide,
+            window_seconds: Some(7 * 86_400),
+            used_percent: Some(20.0),
+            reset_at: Some(reset),
+            limit_reached: true,
+            // Provider 自带的统计不保证与快照同一时间，预测必须重新采样。
+            local_usage: Some(quota_local_usage("acct_test", 999_999)),
+            provider_data: None,
+        }],
+        ..empty_quota()
+    });
+    let mut account = account_record("openai");
+    account.created_at = now - TimeDelta::days(60);
+    let store = FakeAccountStore::with_account(account, events());
+    store.set_quota_window_usage(vec![AccountUsageWindowResult {
+        account_id: "acct_test".to_owned(),
+        key: "week".to_owned(),
+        usage: quota_local_usage("acct_test", 1_000),
+    }]);
+    store.quota_forecast_history.lock().unwrap().usage = QuotaForecastUsage {
+        request_count: 10,
+        tokens: 1_000,
+        known_cost_count: 10,
+        ..Default::default()
+    };
+    let report = accounts_service(provider.clone(), store.clone())
+        .await
+        .accounts()
+        .quota_forecast(&ProviderAccountId::new("acct_test").unwrap())
+        .await
+        .expect("quota forecast");
+    assert_eq!(report.account_id, "acct_test");
+    assert_eq!(report.forecasts[0].estimated_tokens, Some(5_000));
+    assert_eq!(
+        report.forecasts[0].source.as_ref().unwrap().observed_at,
+        Some(observed)
+    );
+    let queries = store.quota_window_queries();
+    assert_eq!(queries.len(), 1);
+    assert_eq!(queries[0].range.start, reset - TimeDelta::days(7));
+    assert_eq!(queries[0].range.end, observed);
+    let requests = provider.quota_requests.lock().unwrap();
+    assert_eq!(requests.len(), 1);
+    assert!(!requests[0].refresh);
+    assert!(requests[0].rolling_usage.is_none());
+}
+
+#[tokio::test]
+async fn quota_forecast_does_not_query_usage_without_a_current_snapshot() {
+    let provider = FakeProviderAdmin::new("openai", events());
+    let store = FakeAccountStore::new("openai", events());
+    let report = accounts_service(provider.clone(), store.clone())
+        .await
+        .accounts()
+        .quota_forecast(&ProviderAccountId::new("acct_test").unwrap())
+        .await
+        .expect("empty forecast");
+    assert!(
+        report
+            .forecasts
+            .iter()
+            .all(|item| item.estimated_tokens.is_none())
+    );
+    assert!(store.quota_window_queries().is_empty());
+    assert!(!provider.quota_requests.lock().unwrap()[0].refresh);
+}
+
+#[tokio::test]
+async fn quota_forecast_mid_cycle_sampling_accepts_small_reset_jitter_but_not_a_changed_bucket() {
+    use gateway_admin::model::quota_forecast_sampling::QuotaForecastHistoryPoint;
+    let now = Utc::now();
+    let observed = now - TimeDelta::minutes(1);
+    let reset = now + TimeDelta::days(1);
+    let added = now - TimeDelta::hours(5);
+    let provider = FakeProviderAdmin::new("openai", events());
+    provider.set_quota(ProviderQuota {
+        plan_type: Some("pro".to_owned()),
+        observed_at: Some(observed),
+        windows: vec![ProviderQuotaWindow {
+            key: "week".to_owned(),
+            group: "shortTerm".to_owned(),
+            label: "周额度".to_owned(),
+            limit_id: None,
+            limit_name: None,
+            role: None,
+            local_usage_attribution: QuotaLocalUsageAttribution::AccountWide,
+            window_seconds: Some(604_800),
+            used_percent: Some(40.0),
+            reset_at: Some(reset),
+            limit_reached: false,
+            local_usage: None,
+            provider_data: None,
+        }],
+        ..empty_quota()
+    });
+    let mut account = account_record("openai");
+    account.created_at = added;
+    let store = FakeAccountStore::with_account(account, events());
+    let make_point = |hours, percent, tokens, delta| {
+        QuotaForecastHistoryPoint {
+        started_at: now - TimeDelta::hours(hours) - TimeDelta::seconds(10),
+        completed_at: now - TimeDelta::hours(hours),
+        usage: QuotaForecastUsage { request_count: tokens / 100, tokens, ..Default::default() },
+        provider_observation: ProviderDocument::new(OpaqueProviderData::new(serde_json::json!({
+            "percent": percent, "reset": (reset + TimeDelta::seconds(delta)).to_rfc3339(), "plan": "pro",
+        }).as_object().unwrap().clone())),
+    }
+    };
+    *store.quota_forecast_history.lock().unwrap() = QuotaForecastHistory {
+        points: vec![
+            make_point(3, 20.0, 1_000, 1),
+            make_point(2, 30.0, 1_500, -1),
+        ],
+        usage: QuotaForecastUsage {
+            request_count: 20,
+            tokens: 2_000,
+            ..Default::default()
+        },
+        pending_request_count: 1,
+    };
+    let services = accounts_service(provider, store.clone()).await;
+    let result = services
+        .accounts()
+        .quota_forecast(&ProviderAccountId::new("acct_test").unwrap())
+        .await
+        .unwrap();
+    assert!(result.forecasts[0].unavailable_reason.is_none());
+    assert_eq!(result.forecasts[0].estimated_tokens, Some(5_000));
+    assert_eq!(result.forecasts[0].remaining_tokens, Some(3_000));
+    assert_eq!(store.quota_window_queries()[0].range.start, added);
+    store
+        .quota_forecast_history
+        .lock()
+        .unwrap()
+        .points
+        .push(make_point(1, 35.0, 1_700, 3_600));
+    let result = services
+        .accounts()
+        .quota_forecast(&ProviderAccountId::new("acct_test").unwrap())
+        .await
+        .unwrap();
+    assert!(result.forecasts[0].estimated_tokens.is_none());
+    assert!(
+        result.forecasts[0]
+            .unavailable_reason
+            .unwrap()
+            .contains("不连续")
+    );
+}
+
 #[tokio::test]
 async fn accounts_list_should_attach_local_usage_to_quota_windows() {
     let provider = FakeProviderAdmin::new("openai", events());
@@ -1746,10 +2002,8 @@ async fn accounts_list_should_attach_local_usage_to_quota_windows() {
         .as_ref()
         .expect("quota window local usage");
     assert_eq!(usage.total_tokens, Some(4_330_000));
-    assert_eq!(
-        item.usage.as_ref().and_then(|usage| usage.total_tokens),
-        Some(4_330_000),
-    );
+    // 短期额度条保留自己的本地用量，但不作为周/月统计面板的回退。
+    assert!(item.usage.is_none());
 
     let queries = store.quota_window_queries();
     assert_eq!(queries.len(), 1);
@@ -1759,6 +2013,98 @@ async fn accounts_list_should_attach_local_usage_to_quota_windows() {
     assert_eq!(queries[0].range.end, reset_at);
 }
 
+#[tokio::test]
+async fn accounts_list_and_quota_refresh_should_select_the_same_weekly_or_monthly_usage() {
+    let provider = FakeProviderAdmin::new("openai", events());
+    let store = FakeAccountStore::new("openai", events());
+    let services = accounts_service(provider.clone(), store.clone()).await;
+    let account_id = ProviderAccountId::new("acct_test").expect("account id");
+    let reset_at = Utc::now() + TimeDelta::days(1);
+    let short = ProviderQuotaWindow {
+        key: "short".to_owned(),
+        group: "shortTerm".to_owned(),
+        label: "5小时限额".to_owned(),
+        limit_id: None,
+        limit_name: None,
+        role: None,
+        local_usage_attribution: QuotaLocalUsageAttribution::AccountWide,
+        window_seconds: Some(18_000),
+        used_percent: Some(50.0),
+        reset_at: Some(reset_at),
+        limit_reached: false,
+        local_usage: None,
+        provider_data: None,
+    };
+    let week = ProviderQuotaWindow {
+        key: "week".to_owned(),
+        label: "周额度".to_owned(),
+        window_seconds: Some(7 * 86_400),
+        ..short.clone()
+    };
+    let month = ProviderQuotaWindow {
+        key: "month".to_owned(),
+        group: "monthly".to_owned(),
+        label: "月额度".to_owned(),
+        window_seconds: Some(30 * 86_400),
+        ..short.clone()
+    };
+    for (windows, selected_key, tokens, duration) in [
+        (vec![short.clone(), month.clone(), week], "week", 700, 7),
+        (vec![short, month], "month", 3000, 30),
+    ] {
+        provider.set_quota(ProviderQuota {
+            windows,
+            ..empty_quota()
+        });
+        store.set_quota_window_usage(
+            [("short", 50), ("week", 700), ("month", 3000)]
+                .into_iter()
+                .map(|(key, total)| AccountUsageWindowResult {
+                    account_id: account_id.to_string(),
+                    key: key.to_owned(),
+                    usage: quota_local_usage(account_id.as_str(), total),
+                })
+                .collect(),
+        );
+        let page = services
+            .accounts()
+            .list(AccountListQuery {
+                page: 1,
+                page_size: gateway_admin::model::PageSize::new(20).expect("page size"),
+                provider_kind: None,
+                group_filter: None,
+                search: None,
+                status: None,
+                sort: None,
+            })
+            .await
+            .expect("list accounts");
+        let refreshed = services
+            .accounts()
+            .quota(&account_id, true)
+            .await
+            .expect("refresh quota");
+        let expected = quota_local_usage(account_id.as_str(), tokens);
+        for item in [&page.items[0], &refreshed] {
+            let usage = item.usage.as_ref().expect("selected window usage");
+            assert_eq!(usage.total_tokens, expected.total_tokens);
+            assert_eq!(
+                item.quota
+                    .usage_window()
+                    .map(|(window, _)| window.key.as_str()),
+                Some(selected_key)
+            );
+        }
+        let queries = store.quota_window_queries();
+        let selected = queries
+            .iter()
+            .find(|query| query.key == selected_key)
+            .expect("selected query");
+        assert_eq!(selected.range.start, reset_at - TimeDelta::days(duration));
+        assert_eq!(selected.range.end, reset_at);
+    }
+}
+
 #[tokio::test]
 async fn accounts_list_should_not_attach_account_usage_to_model_specific_quota_windows() {
     let provider = FakeProviderAdmin::new("openai", events());
@@ -2125,6 +2471,167 @@ fn rotation_result(command: CredentialRotationCommit) -> CredentialMutationResul
     }
 }
 
+fn empty_profile_statistics() -> ProviderProfileStatistics {
+    ProviderProfileStatistics {
+        display_name: Some("Preview user".to_owned()),
+        username: None,
+        image_url: None,
+        has_stats_error: false,
+        summary: ProviderProfileStatisticsSummary {
+            total_text_tokens: Some(123),
+            peak_tokens: None,
+            longest_task_duration_ms: None,
+            current_streak_days: None,
+            longest_streak_days: None,
+        },
+        daily_usage: None,
+        activity_insights: ProviderProfileActivityInsights {
+            fast_mode_percent: None,
+            reasoning_effort: None,
+            reasoning_effort_percent: None,
+            skills_explored: None,
+            total_skills_used: None,
+            total_threads: None,
+            invocations: None,
+        },
+    }
+}
+
+fn personal_info_subscription() -> ProviderSubscription {
+    ProviderSubscription {
+        starts_at: None,
+        expires_at: Utc::now(),
+        will_renew: Some(true),
+        billing_period: Some("monthly".to_owned()),
+        billing_currency: Some("USD".to_owned()),
+        observed_at: Utc::now(),
+    }
+}
+
+#[tokio::test]
+async fn personal_info_should_query_both_parts_concurrently_once_on_every_request() {
+    let events = events();
+    let provider = FakeProviderAdmin::new("openai", events.clone());
+    let subscription = personal_info_subscription();
+    *provider.subscription_result.lock().unwrap() = Ok(Some(subscription.clone()));
+    *provider.personal_info_barrier.lock().unwrap() = Some(Arc::new(tokio::sync::Barrier::new(2)));
+    let store = FakeAccountStore::new("openai", events.clone());
+    let services = accounts_service(provider, store).await;
+    let account_id = ProviderAccountId::new("acct_test").unwrap();
+
+    for _ in 0..2 {
+        let info = tokio::time::timeout(
+            std::time::Duration::from_secs(1),
+            services.accounts().personal_info(&account_id),
+        )
+        .await
+        .expect("两项查询应并发执行")
+        .unwrap();
+        assert_eq!(info.profile.unwrap(), empty_profile_statistics());
+        assert_eq!(info.subscription, Some(subscription.clone()));
+    }
+    assert_eq!(
+        recorded(&events),
+        [
+            "store.load_account",
+            "provider.profile_statistics",
+            "provider.subscription",
+            "store.load_account",
+            "store.load_account",
+            "provider.profile_statistics",
+            "provider.subscription",
+            "store.load_account",
+        ]
+    );
+}
+
+#[tokio::test]
+async fn personal_info_should_keep_profile_when_subscription_is_missing_or_fails() {
+    for subscription in [Ok(None), Err(ProviderAdminErrorKind::Unavailable)] {
+        let provider = FakeProviderAdmin::new("openai", events());
+        *provider.subscription_result.lock().unwrap() = subscription;
+        let services = accounts_service(provider, FakeAccountStore::new("openai", events())).await;
+        let info = services
+            .accounts()
+            .personal_info(&ProviderAccountId::new("acct_test").unwrap())
+            .await
+            .unwrap();
+        assert_eq!(info.profile.unwrap(), empty_profile_statistics());
+        assert_eq!(info.subscription, None);
+    }
+}
+
+#[tokio::test]
+async fn personal_info_should_keep_subscription_when_profile_fails() {
+    let provider = FakeProviderAdmin::new("openai", events());
+    *provider.profile_result.lock().unwrap() = Err(ProviderAdminErrorKind::BadGateway);
+    let subscription = personal_info_subscription();
+    *provider.subscription_result.lock().unwrap() = Ok(Some(subscription.clone()));
+    let services = accounts_service(provider, FakeAccountStore::new("openai", events())).await;
+    let info = services
+        .accounts()
+        .personal_info(&ProviderAccountId::new("acct_test").unwrap())
+        .await
+        .unwrap();
+    assert_eq!(
+        info.profile.unwrap_err().kind(),
+        gateway_admin::model::AdminErrorKind::BadGateway
+    );
+    assert_eq!(info.subscription, Some(subscription));
+}
+
+#[tokio::test]
+async fn personal_info_should_reject_missing_account_before_querying_provider() {
+    let events = events();
+    let provider = FakeProviderAdmin::new("openai", events.clone());
+    let store = FakeAccountStore::new("openai", events.clone());
+    store.set_accounts(Vec::new());
+    let services = accounts_service(provider, store).await;
+    let error = services
+        .accounts()
+        .personal_info(&ProviderAccountId::new("acct_test").unwrap())
+        .await
+        .unwrap_err();
+    assert_eq!(error.kind(), gateway_admin::model::AdminErrorKind::NotFound);
+    assert_eq!(recorded(&events), ["store.load_account"]);
+}
+
+#[tokio::test]
+async fn personal_info_should_discard_results_when_account_changes_during_query() {
+    for change in 0..5 {
+        let provider = FakeProviderAdmin::new("openai", events());
+        let barrier = Arc::new(tokio::sync::Barrier::new(3));
+        *provider.personal_info_barrier.lock().unwrap() = Some(barrier.clone());
+        let store = FakeAccountStore::new("openai", events());
+        let services = accounts_service(provider, store.clone()).await;
+        let account_id = ProviderAccountId::new("acct_test").unwrap();
+        let mutate = async {
+            barrier.wait().await;
+            let mut accounts = store.accounts.lock().unwrap().clone();
+            match change {
+                0 => accounts[0].credential_revision = revision(99),
+                1 => accounts[0].upstream_account_id = Some("changed-account".to_owned()),
+                2 => accounts[0].upstream_user_id = Some("changed-user".to_owned()),
+                3 => accounts[0].provider_kind = ProviderKind::new("xai").unwrap(),
+                _ => accounts.clear(),
+            }
+            store.set_accounts(accounts);
+            barrier.wait().await;
+        };
+        let (result, ()) = tokio::time::timeout(std::time::Duration::from_secs(1), async {
+            tokio::join!(services.accounts().personal_info(&account_id), mutate)
+        })
+        .await
+        .unwrap();
+        let expected = if change == 4 {
+            gateway_admin::model::AdminErrorKind::NotFound
+        } else {
+            gateway_admin::model::AdminErrorKind::Conflict
+        };
+        assert_eq!(result.unwrap_err().kind(), expected);
+    }
+}
+
 async fn accounts_service(
     provider: Arc<FakeProviderAdmin>,
     store: Arc<FakeAccountStore>,

backend/crates/gateway-admin/tests/use_case/client_keys.rs

@@ -1,22 +1,31 @@
+use std::sync::{Arc, Mutex};
+
 use async_trait::async_trait;
-use gateway_core::policy::ClientApiKeyId;
+use chrono::Utc;
+use gateway_core::policy::{ClientApiKeyId, PlaintextClientApiKey, RateLimits};
 
 use gateway_admin::{
     model::{
-        AdminErrorKind, MutationContext, Revision,
+        AdminErrorKind, MutationActor, MutationContext, Revision,
         client_keys::{
             ClientKeyCursor, ClientKeyCursorValue, ClientKeyListQuery, ClientKeyPage,
             ClientKeyPageSize, ClientKeyRecord, ClientKeySecret, ClientKeySort, ClientKeySortField,
-            DeleteClientKey, NewClientKey, SetClientKeyEnabled, SortDirection, UpdateClientKey,
+            CreateClientKey, DeleteClientKey, NewClientKey, SetClientKeyEnabled, SortDirection,
+            UpdateClientKey,
         },
     },
     ports::store::{AdminStoreError, AdminStoreErrorKind, AdminStoreResult, ClientKeyStore},
 };
 
-struct UnusedClientKeyStore;
+#[derive(Default)]
+struct TestClientKeyStore {
+    plaintexts: Mutex<Vec<String>>,
+    create_error: Option<AdminStoreErrorKind>,
+    update_error: Option<AdminStoreErrorKind>,
+}
 
 #[async_trait]
-impl ClientKeyStore for UnusedClientKeyStore {
+impl ClientKeyStore for TestClientKeyStore {
     async fn list_client_keys(&self, query: ClientKeyListQuery) -> AdminStoreResult<ClientKeyPage> {
         assert_eq!(query.page_size.get(), u16::MAX);
         Ok(ClientKeyPage {
@@ -36,10 +45,32 @@ impl ClientKeyStore for UnusedClientKeyStore {
 
     async fn create_client_key(
         &self,
-        _: NewClientKey,
+        key: NewClientKey,
         _: &MutationContext,
     ) -> AdminStoreResult<(Revision, ClientKeyRecord)> {
-        Err(unused())
+        if let Some(kind) = self.create_error {
+            return Err(AdminStoreError::new(
+                kind,
+                "client key",
+                "test create failure",
+            ));
+        }
+        self.plaintexts.lock().unwrap().push(key.plaintext);
+        let record = ClientKeyRecord {
+            id: key.id,
+            name: key.name,
+            label: key.label,
+            groups: Vec::new(),
+            provider_kinds: Vec::new(),
+            prefix: String::new(),
+            enabled: true,
+            limits: key.limits,
+            budget: Default::default(),
+            last_used_at: None,
+            created_at: Utc::now(),
+            updated_at: Utc::now(),
+        };
+        Ok((Revision::new(2).unwrap(), record))
     }
 
     async fn update_client_key(
@@ -47,6 +78,13 @@ impl ClientKeyStore for UnusedClientKeyStore {
         _: UpdateClientKey,
         _: &MutationContext,
     ) -> AdminStoreResult<(Revision, ClientKeyRecord)> {
+        if let Some(kind) = self.update_error {
+            return Err(AdminStoreError::new(
+                kind,
+                "client key",
+                "test update failure",
+            ));
+        }
         Err(unused())
     }
 
@@ -70,7 +108,7 @@ impl ClientKeyStore for UnusedClientKeyStore {
 #[tokio::test]
 async fn client_key_cursor_should_reject_value_that_does_not_match_sort() {
     let services = super::AdminHarness::new()
-        .client_keys(std::sync::Arc::new(UnusedClientKeyStore))
+        .client_keys(Arc::new(TestClientKeyStore::default()))
         .build()
         .await;
     let sort = ClientKeySort {
@@ -98,7 +136,7 @@ async fn client_key_cursor_should_reject_value_that_does_not_match_sort() {
 #[tokio::test]
 async fn client_key_list_should_forward_the_full_nonzero_u16_page_size() {
     let services = super::AdminHarness::new()
-        .client_keys(std::sync::Arc::new(UnusedClientKeyStore))
+        .client_keys(Arc::new(TestClientKeyStore::default()))
         .build()
         .await;
     let page = services
@@ -118,6 +156,105 @@ async fn client_key_list_should_forward_the_full_nonzero_u16_page_size() {
     assert_eq!(page.total, 0);
 }
 
+#[tokio::test]
+async fn create_preserves_migrated_keys_and_keeps_default_generation() {
+    let store = Arc::new(TestClientKeyStore::default());
+    let services = super::AdminHarness::new()
+        .client_keys(store.clone())
+        .build()
+        .await;
+    for value in [Some("q".to_owned()), Some("legacy+/=:!".repeat(1024)), None] {
+        let created = services
+            .client_keys()
+            .create(&mutation_context(), create_command(value.as_deref()))
+            .await
+            .unwrap();
+        let plaintext = created.secret.expose_for_response();
+        assert_eq!(store.plaintexts.lock().unwrap().last().unwrap(), plaintext);
+        if let Some(value) = value {
+            assert_eq!(plaintext, value);
+        } else {
+            assert!(plaintext.starts_with("sk_"));
+            assert_eq!(plaintext.len(), 46);
+        }
+    }
+}
+
+#[tokio::test]
+async fn duplicate_keys_return_actionable_conflicts_without_disclosing_the_key() {
+    let services = super::AdminHarness::new()
+        .client_keys(Arc::new(TestClientKeyStore {
+            create_error: Some(AdminStoreErrorKind::Conflict),
+            ..Default::default()
+        }))
+        .build()
+        .await;
+    let key = "legacy-duplicate-must-stay-private";
+    let error = services
+        .client_keys()
+        .create(&mutation_context(), create_command(Some(key)))
+        .await
+        .unwrap_err();
+    assert_eq!(error.kind(), AdminErrorKind::Conflict);
+    assert_eq!(error.message(), "API Key 已存在，请使用其他密钥");
+    assert!(!format!("{error:?}").contains(key));
+}
+
+#[tokio::test]
+async fn duplicate_names_report_the_same_actionable_conflict_on_create_and_update() {
+    let services = super::AdminHarness::new()
+        .client_keys(Arc::new(TestClientKeyStore {
+            create_error: Some(AdminStoreErrorKind::DuplicateName),
+            update_error: Some(AdminStoreErrorKind::DuplicateName),
+            ..Default::default()
+        }))
+        .build()
+        .await;
+    let created = services
+        .client_keys()
+        .create(&mutation_context(), create_command(None))
+        .await
+        .unwrap_err();
+    let updated = services
+        .client_keys()
+        .update(
+            &mutation_context(),
+            UpdateClientKey {
+                id: ClientApiKeyId::new("key_existing").unwrap(),
+                name: "Migration".to_owned(),
+                label: None,
+                group_ids: Vec::new(),
+                limits: RateLimits::unlimited(),
+                daily_limit_usd: None,
+                weekly_limit_usd: None,
+            },
+        )
+        .await
+        .unwrap_err();
+    for error in [created, updated] {
+        assert_eq!(error.kind(), AdminErrorKind::Conflict);
+        assert_eq!(error.message(), "名称已存在");
+    }
+}
+
+fn create_command(key: Option<&str>) -> CreateClientKey {
+    CreateClientKey {
+        custom_key: key.map(|value| PlaintextClientApiKey::new(value).unwrap()),
+        name: "Migration".to_owned(),
+        label: None,
+        group_ids: Vec::new(),
+        limits: RateLimits::unlimited(),
+        budget: Default::default(),
+    }
+}
+
+fn mutation_context() -> MutationContext {
+    MutationContext {
+        actor: MutationActor::System,
+        request_id: "custom-key-test".to_owned(),
+    }
+}
+
 fn unused() -> AdminStoreError {
     AdminStoreError::new(
         AdminStoreErrorKind::Unavailable,

backend/crates/gateway-admin/tests/use_case/mod.rs

@@ -5,6 +5,7 @@ mod backup;
 mod client_keys;
 mod observability;
 mod openai;
+mod proxies;
 mod settings;
 mod system;
 mod xai;
@@ -44,12 +45,11 @@ use gateway_admin::{
         },
         provider_credentials::{
             AuthorizationCommit, AuthorizationStarted, CompleteAuthorization, CredentialDetails,
-            CredentialImportCommit, CredentialImportResult, CredentialListQuery,
-            CredentialMutationResult, CredentialPage, CredentialRotationCommit,
-            PendingAuthorizationMutation, PrepareCredentialImport, PrepareCredentialRefresh,
-            PrepareCredentialRotation, PreparedAuthorizationCommit, PreparedCredentialImport,
-            PreparedCredentialRotation, ProviderExport, ProviderExportCredentialInput,
-            ProviderModels, ProviderQuota,
+            CredentialImportCommit, CredentialImportResult, CredentialMutationResult,
+            CredentialRotationCommit, PendingAuthorizationMutation, PrepareCredentialImport,
+            PrepareCredentialRefresh, PrepareCredentialRotation, PreparedAuthorizationCommit,
+            PreparedCredentialImport, PreparedCredentialRotation, ProviderExport,
+            ProviderExportCredentialInput, ProviderModels, ProviderQuota,
         },
         settings::{AdminApiKey, AdminApiKeyMutation, ReplaceRuntimeSettings, RuntimeSettings},
         system::{SystemOperationAccepted, SystemUpdateDetail, SystemUpdateStatus, SystemVersion},
@@ -82,6 +82,7 @@ pub(super) struct AdminHarness {
     default_password: String,
     session_ttl_minutes: u64,
     accounts: Arc<dyn AccountStore>,
+    proxies: Arc<dyn gateway_admin::ports::proxy::ProxyStore>,
     account_runtime: Arc<dyn AccountRuntimeStore>,
     account_groups: Arc<dyn AccountGroupStore>,
     auth: Arc<dyn AuthStore>,
@@ -101,6 +102,7 @@ impl AdminHarness {
             default_password: "strong-test-password".to_owned(),
             session_ttl_minutes: 60,
             accounts: unavailable.clone(),
+            proxies: Arc::new(proxies::TestProxies::default()),
             account_runtime: unavailable.clone(),
             account_groups: Arc::new(UnavailableAccountGroupStore),
             auth: Arc::new(BootstrapAuthStore::default()),
@@ -179,6 +181,14 @@ impl AdminHarness {
         self
     }
 
+    pub(super) fn proxies(
+        mut self,
+        proxies: Arc<dyn gateway_admin::ports::proxy::ProxyStore>,
+    ) -> Self {
+        self.proxies = proxies;
+        self
+    }
+
     pub(super) fn system(mut self, system: Arc<dyn SystemOperations>) -> Self {
         self.system = system;
         self
@@ -196,6 +206,7 @@ impl AdminHarness {
                     self.accounts,
                     self.account_runtime,
                     self.account_groups,
+                    self.proxies,
                 ),
                 self.auth,
                 self.client_keys,
@@ -205,7 +216,7 @@ impl AdminHarness {
             ),
             self.providers,
             Arc::new(NoopSnapshot),
-            self.probe,
+            (self.probe, Arc::new(proxies::TestProxies::default())),
             Arc::new(NoopClientDistribution),
             self.system,
         )
@@ -360,12 +371,11 @@ impl AccountStore for UnavailableStore {
         Err(unavailable("account quota window usage"))
     }
 
-    async fn list_credentials(
+    async fn load_quota_forecast_history(
         &self,
-        _: &ProviderKind,
-        _: CredentialListQuery,
-    ) -> AdminStoreResult<CredentialPage> {
-        Err(unavailable("credentials"))
+        _: &AccountUsageWindowQuery,
+    ) -> AdminStoreResult<gateway_admin::model::quota_forecast_sampling::QuotaForecastHistory> {
+        Err(unavailable("quota forecast history"))
     }
 
     async fn credential_details(

backend/crates/gateway-admin/tests/use_case/openai.rs

@@ -50,6 +50,7 @@ async fn openai_import_should_prepare_before_atomic_store_commit() {
     services
         .openai()
         .import_document(ImportCredentials {
+            outbound_proxy_id: None,
             settings: Some(super::accounts::import_settings()),
             context: context("import-openai"),
             document: document(),
@@ -57,7 +58,7 @@ async fn openai_import_should_prepare_before_atomic_store_commit() {
         .await
         .expect("import credential");
 
-    await_quota_requests(&provider, 1).await;
+    provider.wait_for_quota_requests(1).await;
 
     assert_eq!(
         recorded(&events),
@@ -107,6 +108,7 @@ async fn openai_import_should_expose_only_explicit_public_errors_without_committ
         let error = services
             .openai()
             .import_document(ImportCredentials {
+                outbound_proxy_id: None,
                 settings: None,
                 context: context("import-openai-pat-failure"),
                 document: document(),
@@ -132,6 +134,7 @@ async fn openai_import_should_refresh_quota_for_every_imported_account() {
     let result = services
         .openai()
         .import_document(ImportCredentials {
+            outbound_proxy_id: None,
             settings: None,
             context: context("import-openai-batch"),
             document: document(),
@@ -139,7 +142,7 @@ async fn openai_import_should_refresh_quota_for_every_imported_account() {
         .await
         .expect("import credentials");
 
-    await_quota_requests(&provider, 2).await;
+    provider.wait_for_quota_requests(2).await;
 
     assert_eq!(
         result.credential_ids,
@@ -176,6 +179,7 @@ async fn openai_import_should_remain_successful_when_quota_refresh_fails() {
     let result = services
         .openai()
         .import_document(ImportCredentials {
+            outbound_proxy_id: None,
             settings: None,
             context: context("import-openai-quota-failure"),
             document: document(),
@@ -183,7 +187,7 @@ async fn openai_import_should_remain_successful_when_quota_refresh_fails() {
         .await
         .expect("committed import remains successful");
 
-    await_quota_requests(&provider, 1).await;
+    provider.wait_for_quota_requests(1).await;
 
     assert_eq!(
         result.credential_ids,
@@ -220,7 +224,7 @@ async fn openai_authorization_create_should_observe_initial_quota() {
         .await
         .expect("complete authorization");
 
-    await_quota_requests(&provider, 1).await;
+    provider.wait_for_quota_requests(1).await;
 
     assert_eq!(
         recorded(&events),
@@ -276,7 +280,7 @@ async fn openai_authorization_create_should_remain_successful_when_initial_quota
         .await
         .expect("quota observation must not fail authorization");
 
-    await_quota_requests(&provider, 1).await;
+    provider.wait_for_quota_requests(1).await;
 
     assert_eq!(result.account_id.as_str(), "acct_prepared");
     assert_eq!(provider.quota_requests().len(), 1);
@@ -318,7 +322,7 @@ async fn openai_authorization_store_failure_should_release_claim_for_retry() {
         .await
         .expect("released claim must permit retry");
 
-    await_quota_requests(&provider, 1).await;
+    provider.wait_for_quota_requests(1).await;
 
     assert_eq!(
         recorded(&events),
@@ -348,6 +352,7 @@ async fn openai_import_provider_error_should_not_touch_store_transaction() {
     services
         .openai()
         .import_document(ImportCredentials {
+            outbound_proxy_id: None,
             settings: None,
             context: context("import-openai-error"),
             document: document(),
@@ -401,7 +406,7 @@ async fn openai_reauthorization_should_commit_after_credential_revision_advances
         .await
         .expect("complete reauthorization");
 
-    await_quota_requests(&provider, 1).await;
+    provider.wait_for_quota_requests(1).await;
 
     assert_eq!(result.credential_revision, Some(revision(3)));
 
@@ -429,16 +434,6 @@ async fn service(provider: Arc<FakeProviderAdmin>, store: Arc<FakeAccountStore>)
         .await
 }
 
-async fn await_quota_requests(provider: &FakeProviderAdmin, expected: usize) {
-    for _ in 0..100 {
-        if provider.quota_requests().len() == expected {
-            return;
-        }
-        tokio::task::yield_now().await;
-    }
-    assert_eq!(provider.quota_requests().len(), expected);
-}
-
 fn deletion(account_id: &str) -> CredentialDeletion {
     CredentialDeletion {
         context: context("request-openai"),

backend/crates/gateway-admin/tests/use_case/proxies.rs

@@ -0,0 +1,227 @@
+use async_trait::async_trait;
+use gateway_admin::{
+    model::{MutationContext, Revision, proxies::*},
+    ports::{
+        proxy::{ProxyProbe, ProxyStore},
+        store::AdminStoreResult,
+    },
+};
+use gateway_core::account::{OutboundProxy, ProviderAccountId};
+
+#[derive(Default)]
+pub(super) struct TestProxies {
+    pub events: Option<super::accounts::EventLog>,
+    pub accounts: Option<Vec<ProxyAccountRef>>,
+}
+
+struct ImportGuard(super::accounts::EventLog);
+
+impl gateway_admin::ports::proxy::ProxyImportGuard for ImportGuard {}
+
+impl Drop for ImportGuard {
+    fn drop(&mut self) {
+        self.0.lock().unwrap().push("proxy.release");
+    }
+}
+
+#[async_trait]
+impl ProxyStore for TestProxies {
+    async fn remove_account(
+        &self,
+        _: &str,
+        _: &ProviderAccountId,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(super::unavailable("proxy"))
+    }
+
+    async fn reserve_import(
+        &self,
+        id: &str,
+    ) -> AdminStoreResult<gateway_admin::ports::proxy::ProxyImportReservation> {
+        let events = self
+            .events
+            .as_ref()
+            .ok_or_else(|| super::unavailable("proxy"))?;
+        events.lock().unwrap().push("proxy.reserve");
+        Ok(gateway_admin::ports::proxy::ProxyImportReservation {
+            binding: ImportProxyBinding {
+                id: id.to_owned(),
+                proxy: OutboundProxy::parse("http://127.0.0.1:8080").unwrap(),
+            },
+            guard: Box::new(ImportGuard(events.clone())),
+        })
+    }
+    async fn list(&self, _: ProxyListQuery) -> AdminStoreResult<ProxyPage> {
+        Err(super::unavailable("proxy"))
+    }
+    async fn list_accounts(
+        &self,
+        query: ProxyAccountListQuery,
+    ) -> AdminStoreResult<ProxyAccountPage> {
+        let items = self
+            .accounts
+            .clone()
+            .ok_or_else(|| super::unavailable("proxy"))?;
+        Ok(ProxyAccountPage {
+            total: items.len() as u64,
+            items,
+            page: query.page,
+            page_size: query.page_size.get(),
+        })
+    }
+    async fn get(&self, _: &str) -> AdminStoreResult<ProxyRecord> {
+        Err(super::unavailable("proxy"))
+    }
+    async fn create(&self, _: NewProxy, _: &MutationContext) -> AdminStoreResult<ProxyMutation> {
+        Err(super::unavailable("proxy"))
+    }
+    async fn update(&self, _: UpdateProxy, _: &MutationContext) -> AdminStoreResult<ProxyMutation> {
+        Err(super::unavailable("proxy"))
+    }
+    async fn delete(
+        &self,
+        _: &str,
+        _: Revision,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(super::unavailable("proxy"))
+    }
+    async fn record_test(
+        &self,
+        _: &str,
+        _: Revision,
+        _: ProxyTestResult,
+        _: &MutationContext,
+    ) -> AdminStoreResult<ProxyRecord> {
+        Err(super::unavailable("proxy"))
+    }
+}
+
+#[async_trait]
+impl ProxyProbe for TestProxies {
+    async fn test(&self, _: &OutboundProxy) -> ProxyTestResult {
+        panic!("unexpected proxy probe")
+    }
+}
+
+#[tokio::test]
+async fn linked_accounts_share_plan_resolution_and_only_read_cached_quota() {
+    use super::accounts::{FakeProviderAdmin, events};
+    use gateway_admin::model::{PageSize, provider_credentials::ProviderQuota};
+    use std::sync::Arc;
+
+    for (stored, cached, expected) in [
+        (None, Some("free"), Some("free")),
+        (Some("unknown"), Some("free"), Some("free")),
+        (Some("plus"), Some("free"), Some("plus")),
+        (None, None, None),
+    ] {
+        let provider = FakeProviderAdmin::new("openai", events());
+        provider.set_quota(ProviderQuota {
+            plan_type: cached.map(str::to_owned),
+            observed_at: None,
+            refresh_token_expires_at: None,
+            windows: vec![],
+            limit_reached: false,
+            provider_data: None,
+        });
+        let services = super::AdminHarness::new()
+            .provider(provider.clone())
+            .proxies(Arc::new(TestProxies {
+                accounts: Some(vec![ProxyAccountRef {
+                    id: "acct_plan".to_owned(),
+                    name: "套餐测试".to_owned(),
+                    email: None,
+                    provider_kind: "openai".to_owned(),
+                    authentication_kind: "oauth".to_owned(),
+                    plan_type: stored.map(str::to_owned),
+                    plan_type_display: None,
+                    groups: vec![],
+                    enabled: true,
+                }]),
+                ..Default::default()
+            }))
+            .build()
+            .await;
+        let result = services
+            .proxies()
+            .list_accounts(ProxyAccountListQuery {
+                proxy_id: "proxy_plan".to_owned(),
+                page: 1,
+                page_size: PageSize::new(20).unwrap(),
+                search: String::new(),
+            })
+            .await
+            .unwrap();
+        assert_eq!(result.items[0].plan_type.as_deref(), expected);
+        assert_eq!(
+            result.items[0].plan_type_display.as_deref(),
+            match expected {
+                Some("free") => Some("OpenaiDisplayFree"),
+                Some("plus") => Some("OpenaiDisplayPlus"),
+                _ => None,
+            }
+        );
+        let requests = provider.quota_requests();
+        assert_eq!(requests.len(), usize::from(stored != Some("plus")));
+        assert!(requests.iter().all(|request| !request.refresh));
+    }
+}
+
+#[tokio::test]
+async fn credential_import_keeps_proxy_reserved_until_commit_and_releases_on_errors() {
+    use super::accounts::{
+        FakeAccountStore, FakeProviderAdmin, context, document, events, recorded,
+    };
+    use gateway_admin::model::provider_credentials::ImportCredentials;
+    use gateway_admin::ports::provider::ProviderAdminErrorKind;
+    use std::sync::Arc;
+
+    for kind in ["openai", "xai"] {
+        for failure in [None, Some("prepare"), Some("commit")] {
+            let events = events();
+            let provider = FakeProviderAdmin::new(kind, events.clone());
+            let store = FakeAccountStore::new(kind, events.clone());
+            if failure == Some("prepare") {
+                provider.fail_next(ProviderAdminErrorKind::Unavailable);
+            }
+            if failure == Some("commit") {
+                store.fail_next_commit();
+            }
+            let services = super::AdminHarness::new()
+                .provider(provider)
+                .accounts(store)
+                .proxies(Arc::new(TestProxies {
+                    events: Some(events.clone()),
+                    ..Default::default()
+                }))
+                .build()
+                .await;
+            let command = ImportCredentials {
+                outbound_proxy_id: Some("proxy_import".to_owned()),
+                settings: None,
+                context: context("reserved-import"),
+                document: document(),
+            };
+            let result = if kind == "openai" {
+                services.openai().import_document(command).await
+            } else {
+                services.xai().import_document(command).await
+            };
+            assert_eq!(result.is_err(), failure.is_some());
+            let events = recorded(&events);
+            let expected = if failure == Some("prepare") {
+                vec!["proxy.reserve", "provider.prepare_import", "proxy.release"]
+            } else {
+                vec![
+                    "proxy.reserve",
+                    "provider.prepare_import",
+                    "store.commit_import",
+                    "proxy.release",
+                ]
+            };
+            assert_eq!(&events[..expected.len()], expected);
+        }
+    }
+}

backend/crates/gateway-admin/tests/use_case/xai.rs

@@ -4,7 +4,9 @@ use gateway_core::account::ProviderAccountId;
 
 use gateway_admin::{
     AdminServices,
-    model::provider_credentials::{ImportCredentials, ProviderQuotaRequest},
+    model::provider_credentials::{
+        CompleteAuthorization, ImportCredentials, ProviderQuotaRequest, StartAuthorization,
+    },
     ports::provider::ProviderAdminErrorKind,
 };
 
@@ -20,6 +22,7 @@ async fn xai_import_should_prepare_before_atomic_store_commit() {
     services
         .xai()
         .import_document(ImportCredentials {
+            outbound_proxy_id: None,
             settings: Some(super::accounts::import_settings()),
             context: context("import-xai"),
             document: document(),
@@ -27,11 +30,13 @@ async fn xai_import_should_prepare_before_atomic_store_commit() {
         .await
         .expect("import xAI credential");
 
+    provider.wait_for_quota_requests(1).await;
     assert_eq!(
         recorded(&events),
         [
             "provider.prepare_import",
             "store.commit_import",
+            "provider.account_facts_changed",
             "provider.quota"
         ]
     );
@@ -61,6 +66,7 @@ async fn xai_import_should_refresh_quota_for_every_imported_account() {
     services
         .xai()
         .import_document(ImportCredentials {
+            outbound_proxy_id: None,
             settings: None,
             context: context("import-xai-batch"),
             document: document(),
@@ -68,6 +74,7 @@ async fn xai_import_should_refresh_quota_for_every_imported_account() {
         .await
         .expect("import credentials");
 
+    provider.wait_for_quota_requests(2).await;
     assert_eq!(
         provider.quota_requests(),
         [
@@ -96,6 +103,7 @@ async fn xai_import_should_remain_successful_when_quota_refresh_fails() {
     let result = services
         .xai()
         .import_document(ImportCredentials {
+            outbound_proxy_id: None,
             settings: None,
             context: context("import-xai-quota-failure"),
             document: document(),
@@ -103,10 +111,120 @@ async fn xai_import_should_remain_successful_when_quota_refresh_fails() {
         .await
         .expect("committed import remains successful");
 
+    provider.wait_for_quota_requests(1).await;
     assert_eq!(result.credential_ids.len(), 1);
     assert_eq!(provider.quota_requests().len(), 1);
 }
 
+#[tokio::test]
+async fn xai_authorization_should_observe_quota_without_affecting_commit() {
+    for quota_failure in [None, Some(ProviderAdminErrorKind::Unavailable)] {
+        let events = events();
+        let provider = FakeProviderAdmin::new("xai", events.clone());
+        if let Some(kind) = quota_failure {
+            provider.fail_next_quota(kind);
+        }
+        let store = FakeAccountStore::new("xai", events.clone());
+        let services = service(provider.clone(), store.clone()).await;
+        services
+            .xai()
+            .start_authorization(StartAuthorization {
+                outbound_proxy: None,
+                context: context("oauth-xai-create"),
+                name: "new xAI credential".to_owned(),
+                reauthorization: None,
+            })
+            .await
+            .expect("start authorization");
+        let result = services
+            .xai()
+            .complete_authorization(CompleteAuthorization {
+                settings: None,
+                context: context("oauth-xai-create"),
+                flow_id: "flow-test".to_owned(),
+                callback_url: "http://localhost/callback?code=test&state=test".to_owned(),
+            })
+            .await
+            .expect("quota observation must not fail authorization");
+
+        provider.wait_for_quota_requests(1).await;
+        assert_eq!(
+            recorded(&events),
+            [
+                "provider.start_authorization",
+                "provider.complete_authorization",
+                "store.commit_authorization",
+                "provider.account_facts_changed",
+                "provider.quota",
+            ]
+        );
+        assert_eq!(
+            provider.quota_requests(),
+            [ProviderQuotaRequest {
+                account_id: result.account_id,
+                refresh: true,
+                rolling_usage: None,
+            }]
+        );
+        assert_eq!(store.audit_requests(), ["oauth-xai-create"]);
+    }
+}
+
+#[tokio::test]
+async fn credential_import_should_return_while_initial_quota_is_pending() {
+    for kind in ["openai", "xai"] {
+        let events = events();
+        let provider = FakeProviderAdmin::new(kind, events.clone());
+        let quota_release = provider.pause_next_quota();
+        let store = FakeAccountStore::new(kind, events);
+        let services = service(provider.clone(), store).await;
+        let command = ImportCredentials {
+            outbound_proxy_id: None,
+            settings: None,
+            context: context("import-slow-quota"),
+            document: document(),
+        };
+        let result = tokio::time::timeout(std::time::Duration::from_secs(5), async {
+            match kind {
+                "openai" => services.openai().import_document(command).await,
+                _ => services.xai().import_document(command).await,
+            }
+        })
+        .await
+        .expect("committed import must not wait for quota")
+        .expect("import credentials");
+        provider.wait_for_quota_requests(1).await;
+        assert_eq!(result.credential_ids.len(), 1);
+        quota_release.send(()).expect("finish quota observation");
+    }
+}
+
+#[tokio::test]
+async fn xai_import_store_failure_should_not_observe_quota_or_invalidate_provider_facts() {
+    let events = events();
+    let provider = FakeProviderAdmin::new("xai", events.clone());
+    let store = FakeAccountStore::new("xai", events.clone());
+    store.fail_next_commit();
+    let services = service(provider.clone(), store).await;
+
+    services
+        .xai()
+        .import_document(ImportCredentials {
+            outbound_proxy_id: None,
+            settings: None,
+            context: context("import-xai-store-failure"),
+            document: document(),
+        })
+        .await
+        .expect_err("store commit fails");
+
+    assert_eq!(
+        recorded(&events),
+        ["provider.prepare_import", "store.commit_import"]
+    );
+    assert!(provider.quota_requests().is_empty());
+}
+
 async fn service(provider: Arc<FakeProviderAdmin>, store: Arc<FakeAccountStore>) -> AdminServices {
     super::AdminHarness::new()
         .provider(provider)

backend/crates/gateway-api/Cargo.toml

@@ -16,6 +16,7 @@ axum = { version = "0.8.9", default-features = false, features = ["json", "query
 base64 = "0.23.0"
 bytes = "1.11.1"
 chrono = { version = "0.4.45", features = ["serde"] }
+flate2 = "1.1.9"
 futures = "0.3.32"
 gateway-admin = { path = "../gateway-admin" }
 gateway-core = { path = "../gateway-core" }
@@ -29,6 +30,7 @@ tower-http = { version = "0.7.0", features = ["cors", "fs", "request-id", "timeo
 tracing = "0.1.44"
 url = "2.5.8"
 uuid = { version = "1.23.3", features = ["v7"] }
+zstd = "=0.13.3"
 
 [dev-dependencies]
 async-trait = "0.1.89"

backend/crates/gateway-api/src/admin/accounts/credentials.rs

@@ -53,6 +53,7 @@ impl AccountImportSettingsRequest {
 #[derive(Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct AccountImportRequest {
+    pub outbound_proxy_id: Option<String>,
     pub settings: Option<AccountImportSettingsRequest>,
     pub provider: String,
     pub data: Value,
@@ -60,6 +61,9 @@ pub struct AccountImportRequest {
 
 impl AccountImportRequest {
     pub fn validate(&self) -> Result<(), WireValidationError> {
+        if let Some(id) = &self.outbound_proxy_id {
+            require_wire_id(id, "outboundProxyId")?;
+        }
         if let Some(settings) = &self.settings {
             settings.validate()?;
         }
@@ -82,6 +86,7 @@ impl AccountImportRequest {
         Ok((
             provider,
             ImportCredentials {
+                outbound_proxy_id: self.outbound_proxy_id,
                 settings: self
                     .settings
                     .map(AccountImportSettingsRequest::into_settings)
@@ -96,6 +101,7 @@ impl AccountImportRequest {
 #[derive(Debug, Clone, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct StartAccountAuthorizationRequest {
+    pub outbound_proxy_id: Option<String>,
     pub provider: String,
     pub name: String,
     pub account_id: Option<String>,
@@ -129,7 +135,10 @@ impl StartAccountAuthorizationRequest {
                 context,
                 name: self.name,
                 reauthorization,
-                outbound_proxy: self.outbound_proxy_url.and_then(|value| value.0),
+                outbound_proxy: super::wire::proxy_selection(
+                    self.outbound_proxy_id,
+                    self.outbound_proxy_url,
+                )?,
             },
         ))
     }
@@ -188,6 +197,7 @@ impl CompleteAccountAuthorizationRequest {
 #[derive(Debug, Clone, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct UpdateAccountRequest {
+    pub outbound_proxy_id: Option<String>,
     pub outbound_proxy_url: Option<super::wire::AccountProxyUpdate>,
     pub account_id: String,
     pub enabled: bool,
@@ -209,7 +219,10 @@ impl UpdateAccountRequest {
     pub(super) fn into_command(self) -> Result<UpdateAccount, WireValidationError> {
         self.validate()?;
         Ok(UpdateAccount {
-            outbound_proxy: self.outbound_proxy_url.map(|value| value.0),
+            outbound_proxy: super::wire::proxy_selection(
+                self.outbound_proxy_id,
+                self.outbound_proxy_url,
+            )?,
             account_id: self.account_id,
             enabled: self.enabled,
             concurrency_limit: parse_concurrency_limit(self.concurrency_limit)?,

backend/crates/gateway-api/src/admin/accounts/handlers.rs

@@ -23,8 +23,12 @@ where
         )
         .route("/api/admin/accounts/quota", get(account_quota::<S>))
         .route(
-            "/api/admin/accounts/profile-statistics",
-            get(account_profile_statistics::<S>),
+            "/api/admin/accounts/personal-info",
+            get(account_personal_info::<S>),
+        )
+        .route(
+            "/api/admin/accounts/quota-forecast",
+            get(account_quota_forecast::<S>),
         )
         .route(
             "/api/admin/accounts/profile-avatar",
@@ -364,7 +368,7 @@ where
     Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(data)))
 }
 
-async fn account_profile_statistics<S>(
+async fn account_quota_forecast<S>(
     _auth: AdminAuth,
     State(state): State<S>,
     AdminQuery(query): AdminQuery<AccountIdQuery>,
@@ -376,12 +380,33 @@ where
     let result = state
         .admin_services()
         .accounts()
-        .profile_statistics(&account_id)
+        .quota_forecast(&account_id)
         .await
         .map_err(map_service_error)?;
     Ok(AdminResponse::new(
         StatusCode::OK,
-        AdminEnvelope::ok(AccountProfileStatisticsData::from(result)),
+        AdminEnvelope::ok(AccountQuotaForecastData::from(result)),
+    ))
+}
+
+async fn account_personal_info<S>(
+    _auth: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<AccountIdQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let account_id = query.into_id().map_err(map_wire_error)?;
+    let result = state
+        .admin_services()
+        .accounts()
+        .personal_info(&account_id)
+        .await
+        .map_err(map_service_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(AccountPersonalInfoData::from(result)),
     ))
 }
 

backend/crates/gateway-api/src/admin/accounts/mod.rs

@@ -25,14 +25,15 @@ use gateway_admin::model::{
         AccountWeight, AccountsUpdateResult, BatchUpdateAccounts, SortDirection, UpdateAccount,
     },
     provider_credentials::{
-        AccountDirectoryItem, AccountDirectoryPage, AccountExportBundle, AccountRefreshResult,
-        AuthorizationStarted, CompleteAuthorization, ConsumeProviderResetCredit,
-        CredentialDeletion, CredentialDeletionResult, CredentialImportResult, CredentialMutation,
-        CredentialMutationResult, ImportCredentials, ProviderDocument, ProviderModels,
-        ProviderProfileActivityInsights, ProviderProfileAvatar, ProviderProfileDailyUsage,
-        ProviderProfileInvocation, ProviderProfileStatistics, ProviderProfileStatisticsSummary,
-        ProviderQuota, ProviderQuotaWindow, ProviderResetCredit, ProviderResetCreditResult,
-        ProviderResetCredits, RotateCredential, StartAuthorization,
+        AccountDirectoryItem, AccountDirectoryPage, AccountExportBundle, AccountPersonalInfo,
+        AccountRefreshResult, AccountUsagePeriod, AuthorizationStarted, CompleteAuthorization,
+        ConsumeProviderResetCredit, CredentialDeletion, CredentialDeletionResult,
+        CredentialImportResult, CredentialMutation, CredentialMutationResult, ImportCredentials,
+        ProviderDocument, ProviderModels, ProviderProfileActivityInsights, ProviderProfileAvatar,
+        ProviderProfileDailyUsage, ProviderProfileInvocation, ProviderProfileStatistics,
+        ProviderProfileStatisticsSummary, ProviderQuota, ProviderQuotaWindow, ProviderResetCredit,
+        ProviderResetCreditResult, ProviderResetCredits, ProviderSubscription, RotateCredential,
+        StartAuthorization,
     },
 };
 use gateway_core::{

backend/crates/gateway-api/src/admin/accounts/presenter.rs

@@ -1,6 +1,7 @@
 //! Admin 领域结果到安全 HTTP wire 的展示投影。
 
 use super::*;
+use gateway_admin::model::quota_forecast::{AccountQuotaForecast, AccountQuotaForecastReport};
 
 pub(super) fn account_page_data(
     result: AccountDirectoryPage,
@@ -69,6 +70,7 @@ pub(super) fn account_view(item: AccountDirectoryItem, now: DateTime<Utc>) -> Ac
     let expires_at = account.access_token_expires_at.as_ref().map(china_rfc3339);
     let added_at = china_rfc3339(&account.created_at);
     let updated_at = china_rfc3339(&account.updated_at);
+    let usage_period = quota.usage_window().map(|(_, period)| period);
     let (quota, refresh_token_expires_at) = account_quota_view(quota, rate_limited_until, now);
     AccountView {
         id: account.id.clone(),
@@ -117,10 +119,68 @@ pub(super) fn account_view(item: AccountDirectoryItem, now: DateTime<Utc>) -> Ac
         updated_at,
         updated_at_display: china_datetime(&account.updated_at),
         quota,
-        usage: account_usage_view(usage, now),
+        usage: account_usage_view(usage, usage_period, now),
     }
 }
 
+impl From<AccountQuotaForecastReport> for AccountQuotaForecastData {
+    fn from(report: AccountQuotaForecastReport) -> Self {
+        Self {
+            account_id: report.account_id,
+            generated_at: china_rfc3339(&report.generated_at),
+            forecasts: report
+                .forecasts
+                .into_iter()
+                .map(quota_forecast_view)
+                .collect(),
+        }
+    }
+}
+
+fn quota_forecast_view(forecast: AccountQuotaForecast) -> AccountQuotaForecastView {
+    AccountQuotaForecastView {
+        period: match forecast.period {
+            AccountUsagePeriod::Weekly => "weekly",
+            AccountUsagePeriod::Monthly => "monthly",
+        },
+        target_days: forecast.target_seconds as f64 / 86_400.0,
+        extrapolated: forecast.extrapolated,
+        source: forecast.source.map(|source| QuotaForecastSourceView {
+            label: source.label,
+            used_percent: source.used_percent,
+            used_percent_display: source
+                .used_percent
+                .map_or_else(|| "—".to_owned(), |value| format!("{value:.1}%")),
+            observed_at: source.observed_at.map(|value| china_rfc3339(&value)),
+            observed_at_display: source
+                .observed_at
+                .map_or_else(|| "—".to_owned(), |value| china_datetime(&value)),
+            reset_at: china_rfc3339(&source.reset_at),
+            tokens_display: display_optional_tokens(source.tokens),
+            usd_display: forecast_usd_display(source.usd),
+        }),
+        unavailable_reason: forecast.unavailable_reason,
+        low_sample: forecast.low_sample,
+        incomplete_cost: forecast.incomplete_cost,
+        incomplete_tokens: forecast.incomplete_tokens,
+        estimated_tokens: forecast.estimated_tokens,
+        estimated_tokens_display: display_optional_tokens(forecast.estimated_tokens),
+        estimated_usd: forecast.estimated_usd,
+        estimated_usd_display: forecast_usd_display(forecast.estimated_usd),
+        remaining_tokens: forecast.remaining_tokens,
+        remaining_tokens_display: display_optional_tokens(forecast.remaining_tokens),
+        remaining_usd: forecast.remaining_usd,
+        remaining_usd_display: forecast_usd_display(forecast.remaining_usd),
+    }
+}
+
+fn forecast_usd_display(value: Option<f64>) -> String {
+    value.map_or_else(
+        || "—".to_owned(),
+        |value| format_decimal_currency(&format!("{value:.10}"), "USD"),
+    )
+}
+
 pub(super) fn account_quota_view(
     mut quota: ProviderQuota,
     rate_limited_until: Option<DateTime<Utc>>,
@@ -211,6 +271,7 @@ pub(super) fn quota_local_usage(usage: &AccountUsage) -> Value {
 
 pub(super) fn account_usage_view(
     usage: Option<AccountUsage>,
+    period: Option<AccountUsagePeriod>,
     now: DateTime<Utc>,
 ) -> AccountUsageView {
     let Some(usage) = usage else {
@@ -228,6 +289,12 @@ pub(super) fn account_usage_view(
         "known"
     };
     AccountUsageView {
+        window_label_display: match period {
+            Some(AccountUsagePeriod::Weekly) => "周额度窗口",
+            Some(AccountUsagePeriod::Monthly) => "月额度窗口",
+            None => "周/月额度窗口",
+        }
+        .to_owned(),
         request_count: Some(usage.request_count),
         request_count_display: format_number(usage.request_count),
         input_tokens: usage.input_tokens,
@@ -347,6 +414,7 @@ pub(super) fn display_optional_tokens(value: Option<u64>) -> String {
 
 pub(super) fn empty_account_usage() -> AccountUsageView {
     AccountUsageView {
+        window_label_display: "周/月额度窗口".to_owned(),
         request_count: None,
         request_count_display: "—".to_owned(),
         input_tokens: None,

backend/crates/gateway-api/src/admin/accounts/wire.rs

@@ -17,6 +17,33 @@ impl<'de> Deserialize<'de> for AccountProxyUpdate {
     }
 }
 
+pub(super) fn proxy_selection(
+    id: Option<String>,
+    url: Option<AccountProxyUpdate>,
+) -> Result<Option<gateway_admin::model::proxies::AccountProxySelection>, WireValidationError> {
+    use gateway_admin::model::proxies::AccountProxySelection;
+    match (id, url) {
+        (Some(_), Some(_)) => Err(WireValidationError::new("outboundProxyId")),
+        (Some(id), None) if id.is_empty() => Ok(Some(AccountProxySelection::Direct)),
+        (Some(id), None) => {
+            if id.len() > 128
+                || !id
+                    .bytes()
+                    .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'-'))
+            {
+                return Err(WireValidationError::new("outboundProxyId"));
+            }
+            Ok(Some(AccountProxySelection::Saved(id)))
+        }
+        (None, Some(value)) => Ok(Some(
+            value
+                .0
+                .map_or(AccountProxySelection::Direct, AccountProxySelection::Url),
+        )),
+        (None, None) => Ok(None),
+    }
+}
+
 /// 账号列表查询参数。
 #[derive(Debug, Clone, Default, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
@@ -34,6 +61,7 @@ pub struct ListQuery {
 #[derive(Debug, Clone, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct BatchUpdateAccountsRequest {
+    pub outbound_proxy_id: Option<String>,
     pub outbound_proxy_url: Option<AccountProxyUpdate>,
     pub account_ids: Vec<String>,
     pub enabled: bool,
@@ -84,7 +112,7 @@ impl BatchUpdateAccountsRequest {
     pub(super) fn into_command(self) -> Result<BatchUpdateAccounts, WireValidationError> {
         self.validate()?;
         Ok(BatchUpdateAccounts {
-            outbound_proxy: self.outbound_proxy_url.map(|value| value.0),
+            outbound_proxy: proxy_selection(self.outbound_proxy_id, self.outbound_proxy_url)?,
             account_ids: self.account_ids,
             enabled: self.enabled,
             concurrency_limit: parse_concurrency_limit(self.concurrency_limit)?,
@@ -244,6 +272,49 @@ pub struct AccountView {
     pub usage: AccountUsageView,
 }
 
+/// 容量估算仅供管理端展示；金额不是订阅账单或可消费余额。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountQuotaForecastData {
+    pub account_id: String,
+    pub generated_at: String,
+    pub forecasts: Vec<AccountQuotaForecastView>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountQuotaForecastView {
+    pub period: &'static str,
+    pub target_days: f64,
+    pub extrapolated: bool,
+    pub source: Option<QuotaForecastSourceView>,
+    pub unavailable_reason: Option<&'static str>,
+    pub low_sample: bool,
+    pub incomplete_cost: bool,
+    pub incomplete_tokens: bool,
+    pub estimated_tokens: Option<u64>,
+    pub estimated_tokens_display: String,
+    pub estimated_usd: Option<f64>,
+    pub estimated_usd_display: String,
+    pub remaining_tokens: Option<u64>,
+    pub remaining_tokens_display: String,
+    pub remaining_usd: Option<f64>,
+    pub remaining_usd_display: String,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct QuotaForecastSourceView {
+    pub label: String,
+    pub used_percent: Option<f64>,
+    pub used_percent_display: String,
+    pub observed_at: Option<String>,
+    pub observed_at_display: String,
+    pub reset_at: String,
+    pub tokens_display: String,
+    pub usd_display: String,
+}
+
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct AccountGroupRefView {
@@ -288,6 +359,7 @@ pub struct AccountQuotaWindowView {
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct AccountUsageView {
+    pub window_label_display: String,
     pub request_count: Option<u64>,
     pub request_count_display: String,
     pub input_tokens: Option<u64>,
@@ -581,6 +653,54 @@ pub struct AccountQuotaData {
     pub account: AccountView,
 }
 
+/// 个人资料、累计统计与订阅的统一响应。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountPersonalInfoData {
+    pub profile: Option<AccountProfileStatisticsData>,
+    pub profile_error: Option<String>,
+    pub subscription: Option<AccountSubscriptionData>,
+}
+
+impl From<AccountPersonalInfo> for AccountPersonalInfoData {
+    fn from(info: AccountPersonalInfo) -> Self {
+        let (profile, profile_error) = match info.profile {
+            Ok(profile) => (Some(AccountProfileStatisticsData::from(profile)), None),
+            Err(error) => (None, Some(error.message().to_owned())),
+        };
+        Self {
+            profile,
+            profile_error,
+            subscription: info.subscription.map(AccountSubscriptionData::from),
+        }
+    }
+}
+
+/// 按需读取的订阅安全字段，不暴露原始上游响应。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccountSubscriptionData {
+    pub starts_at: Option<String>,
+    pub expires_at: String,
+    pub will_renew: Option<bool>,
+    pub billing_period: Option<String>,
+    pub billing_currency: Option<String>,
+    pub observed_at: String,
+}
+
+impl From<ProviderSubscription> for AccountSubscriptionData {
+    fn from(subscription: ProviderSubscription) -> Self {
+        Self {
+            starts_at: subscription.starts_at.map(|value| value.to_rfc3339()),
+            expires_at: subscription.expires_at.to_rfc3339(),
+            will_renew: subscription.will_renew,
+            billing_period: subscription.billing_period,
+            billing_currency: subscription.billing_currency,
+            observed_at: subscription.observed_at.to_rfc3339(),
+        }
+    }
+}
+
 /// Provider 官方个人资料统计响应。
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]

backend/crates/gateway-api/src/admin/auth.rs

@@ -5,7 +5,11 @@ use std::fmt;
 use axum::{
     Router,
     extract::{FromRequestParts, State},
-    http::{HeaderMap, HeaderValue, StatusCode, header::SET_COOKIE, request::Parts},
+    http::{
+        HeaderMap, HeaderValue, StatusCode,
+        header::{ORIGIN, SET_COOKIE},
+        request::Parts,
+    },
     response::{IntoResponse, Response},
     routing::{get, post},
 };
@@ -15,18 +19,37 @@ use gateway_admin::{
 };
 use serde::{Deserialize, Serialize};
 use tower_http::request_id::RequestId;
+use url::Url;
 
 use super::{AdminEnvelope, AdminError, AdminJson, AdminResponse};
 
 const REQUEST_ID_HEADER: &str = "x-request-id";
 const ADMIN_SESSION_COOKIE: &str = "cpr_admin_session";
-const ADMIN_SESSION_COOKIE_ATTRS: &str = "Path=/; Secure; HttpOnly; SameSite=Lax";
 
 /// 所有管理 HTTP 模块从 state 消费同一个认证用例端口。
 pub trait AdminSessionState {
     fn admin_services(&self) -> &AdminServices;
 }
 
+fn admin_session_cookie_attrs(headers: &HeaderMap) -> &'static str {
+    // 同源管理端的 POST 由浏览器携带 Origin，HTTPS 反代回源 HTTP 不改变它。
+    // 只对明确的 HTTP 来源放宽；缺失、opaque 或非法来源继续使用 Secure。
+    let http_origin = headers.get_all(ORIGIN).iter().count() == 1
+        && headers
+            .get(ORIGIN)
+            .and_then(|value| value.to_str().ok())
+            .is_some_and(|origin| {
+                Url::parse(origin).is_ok_and(|url| {
+                    url.scheme() == "http" && url.origin().ascii_serialization() == origin
+                })
+            });
+    if http_origin {
+        "Path=/; HttpOnly; SameSite=Lax"
+    } else {
+        "Path=/; Secure; HttpOnly; SameSite=Lax"
+    }
+}
+
 /// 已通过管理员会话或部署级管理 API Key 鉴权的请求。
 pub struct AdminAuth {
     context: AdminRequestContext,
@@ -203,6 +226,7 @@ where
 
 async fn login<S>(
     State(state): State<S>,
+    headers: HeaderMap,
     AdminJson(payload): AdminJson<AdminLoginRequest>,
 ) -> Result<Response, AdminError>
 where
@@ -221,8 +245,9 @@ where
     )
     .into_response();
     let cookie = format!(
-        "{ADMIN_SESSION_COOKIE}={}; {ADMIN_SESSION_COOKIE_ATTRS}",
-        session.session_id
+        "{ADMIN_SESSION_COOKIE}={}; {}",
+        session.session_id,
+        admin_session_cookie_attrs(&headers)
     );
     response.headers_mut().insert(
         SET_COOKIE,
@@ -260,7 +285,10 @@ where
     let mut response =
         AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(AdminLogoutData::new()))
             .into_response();
-    let cookie = format!("{ADMIN_SESSION_COOKIE}=; {ADMIN_SESSION_COOKIE_ATTRS}; Max-Age=0");
+    let cookie = format!(
+        "{ADMIN_SESSION_COOKIE}=; {}; Max-Age=0",
+        admin_session_cookie_attrs(&headers)
+    );
     response.headers_mut().insert(
         SET_COOKIE,
         HeaderValue::from_str(&cookie).map_err(|_| AdminError::internal())?,

backend/crates/gateway-api/src/admin/client_keys.rs

@@ -13,7 +13,7 @@ use gateway_admin::model::client_keys::{
 use gateway_core::{
     engine::budget::ClientBudgetLimits,
     metering::Decimal,
-    policy::{ClientApiKeyId, RateLimits},
+    policy::{ClientApiKeyId, PlaintextClientApiKey, RateLimits},
     routing::AccountGroupId,
 };
 use serde::{Deserialize, Serialize};
@@ -70,9 +70,7 @@ impl ListClientKeysQuery {
         }
         let search = self.search.map(|search| search.trim().to_owned());
         if search.as_deref().is_some_and(|search| {
-            search.len() > MAX_SEARCH_BYTES
-                || search.chars().any(char::is_control)
-                || contains_client_key_material(search)
+            search.len() > MAX_SEARCH_BYTES || search.chars().any(char::is_control)
         }) {
             return Err(WireValidationError::new("search"));
         }
@@ -143,9 +141,10 @@ impl ClientKeySort {
 }
 
 /// 创建 Client Key 请求。
-#[derive(Debug, Clone, PartialEq, Deserialize)]
+#[derive(Clone, PartialEq, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct CreateClientKeyRequest {
+    custom_key: Option<String>,
     name: String,
     label: Option<String>,
     group_ids: Vec<String>,
@@ -155,6 +154,16 @@ pub struct CreateClientKeyRequest {
     weekly_limit_usd: Option<String>,
 }
 
+impl fmt::Debug for CreateClientKeyRequest {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("CreateClientKeyRequest")
+            .field("name", &self.name)
+            .field("custom_key", &"[REDACTED]")
+            .finish_non_exhaustive()
+    }
+}
+
 impl CreateClientKeyRequest {
     /// 校验 wire 边界并直接构造管理用例命令。
     pub fn into_command(self) -> Result<CreateClientKey, WireValidationError> {
@@ -164,6 +173,12 @@ impl CreateClientKeyRequest {
         validate_limit(self.max_concurrency, "maxConcurrency")?;
         validate_limit(self.requests_per_minute, "requestsPerMinute")?;
         Ok(CreateClientKey {
+            custom_key: self
+                .custom_key
+                .filter(|key| !key.is_empty())
+                .map(PlaintextClientApiKey::new)
+                .transpose()
+                .map_err(|_| WireValidationError::new("customKey"))?,
             name: self.name,
             label: self.label,
             group_ids,
@@ -275,7 +290,6 @@ pub struct ClientKeyView {
     weekly_used_usd: String,
     daily_resets_at: Option<DateTime<Utc>>,
     weekly_resets_at: Option<DateTime<Utc>>,
-    unresolved_requests: u64,
     created_at: DateTime<Utc>,
     updated_at: DateTime<Utc>,
     last_used_at: Option<DateTime<Utc>>,
@@ -327,7 +341,6 @@ impl From<ClientKeyRecord> for ClientKeyView {
             weekly_used_usd: record.budget.weekly_used_usd.canonical(),
             daily_resets_at: record.budget.daily_resets_at.map(DateTime::from),
             weekly_resets_at: record.budget.weekly_resets_at.map(DateTime::from),
-            unresolved_requests: record.budget.unresolved_requests,
             created_at: record.created_at,
             updated_at: record.updated_at,
             last_used_at: record.last_used_at,
@@ -663,15 +676,6 @@ fn validate_optional_text(
     Ok(())
 }
 
-fn contains_client_key_material(value: &str) -> bool {
-    value.as_bytes().windows(46).any(|window| {
-        &window[..3] == b"sk_"
-            && window[3..]
-                .iter()
-                .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_'))
-    })
-}
-
 /// 构造固定 GET/POST 且 ID 仅位于 query/body 的 Client API Key 路由。
 pub fn router<S>() -> Router<S>
 where
@@ -679,14 +683,6 @@ where
 {
     Router::new()
         .route("/api/admin/client-keys", get(list_client_keys::<S>))
-        .route(
-            "/api/admin/client-keys/unresolved-charges",
-            get(unresolved_client_charges::<S>),
-        )
-        .route(
-            "/api/admin/client-keys/reconcile-charge",
-            post(reconcile_client_charge::<S>),
-        )
         .route(
             "/api/admin/client-keys/create",
             post(create_client_key::<S>),
@@ -710,66 +706,6 @@ where
         )
 }
 
-#[derive(Deserialize)]
-#[serde(rename_all = "camelCase", deny_unknown_fields)]
-struct ReconcileClientChargeRequest {
-    id: String,
-    request_id: String,
-    amount_usd: String,
-    reason: String,
-}
-
-async fn unresolved_client_charges<S>(
-    _auth: AdminAuth,
-    State(state): State<S>,
-    AdminQuery(query): AdminQuery<ClientKeyIdQuery>,
-) -> Result<impl IntoResponse, AdminError>
-where
-    S: AdminSessionState + Send + Sync,
-{
-    let id = query.into_domain_id().map_err(map_wire_error)?;
-    let items = state.admin_services().client_keys().unresolved_charges(&id).await.map_err(map_service_error)?
-        .into_iter().map(|event| serde_json::json!({
-            "requestId": event.request_id, "startedAt": event.started_at.to_rfc3339(),
-            "completedAt": event.completed_at.map(|time| time.to_rfc3339()), "state": event.state,
-        })).collect::<Vec<_>>();
-    Ok(AdminResponse::new(
-        StatusCode::OK,
-        AdminEnvelope::ok(serde_json::json!({"items": items})),
-    ))
-}
-
-async fn reconcile_client_charge<S>(
-    auth: AdminAuth,
-    State(state): State<S>,
-    AdminJson(payload): AdminJson<ReconcileClientChargeRequest>,
-) -> Result<impl IntoResponse, AdminError>
-where
-    S: AdminSessionState + Send + Sync,
-{
-    let key_id = client_key_id(payload.id, "id").map_err(map_wire_error)?;
-    let amount_usd = payload
-        .amount_usd
-        .parse::<Decimal>()
-        .map_err(|_| map_wire_error(WireValidationError::new("amountUsd")))?;
-    let command = gateway_admin::model::client_keys::ReconcileClientCharge {
-        key_id,
-        request_id: payload.request_id,
-        amount_usd,
-        reason: payload.reason,
-    };
-    state
-        .admin_services()
-        .client_keys()
-        .reconcile_charge(&auth.context().mutation_context(), command)
-        .await
-        .map_err(map_service_error)?;
-    Ok(AdminResponse::new(
-        StatusCode::OK,
-        AdminEnvelope::ok(serde_json::json!({"reconciled": true})),
-    ))
-}
-
 async fn list_client_keys<S>(
     _auth: AdminAuth,
     State(state): State<S>,

backend/crates/gateway-api/src/admin/mod.rs

@@ -16,6 +16,7 @@ pub mod client_keys;
 mod extract;
 pub mod observability;
 pub mod presenter;
+pub mod proxies;
 pub mod settings;
 pub mod system;
 pub mod wire;
@@ -34,6 +35,7 @@ where
 {
     Router::new()
         .merge(account_groups::router::<S>())
+        .merge(proxies::router::<S>())
         .merge(accounts::router::<S>())
         .merge(auth::router::<S>())
         .merge(backups::router::<S>())

backend/crates/gateway-api/src/admin/proxies.rs

@@ -0,0 +1,452 @@
+use axum::{
+    Router,
+    extract::State,
+    http::StatusCode,
+    response::IntoResponse,
+    routing::{get, post},
+};
+use gateway_admin::model::{
+    PageSize, Revision,
+    proxies::{
+        NewProxy, ProxyAccountListQuery, ProxyListQuery, ProxyMutation, ProxyRecord,
+        ProxyTestResult, UpdateProxy,
+    },
+};
+use serde::{Deserialize, Serialize};
+
+use super::{
+    AdminAuth, AdminEnvelope, AdminError, AdminJson, AdminQuery, AdminResponse, AdminSessionState,
+    PageMeta,
+    accounts::{AccountGroupRefView, AccountProxyUpdate},
+};
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct ListQuery {
+    page: Option<u32>,
+    page_size: Option<u16>,
+    search: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct AccountsQuery {
+    proxy_id: String,
+    page: Option<u32>,
+    page_size: Option<u16>,
+    search: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct RemoveAccountRequest {
+    proxy_id: String,
+    account_id: String,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct CreateRequest {
+    name: String,
+    proxy_url: AccountProxyUpdate,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct UpdateRequest {
+    id: String,
+    revision: u64,
+    name: String,
+    proxy_url: Option<AccountProxyUpdate>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct IdRequest {
+    id: String,
+    revision: u64,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct ProbeRequest {
+    proxy_url: AccountProxyUpdate,
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct ProxyTestView {
+    success: bool,
+    latency_ms: u64,
+    exit_ip: Option<String>,
+    message: String,
+}
+
+impl From<ProxyTestResult> for ProxyTestView {
+    fn from(result: ProxyTestResult) -> Self {
+        Self {
+            success: result.success,
+            latency_ms: result.latency_ms,
+            exit_ip: result.exit_ip.map(|ip| ip.to_string()),
+            message: result.message,
+        }
+    }
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct ProxyAccountView {
+    id: String,
+    name: String,
+    email: Option<String>,
+    provider: String,
+    authentication_kind: String,
+    plan_type: Option<String>,
+    plan_type_display: Option<String>,
+    groups: Vec<AccountGroupRefView>,
+    enabled: bool,
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct ProxyView {
+    id: String,
+    name: String,
+    endpoint: String,
+    has_authentication: bool,
+    revision: u64,
+    account_count: u64,
+    last_test_at: Option<String>,
+    last_test: Option<ProxyTestView>,
+    created_at: String,
+    updated_at: String,
+}
+
+impl From<ProxyRecord> for ProxyView {
+    fn from(record: ProxyRecord) -> Self {
+        let endpoint = record.proxy.endpoint();
+        Self {
+            id: record.id,
+            name: record.name,
+            has_authentication: record.proxy.expose_url() != endpoint,
+            endpoint,
+            revision: record.revision.get(),
+            account_count: record.account_count,
+            last_test_at: record.last_test_at.map(|at| at.to_rfc3339()),
+            last_test: record.last_test.map(Into::into),
+            created_at: record.created_at.to_rfc3339(),
+            updated_at: record.updated_at.to_rfc3339(),
+        }
+    }
+}
+
+#[derive(Serialize)]
+struct ProxyPageView {
+    items: Vec<ProxyView>,
+    page: PageMeta,
+}
+
+#[derive(Serialize)]
+struct ProxyAccountPageView {
+    items: Vec<ProxyAccountView>,
+    page: PageMeta,
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct MutationView {
+    record: ProxyView,
+    config_revision: u64,
+}
+
+impl From<ProxyMutation> for MutationView {
+    fn from(value: ProxyMutation) -> Self {
+        Self {
+            record: value.record.into(),
+            config_revision: value.config_revision.get(),
+        }
+    }
+}
+
+pub fn router<S>() -> Router<S>
+where
+    S: AdminSessionState + Clone + Send + Sync + 'static,
+{
+    Router::new()
+        .route("/api/admin/proxies", get(list::<S>))
+        .route("/api/admin/proxies/accounts", get(list_accounts::<S>))
+        .route(
+            "/api/admin/proxies/accounts/remove",
+            post(remove_account::<S>),
+        )
+        .route("/api/admin/proxies/create", post(create::<S>))
+        .route("/api/admin/proxies/update", post(update::<S>))
+        .route("/api/admin/proxies/delete", post(delete::<S>))
+        .route("/api/admin/proxies/test", post(test::<S>))
+        .route("/api/admin/proxies/probe", post(probe::<S>))
+}
+
+fn revision(value: u64) -> Result<Revision, AdminError> {
+    if value > i64::MAX as u64 {
+        return Err(AdminError::bad_request("代理版本不合法"));
+    }
+    Revision::new(value).map_err(|_| AdminError::bad_request("代理版本不合法"))
+}
+
+fn map_error(error: gateway_admin::model::AdminError) -> AdminError {
+    super::wire::map_admin_service_error(error)
+}
+
+async fn list<S>(
+    _: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<ListQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let result = state
+        .admin_services()
+        .proxies()
+        .list(ProxyListQuery {
+            page: query.page.unwrap_or(1),
+            page_size: PageSize::new(query.page_size.unwrap_or(20))
+                .map_err(|_| AdminError::bad_request("分页大小不合法"))?,
+            search: query.search.unwrap_or_default().trim().to_owned(),
+        })
+        .await
+        .map_err(map_error)?;
+    let total_pages = result.total.div_ceil(u64::from(result.page_size));
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(ProxyPageView {
+            items: result.items.into_iter().map(Into::into).collect(),
+            page: PageMeta::new(
+                result.page,
+                u32::from(result.page_size),
+                result.total,
+                u32::try_from(total_pages).unwrap_or(u32::MAX),
+            ),
+        }),
+    ))
+}
+
+async fn list_accounts<S>(
+    _: AdminAuth,
+    State(state): State<S>,
+    AdminQuery(query): AdminQuery<AccountsQuery>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let result = state
+        .admin_services()
+        .proxies()
+        .list_accounts(ProxyAccountListQuery {
+            proxy_id: query.proxy_id,
+            page: query.page.unwrap_or(1),
+            page_size: PageSize::new(query.page_size.unwrap_or(20))
+                .map_err(|_| AdminError::bad_request("分页大小不合法"))?,
+            search: query.search.unwrap_or_default().trim().to_owned(),
+        })
+        .await
+        .map_err(map_error)?;
+    let total_pages = result.total.div_ceil(u64::from(result.page_size));
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(ProxyAccountPageView {
+            items: result
+                .items
+                .into_iter()
+                .map(|account| ProxyAccountView {
+                    id: account.id,
+                    name: account.name,
+                    email: account.email,
+                    provider: account.provider_kind,
+                    authentication_kind: account.authentication_kind,
+                    plan_type: account.plan_type,
+                    plan_type_display: account.plan_type_display,
+                    groups: account
+                        .groups
+                        .into_iter()
+                        .map(|group| AccountGroupRefView {
+                            id: group.id.to_string(),
+                            name: group.name,
+                            color: group.color.as_str().to_owned(),
+                            enabled: group.enabled,
+                        })
+                        .collect(),
+                    enabled: account.enabled,
+                })
+                .collect(),
+            page: PageMeta::new(
+                result.page,
+                u32::from(result.page_size),
+                result.total,
+                u32::try_from(total_pages).unwrap_or(u32::MAX),
+            ),
+        }),
+    ))
+}
+
+async fn create<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<CreateRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let proxy = request
+        .proxy_url
+        .0
+        .ok_or_else(|| AdminError::bad_request("代理 URL 不能为空"))?;
+    let result = state
+        .admin_services()
+        .proxies()
+        .create(
+            NewProxy {
+                name: request.name,
+                proxy,
+            },
+            &auth.context().mutation_context(),
+        )
+        .await
+        .map_err(map_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::CREATED,
+        AdminEnvelope::ok(MutationView::from(result)),
+    ))
+}
+
+async fn remove_account<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<RemoveAccountRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let revision = state
+        .admin_services()
+        .proxies()
+        .remove_account(
+            &request.proxy_id,
+            &request.account_id,
+            &auth.context().mutation_context(),
+        )
+        .await
+        .map_err(map_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(serde_json::json!({"configRevision": revision.get()})),
+    ))
+}
+
+async fn update<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<UpdateRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let proxy = request
+        .proxy_url
+        .map(|value| {
+            value
+                .0
+                .ok_or_else(|| AdminError::bad_request("代理 URL 不能为空"))
+        })
+        .transpose()?;
+    let result = state
+        .admin_services()
+        .proxies()
+        .update(
+            UpdateProxy {
+                id: request.id,
+                revision: revision(request.revision)?,
+                name: request.name,
+                proxy,
+            },
+            &auth.context().mutation_context(),
+        )
+        .await
+        .map_err(map_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(MutationView::from(result)),
+    ))
+}
+
+async fn delete<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<IdRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let result = state
+        .admin_services()
+        .proxies()
+        .delete(
+            &request.id,
+            revision(request.revision)?,
+            &auth.context().mutation_context(),
+        )
+        .await
+        .map_err(map_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(serde_json::json!({"configRevision": result.get()})),
+    ))
+}
+
+async fn probe<S>(
+    _: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<ProbeRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let proxy = request
+        .proxy_url
+        .0
+        .ok_or_else(|| AdminError::bad_request("代理 URL 不能为空"))?;
+    let result = state
+        .admin_services()
+        .proxies()
+        .probe(&proxy)
+        .await
+        .map_err(map_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(ProxyTestView::from(result)),
+    ))
+}
+
+async fn test<S>(
+    auth: AdminAuth,
+    State(state): State<S>,
+    AdminJson(request): AdminJson<IdRequest>,
+) -> Result<impl IntoResponse, AdminError>
+where
+    S: AdminSessionState + Send + Sync,
+{
+    let result = state
+        .admin_services()
+        .proxies()
+        .test(
+            &request.id,
+            revision(request.revision)?,
+            &auth.context().mutation_context(),
+        )
+        .await
+        .map_err(map_error)?;
+    Ok(AdminResponse::new(
+        StatusCode::OK,
+        AdminEnvelope::ok(ProxyView::from(result)),
+    ))
+}

backend/crates/gateway-api/src/admin/wire.rs

@@ -331,7 +331,7 @@ impl AdminError {
 pub(crate) fn map_admin_service_error(error: gateway_admin::model::AdminError) -> AdminError {
     use gateway_admin::model::AdminErrorKind;
 
-    match error.kind() {
+    let mut response = match error.kind() {
         AdminErrorKind::Invalid => AdminError::bad_request(error.message()),
         AdminErrorKind::Unauthorized => AdminError::admin_session_required(),
         AdminErrorKind::NotFound => AdminError::not_found(error.message()),
@@ -341,7 +341,19 @@ pub(crate) fn map_admin_service_error(error: gateway_admin::model::AdminError) -
         AdminErrorKind::UpstreamResultUnknown => AdminError::upstream_result_unknown(),
         AdminErrorKind::Unavailable => AdminError::service_unavailable(),
         AdminErrorKind::Internal => AdminError::internal(),
+    };
+    // Admin owner 已负责公开文案，不能在 HTTP 边界再次丢掉安全的业务原因。
+    // 认证与未知内部异常仍使用固定提示，不放行底层诊断或任意 500 消息。
+    if matches!(
+        error.kind(),
+        AdminErrorKind::BadGateway
+            | AdminErrorKind::UpstreamResultUnknown
+            | AdminErrorKind::Unavailable
+    ) && !error.message().trim().is_empty()
+    {
+        response.body.message = error.message().to_owned();
     }
+    response
 }
 
 impl IntoResponse for AdminError {

backend/crates/gateway-api/src/openai/auth.rs

@@ -86,7 +86,7 @@ impl ClientApiKeyAuthError {
 ///
 /// # Errors
 ///
-/// Header 缺失、Bearer 语法错误或不是网关 Client Key 前缀时返回稳定错误。
+/// Header 缺失、Bearer 语法错误或 Key 不能作为 HTTP Bearer 值时返回稳定错误。
 pub fn bearer_client_api_key(headers: &HeaderMap) -> Result<&str, ClientApiKeyAuthError> {
     let raw = headers
         .get(AUTHORIZATION)
@@ -100,7 +100,7 @@ pub fn bearer_client_api_key(headers: &HeaderMap) -> Result<&str, ClientApiKeyAu
     if token.is_empty() {
         return Err(ClientApiKeyAuthError::MalformedAuthorization);
     }
-    if !token.starts_with("sk_") {
+    if gateway_core::policy::PlaintextClientApiKey::validate(token).is_err() {
         return Err(ClientApiKeyAuthError::InvalidKeyFormat);
     }
     Ok(token)

backend/crates/gateway-api/src/openai/endpoint.rs

@@ -5,7 +5,7 @@ use axum::{
     http::{HeaderName, HeaderValue, StatusCode, header::CONTENT_TYPE},
     response::{IntoResponse, Response},
 };
-use gateway_core::engine::execution::StartedExecution;
+use gateway_core::engine::execution::{ExecutionSession, StartedExecution};
 use gateway_core::event::{ProviderEvent, ProviderResponseHeader};
 
 use super::{
@@ -15,7 +15,12 @@ use super::{
 
 /// 收集一个 Provider 原生 JSON 响应，并在 Core commit 后按原始 bytes 交付。
 pub(super) async fn collect_raw_json_response(started: StartedExecution) -> Response {
-    let mut execution = PendingExecution::new(started.session);
+    let response = collect_raw_json_session(started.session).await;
+    super::with_model_request_id(response, &started.request_id)
+}
+
+async fn collect_raw_json_session(session: Box<dyn ExecutionSession>) -> Response {
+    let mut execution = PendingExecution::new(session);
     let Some(session) = execution.session_mut() else {
         return invalid_upstream_response();
     };

backend/crates/gateway-api/src/openai/error.rs

@@ -190,7 +190,15 @@ pub fn engine_error_response(error: &EngineError) -> Response {
         }
         return response;
     }
-    gateway_error_response(&gateway_error_from_engine(error))
+    let mut response = gateway_error_response(&gateway_error_from_engine(error));
+    // 正文未完整取得时不能透传残缺响应，但已确认的上游关联 ID 仍应交付。
+    if let EngineError::Provider(error) = error
+        && let Some(request_id) = error.upstream_request_id()
+        && let Ok(value) = HeaderValue::from_str(request_id.as_str())
+    {
+        response.headers_mut().insert("x-request-id", value);
+    }
+    response
 }
 
 /// Gateway 错误稳定映射，供 HTTP、SSE 和 WebSocket 共用。

backend/crates/gateway-api/src/openai/mod.rs

@@ -9,3 +9,28 @@ pub mod responses;
 pub mod router;
 pub mod search;
 pub(crate) mod service;
+
+/// 客户端可读的 ID 必须能按现有请求记录检索；不以无关入口 ID 补位。
+fn with_model_request_id(
+    mut response: axum::response::Response,
+    request_id: &gateway_core::engine::ModelRequestId,
+) -> axum::response::Response {
+    use axum::http::HeaderValue;
+
+    let Ok(gateway_id) = HeaderValue::from_str(request_id.as_str()) else {
+        return response;
+    };
+    let headers = response.headers_mut();
+    let usable = |value: &HeaderValue| value.to_str().is_ok_and(|id| !id.trim().is_empty());
+    if !headers.get("x-request-id").is_some_and(usable) {
+        // 只有别名时沿用同一个上游值，避免外层 middleware 再填入入口 ID。
+        let client_id = headers
+            .get("x-oai-request-id")
+            .filter(|value| usable(value))
+            .unwrap_or(&gateway_id)
+            .clone();
+        headers.insert("x-request-id", client_id);
+    }
+    headers.insert("x-gateway-request-id", gateway_id);
+    response
+}

backend/crates/gateway-api/src/openai/models.rs

@@ -6,7 +6,7 @@ use axum::{
     http::{HeaderMap, StatusCode},
     response::{IntoResponse, Response},
 };
-use gateway_core::routing::{PublicModelId, PublicModelProfile};
+use gateway_core::routing::{PublicModelDescriptor, PublicModelId, PublicModelProfile};
 use serde::Deserialize;
 use serde_json::{Value, json};
 
@@ -14,7 +14,7 @@ use crate::ApiState;
 
 use super::{
     auth::{authenticate_client, client_access_error_response},
-    error::model_not_found_response,
+    error::{model_not_found_response, openai_error_response},
 };
 
 const MODEL_CREATED_TIMESTAMP: i64 = 1_700_000_000;
@@ -37,19 +37,53 @@ pub(crate) async fn models(
         Err(error) => return client_access_error_response(error),
     };
 
-    if query
+    if let Some(version) = query
         .client_version
         .as_deref()
-        .is_some_and(|version| !version.trim().is_empty())
+        .filter(|version| !version.trim().is_empty())
     {
-        let models = service
-            .public_model_profiles(&client)
+        if version.len() > 64
+            || !version
+                .bytes()
+                .all(|byte| byte.is_ascii_alphanumeric() || b".-+".contains(&byte))
+        {
+            return openai_error_response(
+                StatusCode::BAD_REQUEST,
+                "Invalid client_version",
+                "invalid_request_error",
+                "invalid_client_version",
+            )
+            .into_response();
+        }
+        let catalog = match service.client_model_catalog(&client, version).await {
+            Ok(catalog) => catalog,
+            Err(_) => return catalog_unavailable_response(),
+        };
+        let models = catalog
             .iter()
             .enumerate()
-            .map(|(index, profile)| codex_model_json(profile, index))
-            .collect::<Vec<_>>();
+            .map(|(index, entry)| match entry {
+                PublicModelDescriptor::Adapted(profile) => Ok(codex_model_json(profile, index)),
+                PublicModelDescriptor::Native { model, payload } => {
+                    if payload.protocol() != "codex" {
+                        return Err(());
+                    }
+                    let mut value: Value =
+                        serde_json::from_slice(payload.body()).map_err(|_| ())?;
+                    let object = value.as_object_mut().ok_or(())?;
+                    // 别名只改变请求标识，能力、提示词、顺序等仍由上游目录决定。
+                    object.insert("slug".to_owned(), Value::String(model.as_str().to_owned()));
+                    Ok(value)
+                }
+            })
+            .collect::<Result<Vec<_>, ()>>();
+        let Ok(models) = models else {
+            return catalog_unavailable_response();
+        };
         return (
             StatusCode::OK,
+            // 目录经过账号选择/别名/多 Provider 聚合，不能借用上游 ETag 表示改写后的正文。
+            [("cache-control", "private, no-store")],
             Json(json!({
                 "models": models,
             })),
@@ -72,6 +106,16 @@ pub(crate) async fn models(
         .into_response()
 }
 
+fn catalog_unavailable_response() -> Response {
+    openai_error_response(
+        StatusCode::SERVICE_UNAVAILABLE,
+        "Model catalog is temporarily unavailable",
+        "server_error",
+        "model_catalog_unavailable",
+    )
+    .into_response()
+}
+
 /// `GET /v1/models/{model_id}`。
 pub(crate) async fn model_detail(
     State(state): State<ApiState>,
@@ -124,6 +168,7 @@ fn codex_model_json(profile: &PublicModelProfile, index: usize) -> Value {
         .iter()
         .any(|effort| effort != "none");
     let context_window = presentation.context_window_tokens();
+    let max_context_window = presentation.max_context_window_tokens();
     let input_modalities = if presentation.image_input() {
         vec!["text", "image"]
     } else {
@@ -173,7 +218,7 @@ fn codex_model_json(profile: &PublicModelProfile, index: usize) -> Value {
         "supports_parallel_tool_calls": presentation.parallel_tool_calls(),
         "supports_image_detail_original": presentation.image_detail_original(),
         "context_window": context_window,
-        "max_context_window": context_window,
+        "max_context_window": max_context_window,
         "effective_context_window_percent": 95,
         "experimental_supported_tools": [],
         "input_modalities": input_modalities,

backend/crates/gateway-api/src/openai/responses/error.rs

@@ -40,6 +40,15 @@ pub enum RequestDecodeError {
     /// 请求不是合法 JSON。
     #[error("request body must be valid JSON")]
     MalformedJson,
+    /// 请求体解压后超过允许上限。
+    #[error("decompressed request body is too large")]
+    DecompressedBodyTooLarge,
+    /// 请求使用了网关不支持的 `Content-Encoding`。
+    #[error("request content-encoding `{encoding}` is not supported")]
+    UnsupportedContentEncoding {
+        /// Content-Encoding 标识。
+        encoding: String,
+    },
     /// 顶层不是 object。
     #[error("request body must be a JSON object")]
     ExpectedObject,
@@ -99,6 +108,16 @@ impl RequestDecodeError {
                 "Request body must be valid JSON.".to_owned(),
                 None,
             ),
+            Self::DecompressedBodyTooLarge => (
+                "request_too_large",
+                "Decompressed request body exceeds the allowed size.".to_owned(),
+                None,
+            ),
+            Self::UnsupportedContentEncoding { encoding } => (
+                "unsupported_content_encoding",
+                format!("Content-Encoding `{encoding}` is not supported."),
+                None,
+            ),
             Self::ExpectedObject => (
                 "invalid_request_body",
                 "Request body must be a JSON object.".to_owned(),

backend/crates/gateway-api/src/openai/responses/http.rs

@@ -93,20 +93,17 @@ pub(crate) async fn responses(
         "ingressRequestId": ingress_id.as_ref().and_then(|Extension(id)| id.header_value().to_str().ok()),
     }), headers.iter().map(|(name, value)| (name.as_str(), value.as_bytes())));
     trace.capture("client.request.body", &body);
-    let request_id_header = HeaderValue::from_str(started.request_id.as_str()).ok();
+    let request_id = started.request_id;
     let StartedExecution {
         stream, session, ..
     } = started;
-    let mut response = if stream {
+    let response = if stream {
         stream_execution_response(session, connection_guard).await
     } else {
         drop(connection_guard);
         collect_execution_response(session).await
     };
-    if let Some(id) = request_id_header {
-        response.headers_mut().insert("x-gateway-request-id", id);
-    }
-    response
+    crate::openai::with_model_request_id(response, &request_id)
 }
 
 /// 从 socket 与标准转发头提取旧 Usage 页面使用的诊断事实。
@@ -271,7 +268,26 @@ fn engine_error_response_with_headers(
     error: &EngineError,
     response_headers: &[ProviderResponseHeader],
 ) -> Response {
-    apply_response_headers(engine_error_response(error), response_headers)
+    let response = engine_error_response(error);
+    let failure_request_ids: Vec<_> = ["x-request-id", "x-oai-request-id"]
+        .into_iter()
+        .flat_map(|name| {
+            response
+                .headers()
+                .get_all(name)
+                .iter()
+                .cloned()
+                .map(move |value| (name, value))
+        })
+        .collect();
+    // 失败后仍须交付已采集的 turn state；只隔离 opening 身份，不丢弃会话状态。
+    let mut response = apply_response_headers(response, response_headers);
+    response.headers_mut().remove("x-request-id");
+    response.headers_mut().remove("x-oai-request-id");
+    for (name, value) in failure_request_ids {
+        response.headers_mut().append(name, value);
+    }
+    response
 }
 
 /// 编码首个 SSE frame 后提交下游，再持续驱动同一执行会话。

backend/crates/gateway-api/src/openai/responses/request.rs

@@ -1,12 +1,13 @@
 //! OpenAI Responses JSON 到 Core 路由事实与不透明 wire payload 的单一解码边界。
 
-use std::{fmt, net::IpAddr};
+use std::{borrow::Cow, fmt, net::IpAddr};
 
 use axum::http::HeaderMap;
 use base64::{Engine as _, engine::general_purpose::STANDARD};
 use gateway_core::operation::{GenerateRequest, Operation, ProtocolPayload, ProviderSessionState};
 use gateway_protocol::openai::{
     X_OPENAI_INTERNAL_CODEX_RESPONSES_LITE_HEADER, X_OPENAI_MEMGEN_REQUEST_HEADER,
+    is_transport_managed_request_header,
 };
 use serde_json::{Map, Value};
 
@@ -322,12 +323,87 @@ impl fmt::Debug for DecodedResponsesRequest {
 ///
 /// # Errors
 ///
-/// JSON 非法、顶层不是 object，或网关必须解释的路由字段无效时返回安全错误。
+/// 编码不支持、压缩正文损坏或超限、JSON 非法，或路由字段无效时返回安全错误。
 pub fn decode_request_with_headers(
     body: &[u8],
     headers: &HeaderMap,
 ) -> Result<DecodedResponsesRequest, RequestDecodeError> {
-    decode_request_inner(body, &OpenAiRequestHeaders::from_headers(headers))
+    let body = decompress_request_body(body, headers)?;
+    decode_request_inner(&body, &OpenAiRequestHeaders::from_headers(headers))
+}
+
+/// 下游请求体解压后的最大字节数；防御解压炸弹。
+const MAX_DECOMPRESSED_REQUEST_BYTES: usize = 64 * 1024 * 1024;
+
+/// 按 `Content-Encoding` 解压下游请求体。
+///
+/// 未压缩与 `identity` 借用原始正文；压缩正文在读取过程中限制展开大小，
+/// 避免先完整分配再检查。只接受单一编码，重复头和叠加编码不能只解释第一项。
+fn decompress_request_body<'a>(
+    body: &'a [u8],
+    headers: &HeaderMap,
+) -> Result<Cow<'a, [u8]>, RequestDecodeError> {
+    let encoding = headers
+        .get_all(axum::http::header::CONTENT_ENCODING)
+        .iter()
+        .map(|value| {
+            value
+                .to_str()
+                .map_err(|_| RequestDecodeError::MalformedJson)
+        })
+        .collect::<Result<Vec<_>, _>>()?
+        .join(",");
+    match encoding.trim().to_ascii_lowercase().as_str() {
+        "" | "identity" => Ok(Cow::Borrowed(body)),
+        "gzip" => {
+            let decoder = flate2::read::MultiGzDecoder::new(body);
+            read_bounded(decoder).map(Cow::Owned)
+        }
+        "deflate" => {
+            let decoder = flate2::read::ZlibDecoder::new(body);
+            read_bounded(decoder).map(Cow::Owned)
+        }
+        "zstd" => {
+            let mut decoder = zstd::stream::read::Decoder::with_buffer(body)
+                .map_err(|_| RequestDecodeError::MalformedJson)?;
+            // 输出有界之外，也限制压缩帧声明的回溯窗口，防止解码器内部过量分配。
+            decoder
+                .window_log_max(MAX_DECOMPRESSED_REQUEST_BYTES.ilog2())
+                .map_err(|_| RequestDecodeError::MalformedJson)?;
+            read_bounded(decoder).map(Cow::Owned)
+        }
+        other => Err(RequestDecodeError::UnsupportedContentEncoding {
+            encoding: other.to_owned(),
+        }),
+    }
+}
+
+fn read_bounded<R: std::io::Read>(mut reader: R) -> Result<Vec<u8>, RequestDecodeError> {
+    let mut decoded = Vec::new();
+    let mut chunk = [0; 8192];
+    loop {
+        let remaining = MAX_DECOMPRESSED_REQUEST_BYTES - decoded.len();
+        let read_limit = chunk.len().min(remaining + 1);
+        let read = reader
+            .read(&mut chunk[..read_limit])
+            .map_err(|_| RequestDecodeError::MalformedJson)?;
+        if read == 0 {
+            return Ok(decoded);
+        }
+        if read > remaining {
+            return Err(RequestDecodeError::DecompressedBodyTooLarge);
+        }
+        // 默认 Vec 扩容和 read_to_end 的 EOF 探测可能突破输出上限；
+        // 容量增长也受相同边界约束，越界探测只使用栈上分块缓冲区。
+        let required = decoded.len() + read;
+        if required > decoded.capacity() {
+            let capacity = (decoded.capacity() * 2)
+                .max(required)
+                .min(MAX_DECOMPRESSED_REQUEST_BYTES);
+            decoded.reserve_exact(capacity - decoded.len());
+        }
+        decoded.extend_from_slice(&chunk[..read]);
+    }
 }
 
 pub(super) fn decode_request_inner(
@@ -458,7 +534,7 @@ fn passthrough_header_name(name: &str, connection_headers: &[String]) -> bool {
     if connection_headers
         .iter()
         .any(|connection_header| connection_header.eq_ignore_ascii_case(name))
-        || name.starts_with("sec-websocket-")
+        || is_transport_managed_request_header(name)
         || name.starts_with("x-grok-")
         || name.starts_with("x-xai-")
     {
@@ -467,30 +543,8 @@ fn passthrough_header_name(name: &str, connection_headers: &[String]) -> bool {
 
     !matches!(
         name,
-        // 逐跳头、上游 authority 和重序列化后的实体长度由 transport 重建。
-        "connection"
-            | "keep-alive"
-            | "proxy-connection"
-            | "proxy-authenticate"
-            | "proxy-authorization"
-            | "te"
-            | "trailer"
-            | "transfer-encoding"
-            | "upgrade"
-            | "host"
-            | "content-length"
-            // 下游连接诊断事实只用于本地观测，不能伪装成 OpenAI 请求事实。
-            | "forwarded"
-            | "x-forwarded-for"
-            | "x-forwarded-host"
-            | "x-forwarded-proto"
-            | "x-forwarded-port"
-            | "x-real-ip"
-            | "true-client-ip"
-            | "cf-connecting-ip"
-            | "x-request-id"
-            // 下游鉴权和账号 cookie 绝不能成为上游账号身份。
-            | "authorization"
+        // 下游鉴权和账号 cookie 绝不能成为上游账号身份。
+        "authorization"
             | "x-api-key"
             // Codex 的服务端托管认证标记只用于客户端能力判断，不代表上游身份。
             | "x-openai-actor-authorization"

backend/crates/gateway-api/src/openai/responses/response.rs

@@ -2,7 +2,9 @@
 
 use bytes::Bytes;
 use gateway_core::event::{GatewayEvent, ProtocolWireEvent, ProviderEvent};
-use gateway_protocol::openai::sse::encode_sse_event_with_metadata;
+use gateway_protocol::openai::sse::{
+    encode_sse_event_with_metadata, response_failed_sse_data_from_error_event,
+};
 use serde_json::Value;
 
 use super::error::ResponseEncodeError;
@@ -17,6 +19,7 @@ const OPENAI_PROTOCOL: &str = "openai";
 #[derive(Debug, Default)]
 pub struct OpenAiResponsesEncoder {
     response_id: Option<String>,
+    response_snapshot: Option<Value>,
     wire_terminal: Option<Value>,
     wire_failure: bool,
 }
@@ -27,6 +30,7 @@ impl OpenAiResponsesEncoder {
     pub const fn new() -> Self {
         Self {
             response_id: None,
+            response_snapshot: None,
             wire_terminal: None,
             wire_failure: false,
         }
@@ -39,6 +43,22 @@ impl OpenAiResponsesEncoder {
             return Vec::new();
         };
         self.observe_wire(wire);
+        // 当前 Codex 不消费 Responses `error` event，会在 EOF 时丢失失败原因。
+        // 在客户端 SSE 边界统一投影成它能识别的 `response.failed`。
+        if wire.event_type() == Some("error")
+            && let Some(data) = response_failed_sse_data_from_error_event(
+                self.response_snapshot.as_ref(),
+                self.response_id.as_deref(),
+                wire.data(),
+            )
+        {
+            return vec![Bytes::from(encode_sse_event_with_metadata(
+                "response.failed",
+                &data.to_string(),
+                wire.sse_id(),
+                wire.sse_retry(),
+            ))];
+        }
         if let Some(raw_sse_frame) = wire.raw_sse_frame() {
             return vec![raw_sse_frame.clone()];
         }
@@ -110,6 +130,16 @@ impl OpenAiResponsesEncoder {
         let effective_type = wire
             .event_type()
             .or_else(|| wire.data().get("type").and_then(Value::as_str));
+        if matches!(
+            effective_type,
+            Some("response.created" | "response.in_progress" | "response.queued")
+        ) && let Some(response) = wire
+            .data()
+            .get("response")
+            .filter(|value| value.is_object())
+        {
+            self.response_snapshot = Some(response.clone());
+        }
         if matches!(
             effective_type,
             Some("response.completed" | "response.incomplete")

backend/crates/gateway-api/src/openai/responses/websocket/forward.rs

@@ -14,7 +14,7 @@ use crate::openai::error::{gateway_error_contract, gateway_error_from_engine};
 use super::{
     super::{DecodedResponsesRequest, OpenAiResponsesEncoder, PendingExecution, ProtocolErrorBody},
     connection::{FramePhase, ResponsesWebSocketConnection, WriteContext},
-    protocol::{error_event, response_metadata_event},
+    protocol::{error_event, initial_engine_error_event, response_metadata_event},
 };
 
 #[derive(Clone, Copy, PartialEq, Eq)]
@@ -273,8 +273,12 @@ async fn send_initial_engine_error(
     {
         return ForwardOutcome::Disconnect;
     }
-    let error = gateway_error_from_engine(error);
-    send_gateway_error(connection, &error, request_id).await
+    send_error_message(
+        connection,
+        initial_engine_error_event(error, request_id, &response_headers),
+        request_id,
+    )
+    .await
 }
 
 fn commit_connection_replay(
@@ -393,10 +397,31 @@ async fn send_error(
     message: &str,
     param: Option<&str>,
     request_id: &Arc<str>,
+) -> ForwardOutcome {
+    send_error_message(
+        connection,
+        error_event(
+            status,
+            error_type,
+            code,
+            message,
+            param,
+            Some(request_id),
+            serde_json::Map::new(),
+        ),
+        request_id,
+    )
+    .await
+}
+
+async fn send_error_message(
+    connection: &mut ResponsesWebSocketConnection,
+    message: String,
+    request_id: &Arc<str>,
 ) -> ForwardOutcome {
     if connection
         .send_text(
-            error_event(status, error_type, code, message, param, Some(request_id)),
+            message,
             WriteContext::request(request_id, FramePhase::Error),
         )
         .await

backend/crates/gateway-api/src/openai/responses/websocket/protocol.rs

@@ -1,10 +1,13 @@
 //! Responses WebSocket 入站请求与下行事件的纯协议映射。
 
-use axum::http::{HeaderName, StatusCode};
+use axum::http::{HeaderName, HeaderValue, StatusCode};
+use gateway_core::engine::EngineError;
 use gateway_core::event::ProviderResponseHeader;
 use serde_json::{Map, Value, json};
 use thiserror::Error;
 
+use crate::openai::error::{gateway_error_contract, gateway_error_from_engine};
+
 use super::super::{
     DecodedResponsesRequest, ProtocolErrorBody, RequestDecodeError,
     request::{OpenAiRequestHeaders, RequestDecodeSource},
@@ -91,21 +94,7 @@ pub(super) fn response_metadata_event(
     request_id: &str,
     response_headers: &[ProviderResponseHeader],
 ) -> String {
-    let connection_options = super::super::response_connection_options(response_headers);
-    let mut headers = Map::new();
-    for header in response_headers {
-        if !super::super::response_header_is_forwardable(header.name(), &connection_options) {
-            continue;
-        }
-        let Ok(name) = HeaderName::from_bytes(header.name().as_bytes()) else {
-            continue;
-        };
-        let Ok(value) = std::str::from_utf8(header.value()) else {
-            continue;
-        };
-        // 官方 response.metadata 使用 string map，无法表达同名多值；后值保持既有覆盖语义。
-        headers.insert(name.as_str().to_owned(), Value::String(value.to_owned()));
-    }
+    let mut headers = response_event_headers(response_headers);
     headers
         .entry("x-request-id".to_owned())
         .or_insert_with(|| Value::String(request_id.to_owned()));
@@ -116,6 +105,84 @@ pub(super) fn response_metadata_event(
     .to_string()
 }
 
+fn response_event_headers(response_headers: &[ProviderResponseHeader]) -> Map<String, Value> {
+    let connection_options = super::super::response_connection_options(response_headers);
+    let mut headers = Map::new();
+    for header in response_headers {
+        if !super::super::response_header_is_forwardable(header.name(), &connection_options) {
+            continue;
+        }
+        let Ok(name) = HeaderName::from_bytes(header.name().as_bytes()) else {
+            continue;
+        };
+        let Ok(http_value) = HeaderValue::from_bytes(header.value()) else {
+            continue;
+        };
+        let Ok(value) = std::str::from_utf8(header.value()) else {
+            continue;
+        };
+        if matches!(name.as_str(), "x-request-id" | "x-oai-request-id")
+            && (value.trim().is_empty() || http_value.to_str().is_err())
+        {
+            continue;
+        }
+        // 官方 WS 事件使用 string map，无法表达同名多值；后值保持既有覆盖语义。
+        headers.insert(name.as_str().to_owned(), Value::String(value.to_owned()));
+    }
+    headers
+}
+
+pub(super) fn initial_engine_error_event(
+    error: &EngineError,
+    request_id: &str,
+    response_headers: &[ProviderResponseHeader],
+) -> String {
+    let gateway = gateway_error_from_engine(error);
+    let (default_status, default_type, default_code) = gateway_error_contract(gateway.kind());
+    let provider = match error {
+        EngineError::Provider(provider) => Some(provider),
+        _ => None,
+    };
+    let upstream = provider.and_then(|error| error.client_visible_upstream_response());
+    // 最终失败响应优先于会话快照，避免混入先前 attempt 或 opening 的关联头。
+    let mut headers =
+        response_event_headers(upstream.map_or(response_headers, |response| response.headers()));
+    if upstream.is_none() {
+        // 会话 opening 身份不证明当前失败属于该请求；仅保留其他允许的会话头。
+        headers.remove("x-request-id");
+        headers.remove("x-oai-request-id");
+    }
+    let status = upstream
+        .map(|response| response.status())
+        .or_else(|| provider.and_then(|error| error.upstream_status()))
+        .and_then(|value| StatusCode::from_u16(value).ok())
+        .filter(|value| !value.is_success() && !value.is_informational())
+        .unwrap_or(default_status);
+    // 无原响应关联头时使用 Provider 的失败事实；不能让旧会话 ID 遮住当前失败。
+    if !has_request_id(&headers)
+        && let Some(request_id) = provider.and_then(|error| error.upstream_request_id())
+        && let Ok(value) = HeaderValue::from_str(request_id.as_str())
+        && let Ok(value) = value.to_str()
+        && !value.trim().is_empty()
+    {
+        headers.insert("x-request-id".to_owned(), Value::String(value.to_owned()));
+    }
+    // 只桥接 Provider 已提取的结构化错误；原始 HTML/文本正文不成为安全 fallback 的 message。
+    error_event(
+        status,
+        gateway.client_error_type().unwrap_or(default_type),
+        gateway.client_error_code().unwrap_or(default_code),
+        gateway.client_message(),
+        None,
+        Some(request_id),
+        headers,
+    )
+}
+
+fn has_request_id(headers: &Map<String, Value>) -> bool {
+    headers.contains_key("x-request-id") || headers.contains_key("x-oai-request-id")
+}
+
 pub(super) fn error_event(
     status: StatusCode,
     error_type: &str,
@@ -123,6 +190,7 @@ pub(super) fn error_event(
     message: &str,
     param: Option<&str>,
     request_id: Option<&str>,
+    mut headers: Map<String, Value>,
 ) -> String {
     let mut error = Map::new();
     error.insert("type".to_owned(), Value::String(error_type.to_owned()));
@@ -136,11 +204,26 @@ pub(super) fn error_event(
     event.insert("status".to_owned(), Value::Number(status.as_u16().into()));
     event.insert("error".to_owned(), Value::Object(error));
     if let Some(request_id) = request_id {
+        // Codex 从本 error 事件的 headers 读 ID，独立 metadata 和顶层 request_id 不能替代。
+        // 网关身份独立保存；有上游关联头时不冒充或覆盖上游身份。
+        if !has_request_id(&headers) {
+            headers.insert(
+                "x-request-id".to_owned(),
+                Value::String(request_id.to_owned()),
+            );
+        }
+        headers.insert(
+            "x-gateway-request-id".to_owned(),
+            Value::String(request_id.to_owned()),
+        );
         event.insert(
             "request_id".to_owned(),
             Value::String(request_id.to_owned()),
         );
     }
+    if !headers.is_empty() {
+        event.insert("headers".to_owned(), Value::Object(headers));
+    }
     Value::Object(event).to_string()
 }
 
@@ -152,5 +235,6 @@ pub(super) fn connection_limit_event() -> String {
         "Responses websocket connection limit reached (60 minutes). Create a new websocket connection to continue.",
         None,
         None,
+        Map::new(),
     )
 }

backend/crates/gateway-api/src/openai/service.rs

@@ -10,7 +10,7 @@ use gateway_core::engine::execution::{
 };
 use gateway_core::error::{GatewayError, GatewayErrorKind};
 use gateway_core::lifecycle::{ConnectionDraining, ConnectionGuard, ConnectionLifecycle};
-use gateway_core::routing::{PublicModelId, PublicModelProfile};
+use gateway_core::routing::{ProviderCatalogUnavailable, PublicModelDescriptor, PublicModelId};
 use uuid::Uuid;
 
 use super::auth::ClientApiKeyAuthError;
@@ -52,11 +52,14 @@ impl OpenAiService {
             .collect()
     }
 
-    pub(crate) fn public_model_profiles(
+    pub(crate) async fn client_model_catalog(
         &self,
         client: &AuthenticatedClient,
-    ) -> Vec<PublicModelProfile> {
-        self.execution.public_model_profiles(client)
+        client_version: &str,
+    ) -> Result<Vec<PublicModelDescriptor>, ProviderCatalogUnavailable> {
+        self.execution
+            .client_model_catalog(client, "codex", client_version)
+            .await
     }
 
     pub(crate) fn contains_public_model(

backend/crates/gateway-api/tests/admin/accounts/handlers.rs

@@ -0,0 +1,90 @@
+use axum::{
+    body::{Body, to_bytes},
+    http::{Request, StatusCode, header},
+};
+use gateway_api::admin;
+use tower::ServiceExt as _;
+
+use super::super::{AdminTestFixture, AdminTestState};
+
+#[tokio::test]
+async fn personal_info_requires_admin_and_a_valid_account_query() {
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    for (query, authenticated, expected) in [
+        ("?accountId=acct_test", false, StatusCode::UNAUTHORIZED),
+        ("", true, StatusCode::BAD_REQUEST),
+        ("?accountId=bad", true, StatusCode::BAD_REQUEST),
+        (
+            "?accountId=acct_test&refresh=true",
+            true,
+            StatusCode::BAD_REQUEST,
+        ),
+        // 此夹具未提供账号 Store，合法查询应透传服务不可用，而非绕过查询。
+        (
+            "?accountId=acct_test",
+            true,
+            StatusCode::SERVICE_UNAVAILABLE,
+        ),
+    ] {
+        let mut request = Request::builder()
+            .uri(format!("/api/admin/accounts/personal-info{query}"))
+            .header("x-request-id", "req_personal_info");
+        if authenticated {
+            request = request.header(header::COOKIE, "cpr_admin_session=valid-session");
+        }
+        let response = admin::router::<AdminTestState>()
+            .with_state(fixture.state())
+            .oneshot(request.body(Body::empty()).unwrap())
+            .await
+            .unwrap();
+        assert_eq!(response.status(), expected, "{query}");
+        assert_eq!(response.headers()[header::CACHE_CONTROL], "no-store");
+    }
+}
+
+#[tokio::test]
+async fn quota_forecast_requires_admin_and_valid_account_query() {
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    for (uri, authenticated, expected) in [
+        (
+            "/api/admin/accounts/quota-forecast?accountId=acct_test",
+            false,
+            StatusCode::UNAUTHORIZED,
+        ),
+        (
+            "/api/admin/accounts/quota-forecast",
+            true,
+            StatusCode::BAD_REQUEST,
+        ),
+        (
+            "/api/admin/accounts/quota-forecast?accountId=bad",
+            true,
+            StatusCode::BAD_REQUEST,
+        ),
+        (
+            "/api/admin/accounts/quota-forecast?accountId=acct_test&refresh=true",
+            true,
+            StatusCode::BAD_REQUEST,
+        ),
+    ] {
+        let mut request = Request::builder()
+            .uri(uri)
+            .header("x-request-id", "req_forecast");
+        if authenticated {
+            request = request.header(header::COOKIE, "cpr_admin_session=valid-session");
+        }
+        let response = admin::router::<AdminTestState>()
+            .with_state(fixture.state())
+            .oneshot(request.body(Body::empty()).unwrap())
+            .await
+            .unwrap();
+        assert_eq!(response.status(), expected, "{uri}");
+        assert_eq!(response.headers()[header::CACHE_CONTROL], "no-store");
+        let body = to_bytes(response.into_body(), 8192).await.unwrap();
+        let value: serde_json::Value = serde_json::from_slice(&body).unwrap();
+        assert!(value["data"].is_null());
+        assert!(value["message"].is_string());
+    }
+}

backend/crates/gateway-api/tests/admin/accounts/mod.rs

@@ -1,3 +1,77 @@
+mod handlers;
+mod presenter;
+
+mod personal_info {
+    use chrono::{TimeZone as _, Utc};
+    use gateway_admin::model::{
+        AdminError,
+        provider_credentials::{AccountPersonalInfo, ProviderSubscription},
+    };
+    use gateway_api::admin::accounts::{AccountPersonalInfoData, AccountSubscriptionData};
+    use serde_json::json;
+
+    #[test]
+    fn subscription_response_exposes_only_display_fields_and_preserves_unknowns() {
+        let observed = Utc.with_ymd_and_hms(2026, 9, 14, 0, 0, 0).unwrap();
+        let response = AccountSubscriptionData::from(ProviderSubscription {
+            starts_at: None,
+            expires_at: observed,
+            will_renew: None,
+            billing_period: None,
+            billing_currency: Some("USD".to_owned()),
+            observed_at: observed,
+        });
+        assert_eq!(
+            serde_json::to_value(response).unwrap(),
+            json!({
+                "startsAt": null, "expiresAt": "2026-09-14T00:00:00+00:00",
+                "willRenew": null, "billingPeriod": null, "billingCurrency": "USD",
+                "observedAt": "2026-09-14T00:00:00+00:00"
+            })
+        );
+    }
+
+    #[test]
+    fn personal_info_response_preserves_subscription_when_profile_fails() {
+        let observed = Utc.with_ymd_and_hms(2026, 9, 14, 0, 0, 0).unwrap();
+        let response = AccountPersonalInfoData::from(AccountPersonalInfo {
+            profile: Err(AdminError::bad_gateway("上游服务请求失败")),
+            subscription: Some(ProviderSubscription {
+                starts_at: None,
+                expires_at: observed,
+                will_renew: None,
+                billing_period: None,
+                billing_currency: None,
+                observed_at: observed,
+            }),
+        });
+        let value = serde_json::to_value(response).unwrap();
+        assert!(value["profile"].is_null());
+        assert_eq!(value["profileError"], "上游服务请求失败");
+        assert_eq!(
+            value["subscription"]["expiresAt"],
+            "2026-09-14T00:00:00+00:00"
+        );
+        assert_eq!(value.as_object().unwrap().len(), 3);
+    }
+
+    #[test]
+    fn personal_info_response_preserves_unknown_subscription_and_profile_error() {
+        let response = AccountPersonalInfoData::from(AccountPersonalInfo {
+            profile: Err(AdminError::unavailable("Provider 服务暂不可用")),
+            subscription: None,
+        });
+        assert_eq!(
+            serde_json::to_value(response).unwrap(),
+            json!({
+                "profile": null,
+                "profileError": "Provider 服务暂不可用",
+                "subscription": null,
+            })
+        );
+    }
+}
+
 mod query {
     use gateway_admin::model::accounts::{AccountSortField, AccountStatus, SortDirection};
     use gateway_api::admin::accounts::ListQuery;
@@ -340,6 +414,7 @@ mod response {
     #[test]
     fn account_usage_view_should_keep_unobserved_numbers_null() {
         let view = AccountUsageView {
+            window_label_display: "周/月额度窗口".to_owned(),
             request_count: None,
             request_count_display: "-".to_owned(),
             input_tokens: None,
@@ -374,6 +449,7 @@ mod response {
             models: Vec::new(),
         };
         let value = serde_json::to_value(view).expect("serialize account usage");
+        assert_eq!(value["windowLabelDisplay"], "周/月额度窗口");
         assert!(value["inputTokens"].is_null());
         assert!(value["totalTokens"].is_null());
         assert!(value["reasoningTokens"].is_null());

backend/crates/gateway-api/tests/admin/accounts/presenter.rs

@@ -0,0 +1,69 @@
+use gateway_admin::model::{
+    provider_credentials::AccountUsagePeriod,
+    quota_forecast::{AccountQuotaForecast, AccountQuotaForecastReport, QuotaForecastSource},
+};
+use gateway_api::admin::accounts::AccountQuotaForecastData;
+
+#[test]
+fn quota_forecast_projection_only_exposes_capacity_and_preserves_null_zero() {
+    let now = "2026-09-12T00:00:00Z".parse().unwrap();
+    let forecast = AccountQuotaForecast {
+        period: AccountUsagePeriod::Weekly,
+        target_seconds: 7 * 86_400,
+        extrapolated: false,
+        source: Some(QuotaForecastSource {
+            label: "周额度".to_owned(),
+            used_percent: Some(100.0),
+            observed_at: Some(now),
+            reset_at: now,
+            tokens: Some(1_000_000),
+            usd: Some(0.1234),
+        }),
+        unavailable_reason: None,
+        low_sample: false,
+        incomplete_cost: true,
+        incomplete_tokens: false,
+        estimated_tokens: Some(1_000_000),
+        estimated_usd: None,
+        remaining_tokens: Some(0),
+        remaining_usd: None,
+    };
+    let mut monthly = forecast.clone();
+    monthly.period = AccountUsagePeriod::Monthly;
+    monthly.extrapolated = true;
+    monthly.target_seconds = 30 * 86_400;
+    let view = AccountQuotaForecastData::from(AccountQuotaForecastReport {
+        account_id: "acct_forecast".to_owned(),
+        generated_at: now,
+        forecasts: [forecast, monthly],
+    });
+    let value = serde_json::to_value(view).unwrap();
+    assert_eq!(value["accountId"], "acct_forecast");
+    assert_eq!(value["generatedAt"], "2026-09-12T08:00:00+08:00");
+    let week = &value["forecasts"][0];
+    assert_eq!(week["estimatedTokens"], 1_000_000);
+    assert_eq!(week["estimatedTokensDisplay"], "1M");
+    assert!(week["estimatedUsd"].is_null());
+    assert_eq!(week["estimatedUsdDisplay"], "—");
+    assert_eq!(week["remainingTokensDisplay"], "0");
+    assert_eq!(
+        week["source"],
+        serde_json::json!({
+            "label": "周额度",
+            "usedPercent": 100.0,
+            "usedPercentDisplay": "100.0%",
+            "observedAt": "2026-09-12T08:00:00+08:00",
+            "observedAtDisplay": "2026-09-12 08:00:00",
+            "resetAt": "2026-09-12T08:00:00+08:00",
+            "tokensDisplay": "1M",
+            "usdDisplay": "$0.1234"
+        })
+    );
+    assert!(week.get("method").is_none());
+    assert!(week.get("methodDisplay").is_none());
+    assert!(value.get("generatedAtDisplay").is_none());
+    assert_eq!(value["forecasts"][1]["period"], "monthly");
+    assert_eq!(value["forecasts"][1]["targetDays"], 30.0);
+    assert_eq!(value["forecasts"][1]["extrapolated"], true);
+    assert!(value.get("account").is_none());
+}

backend/crates/gateway-api/tests/admin/client_keys.rs

@@ -10,6 +10,71 @@ use serde_json::json;
 
 use super::{AdminTestFixture, AdminTestState};
 
+#[test]
+fn custom_client_keys_preserve_migrated_values_and_redact_debug() {
+    for value in [
+        "q".to_owned(),
+        "sk-old!@/key+=value".to_owned(),
+        "x".repeat(8192),
+    ] {
+        let request: CreateClientKeyRequest = serde_json::from_value(json!({
+            "name": "migration", "customKey": value, "groupIds": [],
+            "maxConcurrency": 2, "requestsPerMinute": 0
+        }))
+        .unwrap();
+        let debug = format!("{request:?}");
+        assert!(debug.contains("[REDACTED]"));
+        let command = request.into_command().unwrap();
+        assert_eq!(command.custom_key.unwrap().expose_for_auth(), value);
+    }
+    let secret = "legacy-key-should-not-leak";
+    let request: CreateClientKeyRequest = serde_json::from_value(json!({
+        "name": "migration", "customKey": secret, "groupIds": [],
+        "maxConcurrency": 0, "requestsPerMinute": 0
+    }))
+    .unwrap();
+    assert!(!format!("{request:?}").contains(secret));
+    assert!(!format!("{:?}", request.into_command().unwrap()).contains(secret));
+}
+
+#[test]
+fn custom_client_key_is_optional_and_only_rejects_untransportable_values() {
+    let payload = json!({"name": "migration", "groupIds": [], "maxConcurrency": 0,
+        "requestsPerMinute": 0});
+    for value in [None, Some(json!(null)), Some(json!(""))] {
+        let mut payload = payload.clone();
+        if let Some(value) = value {
+            payload["customKey"] = value;
+        }
+        let command = serde_json::from_value::<CreateClientKeyRequest>(payload)
+            .unwrap()
+            .into_command()
+            .unwrap();
+        assert!(command.custom_key.is_none());
+    }
+    for value in [
+        " key",
+        "key ",
+        "key with spaces",
+        "key\n",
+        "key\tvalue",
+        "密钥",
+    ] {
+        let mut payload = payload.clone();
+        payload["customKey"] = json!(value);
+        let error = serde_json::from_value::<CreateClientKeyRequest>(payload)
+            .unwrap()
+            .into_command()
+            .unwrap_err();
+        assert_eq!(error.field(), "customKey");
+        assert!(!format!("{error:?}").contains(value));
+    }
+    let mut update = payload;
+    update["id"] = json!("key_existing");
+    update["customKey"] = json!("replacement-credential");
+    assert!(serde_json::from_value::<UpdateClientKeyRequest>(update).is_err());
+}
+
 #[test]
 fn budget_inputs_preserve_decimal_precision_and_omitted_updates() {
     let payload = json!({"name": "budget", "groupIds": [], "maxConcurrency": 3,
@@ -50,44 +115,6 @@ fn budget_inputs_preserve_decimal_precision_and_omitted_updates() {
     );
 }
 
-#[tokio::test]
-async fn budget_reconciliation_routes_require_an_admin_session() {
-    use axum::{
-        body::Body,
-        http::{Request, StatusCode},
-    };
-    use tower::ServiceExt as _;
-    let fixture = AdminTestFixture::new().await;
-    let router = client_keys::router::<AdminTestState>().with_state(fixture.state());
-    for (method, path, body) in [
-        (
-            "GET",
-            "/api/admin/client-keys/unresolved-charges?id=key_1",
-            "",
-        ),
-        (
-            "POST",
-            "/api/admin/client-keys/reconcile-charge",
-            r#"{"id":"key_1","requestId":"req_charge","amountUsd":"0","reason":"verified"}"#,
-        ),
-    ] {
-        let response = router
-            .clone()
-            .oneshot(
-                Request::builder()
-                    .method(method)
-                    .uri(path)
-                    .header("content-type", "application/json")
-                    .header("x-request-id", "req_auth_budget")
-                    .body(Body::from(body))
-                    .unwrap(),
-            )
-            .await
-            .unwrap();
-        assert_eq!(response.status(), StatusCode::UNAUTHORIZED);
-    }
-}
-
 #[test]
 fn client_key_queries_should_reject_unknown_zero_and_oversized_fields() {
     let unknown = serde_json::from_value::<ListClientKeysQuery>(json!({ "other": true }));
@@ -101,10 +128,6 @@ fn client_key_queries_should_reject_unknown_zero_and_oversized_fields() {
         "search": "a".repeat(257)
     }))
     .expect("deserialize oversized search");
-    let secret_search = serde_json::from_value::<ListClientKeysQuery>(json!({
-        "search": format!("sk_{}", "a".repeat(43))
-    }))
-    .expect("deserialize secret search");
     let invalid_sort = serde_json::from_value::<ListClientKeysQuery>(json!({
         "sortBy": "plaintextKey",
         "sortDirection": "asc"
@@ -130,13 +153,6 @@ fn client_key_queries_should_reject_unknown_zero_and_oversized_fields() {
             .field(),
         "search"
     );
-    assert_eq!(
-        secret_search
-            .into_command()
-            .expect_err("reject full key in search")
-            .field(),
-        "search"
-    );
     assert_eq!(
         invalid_sort
             .into_command()
@@ -178,6 +194,16 @@ fn client_key_queries_should_reject_unknown_zero_and_oversized_fields() {
     );
 }
 
+#[test]
+fn client_key_name_search_does_not_interpret_names_as_credentials() {
+    let name = format!("sk_{}", "a".repeat(43));
+    let command = serde_json::from_value::<ListClientKeysQuery>(json!({ "search": name }))
+        .unwrap()
+        .into_command()
+        .unwrap();
+    assert_eq!(command.search.as_deref(), Some(name.as_str()));
+}
+
 #[test]
 fn client_key_mutations_should_validate_text_limits_and_unknown_fields() {
     let valid = serde_json::from_value::<CreateClientKeyRequest>(json!({
@@ -320,7 +346,7 @@ fn client_key_responses_should_keep_shape_and_redact_creation_debug() {
     assert_eq!(list["items"][0]["dailyLimitUsd"], "0");
     assert_eq!(list["items"][0]["weeklyLimitUsd"], "0");
     assert_eq!(list["items"][0]["dailyUsedUsd"], "0");
-    assert_eq!(list["items"][0]["unresolvedRequests"], 0);
+    assert!(list["items"][0].get("unresolvedRequests").is_none());
     assert_eq!(
         DateTime::parse_from_rfc3339(
             list["items"][0]["lastUsedAt"]

backend/crates/gateway-api/tests/admin/errors.rs

@@ -318,3 +318,187 @@ async fn admin_auth_failures_should_use_stable_chinese_contracts() {
         ]
     );
 }
+
+mod provider {
+    use std::time::SystemTime;
+
+    use chrono::Utc;
+    use gateway_admin::{
+        model::{
+            Revision,
+            accounts::{AccountPageItem, AccountRecord},
+        },
+        ports::provider::{ProviderAdminError, ProviderAdminErrorKind as Kind},
+    };
+    use gateway_core::{
+        account::{
+            AccountStatusFacts, AccountWeight, CredentialState, QuotaState, resolve_account_status,
+        },
+        routing::ProviderKind,
+    };
+    use tower_http::request_id::{MakeRequestUuid, PropagateRequestIdLayer, SetRequestIdLayer};
+
+    use super::*;
+
+    #[tokio::test]
+    async fn provider_public_errors_survive_import_and_refresh_http_handlers() {
+        let fixture = AdminTestFixture::new().await;
+        fixture.auth.insert_session("valid-session");
+        for provider in ["openai", "xai"] {
+            *fixture.account.lock().unwrap() = Some(account(provider));
+            for (kind, status, code, message) in [
+                (Kind::Invalid, 400, 40001, "刷新令牌已被使用，请重新授权"),
+                (
+                    Kind::Conflict,
+                    409,
+                    40901,
+                    "令牌刷新繁忙，请等待当前刷新完成后重试",
+                ),
+                (
+                    Kind::BadGateway,
+                    502,
+                    50201,
+                    "OpenAI 返回的 Codex PAT 身份资料不完整或格式无效，请稍后重试",
+                ),
+                (
+                    Kind::Unavailable,
+                    503,
+                    50301,
+                    "暂时无法向 OpenAI 验证 Codex PAT，请稍后重试",
+                ),
+                (
+                    Kind::Ambiguous,
+                    502,
+                    50202,
+                    "令牌刷新结果未知，请先核对账号状态，不要立即重复刷新",
+                ),
+            ] {
+                *fixture.provider_error.lock().unwrap() = Some(
+                    ProviderAdminError::new(kind)
+                        .with_public_message(message)
+                        .with_message("raw-upstream-secret-marker"),
+                );
+                for (path, body) in [
+                    (
+                        "/api/admin/accounts/refresh",
+                        json!({"accountId": "acct_error_test"}),
+                    ),
+                    (
+                        "/api/admin/accounts/import",
+                        json!({"provider": provider, "data": {"accessToken": "at-synthetic-test"}}),
+                    ),
+                ] {
+                    let response = send(&fixture, path, body).await;
+                    assert_eq!(response.headers()["x-request-id"], "req_admin_errors");
+                    let actual = response_json(response).await;
+                    assert_eq!(
+                        actual,
+                        (
+                            StatusCode::from_u16(status).unwrap(),
+                            "application/json".to_owned(),
+                            json!({"code": code, "message": message, "data": null}),
+                        )
+                    );
+                    assert!(!actual.2.to_string().contains("raw-upstream-secret-marker"));
+                    assert_eq!(fixture.auth.audit_count(), 0);
+                }
+            }
+        }
+    }
+
+    #[tokio::test]
+    async fn provider_diagnostics_without_public_messages_still_use_safe_fallbacks() {
+        let fixture = AdminTestFixture::new().await;
+        fixture.auth.insert_session("valid-session");
+        for (kind, status, code, message) in [
+            (Kind::BadGateway, 502, 50201, "上游服务请求失败"),
+            (Kind::Unavailable, 503, 50301, "Provider 服务暂不可用"),
+            (
+                Kind::Ambiguous,
+                502,
+                50202,
+                "上游执行结果未知，请刷新状态后再决定是否重试",
+            ),
+            (Kind::Internal, 500, 50001, "服务内部错误"),
+        ] {
+            let error = ProviderAdminError::new(kind).with_message("private-provider-diagnostics");
+            // 即使 Provider 错标了公开文案，未知内部异常仍不得通过 500 信封下发。
+            *fixture.provider_error.lock().unwrap() = Some(if kind == Kind::Internal {
+                error.with_public_message("internal-detail-must-stay-hidden")
+            } else {
+                error
+            });
+            let response = send(
+                &fixture,
+                "/api/admin/accounts/import",
+                json!({"provider": "openai", "data": {}}),
+            )
+            .await;
+            let (actual_status, _, body) = response_json(response).await;
+            assert_eq!(actual_status.as_u16(), status);
+            assert_eq!(
+                body,
+                json!({"code": code, "message": message, "data": null})
+            );
+        }
+    }
+
+    async fn send(fixture: &AdminTestFixture, path: &str, body: Value) -> axum::response::Response {
+        let mut request = request(Method::POST, path, Body::from(body.to_string()));
+        request
+            .headers_mut()
+            .insert(header::COOKIE, SESSION_COOKIE.parse().unwrap());
+        request
+            .headers_mut()
+            .insert(header::CONTENT_TYPE, "application/json".parse().unwrap());
+        let name = header::HeaderName::from_static("x-request-id");
+        app(fixture.state())
+            .layer(PropagateRequestIdLayer::new(name.clone()))
+            .layer(SetRequestIdLayer::new(name, MakeRequestUuid))
+            .oneshot(request)
+            .await
+            .unwrap()
+    }
+
+    fn account(provider: &str) -> AccountPageItem {
+        let now = Utc::now();
+        let facts = AccountStatusFacts {
+            enabled: true,
+            credential_state: CredentialState::Ready,
+            access_token_expires_at: None,
+            quota: QuotaState::unknown(),
+            rate_limited_until: None,
+            last_error_reason: None,
+            last_error_message: None,
+        };
+        AccountPageItem {
+            account: AccountRecord {
+                id: "acct_error_test".to_owned(),
+                provider_kind: ProviderKind::new(provider).unwrap(),
+                groups: Vec::new(),
+                name: "synthetic account".to_owned(),
+                email: None,
+                upstream_user_id: None,
+                upstream_account_id: None,
+                plan_type: None,
+                authentication_kind: "oauth".to_owned(),
+                credential_revision: Revision::new(1).unwrap(),
+                has_refresh_token: true,
+                access_token_expires_at: None,
+                next_refresh_at: None,
+                enabled: facts.enabled,
+                concurrency_limit: None,
+                weight: AccountWeight::default(),
+                outbound_proxy: None,
+                credential_state: facts.credential_state,
+                credential_observed_at: now,
+                quota: facts.quota,
+                last_error_reason: None,
+                last_error_message: None,
+                created_at: now,
+                updated_at: now,
+            },
+            projection: resolve_account_status(&facts, SystemTime::now()),
+        }
+    }
+}

backend/crates/gateway-api/tests/admin/mod.rs

@@ -40,12 +40,11 @@ use gateway_admin::{
         },
         provider_credentials::{
             AuthorizationCommit, AuthorizationStarted, CompleteAuthorization, CredentialDetails,
-            CredentialImportCommit, CredentialImportResult, CredentialListQuery,
-            CredentialMutationResult, CredentialPage, CredentialRotationCommit,
-            PendingAuthorizationMutation, PrepareCredentialImport, PrepareCredentialRefresh,
-            PrepareCredentialRotation, PreparedAuthorizationCommit, PreparedCredentialImport,
-            PreparedCredentialRotation, ProviderExport, ProviderExportCredentialInput,
-            ProviderModels, ProviderQuota,
+            CredentialImportCommit, CredentialImportResult, CredentialMutationResult,
+            CredentialRotationCommit, PendingAuthorizationMutation, PrepareCredentialImport,
+            PrepareCredentialRefresh, PrepareCredentialRotation, PreparedAuthorizationCommit,
+            PreparedCredentialImport, PreparedCredentialRotation, ProviderExport,
+            ProviderExportCredentialInput, ProviderModels, ProviderQuota,
         },
         settings::{
             AdminApiKey, AdminApiKeyMutation, ModelMappings, ReplaceRuntimeSettings,
@@ -82,6 +81,7 @@ mod auth;
 mod client_keys;
 mod errors;
 mod observability;
+mod proxies;
 mod settings;
 mod system;
 mod wire;
@@ -96,6 +96,8 @@ pub(super) struct AdminTestFixture {
     pub ops_errors: Arc<Mutex<Vec<OpsError>>>,
     pub dashboard_observation: Arc<Mutex<Option<DashboardObservation>>>,
     pub dashboard_summary_range: Arc<Mutex<Option<TimeRange>>>,
+    pub provider_error: Arc<Mutex<Option<ProviderAdminError>>>,
+    pub account: Arc<Mutex<Option<AccountPageItem>>>,
 }
 
 impl AdminTestFixture {
@@ -115,6 +117,8 @@ impl AdminTestFixture {
         let ops_errors = Arc::new(Mutex::new(Vec::new()));
         let dashboard_observation = Arc::new(Mutex::new(None));
         let dashboard_summary_range = Arc::new(Mutex::new(None));
+        let provider_error = Arc::new(Mutex::new(None));
+        let account = Arc::new(Mutex::new(None));
         let unused = Arc::new(UnusedStore {
             usage_records: Arc::clone(&usage_records),
             usage_detail: Arc::clone(&usage_detail),
@@ -122,9 +126,15 @@ impl AdminTestFixture {
             ops_errors: Arc::clone(&ops_errors),
             dashboard_observation: Arc::clone(&dashboard_observation),
             dashboard_summary_range: Arc::clone(&dashboard_summary_range),
+            account: Arc::clone(&account),
         });
         let stores = AdminStorePorts::new(
-            AdminAccountStorePorts::new(unused.clone(), unused.clone(), account_groups.clone()),
+            AdminAccountStorePorts::new(
+                unused.clone(),
+                unused.clone(),
+                account_groups.clone(),
+                Arc::new(proxies::MemoryProxies::default()),
+            ),
             auth.clone(),
             client_keys.clone(),
             unused,
@@ -132,8 +142,8 @@ impl AdminTestFixture {
             gateway_admin::ports::backup::BackupStorePorts::disabled(),
         );
         let providers: Vec<Arc<dyn ProviderAdmin>> = vec![
-            Arc::new(UnusedProvider::new("openai")),
-            Arc::new(UnusedProvider::new("xai")),
+            Arc::new(UnusedProvider::new("openai", Arc::clone(&provider_error))),
+            Arc::new(UnusedProvider::new("xai", Arc::clone(&provider_error))),
         ];
         let bundle = gateway_admin::initialize(
             AdminConfig {
@@ -144,7 +154,7 @@ impl AdminTestFixture {
             stores,
             providers,
             Arc::new(NoopSnapshot),
-            Arc::new(NoopProbe),
+            (Arc::new(NoopProbe), Arc::new(proxies::SuccessfulProbe)),
             Arc::new(StaticClientDistribution),
             system,
         )
@@ -160,6 +170,8 @@ impl AdminTestFixture {
             ops_errors,
             dashboard_observation,
             dashboard_summary_range,
+            provider_error,
+            account,
         }
     }
 
@@ -697,6 +709,7 @@ struct UnusedStore {
     ops_errors: Arc<Mutex<Vec<OpsError>>>,
     dashboard_observation: Arc<Mutex<Option<DashboardObservation>>>,
     dashboard_summary_range: Arc<Mutex<Option<TimeRange>>>,
+    account: Arc<Mutex<Option<AccountPageItem>>>,
 }
 
 #[async_trait]
@@ -711,9 +724,12 @@ impl AccountStore for UnusedStore {
 
     async fn load_account(
         &self,
-        _: &str,
+        id: &str,
         _: AccountRuntimeSnapshot,
     ) -> AdminStoreResult<Option<AccountPageItem>> {
+        if let Some(account) = self.account.lock().expect("account").as_ref() {
+            return Ok((account.account.id == id).then(|| account.clone()));
+        }
         Err(unavailable("account"))
     }
 
@@ -732,12 +748,11 @@ impl AccountStore for UnusedStore {
         Err(unavailable("account quota window usage"))
     }
 
-    async fn list_credentials(
+    async fn load_quota_forecast_history(
         &self,
-        _: &ProviderKind,
-        _: CredentialListQuery,
-    ) -> AdminStoreResult<CredentialPage> {
-        Err(unavailable("credential list"))
+        _: &AccountUsageWindowQuery,
+    ) -> AdminStoreResult<gateway_admin::model::quota_forecast_sampling::QuotaForecastHistory> {
+        Err(unavailable("quota forecast history"))
     }
 
     async fn credential_details(
@@ -930,12 +945,14 @@ impl ObservabilityStore for UnusedStore {
 
 struct UnusedProvider {
     kind: ProviderKind,
+    error: Arc<Mutex<Option<ProviderAdminError>>>,
 }
 
 impl UnusedProvider {
-    fn new(kind: &str) -> Self {
+    fn new(kind: &str, error: Arc<Mutex<Option<ProviderAdminError>>>) -> Self {
         Self {
             kind: ProviderKind::new(kind).expect("provider kind"),
+            error,
         }
     }
 }
@@ -976,7 +993,12 @@ impl ProviderAdmin for UnusedProvider {
         &self,
         _: PrepareCredentialImport,
     ) -> Result<PreparedCredentialImport, ProviderAdminError> {
-        Err(unsupported_provider())
+        Err(self
+            .error
+            .lock()
+            .expect("provider error")
+            .clone()
+            .unwrap_or_else(unsupported_provider))
     }
 
     async fn start_authorization(
@@ -1004,7 +1026,12 @@ impl ProviderAdmin for UnusedProvider {
         &self,
         _: PrepareCredentialRefresh,
     ) -> Result<PreparedCredentialRotation, ProviderAdminError> {
-        Err(unsupported_provider())
+        Err(self
+            .error
+            .lock()
+            .expect("provider error")
+            .clone()
+            .unwrap_or_else(unsupported_provider))
     }
 
     async fn quota(

backend/crates/gateway-api/tests/admin/observability/response.rs

@@ -518,6 +518,98 @@ async fn usage_detail_should_keep_attempt_snapshot_contract() {
     );
 }
 
+#[tokio::test]
+async fn zero_attempt_failure_detail_keeps_missing_upstream_facts_and_preparation_trace() {
+    use axum::{
+        body::{Body, to_bytes},
+        http::{Request, StatusCode, header},
+    };
+    use gateway_admin::model::observability::{RequestOutcome, UsageDetail};
+    use gateway_api::admin::observability;
+    use tower::ServiceExt as _;
+
+    use crate::admin::{AdminTestFixture, AdminTestState};
+
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    let mut record = usage_record_with_account("req_early", "", "", "", "", Utc::now());
+    record.provider_kind = None;
+    record.provider_account_ref = None;
+    record.provider_account_name = None;
+    record.provider_account_email = None;
+    record.provider_account_authentication_kind = None;
+    record.upstream_model_id = None;
+    record.upstream_transport = None;
+    record.http_version = None;
+    record.attempt_count = 0;
+    record.upstream_send_state = "not_sent".to_owned();
+    record.downstream_committed_at = None;
+    record.outcome = RequestOutcome::Failed;
+    record.client_status_code = Some(503);
+    record.upstream_status_code = None;
+    record.error_kind = Some("no_available_provider".to_owned());
+    record.error_message = Some("no upstream account is available".to_owned());
+    record.input_tokens = None;
+    record.output_tokens = None;
+    record.cached_tokens = None;
+    record.cache_write_tokens = None;
+    record.reasoning_tokens = None;
+    record.image_input_tokens = None;
+    record.image_output_tokens = None;
+    record.total_tokens = None;
+    let trace = json!({
+        "events": [
+            {"stage": "attempt.started", "attemptIndex": 1},
+            {"stage": "attempt.failed", "attemptIndex": 1},
+            {"stage": "request.finished", "data": {"attempts": 0}},
+        ]
+    });
+    fixture.usage_detail.lock().unwrap().replace(UsageDetail {
+        request: record,
+        attempts: Vec::new(),
+        trace: Some(trace.clone()),
+        related_requests: Vec::new(),
+    });
+    let response = observability::router::<AdminTestState>()
+        .with_state(fixture.state())
+        .oneshot(
+            Request::builder()
+                .uri("/api/admin/usage/records/detail?id=req_early")
+                .header(header::COOKIE, "cpr_admin_session=valid-session")
+                .header("x-request-id", "req_zero_attempt_detail")
+                .body(Body::empty())
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(response.status(), StatusCode::OK);
+    let body = to_bytes(response.into_body(), 1024 * 1024).await.unwrap();
+    let value: serde_json::Value = serde_json::from_slice(&body).unwrap();
+    let data = &value["data"];
+    assert_eq!(data["requestId"], "req_early");
+    assert_eq!(data["attemptCount"], 0);
+    assert_eq!(data["attempts"], json!([]));
+    // 明细仍沿用全局 best-effort 合同，不从预备 trace 推断完整尝试列表。
+    assert_eq!(data["attemptsComplete"], false);
+    assert_eq!(data["trace"], trace);
+    assert_eq!(data["logicalOutcome"], "failed");
+    assert_eq!(data["clientStatusCode"], 503);
+    assert_eq!(data["message"], "no upstream account is available");
+    assert_eq!(data["model"], "coding");
+    assert!(data.get("upstreamStatusCode").is_none());
+    assert!(data.get("httpVersion").is_none());
+    for field in [
+        "provider",
+        "accountId",
+        "upstreamModel",
+        "upstreamTransport",
+        "inputTokens",
+        "outputTokens",
+    ] {
+        assert_eq!(data.get(field), Some(&serde_json::Value::Null), "{field}");
+    }
+}
+
 #[tokio::test]
 async fn ops_errors_should_keep_account_label_and_authentication_contract() {
     use axum::{

backend/crates/gateway-api/tests/admin/proxies.rs

@@ -0,0 +1,520 @@
+use std::sync::Mutex;
+
+use async_trait::async_trait;
+use axum::{
+    body::{Body, to_bytes},
+    http::{Request, StatusCode, header},
+};
+use chrono::Utc;
+use gateway_admin::{
+    model::{MutationContext, Revision, proxies::*},
+    ports::{
+        proxy::{ProxyProbe, ProxyStore},
+        store::{AdminStoreError, AdminStoreErrorKind, AdminStoreResult},
+    },
+};
+use gateway_core::account::{OutboundProxy, ProviderAccountId};
+use serde_json::{Value, json};
+use tower::ServiceExt as _;
+
+use super::{AdminTestFixture, AdminTestState};
+
+#[derive(Default)]
+pub(super) struct MemoryProxies(Mutex<Option<ProxyRecord>>);
+
+fn missing() -> AdminStoreError {
+    AdminStoreError::new(AdminStoreErrorKind::NotFound, "proxy", "missing proxy")
+}
+
+#[async_trait]
+impl ProxyStore for MemoryProxies {
+    async fn remove_account(
+        &self,
+        proxy_id: &str,
+        account_id: &ProviderAccountId,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        if proxy_id != "proxy_test" || account_id.as_str() != "acct_linked" {
+            return Err(AdminStoreError::new(
+                AdminStoreErrorKind::Conflict,
+                "proxy account",
+                "changed binding",
+            ));
+        }
+        Ok(Revision::new(4).unwrap())
+    }
+
+    async fn reserve_import(
+        &self,
+        _: &str,
+    ) -> AdminStoreResult<gateway_admin::ports::proxy::ProxyImportReservation> {
+        Err(missing())
+    }
+    async fn list(&self, query: ProxyListQuery) -> AdminStoreResult<ProxyPage> {
+        let items: Vec<_> = self.0.lock().unwrap().iter().cloned().collect();
+        Ok(ProxyPage {
+            total: u64::try_from(items.len()).unwrap(),
+            items,
+            page: query.page,
+            page_size: query.page_size.get(),
+        })
+    }
+    async fn get(&self, _: &str) -> AdminStoreResult<ProxyRecord> {
+        self.0.lock().unwrap().clone().ok_or_else(missing)
+    }
+    async fn list_accounts(
+        &self,
+        query: ProxyAccountListQuery,
+    ) -> AdminStoreResult<ProxyAccountPage> {
+        if !self
+            .0
+            .lock()
+            .unwrap()
+            .as_ref()
+            .is_some_and(|record| record.id == query.proxy_id)
+        {
+            return Err(missing());
+        }
+        Ok(ProxyAccountPage {
+            items: vec![ProxyAccountRef {
+                id: "acct_linked".to_owned(),
+                name: "工作账号".to_owned(),
+                email: Some("work@example.invalid".to_owned()),
+                provider_kind: "openai".to_owned(),
+                authentication_kind: "oauth".to_owned(),
+                plan_type: Some("plus".to_owned()),
+                plan_type_display: None,
+                groups: vec![],
+                enabled: true,
+            }],
+            total: 21,
+            page: query.page,
+            page_size: query.page_size.get(),
+        })
+    }
+    async fn create(
+        &self,
+        command: NewProxy,
+        _: &MutationContext,
+    ) -> AdminStoreResult<ProxyMutation> {
+        let record = ProxyRecord {
+            id: "proxy_test".to_owned(),
+            name: command.name,
+            proxy: command.proxy,
+            revision: Revision::new(1).unwrap(),
+            account_count: 0,
+            last_test: None,
+            last_test_at: None,
+            created_at: Utc::now(),
+            updated_at: Utc::now(),
+        };
+        *self.0.lock().unwrap() = Some(record.clone());
+        Ok(ProxyMutation {
+            config_revision: record.revision,
+            record,
+        })
+    }
+    async fn update(
+        &self,
+        command: UpdateProxy,
+        _: &MutationContext,
+    ) -> AdminStoreResult<ProxyMutation> {
+        let mut stored = self.0.lock().unwrap();
+        let record = stored.as_mut().ok_or_else(missing)?;
+        record.name = command.name;
+        if let Some(proxy) = command.proxy {
+            record.proxy = proxy;
+        }
+        record.revision = Revision::new(record.revision.get() + 1).unwrap();
+        Ok(ProxyMutation {
+            config_revision: record.revision,
+            record: record.clone(),
+        })
+    }
+    async fn delete(
+        &self,
+        _: &str,
+        _: Revision,
+        _: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        self.0.lock().unwrap().take().ok_or_else(missing)?;
+        Ok(Revision::new(3).unwrap())
+    }
+    async fn record_test(
+        &self,
+        _: &str,
+        _: Revision,
+        result: ProxyTestResult,
+        _: &MutationContext,
+    ) -> AdminStoreResult<ProxyRecord> {
+        let mut stored = self.0.lock().unwrap();
+        let record = stored.as_mut().ok_or_else(missing)?;
+        record.last_test = Some(result);
+        record.last_test_at = Some(Utc::now());
+        Ok(record.clone())
+    }
+}
+
+pub(super) struct SuccessfulProbe;
+
+#[async_trait]
+impl ProxyProbe for SuccessfulProbe {
+    async fn test(&self, proxy: &OutboundProxy) -> ProxyTestResult {
+        assert_eq!(
+            proxy.expose_url(),
+            "http://test-user:private-password@proxy.example:8080/"
+        );
+        ProxyTestResult {
+            success: true,
+            latency_ms: 15,
+            exit_ip: Some("203.0.113.2".parse().unwrap()),
+            message: "Connected".to_owned(),
+        }
+    }
+}
+
+async fn request(
+    fixture: &AdminTestFixture,
+    path: &str,
+    body: Option<Value>,
+    authenticated: bool,
+) -> (StatusCode, Value) {
+    let mut builder = Request::builder()
+        .header("x-request-id", "req_proxy_tests")
+        .uri(path)
+        .method(if body.is_some() { "POST" } else { "GET" });
+    if authenticated {
+        builder = builder.header(header::COOKIE, "cpr_admin_session=valid-session");
+    }
+    let body = body.map_or_else(Body::empty, |body| Body::from(body.to_string()));
+    let response = gateway_api::admin::proxies::router::<AdminTestState>()
+        .with_state(fixture.state())
+        .oneshot(
+            builder
+                .header(header::CONTENT_TYPE, "application/json")
+                .body(body)
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    let status = response.status();
+    let body = to_bytes(response.into_body(), 64 * 1024).await.unwrap();
+    let text = std::str::from_utf8(&body).unwrap();
+    assert!(!text.contains("private-password"));
+    assert!(!text.contains("test-user"));
+    (status, serde_json::from_slice(&body).unwrap())
+}
+
+#[tokio::test]
+async fn proxy_routes_save_reload_test_rename_and_delete_without_exposing_credentials() {
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    let (status, created) = request(
+        &fixture,
+        "/api/admin/proxies/create",
+        Some(json!({
+            "name": "  Office  ", "proxyUrl": "http://test-user:private-password@proxy.example:8080"
+        })),
+        true,
+    )
+    .await;
+    assert_eq!(status, StatusCode::CREATED);
+    assert_eq!(created["data"]["record"]["name"], "Office");
+    assert_eq!(created["data"]["record"]["hasAuthentication"], true);
+    assert_eq!(
+        created["data"]["record"]["endpoint"],
+        "http://proxy.example:8080/"
+    );
+    assert!(created["data"]["record"].get("proxyUrl").is_none());
+    assert_eq!(created["data"]["record"]["accountCount"], 0);
+    assert!(created["data"]["record"].get("accounts").is_none());
+
+    let (status, linked) = request(
+        &fixture,
+        "/api/admin/proxies/accounts?proxyId=proxy_test&page=2&pageSize=20&search=work",
+        None,
+        true,
+    )
+    .await;
+    assert_eq!(status, StatusCode::OK);
+    assert_eq!(
+        linked["data"]["page"],
+        json!({"page":2,"pageSize":20,"total":21,"totalPages":2})
+    );
+    assert_eq!(
+        linked["data"]["items"],
+        json!([{
+            "id":"acct_linked", "name":"工作账号", "email":"work@example.invalid",
+            "provider":"openai", "enabled":true, "authenticationKind":"oauth",
+            "planType":"plus", "planTypeDisplay":"Plus", "groups":[]
+        }])
+    );
+
+    let (status, tested) = request(
+        &fixture,
+        "/api/admin/proxies/test",
+        Some(json!({"id": "proxy_test", "revision": 1})),
+        true,
+    )
+    .await;
+    assert_eq!(status, StatusCode::OK);
+    assert_eq!(tested["data"]["lastTest"]["exitIp"], "203.0.113.2");
+    let (_, listed) = request(
+        &fixture,
+        "/api/admin/proxies?page=1&pageSize=20",
+        None,
+        true,
+    )
+    .await;
+    assert_eq!(listed["data"]["items"][0], tested["data"]);
+
+    let (status, _) = request(
+        &fixture,
+        "/api/admin/proxies/update",
+        Some(json!({"id": "proxy_test", "revision": 1, "name": "Renamed"})),
+        true,
+    )
+    .await;
+    assert_eq!(status, StatusCode::OK);
+    let (status, _) = request(
+        &fixture,
+        "/api/admin/proxies/test",
+        Some(json!({"id": "proxy_test", "revision": 1})),
+        true,
+    )
+    .await;
+    assert_eq!(status, StatusCode::CONFLICT);
+    let (status, _) = request(
+        &fixture,
+        "/api/admin/proxies/test",
+        Some(json!({"id": "proxy_test", "revision": 2})),
+        true,
+    )
+    .await;
+    assert_eq!(status, StatusCode::OK);
+    let (status, _) = request(
+        &fixture,
+        "/api/admin/proxies/delete",
+        Some(json!({"id": "proxy_test", "revision": 2})),
+        true,
+    )
+    .await;
+    assert_eq!(status, StatusCode::OK);
+    let (_, listed) = request(&fixture, "/api/admin/proxies", None, true).await;
+    assert_eq!(listed["data"]["page"]["total"], 0);
+}
+
+#[tokio::test]
+async fn proxy_probe_checks_unsaved_address_without_creating_or_changing_records() {
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    let draft = json!({
+        "proxyUrl": "http://test-user:private-password@proxy.example:8080"
+    });
+    let (status, probed) = request(
+        &fixture,
+        "/api/admin/proxies/probe",
+        Some(draft.clone()),
+        true,
+    )
+    .await;
+    assert_eq!(status, StatusCode::OK);
+    assert_eq!(
+        probed["data"],
+        json!({"success": true, "latencyMs": 15, "exitIp": "203.0.113.2", "message": "Connected"})
+    );
+    let (_, listed) = request(&fixture, "/api/admin/proxies", None, true).await;
+    assert_eq!(listed["data"]["page"]["total"], 0);
+
+    let (_, created) = request(
+        &fixture,
+        "/api/admin/proxies/create",
+        Some(json!({"name": "Saved", "proxyUrl": "http://saved.example:8080"})),
+        true,
+    )
+    .await;
+    let (status, _) = request(&fixture, "/api/admin/proxies/probe", Some(draft), true).await;
+    assert_eq!(status, StatusCode::OK);
+    let (_, listed) = request(&fixture, "/api/admin/proxies", None, true).await;
+    assert_eq!(listed["data"]["items"][0], created["data"]["record"]);
+}
+
+#[tokio::test]
+async fn proxy_probe_rejects_empty_or_invalid_addresses() {
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    for (body, expected) in [
+        (json!({"proxyUrl": ""}), StatusCode::BAD_REQUEST),
+        (json!({"proxyUrl": null}), StatusCode::UNPROCESSABLE_ENTITY),
+        (json!({}), StatusCode::UNPROCESSABLE_ENTITY),
+        (
+            json!({"proxyUrl": "ftp://test-user:private-password@proxy.example"}),
+            StatusCode::UNPROCESSABLE_ENTITY,
+        ),
+        (
+            json!({"proxyUrl": "http://proxy.example:8080", "name": "Not saved"}),
+            StatusCode::UNPROCESSABLE_ENTITY,
+        ),
+    ] {
+        assert_eq!(
+            request(&fixture, "/api/admin/proxies/probe", Some(body), true)
+                .await
+                .0,
+            expected
+        );
+    }
+}
+
+#[tokio::test]
+async fn proxy_routes_require_auth_and_reject_invalid_input() {
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    assert_eq!(
+        request(&fixture, "/api/admin/proxies", None, false).await.0,
+        StatusCode::UNAUTHORIZED
+    );
+    assert_eq!(
+        request(
+            &fixture,
+            "/api/admin/proxies/accounts?proxyId=proxy_test",
+            None,
+            false
+        )
+        .await
+        .0,
+        StatusCode::UNAUTHORIZED
+    );
+    for query in [
+        "",
+        "proxyId=",
+        "proxyId=proxy_test&page=0",
+        "proxyId=proxy_test&pageSize=0",
+        "proxyId=proxy_test&pageSize=201",
+        "proxyId=proxy_test&search=%00",
+        "proxyId=proxy_test&unknown=1",
+    ] {
+        assert_eq!(
+            request(
+                &fixture,
+                &format!("/api/admin/proxies/accounts?{query}"),
+                None,
+                true
+            )
+            .await
+            .0,
+            StatusCode::BAD_REQUEST
+        );
+    }
+    assert_eq!(
+        request(
+            &fixture,
+            "/api/admin/proxies/accounts?proxyId=missing",
+            None,
+            true
+        )
+        .await
+        .0,
+        StatusCode::NOT_FOUND
+    );
+    for action in [
+        "create",
+        "update",
+        "delete",
+        "test",
+        "probe",
+        "accounts/remove",
+    ] {
+        assert_eq!(
+            request(
+                &fixture,
+                &format!("/api/admin/proxies/{action}"),
+                Some(json!({})),
+                false
+            )
+            .await
+            .0,
+            StatusCode::UNAUTHORIZED
+        );
+    }
+    for query in ["page=0", "pageSize=0", "pageSize=201", "unknown=1"] {
+        assert_eq!(
+            request(&fixture, &format!("/api/admin/proxies?{query}"), None, true)
+                .await
+                .0,
+            StatusCode::BAD_REQUEST
+        );
+    }
+    for body in [
+        json!({"name":" ","proxyUrl":"http://proxy.example:8080"}),
+        json!({"name":"Invalid","proxyUrl":""}),
+    ] {
+        assert_eq!(
+            request(&fixture, "/api/admin/proxies/create", Some(body), true)
+                .await
+                .0,
+            StatusCode::BAD_REQUEST
+        );
+    }
+    let (status, _) = request(
+        &fixture,
+        "/api/admin/proxies/create",
+        Some(json!({"name":"Invalid","proxyUrl":"ftp://test-user:private-password@proxy.example"})),
+        true,
+    )
+    .await;
+    assert_eq!(status, StatusCode::UNPROCESSABLE_ENTITY);
+}
+
+#[tokio::test]
+async fn proxy_account_removal_validates_binding_and_input() {
+    let fixture = AdminTestFixture::new().await;
+    fixture.auth.insert_session("valid-session");
+    for (body, expected) in [
+        (
+            json!({"proxyId":"", "accountId":"acct_linked"}),
+            StatusCode::BAD_REQUEST,
+        ),
+        (
+            json!({"proxyId":"proxy_test", "accountId":""}),
+            StatusCode::BAD_REQUEST,
+        ),
+        (
+            json!({"proxyId":"proxy_test", "accountId":"invalid"}),
+            StatusCode::BAD_REQUEST,
+        ),
+        (
+            json!({"proxyId":"proxy_test", "accountId":"acct_linked", "enabled":false}),
+            StatusCode::UNPROCESSABLE_ENTITY,
+        ),
+    ] {
+        assert_eq!(
+            request(
+                &fixture,
+                "/api/admin/proxies/accounts/remove",
+                Some(body),
+                true
+            )
+            .await
+            .0,
+            expected
+        );
+    }
+    let (status, result) = request(
+        &fixture,
+        "/api/admin/proxies/accounts/remove",
+        Some(json!({"proxyId":"proxy_test", "accountId":"acct_linked"})),
+        true,
+    )
+    .await;
+    assert_eq!(status, StatusCode::OK);
+    assert_eq!(result["data"], json!({"configRevision":4}));
+    let (status, result) = request(
+        &fixture,
+        "/api/admin/proxies/accounts/remove",
+        Some(json!({"proxyId":"proxy_previous", "accountId":"acct_linked"})),
+        true,
+    )
+    .await;
+    assert_eq!(status, StatusCode::CONFLICT);
+    assert_eq!(result["message"], "账号的代理绑定已变化，请刷新后重试");
+}

backend/crates/gateway-api/tests/architecture.rs

@@ -50,6 +50,7 @@ fn source_tree_should_match_frozen_machine_manifest() {
         "src/admin/observability/routes.rs",
         "src/admin/observability/wire.rs",
         "src/admin/presenter.rs",
+        "src/admin/proxies.rs",
         "src/admin/settings.rs",
         "src/admin/system.rs",
         "src/admin/wire.rs",
@@ -88,7 +89,9 @@ fn test_tree_should_match_frozen_rust_mirror() {
     actual.sort();
     let mut expected = vec![
         "tests/admin/account_groups.rs",
+        "tests/admin/accounts/handlers.rs",
         "tests/admin/accounts/mod.rs",
+        "tests/admin/accounts/presenter.rs",
         "tests/admin/auth.rs",
         "tests/admin/client_keys.rs",
         "tests/admin/errors.rs",
@@ -96,6 +99,7 @@ fn test_tree_should_match_frozen_rust_mirror() {
         "tests/admin/observability/mod.rs",
         "tests/admin/observability/query.rs",
         "tests/admin/observability/response.rs",
+        "tests/admin/proxies.rs",
         "tests/admin/settings.rs",
         "tests/admin/system.rs",
         "tests/admin/wire.rs",
@@ -110,7 +114,9 @@ fn test_tree_should_match_frozen_rust_mirror() {
         "tests/openai/endpoint.rs",
         "tests/openai/responses/http.rs",
         "tests/openai/responses/mod.rs",
+        "tests/openai/responses/request.rs",
         "tests/openai/responses/websocket/connection.rs",
+        "tests/openai/responses/websocket/forward.rs",
         "tests/openai/responses/websocket/mod.rs",
         "tests/openai/responses/websocket/protocol.rs",
         "tests/openai/router.rs",

backend/crates/gateway-api/tests/openai/auth.rs

@@ -76,10 +76,28 @@ fn bearer_client_api_key_should_reject_empty_bearer_token() {
 }
 
 #[test]
-fn bearer_client_api_key_should_reject_non_gateway_key_prefix() {
-    let mut headers = HeaderMap::new();
-    headers.insert(AUTHORIZATION, HeaderValue::from_static("Bearer xai-secret"));
+fn bearer_client_api_key_should_accept_migrated_formats_without_rewriting() {
+    for key in [
+        "q".to_owned(),
+        "sk-old/key+value=:!@".to_owned(),
+        "x".repeat(8192),
+    ] {
+        let mut headers = HeaderMap::new();
+        headers.insert(
+            AUTHORIZATION,
+            HeaderValue::from_str(&format!("Bearer {key}")).unwrap(),
+        );
+        assert_eq!(bearer_client_api_key(&headers), Ok(key.as_str()));
+    }
+}
 
+#[test]
+fn bearer_client_api_key_should_reject_whitespace_inside_tokens() {
+    let mut headers = HeaderMap::new();
+    headers.insert(
+        AUTHORIZATION,
+        HeaderValue::from_static("Bearer key with spaces"),
+    );
     assert_eq!(
         bearer_client_api_key(&headers),
         Err(ClientApiKeyAuthError::InvalidKeyFormat)

backend/crates/gateway-api/tests/openai/images/mod.rs

@@ -258,6 +258,7 @@ async fn image_routes_should_not_decode_bodies_and_should_preserve_both_directio
             .oneshot(
                 Request::post(*path)
                     .header(AUTHORIZATION, "Bearer sk_images_test")
+                    .header("x-request-id", "caller-image-request")
                     .header("content-type", "application/json")
                     .header("x-codex-image-turn-id", "turn_image_route")
                     .header("session-id", "root-image-session")
@@ -268,6 +269,11 @@ async fn image_routes_should_not_decode_bodies_and_should_preserve_both_directio
             .await
             .expect("image response");
         assert_eq!(response.status(), StatusCode::CREATED);
+        assert_eq!(response.headers()["x-request-id"], "req_images_test");
+        assert_eq!(
+            response.headers()["x-gateway-request-id"],
+            "req_images_test"
+        );
         assert_eq!(
             response.headers().get("x-image-rate-limit"),
             Some(&"42".parse().expect("header value"))
@@ -315,6 +321,11 @@ async fn image_route_should_return_the_exact_upstream_error_response() {
         .expect("image response");
 
     assert_eq!(response.status(), StatusCode::UNPROCESSABLE_ENTITY);
+    assert_eq!(response.headers()["x-request-id"], "req_images_test");
+    assert_eq!(
+        response.headers()["x-gateway-request-id"],
+        "req_images_test"
+    );
     assert_eq!(
         response.headers().get("content-type"),
         Some(&"application/problem+json".parse().expect("content type"))

backend/crates/gateway-api/tests/openai/models.rs

@@ -1,4 +1,4 @@
-use std::sync::Arc;
+use std::sync::{Arc, Mutex};
 
 use axum::{
     body::{Body, to_bytes},
@@ -11,7 +11,8 @@ use gateway_core::engine::execution::{
 };
 use gateway_core::error::{GatewayError, GatewayErrorKind};
 use gateway_core::routing::{
-    ModelPresentation, ModelServiceTier, PublicModelId, PublicModelProfile,
+    ModelPresentation, ModelServiceTier, ProviderCatalogUnavailable, PublicModelDescriptor,
+    PublicModelId, PublicModelProfile,
 };
 use tower::ServiceExt;
 
@@ -19,28 +20,63 @@ use super::{api_router, authenticated_client, authenticated_client_with_min_vers
 
 pub(super) struct ModelsExecution {
     client: AuthenticatedClient,
-    profiles: bool,
+    presentation: Option<ModelPresentation>,
+    native: Option<Result<Vec<PublicModelDescriptor>, ProviderCatalogUnavailable>>,
+    requested_versions: Mutex<Vec<String>>,
 }
 
 impl ModelsExecution {
     pub(super) fn new() -> Arc<Self> {
         Arc::new(Self {
             client: authenticated_client("sk_models_test"),
-            profiles: false,
+            presentation: None,
+            native: None,
+            requested_versions: Mutex::default(),
         })
     }
 
     fn with_profiles() -> Arc<Self> {
+        Self::with_presentation(
+            ModelPresentation::new(
+                Some("Grok 4.5".to_owned()),
+                Some("xAI Grok 4.5 frontier model.".to_owned()),
+            )
+            .with_reasoning(
+                Some("medium".to_owned()),
+                ["low", "medium", "high", "xhigh"]
+                    .map(str::to_owned)
+                    .to_vec(),
+            )
+            .with_context_window_tokens(Some(500_000))
+            .with_max_context_window_tokens(Some(900_000))
+            .with_image_input(true)
+            .with_agent_tools(true, true)
+            .with_service_tiers(vec![
+                ModelServiceTier::new(
+                    "priority",
+                    "Fast",
+                    "Route the request through Codex fast mode.",
+                )
+                .with_speed_tier("fast"),
+            ]),
+        )
+    }
+
+    fn with_presentation(presentation: ModelPresentation) -> Arc<Self> {
         Arc::new(Self {
             client: authenticated_client("sk_models_test"),
-            profiles: true,
+            presentation: Some(presentation),
+            native: None,
+            requested_versions: Mutex::default(),
         })
     }
 
     fn with_cli_min() -> Arc<Self> {
         Arc::new(Self {
             client: authenticated_client_with_min_versions("sk_models_test", None, Some("0.40.0")),
-            profiles: false,
+            presentation: None,
+            native: None,
+            requested_versions: Mutex::default(),
         })
     }
 
@@ -51,12 +87,49 @@ impl ModelsExecution {
                 Some("26.825.51511"),
                 None,
             ),
-            profiles: false,
+            presentation: None,
+            native: None,
+            requested_versions: Mutex::default(),
         })
     }
+
+    fn profiles(&self) -> Vec<PublicModelProfile> {
+        self.presentation
+            .as_ref()
+            .map(|presentation| {
+                PublicModelProfile::new(
+                    PublicModelId::new("grok-4.5").expect("model"),
+                    presentation.clone(),
+                )
+            })
+            .into_iter()
+            .collect()
+    }
 }
 
 impl ExecutionService for ModelsExecution {
+    fn client_model_catalog<'a>(
+        &'a self,
+        _client: &'a AuthenticatedClient,
+        protocol: &'a str,
+        version: &'a str,
+    ) -> BoxFuture<'a, Result<Vec<PublicModelDescriptor>, ProviderCatalogUnavailable>> {
+        Box::pin(async move {
+            assert_eq!(protocol, "codex");
+            self.requested_versions
+                .lock()
+                .expect("versions")
+                .push(version.to_owned());
+            self.native.clone().unwrap_or_else(|| {
+                Ok(self
+                    .profiles()
+                    .into_iter()
+                    .map(PublicModelDescriptor::Adapted)
+                    .collect())
+            })
+        })
+    }
+
     fn authenticate(
         &self,
         plaintext: &str,
@@ -75,36 +148,6 @@ impl ExecutionService for ModelsExecution {
             .collect()
     }
 
-    fn public_model_profiles(&self, _: &AuthenticatedClient) -> Vec<PublicModelProfile> {
-        if !self.profiles {
-            return Vec::new();
-        }
-        vec![PublicModelProfile::new(
-            PublicModelId::new("grok-4.5").expect("model"),
-            ModelPresentation::new(
-                Some("Grok 4.5".to_owned()),
-                Some("xAI Grok 4.5 frontier model.".to_owned()),
-            )
-            .with_reasoning(
-                Some("medium".to_owned()),
-                ["low", "medium", "high", "xhigh"]
-                    .map(str::to_owned)
-                    .to_vec(),
-            )
-            .with_context_window_tokens(Some(500_000))
-            .with_image_input(true)
-            .with_agent_tools(true, true)
-            .with_service_tiers(vec![
-                ModelServiceTier::new(
-                    "priority",
-                    "Fast",
-                    "Route the request through Codex fast mode.",
-                )
-                .with_speed_tier("fast"),
-            ]),
-        )]
-    }
-
     fn contains_public_model(&self, _: &AuthenticatedClient, model: &PublicModelId) -> bool {
         matches!(model.as_str(), "model-a" | "model-b")
     }
@@ -138,6 +181,102 @@ fn authorized_request(path: &str) -> Request<Body> {
         .expect("build models request")
 }
 
+#[tokio::test]
+async fn native_catalog_preserves_complete_objects_and_only_rewrites_alias_slug() {
+    let original = serde_json::json!({
+        "slug": "gpt-native", "display_name": "Official name", "priority": 47,
+        "base_instructions": "Official instructions\nDo not replace.",
+        "model_messages": {"token_budget": "upstream template", "future_section": [null, {"a": true}]},
+        "service_tiers": [{"id": "priority", "name": "Fast", "description": "Official speed tier"}],
+        "tool_mode": "code_mode_only", "use_responses_lite": true,
+        "future_field": {"nested": [1, null, "value"]}, "explicit_null": null
+    });
+    let entry = |model: &str| PublicModelDescriptor::Native {
+        model: PublicModelId::new(model).expect("model"),
+        payload: gateway_core::operation::RawJsonPayload::new(
+            "codex",
+            serde_json::to_vec(&original).expect("JSON").into(),
+        )
+        .expect("payload"),
+    };
+    let execution = Arc::new(ModelsExecution {
+        client: authenticated_client("sk_models_test"),
+        presentation: None,
+        native: Some(Ok(vec![entry("gpt-native"), entry("my-alias")])),
+        requested_versions: Mutex::default(),
+    });
+    let response = api_router(execution.clone())
+        .await
+        .oneshot(authorized_request(
+            "/v1/models?client_version=0.154.0-alpha.3",
+        ))
+        .await
+        .expect("response");
+    assert_eq!(response.status(), StatusCode::OK);
+    assert_eq!(response.headers()["cache-control"], "private, no-store");
+    assert!(response.headers().get("etag").is_none());
+    let body = to_bytes(response.into_body(), usize::MAX)
+        .await
+        .expect("body");
+    let value: serde_json::Value = serde_json::from_slice(&body).expect("JSON");
+    assert_eq!(value["models"][0], original);
+    let mut alias = original;
+    alias["slug"] = serde_json::json!("my-alias");
+    assert_eq!(value["models"][1], alias);
+    assert_eq!(
+        *execution.requested_versions.lock().expect("versions"),
+        ["0.154.0-alpha.3"]
+    );
+}
+
+#[tokio::test]
+async fn native_catalog_failure_does_not_publish_a_synthetic_or_empty_success() {
+    let execution = Arc::new(ModelsExecution {
+        client: authenticated_client("sk_models_test"),
+        presentation: None,
+        native: Some(Err(ProviderCatalogUnavailable)),
+        requested_versions: Mutex::default(),
+    });
+    let response = api_router(execution)
+        .await
+        .oneshot(authorized_request("/v1/models?client_version=0.154.0"))
+        .await
+        .expect("response");
+    assert_eq!(response.status(), StatusCode::SERVICE_UNAVAILABLE);
+    let body = to_bytes(response.into_body(), usize::MAX)
+        .await
+        .expect("body");
+    let value: serde_json::Value = serde_json::from_slice(&body).expect("JSON");
+    assert_eq!(value["error"]["code"], "model_catalog_unavailable");
+    assert!(value.get("models").is_none());
+}
+
+#[tokio::test]
+async fn catalog_rejects_unbounded_or_control_character_versions_before_fetching() {
+    for version in [
+        "x".repeat(65),
+        "0.154.0%0A".to_owned(),
+        "0.154.0%20".to_owned(),
+    ] {
+        let execution = ModelsExecution::new();
+        let response = api_router(execution.clone())
+            .await
+            .oneshot(authorized_request(&format!(
+                "/v1/models?client_version={version}"
+            )))
+            .await
+            .expect("response");
+        assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+        assert!(
+            execution
+                .requested_versions
+                .lock()
+                .expect("versions")
+                .is_empty()
+        );
+    }
+}
+
 #[tokio::test]
 async fn models_should_encode_the_service_visible_catalog() {
     let response = api_router(ModelsExecution::new())
@@ -289,6 +428,7 @@ async fn models_should_encode_provider_profiles_for_current_codex_clients() {
     assert_eq!(model["slug"], "grok-4.5");
     assert_eq!(model["default_reasoning_level"], "medium");
     assert_eq!(model["context_window"], 500_000);
+    assert_eq!(model["max_context_window"], 900_000);
     assert_eq!(model["apply_patch_tool_type"], "freeform");
     assert_eq!(model["additional_speed_tiers"], serde_json::json!(["fast"]));
     assert_eq!(
@@ -322,6 +462,34 @@ async fn models_should_encode_provider_profiles_for_current_codex_clients() {
     );
 }
 
+#[tokio::test]
+async fn models_should_preserve_unknown_context_windows() {
+    for (context_window, max_context_window) in
+        [(None, None), (Some(272_000), None), (None, Some(872_000))]
+    {
+        let presentation = ModelPresentation::default()
+            .with_context_window_tokens(context_window)
+            .with_max_context_window_tokens(max_context_window);
+        let response = api_router(ModelsExecution::with_presentation(presentation))
+            .await
+            .oneshot(authorized_request("/v1/models?client_version=0.145.0"))
+            .await
+            .expect("list Codex models response");
+        assert_eq!(response.status(), StatusCode::OK);
+        let body = to_bytes(response.into_body(), usize::MAX)
+            .await
+            .expect("read Codex models body");
+        let value: serde_json::Value = serde_json::from_slice(&body).expect("models JSON");
+        let model = &value["models"][0];
+
+        assert_eq!(model["context_window"], serde_json::json!(context_window));
+        assert_eq!(
+            model["max_context_window"],
+            serde_json::json!(max_context_window)
+        );
+    }
+}
+
 #[tokio::test]
 async fn models_should_keep_the_codex_contract_when_profiles_are_empty() {
     let response = api_router(ModelsExecution::new())

backend/crates/gateway-api/tests/openai/responses/http.rs

@@ -1,4 +1,5 @@
 use std::collections::VecDeque;
+use std::io::Read;
 use std::net::{IpAddr, SocketAddr};
 use std::sync::{
     Arc, Mutex,
@@ -11,7 +12,7 @@ use axum::{
     extract::connect_info::ConnectInfo,
     http::{
         HeaderMap, HeaderValue, Request, StatusCode,
-        header::{AUTHORIZATION, CONTENT_TYPE},
+        header::{AUTHORIZATION, CONTENT_ENCODING, CONTENT_LENGTH, CONTENT_TYPE},
     },
 };
 use bytes::Bytes;
@@ -21,7 +22,7 @@ use gateway_core::engine::execution::{
     AuthenticatedClient, ClientAuthenticationError, ExecutionService, ExecutionSession,
     StartExecution, StartProviderExecution, StartedExecution,
 };
-use gateway_core::engine::{CommitRequirement, CoordinatedEvent, EngineError};
+use gateway_core::engine::{CommitRequirement, CoordinatedEvent, EngineError, ModelRequestId};
 use gateway_core::error::{
     ClientVisibleUpstreamError, ClientVisibleUpstreamResponse, GatewayError, GatewayErrorKind,
     ProviderError, ProviderErrorKind,
@@ -32,7 +33,8 @@ use gateway_core::event::{
 };
 use gateway_core::operation::{Operation, OperationKind};
 use gateway_core::routing::PublicModelId;
-use gateway_core::upstream::UpstreamSendState;
+use gateway_core::upstream::{OpaqueUpstreamValue, UpstreamSendState};
+use gateway_protocol::openai::sse::{encode_sse_event, parse_sse_events};
 use serde_json::{Value, json};
 
 use gateway_api::openai::responses::{collect_execution_response, stream_execution_response};
@@ -451,9 +453,26 @@ async fn captured_client_context(
 async fn captured_http_request(
     provider_name: &str,
     body: Value,
-    mut headers: HeaderMap,
+    headers: HeaderMap,
     peer_address: Option<SocketAddr>,
 ) -> CapturedClientContext {
+    let (response, observed) = http_request_with_body(
+        provider_name,
+        body.to_string().into(),
+        headers,
+        peer_address,
+    )
+    .await;
+    assert_eq!(response.status(), StatusCode::INTERNAL_SERVER_ERROR);
+    observed.expect("captured request context")
+}
+
+async fn http_request_with_body(
+    provider_name: &str,
+    body: Bytes,
+    mut headers: HeaderMap,
+    peer_address: Option<SocketAddr>,
+) -> (axum::response::Response, Option<CapturedClientContext>) {
     headers.insert(
         AUTHORIZATION,
         "Bearer sk_context_test".parse().expect("authorization"),
@@ -464,7 +483,7 @@ async fn captured_http_request(
         client: authenticated_client_for_provider("sk_context_test", provider_name),
     });
     let mut request = Request::post("/v1/responses")
-        .body(Body::from(body.to_string()))
+        .body(Body::from(body))
         .expect("context request");
     *request.headers_mut() = headers;
     if let Some(peer_address) = peer_address {
@@ -475,12 +494,75 @@ async fn captured_http_request(
         .oneshot(request)
         .await
         .expect("context response");
-    assert_eq!(response.status(), StatusCode::INTERNAL_SERVER_ERROR);
-    observed
-        .lock()
-        .expect("context capture lock")
-        .clone()
-        .expect("captured request context")
+    let observed = observed.lock().expect("context capture lock").clone();
+    (response, observed)
+}
+
+#[tokio::test]
+async fn compressed_http_requests_should_preserve_execution_context_without_transport_headers() {
+    let body = json!({
+        "model": "model-a", "input": "hello", "previous_response_id": "resp_previous",
+        "prompt_cache_key": "cache-key", "client_metadata": {"source": "test"}
+    });
+    let mut headers = HeaderMap::new();
+    headers.insert(CONTENT_TYPE, HeaderValue::from_static("application/json"));
+    headers.insert("session_id", HeaderValue::from_static("session-test"));
+    let expected = captured_http_request("openai", body.clone(), headers.clone(), None).await;
+    for encoding in ["gzip", "deflate", "zstd"] {
+        let compressed = super::request::encode_body(encoding, body.to_string().as_bytes());
+        let mut headers = headers.clone();
+        headers.insert(CONTENT_ENCODING, HeaderValue::from_static(encoding));
+        headers.insert(
+            CONTENT_LENGTH,
+            HeaderValue::from_str(&compressed.len().to_string()).expect("compressed length"),
+        );
+        let (response, observed) =
+            http_request_with_body("openai", compressed.into(), headers, None).await;
+        // 捕获执行器在解码成功后主动返回 500；正文和业务头应与未压缩请求一致，
+        // 压缩编码及长度不能泄漏到已解压正文的上游协议上下文。
+        assert_eq!(response.status(), StatusCode::INTERNAL_SERVER_ERROR);
+        assert_eq!(observed.as_ref(), Some(&expected), "{encoding}");
+    }
+}
+
+#[tokio::test]
+async fn invalid_compressed_http_requests_should_fail_before_execution() {
+    for (encoding, body, code, message) in [
+        (
+            "gzip",
+            Bytes::from_static(b"broken gzip"),
+            "invalid_json",
+            "Request body must be valid JSON.",
+        ),
+        (
+            "br",
+            Bytes::from_static(b"{}"),
+            "unsupported_content_encoding",
+            "Content-Encoding `br` is not supported.",
+        ),
+        (
+            "zstd",
+            super::request::encode_body("zstd", std::io::repeat(0).take(64 * 1024 * 1024 + 1))
+                .into(),
+            "request_too_large",
+            "Decompressed request body exceeds the allowed size.",
+        ),
+    ] {
+        let headers = HeaderMap::from_iter([
+            (CONTENT_ENCODING, HeaderValue::from_static(encoding)),
+            (CONTENT_TYPE, HeaderValue::from_static("application/json")),
+        ]);
+        let (response, observed) = http_request_with_body("openai", body, headers, None).await;
+        assert_eq!(response.status(), StatusCode::BAD_REQUEST, "{encoding}");
+        assert!(observed.is_none(), "invalid body must not start execution");
+        let body = to_bytes(response.into_body(), 4096)
+            .await
+            .expect("error body");
+        assert_eq!(
+            serde_json::from_slice::<Value>(&body).expect("error JSON"),
+            json!({"error": {"type": "invalid_request_error", "code": code, "message": message}})
+        );
+    }
 }
 
 async fn captured_http_compaction(provider_name: &str) -> CapturedClientContext {
@@ -1491,6 +1573,113 @@ async fn streaming_upstream_wire_failure_should_not_be_rewritten_as_a_gateway_er
     );
 }
 
+#[tokio::test]
+async fn streaming_upstream_error_event_should_be_translated_to_response_failed_for_sse() {
+    let trace = Arc::new(Trace::default());
+    let error_data = json!({
+        "type": "error",
+        "error": {
+            "type": "service_unavailable_error",
+            "code": "server_is_overloaded",
+            "message": "Our servers are currently overloaded. Please try again later.",
+            "param": null,
+            "future_error_field": {"keep": true}
+        },
+        "sequence_number": 2,
+        "future_event_field": {"keep": true}
+    });
+    let projected_error_frame = Bytes::from(encode_sse_event("error", &error_data.to_string()));
+    let error_wire = ProviderEvent::wire(
+        ProtocolWireEvent::json_with_raw_sse_metadata(
+            "openai",
+            Some("error".to_owned()),
+            error_data,
+            projected_error_frame,
+            None,
+            None,
+        )
+        .expect("valid upstream error wire"),
+    );
+    let started_wire = ProviderEvent::canonical_with_wire(
+        vec![started()],
+        ProtocolWireEvent::json(
+            "openai",
+            Some("response.created".to_owned()),
+            json!({
+                "type": "response.created",
+                "response": {
+                    "id": "resp_test",
+                    "model": "public-model",
+                    "status": "in_progress",
+                    "future_response_field": {"keep": true}
+                }
+            }),
+        )
+        .expect("valid upstream started wire"),
+    );
+    let session = FakeSession::streaming(
+        Arc::clone(&trace),
+        vec![
+            NextStep::Event(CoordinatedEvent::single(
+                started_wire,
+                CommitRequirement::CommitBeforeDelivery,
+            )),
+            NextStep::Event(CoordinatedEvent::single(
+                error_wire,
+                CommitRequirement::AlreadyCommitted,
+            )),
+            NextStep::Error(EngineError::Provider(ProviderError::new(
+                ProviderErrorKind::UpstreamCapacityUnavailable,
+                UpstreamSendState::Sent,
+            ))),
+        ],
+    );
+
+    let response = stream_execution_response(Box::new(session), None).await;
+    let body = to_bytes(response.into_body(), usize::MAX)
+        .await
+        .expect("read SSE body");
+    let body = String::from_utf8(body.to_vec()).expect("SSE is UTF-8");
+    let events = parse_sse_events(&body).expect("translated SSE should parse");
+    let failed = events
+        .iter()
+        .find(|event| event.event.as_deref() == Some("response.failed"))
+        .expect("translated response.failed event");
+    let failed: Value = serde_json::from_str(&failed.data).expect("response.failed JSON");
+
+    assert_eq!(
+        (
+            failed,
+            body.matches("event: response.failed").count(),
+            body.contains("event: error\n"),
+            body.ends_with("data: [DONE]\n\n"),
+        ),
+        (
+            json!({
+                "type": "response.failed",
+                "response": {
+                    "id": "resp_test",
+                    "model": "public-model",
+                    "status": "failed",
+                    "error": {
+                        "type": "service_unavailable_error",
+                        "code": "server_is_overloaded",
+                        "message": "Our servers are currently overloaded. Please try again later.",
+                        "param": null,
+                        "future_error_field": {"keep": true}
+                    },
+                    "future_response_field": {"keep": true}
+                },
+                "sequence_number": 2,
+                "future_event_field": {"keep": true}
+            }),
+            1,
+            false,
+            true,
+        )
+    );
+}
+
 #[tokio::test]
 async fn atomic_uncommitted_upstream_failure_batch_should_be_forwarded_once() {
     let trace = Arc::new(Trace::default());
@@ -1738,3 +1927,223 @@ fn response_status_from_body(body: &[u8]) -> Option<String> {
     let value: serde_json::Value = serde_json::from_slice(body).ok()?;
     value.pointer("/error/code")?.as_str().map(str::to_owned)
 }
+
+const MODEL_REQUEST_ID: &str = "req_model_correlation";
+
+struct SessionExecution {
+    client: AuthenticatedClient,
+    session: Mutex<Option<Box<dyn ExecutionSession>>>,
+}
+
+impl ExecutionService for SessionExecution {
+    fn authenticate(&self, _: &str) -> Result<AuthenticatedClient, ClientAuthenticationError> {
+        Ok(self.client.clone())
+    }
+
+    fn public_models(&self, _: &AuthenticatedClient) -> Vec<PublicModelId> {
+        Vec::new()
+    }
+
+    fn contains_public_model(&self, _: &AuthenticatedClient, _: &PublicModelId) -> bool {
+        true
+    }
+
+    fn start(
+        &self,
+        request: StartExecution,
+    ) -> BoxFuture<'_, Result<StartedExecution, GatewayError>> {
+        Box::pin(async move {
+            Ok(StartedExecution {
+                request_id: ModelRequestId::new(MODEL_REQUEST_ID).unwrap(),
+                created_at: std::time::SystemTime::now(),
+                stream: request.metadata.stream,
+                session: self.session.lock().unwrap().take().expect("one execution"),
+            })
+        })
+    }
+
+    fn start_provider_endpoint(
+        &self,
+        _: StartProviderExecution,
+    ) -> BoxFuture<'_, Result<StartedExecution, GatewayError>> {
+        Box::pin(async { panic!("Responses must use model execution") })
+    }
+}
+
+async fn response(
+    provider: &str,
+    session: FakeSession,
+    streaming: bool,
+) -> axum::response::Response {
+    let execution = Arc::new(SessionExecution {
+        client: authenticated_client_for_provider("sk_correlation_test", provider),
+        session: Mutex::new(Some(Box::new(session))),
+    });
+    api_router(execution)
+        .await
+        .oneshot(
+            Request::post("/v1/responses")
+                .header(AUTHORIZATION, "Bearer sk_correlation_test")
+                .header("x-request-id", "caller-chosen-not-a-model-id")
+                .header("user-agent", "AnotherTerminal/1.0")
+                .body(Body::from(
+                    json!({
+                        "model": "model-a", "input": "synthetic", "stream": streaming
+                    })
+                    .to_string(),
+                ))
+                .unwrap(),
+        )
+        .await
+        .unwrap()
+}
+
+fn headers(values: &[(&str, &'static str)]) -> Vec<ProviderResponseHeader> {
+    values
+        .iter()
+        .map(|(name, value)| {
+            ProviderResponseHeader::new(*name, Bytes::from_static(value.as_bytes()))
+        })
+        .collect()
+}
+
+fn failed_session(streaming: bool, error: EngineError) -> FakeSession {
+    let trace = Arc::new(Trace::default());
+    if streaming {
+        FakeSession::streaming(trace, vec![NextStep::Error(error)])
+    } else {
+        FakeSession::buffered(trace, Vec::new()).with_collect_error(error)
+    }
+}
+
+#[tokio::test]
+async fn response_ids_are_provider_and_client_independent() {
+    let cases: &[(&[(&str, &str)], &str)] = &[
+        (&[], MODEL_REQUEST_ID),
+        (&[("x-request-id", "upstream-primary")], "upstream-primary"),
+        (&[("x-oai-request-id", "upstream-alias")], "upstream-alias"),
+        (
+            &[
+                ("x-request-id", "upstream-primary"),
+                ("x-oai-request-id", "upstream-alias"),
+            ],
+            "upstream-primary",
+        ),
+        (
+            &[
+                ("x-request-id", " "),
+                ("x-oai-request-id", "upstream-alias"),
+            ],
+            "upstream-alias",
+        ),
+        (&[("x-request-id", "")], MODEL_REQUEST_ID),
+    ];
+    for provider in ["openai", "xai"] {
+        for streaming in [false, true] {
+            for (upstream_headers, expected) in cases {
+                let trace = Arc::new(Trace::default());
+                let session = if streaming {
+                    FakeSession::streaming(
+                        trace,
+                        vec![
+                            NextStep::Event(delivery(
+                                started(),
+                                CommitRequirement::CommitBeforeDelivery,
+                            )),
+                            NextStep::Event(delivery(
+                                completed(),
+                                CommitRequirement::AlreadyCommitted,
+                            )),
+                            NextStep::FinalizeSuccess,
+                        ],
+                    )
+                } else {
+                    FakeSession::buffered(trace, vec![started(), completed()])
+                }
+                .with_response_headers(headers(upstream_headers));
+                let response = response(provider, session, streaming).await;
+                assert_eq!(response.status(), StatusCode::OK);
+                assert_eq!(response.headers()["x-request-id"], *expected);
+                assert_eq!(response.headers()["x-gateway-request-id"], MODEL_REQUEST_ID);
+                assert!(
+                    !to_bytes(response.into_body(), 64 * 1024)
+                        .await
+                        .unwrap()
+                        .is_empty()
+                );
+            }
+        }
+    }
+}
+
+#[tokio::test]
+async fn failure_ids_prefer_the_actual_error_over_session_headers() {
+    for provider in ["openai", "xai"] {
+        for streaming in [false, true] {
+            for upstream_headers in [vec![], headers(&[("x-oai-request-id", "actual-error")])] {
+                let expected = if upstream_headers.is_empty() {
+                    MODEL_REQUEST_ID
+                } else {
+                    "actual-error"
+                };
+                let raw =
+                    Bytes::from_static(br#"{"error":{"message":"synthetic upstream detail"}}"#);
+                let error =
+                    ProviderError::new(ProviderErrorKind::InvalidRequest, UpstreamSendState::Sent)
+                        .with_client_visible_upstream_response(
+                            ClientVisibleUpstreamResponse::new(
+                                422,
+                                Some(b"application/json".to_vec()),
+                                raw.clone(),
+                            )
+                            .with_headers(upstream_headers),
+                        );
+                let session = failed_session(streaming, EngineError::Provider(error))
+                    .with_response_headers(headers(&[("x-request-id", "earlier-session")]));
+                let response = response(provider, session, streaming).await;
+                assert_eq!(response.status(), StatusCode::UNPROCESSABLE_ENTITY);
+                assert_eq!(response.headers()["x-request-id"], expected);
+                assert_eq!(response.headers()["x-gateway-request-id"], MODEL_REQUEST_ID);
+                assert_eq!(to_bytes(response.into_body(), 4096).await.unwrap(), raw);
+            }
+
+            let error =
+                ProviderError::new(ProviderErrorKind::Transport, UpstreamSendState::Ambiguous)
+                    .with_status(503)
+                    .with_upstream_request_id(OpaqueUpstreamValue::new("body-read-error"));
+            let session = failed_session(streaming, EngineError::Provider(error))
+                .with_response_headers(headers(&[
+                    ("x-request-id", "earlier-session"),
+                    ("x-oai-request-id", "earlier-alias"),
+                ]));
+            let response = response(provider, session, streaming).await;
+            assert_eq!(response.status(), StatusCode::BAD_GATEWAY);
+            assert_eq!(response.headers()["x-request-id"], "body-read-error");
+            assert_eq!(response.headers().get_all("x-request-id").iter().count(), 1);
+            assert!(response.headers().get("x-oai-request-id").is_none());
+            assert_eq!(response.headers()["x-gateway-request-id"], MODEL_REQUEST_ID);
+        }
+    }
+}
+
+#[tokio::test]
+async fn local_execution_failure_uses_the_existing_model_id() {
+    for provider in ["openai", "xai"] {
+        for streaming in [false, true] {
+            let session =
+                failed_session(streaming, EngineError::Deadline).with_response_headers(headers(&[
+                    ("x-request-id", "opening-primary"),
+                    ("x-oai-request-id", "opening-alias"),
+                    ("x-codex-turn-state", "retained-turn-state"),
+                ]));
+            let response = response(provider, session, streaming).await;
+            assert_eq!(response.headers()["x-request-id"], MODEL_REQUEST_ID);
+            assert_eq!(response.headers()["x-gateway-request-id"], MODEL_REQUEST_ID);
+            assert!(response.headers().get("x-oai-request-id").is_none());
+            assert_eq!(
+                response.headers()["x-codex-turn-state"],
+                "retained-turn-state"
+            );
+        }
+    }
+}

backend/crates/gateway-api/tests/openai/responses/mod.rs

@@ -1,4 +1,5 @@
 mod http;
+mod request;
 mod websocket;
 
 use axum::http::{HeaderMap, HeaderValue};
@@ -369,6 +370,47 @@ fn decoder_should_preserve_ordinary_request_headers_as_opaque_multivalues() {
     }
 }
 
+#[test]
+fn decoder_should_exclude_downstream_transport_headers_from_opaque_context() {
+    let mut headers = HeaderMap::new();
+    for name in [
+        "cf-visitor",
+        "cf-connecting-ip",
+        "cf-connecting-ipv6",
+        "cf-pseudo-ipv4",
+        "cf-ray",
+        "cf-ipcountry",
+        "cf-warp-tag-id",
+        "cf-worker",
+        "cf-ew-via",
+        "cdn-loop",
+        "via",
+        "forwarded",
+        "x-forwarded-for",
+        "x-forwarded-prefix",
+        "accept-encoding",
+    ] {
+        headers.insert(name, HeaderValue::from_static("downstream-only"));
+    }
+    headers.insert(
+        "CF-Visitor",
+        HeaderValue::from_static(r#"{"scheme":"https"}"#),
+    );
+    headers.insert("accept-encoding", HeaderValue::from_static("br, gzip"));
+    // 正文未压缩；入口现在消费 Content-Encoding，但仍不得向上游透传。
+    headers.insert("content-encoding", HeaderValue::from_static("identity"));
+    headers.insert("x-openai-future-mode", HeaderValue::from_static("keep"));
+
+    let decoded =
+        decode_request_with_headers(br#"{"model":"smart-code","input":"hello"}"#, &headers)
+            .expect("decode request behind a reverse proxy");
+
+    assert_eq!(
+        openai_protocol_context(&decoded).get("opaque_request_headers"),
+        Some(&json!([["x-openai-future-mode", STANDARD.encode(b"keep")]])),
+    );
+}
+
 #[test]
 fn decoder_should_preserve_unknown_nested_values_without_debug_disclosure() {
     let secret = "nested-private-value";

backend/crates/gateway-api/tests/openai/responses/request.rs

@@ -0,0 +1,174 @@
+use std::io::{Read, Write, copy, repeat};
+
+use axum::http::{HeaderMap, HeaderValue, header::CONTENT_ENCODING};
+use gateway_api::openai::responses::{RequestDecodeError, decode_request_with_headers};
+use serde_json::json;
+
+use super::openai_wire_body;
+
+const ENCODINGS: [&str; 3] = ["gzip", "deflate", "zstd"];
+const REQUEST: &[u8] = br#"{"model":"gpt-test","input":"hello","future_field":{"value":1}}"#;
+const DECOMPRESSED_LIMIT: u64 = 64 * 1024 * 1024;
+
+pub(super) fn encode_body(encoding: &str, mut data: impl Read) -> Vec<u8> {
+    match encoding {
+        "gzip" => {
+            let mut encoder =
+                flate2::write::GzEncoder::new(Vec::new(), flate2::Compression::fast());
+            copy(&mut data, &mut encoder).expect("gzip encode");
+            encoder.finish().expect("gzip finish")
+        }
+        "deflate" => {
+            let mut encoder =
+                flate2::write::ZlibEncoder::new(Vec::new(), flate2::Compression::fast());
+            copy(&mut data, &mut encoder).expect("deflate encode");
+            encoder.finish().expect("deflate finish")
+        }
+        "zstd" => zstd::stream::encode_all(data, 3).expect("zstd encode"),
+        _ => panic!("unsupported fixture encoding"),
+    }
+}
+
+fn headers(encoding: &str) -> HeaderMap {
+    HeaderMap::from_iter([(
+        CONTENT_ENCODING,
+        HeaderValue::from_str(encoding).expect("encoding header"),
+    )])
+}
+
+#[test]
+fn http_decode_should_preserve_compressed_request_fields() {
+    let expected = serde_json::from_slice::<serde_json::Value>(REQUEST).expect("fixture JSON");
+    for encoding in ENCODINGS {
+        let compressed = encode_body(encoding, REQUEST);
+        let decoded = decode_request_with_headers(&compressed, &headers(encoding)).expect(encoding);
+        assert_eq!(
+            openai_wire_body(&decoded),
+            expected.as_object().expect("object")
+        );
+    }
+}
+
+#[test]
+fn http_decode_should_accept_plain_identity_and_case_insensitive_encodings() {
+    for request_headers in [HeaderMap::new(), headers(""), headers(" identity ")] {
+        assert!(decode_request_with_headers(REQUEST, &request_headers).is_ok());
+    }
+    let compressed = encode_body("gzip", REQUEST);
+    assert!(decode_request_with_headers(&compressed, &headers(" GZip ")).is_ok());
+}
+
+#[test]
+fn http_decode_should_reject_unknown_and_stacked_encodings() {
+    let mut repeated = headers("identity");
+    repeated.append(CONTENT_ENCODING, HeaderValue::from_static("gzip"));
+    for request_headers in [headers("br"), headers("gzip, zstd"), repeated] {
+        let error = decode_request_with_headers(REQUEST, &request_headers)
+            .expect_err("unsupported encoding");
+        assert!(matches!(
+            error,
+            RequestDecodeError::UnsupportedContentEncoding { .. }
+        ));
+        assert_eq!(
+            error.protocol_body().into_value()["error"]["code"],
+            "unsupported_content_encoding"
+        );
+    }
+}
+
+#[test]
+fn http_decode_should_reject_corrupted_and_truncated_compressed_bodies() {
+    for encoding in ENCODINGS {
+        let mut truncated = encode_body(encoding, REQUEST);
+        truncated.truncate(truncated.len() - 4);
+        for body in [b"not-a-compressed-stream".as_slice(), truncated.as_slice()] {
+            let error = decode_request_with_headers(body, &headers(encoding)).expect_err(encoding);
+            assert_eq!(
+                error.protocol_body().into_value(),
+                json!({"error": {
+                    "type": "invalid_request_error", "code": "invalid_json",
+                    "message": "Request body must be valid JSON."
+                }})
+            );
+        }
+    }
+}
+
+#[test]
+fn http_decode_should_read_all_gzip_members_and_zstd_frames() {
+    for encoding in ["gzip", "zstd"] {
+        let mut compressed = encode_body(encoding, &REQUEST[..12]);
+        compressed.extend(encode_body(encoding, &REQUEST[12..]));
+        let decoded = decode_request_with_headers(&compressed, &headers(encoding)).expect(encoding);
+        assert_eq!(openai_wire_body(&decoded)["input"], "hello");
+    }
+}
+
+#[test]
+fn http_decode_should_not_ignore_invalid_trailing_members() {
+    for encoding in ["gzip", "zstd"] {
+        let mut compressed = encode_body(encoding, REQUEST);
+        compressed.extend(encode_body(encoding, b"invalid trailing JSON".as_slice()));
+        assert_eq!(
+            decode_request_with_headers(&compressed, &headers(encoding)).expect_err(encoding),
+            RequestDecodeError::MalformedJson
+        );
+    }
+}
+
+#[test]
+fn http_decode_should_reject_zstd_frames_with_an_excessive_window() {
+    let mut encoder = zstd::stream::write::Encoder::new(Vec::new(), 3).expect("zstd encoder");
+    encoder.window_log(27).expect("128 MiB window");
+    encoder.write_all(REQUEST).expect("write JSON");
+    // 提前输出帧头，避免编码器根据最终小正文缩减窗口。
+    encoder.flush().expect("flush frame header");
+    let compressed = encoder.finish().expect("finish frame");
+    assert_eq!(
+        zstd::stream::decode_all(compressed.as_slice()).expect("valid zstd frame"),
+        REQUEST
+    );
+    assert_eq!(
+        decode_request_with_headers(&compressed, &headers("zstd")).expect_err("oversized window"),
+        RequestDecodeError::MalformedJson
+    );
+}
+
+#[test]
+fn http_decode_should_accept_the_exact_decompressed_limit() {
+    let padding = repeat(b' ').take(DECOMPRESSED_LIMIT - REQUEST.len() as u64);
+    let compressed = encode_body("zstd", REQUEST.chain(padding));
+    let decoded = decode_request_with_headers(&compressed, &headers("zstd")).expect("exact limit");
+    assert_eq!(decoded.metadata().requested_model(), "gpt-test");
+}
+
+#[test]
+fn http_decode_should_reject_bodies_above_the_decompressed_limit() {
+    for encoding in ENCODINGS {
+        let compressed = encode_body(encoding, repeat(0).take(DECOMPRESSED_LIMIT + 1));
+        let error =
+            decode_request_with_headers(&compressed, &headers(encoding)).expect_err(encoding);
+        assert_eq!(
+            error,
+            RequestDecodeError::DecompressedBodyTooLarge,
+            "{encoding}"
+        );
+    }
+}
+
+#[test]
+fn http_decode_should_stop_at_limit_before_reading_invalid_trailing_frames() {
+    for encoding in ["zstd", "gzip"] {
+        // 尾部故意损坏：若先完整解压再检查长度，就会错误地返回 invalid_json，
+        // 这个断言验证越界时已经停止读取，而不只是最终返回了某个超限错误。
+        let mut compressed = encode_body(encoding, repeat(0).take(DECOMPRESSED_LIMIT + 1));
+        compressed.extend_from_slice(b"invalid trailing frame");
+        let error =
+            decode_request_with_headers(&compressed, &headers(encoding)).expect_err(encoding);
+        assert_eq!(
+            error,
+            RequestDecodeError::DecompressedBodyTooLarge,
+            "{encoding}"
+        );
+    }
+}

backend/crates/gateway-api/tests/openai/responses/websocket/forward.rs

@@ -0,0 +1,449 @@
+use std::collections::VecDeque;
+use std::sync::{Arc, Mutex, atomic::Ordering};
+use std::time::Duration;
+
+use axum::http::{StatusCode, header::AUTHORIZATION};
+use bytes::Bytes;
+use futures::{SinkExt, StreamExt};
+use gateway_core::engine::{CommitRequirement, CoordinatedEvent, EngineError};
+use gateway_core::error::{
+    ClientVisibleUpstreamError, ClientVisibleUpstreamResponse, ProviderError, ProviderErrorKind,
+};
+use gateway_core::event::{ProtocolWireEvent, ProviderEvent, ProviderResponseHeader};
+use gateway_core::upstream::{OpaqueUpstreamValue, UpstreamSendState};
+use serde_json::{Value, json};
+use tokio::net::TcpStream;
+use tokio_tungstenite::{
+    MaybeTlsStream, WebSocketStream, connect_async,
+    tungstenite::{Message, client::IntoClientRequest},
+};
+
+use super::{AtomicFailureExecution, AtomicFailureTrace};
+use crate::openai::{api_router, authenticated_client};
+
+type TestSocket = WebSocketStream<MaybeTlsStream<TcpStream>>;
+
+// 全部使用合成响应事实和真实 API 路由，不读取账号、日志或请求转储。
+struct TestServer(tokio::task::JoinHandle<()>);
+
+impl Drop for TestServer {
+    fn drop(&mut self) {
+        self.0.abort();
+    }
+}
+
+async fn connect(
+    trace: Arc<AtomicFailureTrace>,
+    response_headers: Vec<ProviderResponseHeader>,
+) -> (TestSocket, TestServer) {
+    let execution = Arc::new(AtomicFailureExecution {
+        client: authenticated_client("sk_ws_atomic"),
+        trace,
+        response_headers,
+        fail_before_first_event: false,
+    });
+    let app = api_router(execution).await;
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("bind local API");
+    let address = listener.local_addr().unwrap();
+    let server = TestServer(tokio::spawn(async move {
+        axum::serve(listener, app).await.expect("serve local API");
+    }));
+    let mut request = format!("ws://{address}/v1/responses")
+        .into_client_request()
+        .unwrap();
+    request
+        .headers_mut()
+        .insert(AUTHORIZATION, "Bearer sk_ws_atomic".parse().unwrap());
+    let (socket, response) = connect_async(request).await.expect("upgrade WebSocket");
+    assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);
+    (socket, server)
+}
+
+async fn send_request(socket: &mut TestSocket) {
+    socket
+        .send(Message::Text(
+            json!({"type": "response.create", "model": "model-a", "input": "synthetic"})
+                .to_string()
+                .into(),
+        ))
+        .await
+        .unwrap();
+}
+
+async fn next_event(socket: &mut TestSocket) -> Value {
+    let frame = tokio::time::timeout(Duration::from_secs(2), socket.next())
+        .await
+        .expect("event timeout")
+        .expect("connection remains open")
+        .expect("valid frame");
+    let Message::Text(text) = frame else {
+        panic!("expected a JSON text frame, got {frame:?}");
+    };
+    serde_json::from_str(&text).expect("JSON event")
+}
+
+async fn next_error(socket: &mut TestSocket) -> Value {
+    let first = next_event(socket).await;
+    let error = if first["type"] == "response.metadata" {
+        next_event(socket).await
+    } else {
+        first
+    };
+    assert_eq!(error["type"], "error");
+    error
+}
+
+async fn assert_no_duplicate_failure(socket: &mut TestSocket) {
+    // 后续入站帧只会在本轮收敛后处理，比固定等待窗口更可靠地检查没有重复失败终态。
+    socket.send(Message::Text("{".into())).await.unwrap();
+    let error = next_event(socket).await;
+    assert_eq!(error["error"]["code"], "invalid_json");
+    assert_eq!(error["status"], 400);
+    assert_eq!(error["headers"]["x-request-id"], error["request_id"]);
+    assert_eq!(
+        error["headers"]["x-gateway-request-id"],
+        error["request_id"]
+    );
+}
+
+async fn initial_error(error: EngineError, response_headers: Vec<ProviderResponseHeader>) -> Value {
+    let trace = Arc::new(AtomicFailureTrace {
+        initial_errors: Mutex::new(VecDeque::from([error])),
+        ..AtomicFailureTrace::default()
+    });
+    let (mut socket, _server) = connect(Arc::clone(&trace), response_headers).await;
+    send_request(&mut socket).await;
+    let error = next_error(&mut socket).await;
+    assert!(!trace.committed.load(Ordering::Acquire));
+    assert!(trace.finalized.load(Ordering::Acquire));
+    assert_eq!(error["request_id"], "req_ws_atomic");
+    assert_eq!(error["headers"]["x-gateway-request-id"], "req_ws_atomic");
+    assert_no_duplicate_failure(&mut socket).await;
+    socket.close(None).await.unwrap();
+    error
+}
+
+fn header(name: &str, value: &'static [u8]) -> ProviderResponseHeader {
+    ProviderResponseHeader::new(name, Bytes::from_static(value))
+}
+
+fn upstream_failure(
+    status: u16,
+    body: &'static [u8],
+    headers: Vec<ProviderResponseHeader>,
+) -> ProviderError {
+    ProviderError::new(ProviderErrorKind::Unavailable, UpstreamSendState::Sent)
+        .with_status(status)
+        .with_client_visible_upstream_response(
+            ClientVisibleUpstreamResponse::new(status, None, Bytes::from_static(body))
+                .with_headers(headers),
+        )
+}
+
+#[tokio::test]
+async fn initial_http_or_opening_failure_preserves_status_and_structured_error() {
+    // 分类故意都用 Unavailable：不能把收到的 401/429/500 等按网关分类改成 502。
+    for status in [302, 400, 401, 403, 429, 500, 502, 503] {
+        let provider = upstream_failure(
+            status,
+            br#"{"error":{"message":"synthetic upstream marker","code":"custom_code","type":"custom_type"}}"#,
+            vec![header("x-request-id", b"req_current"), header("retry-after", b"7")],
+        )
+        .with_client_visible_upstream_error(ClientVisibleUpstreamError::new(
+            "synthetic upstream marker",
+            Some("custom_code".to_owned()),
+            Some("custom_type".to_owned()),
+        ));
+        let error = initial_error(EngineError::Provider(provider), Vec::new()).await;
+        assert_eq!(error["status"], status);
+        assert_eq!(
+            error["error"],
+            json!({
+                "message": "synthetic upstream marker", "code": "custom_code", "type": "custom_type",
+            })
+        );
+        assert_eq!(error["headers"]["x-request-id"], "req_current");
+        assert_eq!(error["headers"]["retry-after"], "7");
+    }
+}
+
+#[tokio::test]
+async fn non_structured_bodies_use_safe_fallback_without_losing_status_or_ids() {
+    for body in [
+        b"<html>synthetic-private-body-marker</html>".as_slice(),
+        b"synthetic-private-body-marker",
+        b"",
+        br#""synthetic-private-body-marker""#,
+        br#"{"error":"synthetic-private-body-marker"}"#,
+        br#"{"detail":"synthetic-private-body-marker"}"#,
+        br#"{"error":{"code":"synthetic-private-body-marker"}}"#,
+    ] {
+        let provider = upstream_failure(
+            503,
+            body,
+            vec![header("x-request-id", b"req_body_fallback")],
+        );
+        let error = initial_error(EngineError::Provider(provider), Vec::new()).await;
+        assert_eq!(error["status"], 503);
+        assert_eq!(error["headers"]["x-request-id"], "req_body_fallback");
+        assert_eq!(
+            error["error"],
+            json!({
+                "message": "upstream service is unavailable",
+                "code": "upstream_unavailable",
+                "type": "server_error",
+            })
+        );
+        assert!(!error.to_string().contains("synthetic-private-body-marker"));
+    }
+}
+
+#[tokio::test]
+async fn final_failure_headers_take_precedence_over_observed_opening_headers() {
+    let provider = upstream_failure(403, b"", vec![header("x-oai-request-id", b"req_final")])
+        .with_status(502)
+        .with_upstream_request_id(OpaqueUpstreamValue::new("req_stale_fact"));
+    let error = initial_error(
+        EngineError::Provider(provider),
+        vec![
+            header("x-request-id", b"req_old_opening"),
+            header("x-codex-turn-state", b"old-turn-state"),
+        ],
+    )
+    .await;
+    assert_eq!(error["status"], 403);
+    assert_eq!(error["headers"]["x-oai-request-id"], "req_final");
+    assert!(error["headers"].get("x-request-id").is_none());
+    assert!(!error.to_string().contains("req_old_opening"));
+    assert!(!error.to_string().contains("req_stale_fact"));
+    assert!(!error.to_string().contains("old-turn-state"));
+}
+
+#[tokio::test]
+async fn provider_failure_facts_survive_without_a_complete_http_response() {
+    let provider = ProviderError::new(ProviderErrorKind::Transport, UpstreamSendState::Ambiguous)
+        .with_status(429)
+        .with_upstream_request_id(OpaqueUpstreamValue::new("req_body_read_failed"));
+    let error = initial_error(
+        EngineError::Provider(provider),
+        vec![
+            header("x-request-id", b"req_old"),
+            header("x-oai-request-id", b"req_old_alias"),
+            header("x-codex-turn-state", b"observed-turn-state"),
+        ],
+    )
+    .await;
+    assert_eq!(error["status"], 429);
+    assert_eq!(error["headers"]["x-request-id"], "req_body_read_failed");
+    assert_eq!(
+        error["headers"]["x-codex-turn-state"],
+        "observed-turn-state"
+    );
+    assert!(error["headers"].get("x-oai-request-id").is_none());
+    assert_eq!(error["error"]["message"], "upstream service is unavailable");
+}
+
+#[tokio::test]
+async fn initial_error_headers_apply_the_response_security_boundary() {
+    let provider = upstream_failure(
+        502,
+        b"",
+        vec![
+            header("X-Request-Id", b"req_safe"),
+            header("x-gateway-request-id", b"upstream-cannot-claim-gateway-id"),
+            header("x-future-header", b"first"),
+            header("x-future-header", b"second"),
+            header("cf-ray", b"synthetic-ray"),
+            header("retry-after", b"11"),
+            header("authorization", b"synthetic-private-header-marker"),
+            header("set-cookie", b"synthetic-private-header-marker"),
+            header("chatgpt-account-id", b"synthetic-private-header-marker"),
+            header(
+                "x-codex-installation-id",
+                b"synthetic-private-header-marker",
+            ),
+            header("connection", b"x-private-hop"),
+            header("x-private-hop", b"synthetic-private-header-marker"),
+            header("sec-websocket-accept", b"synthetic-private-header-marker"),
+            header("content-length", b"123"),
+            header("content-type", b"text/html"),
+            header("bad\0name", b"synthetic-private-header-marker"),
+            header("x-bad-value", b"synthetic-private-header-marker\r\n"),
+            header("x-non-utf8", b"\xff"),
+        ],
+    );
+    let error = initial_error(EngineError::Provider(provider), Vec::new()).await;
+    assert_eq!(
+        error["headers"],
+        json!({
+            "x-request-id": "req_safe",
+            "x-gateway-request-id": "req_ws_atomic",
+            "x-future-header": "second",
+            "cf-ray": "synthetic-ray",
+            "retry-after": "11",
+        })
+    );
+}
+
+#[tokio::test]
+async fn initial_error_without_upstream_facts_keeps_the_local_contract() {
+    for (error, status, code) in [
+        (EngineError::Deadline, 504, "request_timeout"),
+        (EngineError::EmptyRoutingPlan, 503, "no_available_provider"),
+        (
+            EngineError::Provider(ProviderError::new(
+                ProviderErrorKind::Transport,
+                UpstreamSendState::NotSent,
+            )),
+            502,
+            "upstream_unavailable",
+        ),
+    ] {
+        let error = initial_error(error, Vec::new()).await;
+        assert_eq!(error["status"], status);
+        assert_eq!(error["error"]["code"], code);
+        assert_eq!(error["headers"]["x-request-id"], "req_ws_atomic");
+    }
+}
+
+#[tokio::test]
+async fn initial_error_never_uses_a_success_or_upgrade_status_as_an_error_status() {
+    for status in [0, 99, 101, 200, 204] {
+        let error = initial_error(
+            EngineError::Provider(upstream_failure(status, b"", Vec::new())),
+            Vec::new(),
+        )
+        .await;
+        assert_eq!(error["status"], 502);
+    }
+}
+
+#[tokio::test]
+async fn opening_ids_stay_in_metadata_but_do_not_identify_initial_failures() {
+    for (failure, status) in [
+        (EngineError::Deadline, 504),
+        (
+            EngineError::Provider(ProviderError::new(
+                ProviderErrorKind::Transport,
+                UpstreamSendState::Ambiguous,
+            )),
+            502,
+        ),
+    ] {
+        let trace = Arc::new(AtomicFailureTrace {
+            initial_errors: Mutex::new(VecDeque::from([failure])),
+            ..AtomicFailureTrace::default()
+        });
+        let (mut socket, _server) = connect(
+            trace,
+            vec![
+                header("x-request-id", b"req_old_opening"),
+                header("x-oai-request-id", b"req_observed"),
+                header("x-codex-turn-state", b"observed-turn-state"),
+                header("x-future-header", b"future-value"),
+            ],
+        )
+        .await;
+        send_request(&mut socket).await;
+        // metadata 仍交付原会话观测；opening ID 不能因此成为当前失败的请求身份。
+        assert_eq!(
+            next_event(&mut socket).await,
+            json!({
+                "type": "response.metadata",
+                "headers": {
+                    "x-request-id": "req_old_opening",
+                    "x-oai-request-id": "req_observed",
+                    "x-codex-turn-state": "observed-turn-state",
+                    "x-future-header": "future-value",
+                },
+            })
+        );
+        let error = next_event(&mut socket).await;
+        assert_eq!(error["type"], "error");
+        assert_eq!(error["status"], status);
+        assert_eq!(error["request_id"], "req_ws_atomic");
+        assert_eq!(
+            error["headers"],
+            json!({
+                "x-request-id": "req_ws_atomic",
+                "x-gateway-request-id": "req_ws_atomic",
+                "x-codex-turn-state": "observed-turn-state",
+                "x-future-header": "future-value",
+            })
+        );
+        assert_no_duplicate_failure(&mut socket).await;
+        socket.close(None).await.unwrap();
+    }
+}
+
+#[tokio::test]
+async fn errors_on_a_reused_connection_keep_their_own_upstream_ids() {
+    let errors = ["req_first", "req_second"].map(|request_id| {
+        EngineError::Provider(
+            upstream_failure(502, b"", Vec::new())
+                .with_upstream_request_id(OpaqueUpstreamValue::new(request_id)),
+        )
+    });
+    let trace = Arc::new(AtomicFailureTrace {
+        initial_errors: Mutex::new(VecDeque::from(errors)),
+        ..AtomicFailureTrace::default()
+    });
+    let (mut socket, _server) = connect(trace, Vec::new()).await;
+    for request_id in ["req_first", "req_second"] {
+        send_request(&mut socket).await;
+        let error = next_error(&mut socket).await;
+        assert_eq!(error["headers"]["x-request-id"], request_id);
+        assert_eq!(error["headers"]["x-gateway-request-id"], "req_ws_atomic");
+    }
+    assert_no_duplicate_failure(&mut socket).await;
+    socket.close(None).await.unwrap();
+}
+
+#[tokio::test]
+async fn deliverable_business_failures_are_not_rewritten_or_followed_by_a_second_error() {
+    for raw in [
+        json!({
+            "type": "error",
+            "status": 429,
+            "headers": {"x-request-id": "req_raw"},
+            "error": {"message": "raw marker", "type": "custom_type", "code": "custom_code"},
+            "future": {"keep": true},
+        }),
+        json!({
+            "type": "response.failed",
+            "response": {
+                "id": "resp_raw",
+                "status": "failed",
+                "error": {"message": "raw marker", "code": "custom_code"},
+            },
+            "future": {"keep": true},
+        }),
+    ] {
+        let event = ProviderEvent::wire(
+            ProtocolWireEvent::json(
+                "openai",
+                Some(raw["type"].as_str().unwrap().to_owned()),
+                raw.clone(),
+            )
+            .unwrap(),
+        );
+        let trace = Arc::new(AtomicFailureTrace {
+            first_batch: Mutex::new(Some(
+                CoordinatedEvent::try_batch(vec![event], CommitRequirement::CommitBeforeDelivery)
+                    .unwrap(),
+            )),
+            ..AtomicFailureTrace::default()
+        });
+        let (mut socket, _server) = connect(Arc::clone(&trace), Vec::new()).await;
+        send_request(&mut socket).await;
+        assert_eq!(next_event(&mut socket).await["type"], "response.metadata");
+        assert_eq!(next_event(&mut socket).await, raw);
+        assert_no_duplicate_failure(&mut socket).await;
+        assert!(trace.committed.load(Ordering::Acquire));
+        assert!(trace.finalized.load(Ordering::Acquire));
+        assert_eq!(trace.next_calls.load(Ordering::Acquire), 2);
+        socket.close(None).await.unwrap();
+    }
+}

backend/crates/gateway-api/tests/openai/responses/websocket/mod.rs

@@ -1,4 +1,5 @@
 mod connection;
+mod forward;
 mod protocol;
 
 use std::sync::{
@@ -7,6 +8,7 @@ use std::sync::{
 };
 use std::time::{Duration, SystemTime};
 
+use async_trait::async_trait;
 use axum::{
     body::Body,
     http::{HeaderMap, HeaderValue, Request, StatusCode, header::AUTHORIZATION},
@@ -17,18 +19,40 @@ use gateway_api::openai::responses::{
     DecodedResponsesRequest, OpenAiRequestHeaders, ResponseCreateFrameError,
     decode_response_create_with_context,
 };
+use gateway_core::account::ProviderAccountId;
+use gateway_core::engine::admission::{
+    ClientAdmissionDecision, ClientAdmissionError, ClientAdmissionPort, ClientAdmissionRecovery,
+    ClientAdmissionRequest, ClientAdmissionRestoreResult,
+};
+use gateway_core::engine::budget::{ClientBudgetCharge, ClientBudgetError, ClientBudgetPort};
 use gateway_core::engine::execution::{
-    AuthenticatedClient, ClientAuthenticationError, ExecutionService, ExecutionSession,
+    AuthenticatedClient, ClientAuthenticationError, DefaultExecutionService, ExecutionService,
+    ExecutionSession, ProviderCircuitDecision, ProviderCircuitError, ProviderCircuitPort,
     StartExecution, StartProviderExecution, StartedExecution,
 };
-use gateway_core::engine::{CommitRequirement, CoordinatedEvent, EngineError};
-use gateway_core::error::{GatewayError, ProviderError, ProviderErrorKind};
+use gateway_core::engine::provider::{
+    Provider, ProviderCallMetadata, ProviderRegistry, ProviderRequest, ProviderStream,
+};
+use gateway_core::engine::{
+    AttemptContext, AttemptRecord, CommitRequirement, CoordinatedEvent, EngineError,
+    ExecutionStore, IntermediateFailure, ModelRequestFinalization, ModelRequestId, NewModelRequest,
+    RecoveryReport,
+};
+use gateway_core::error::{GatewayError, ProviderError, ProviderErrorKind, StoreError};
 use gateway_core::event::{
     GatewayEvent, ProtocolWireEvent, ProviderEvent, ProviderResponseHeader, ResponseMeta,
 };
+use gateway_core::lifecycle::{
+    CancellationToken, ConnectionDraining, ConnectionGuard, ConnectionLifecycle,
+};
+use gateway_core::metering::{Decimal, ProviderReportedCost};
 use gateway_core::operation::Operation;
-use gateway_core::routing::PublicModelId;
-use gateway_core::upstream::UpstreamSendState;
+use gateway_core::policy::ClientApiKeyId;
+use gateway_core::routing::{
+    ProviderCatalogGeneration, ProviderKind, ProviderModelCapabilities, PublicModelId,
+};
+use gateway_core::runtime::RuntimeSnapshotHandle;
+use gateway_core::upstream::{UpstreamSendState, UpstreamTransport};
 use gateway_protocol::openai::codex_responses_request_semantics;
 use serde_json::{Value, json};
 use tokio_tungstenite::connect_async;
@@ -37,7 +61,10 @@ use tokio_tungstenite::tungstenite::client::IntoClientRequest;
 use tower::ServiceExt;
 
 use super::decode_response_create;
-use crate::openai::{api_router, authenticated_client, models::ModelsExecution};
+use crate::openai::{
+    EmptyWorkerHealth, IgnoredClientApiKeyUsage, UnusedContinuation, api_router,
+    authenticated_client, models::ModelsExecution, snapshot,
+};
 
 fn decode_response_create_with_turn_header(
     payload: Value,
@@ -281,6 +308,8 @@ struct AtomicFailureTrace {
     committed: AtomicBool,
     finalized: AtomicBool,
     downstream_websocket_connection_ids: Mutex<Vec<String>>,
+    initial_errors: Mutex<std::collections::VecDeque<EngineError>>,
+    first_batch: Mutex<Option<CoordinatedEvent>>,
 }
 
 struct AtomicFailureSession {
@@ -293,6 +322,10 @@ impl ExecutionSession for AtomicFailureSession {
     fn next_event(&mut self) -> BoxFuture<'_, Result<Option<CoordinatedEvent>, EngineError>> {
         Box::pin(async move {
             let next_call = self.trace.next_calls.fetch_add(1, Ordering::AcqRel);
+            if let Some(error) = self.trace.initial_errors.lock().unwrap().pop_front() {
+                self.trace.finalized.store(true, Ordering::Release);
+                return Err(error);
+            }
             if self.fail_before_first_event && next_call == 0 {
                 return Err(EngineError::Provider(ProviderError::new(
                     ProviderErrorKind::Unavailable,
@@ -300,7 +333,14 @@ impl ExecutionSession for AtomicFailureSession {
                 )));
             }
             match next_call {
-                0 => Ok(Some(atomic_failure_batch())),
+                0 => Ok(Some(
+                    self.trace
+                        .first_batch
+                        .lock()
+                        .unwrap()
+                        .take()
+                        .unwrap_or_else(atomic_failure_batch),
+                )),
                 1 => {
                     self.trace.finalized.store(true, Ordering::Release);
                     Err(EngineError::Provider(ProviderError::new(
@@ -811,6 +851,352 @@ async fn websocket_response_create_should_not_have_a_private_16_mib_frame_limit(
 
 const TEST_WEBSOCKET_KEY: &str = "AAAAAAAAAAAAAAAAAAAAAA==";
 
+#[derive(Default)]
+struct SettlementPorts {
+    request_id: Mutex<Option<ModelRequestId>>,
+    finalizations: Mutex<Vec<ModelRequestFinalization>>,
+    active: AtomicBool,
+    settlement_calls: AtomicUsize,
+    settlement_started: tokio::sync::Notify,
+    settlement_gate: Mutex<Option<tokio::sync::oneshot::Receiver<()>>>,
+    charges: Mutex<Vec<ClientBudgetCharge>>,
+    releases: AtomicUsize,
+    released: tokio::sync::Notify,
+}
+
+#[async_trait]
+impl ExecutionStore for SettlementPorts {
+    async fn create_model_request(&self, request: NewModelRequest) -> Result<(), StoreError> {
+        *self.request_id.lock().unwrap() = Some(request.id);
+        Ok(())
+    }
+
+    async fn record_attempt(&self, _: AttemptRecord) -> Result<(), StoreError> {
+        Ok(())
+    }
+
+    async fn mark_send_state(
+        &self,
+        _: &ModelRequestId,
+        _: UpstreamSendState,
+    ) -> Result<(), StoreError> {
+        Ok(())
+    }
+
+    async fn mark_downstream_committed(
+        &self,
+        _: &ModelRequestId,
+        _: SystemTime,
+        _: Option<u16>,
+    ) -> Result<(), StoreError> {
+        Ok(())
+    }
+
+    async fn record_client_status(&self, _: &ModelRequestId, _: u16) -> Result<(), StoreError> {
+        Ok(())
+    }
+
+    async fn record_intermediate_failure(&self, _: IntermediateFailure) -> Result<(), StoreError> {
+        Ok(())
+    }
+
+    async fn finalize_model_request(
+        &self,
+        finalization: ModelRequestFinalization,
+    ) -> Result<(), StoreError> {
+        self.finalizations.lock().unwrap().push(finalization);
+        Ok(())
+    }
+
+    async fn recover_expired(&self, _: SystemTime) -> Result<RecoveryReport, StoreError> {
+        unreachable!("the WebSocket test does not recover requests")
+    }
+}
+
+impl ClientAdmissionPort for SettlementPorts {
+    fn admit(
+        &self,
+        _: ClientAdmissionRequest,
+    ) -> BoxFuture<'_, Result<ClientAdmissionDecision, ClientAdmissionError>> {
+        Box::pin(async {
+            assert!(!self.active.swap(true, Ordering::SeqCst));
+            Ok(ClientAdmissionDecision::Granted)
+        })
+    }
+
+    fn release<'a>(
+        &'a self,
+        _: &'a ClientApiKeyId,
+        request_id: &'a ModelRequestId,
+    ) -> BoxFuture<'a, Result<bool, ClientAdmissionError>> {
+        Box::pin(async move {
+            assert_eq!(
+                self.charges.lock().unwrap().len(),
+                1,
+                "settlement must finish first"
+            );
+            assert_eq!(self.request_id.lock().unwrap().as_ref(), Some(request_id));
+            self.releases.fetch_add(1, Ordering::SeqCst);
+            let active = self.active.swap(false, Ordering::SeqCst);
+            self.released.notify_one();
+            Ok(active)
+        })
+    }
+
+    fn restore(
+        &self,
+        _: ClientAdmissionRecovery,
+    ) -> BoxFuture<'_, Result<ClientAdmissionRestoreResult, ClientAdmissionError>> {
+        Box::pin(async { unreachable!("the WebSocket test does not restore admission") })
+    }
+}
+
+impl ClientBudgetPort for SettlementPorts {
+    fn admit(&self, _: ClientApiKeyId) -> BoxFuture<'_, Result<(), GatewayError>> {
+        Box::pin(async { Ok(()) })
+    }
+
+    fn settle(&self, charge: ClientBudgetCharge) -> BoxFuture<'_, Result<(), ClientBudgetError>> {
+        Box::pin(async move {
+            self.settlement_calls.fetch_add(1, Ordering::SeqCst);
+            assert!(self.active.load(Ordering::SeqCst));
+            let gate = self
+                .settlement_gate
+                .lock()
+                .unwrap()
+                .take()
+                .expect("one settlement");
+            self.settlement_started.notify_one();
+            gate.await
+                .expect("release settlement after client disconnect");
+            assert!(self.active.load(Ordering::SeqCst));
+            self.charges.lock().unwrap().push(charge);
+            Ok(())
+        })
+    }
+}
+
+impl ProviderCircuitPort for SettlementPorts {
+    fn decision<'a>(
+        &'a self,
+        _: &'a ProviderKind,
+    ) -> BoxFuture<'a, Result<ProviderCircuitDecision, ProviderCircuitError>> {
+        Box::pin(async { Ok(ProviderCircuitDecision::Allow) })
+    }
+
+    fn observe_failure<'a>(
+        &'a self,
+        _: &'a ProviderKind,
+    ) -> BoxFuture<'a, Result<(), ProviderCircuitError>> {
+        Box::pin(async { Ok(()) })
+    }
+
+    fn observe_success<'a>(
+        &'a self,
+        _: &'a ProviderKind,
+    ) -> BoxFuture<'a, Result<(), ProviderCircuitError>> {
+        Box::pin(async { Ok(()) })
+    }
+}
+
+struct ChargedWebSocketProvider;
+
+fn websocket_charge() -> Decimal {
+    "1.25".parse().unwrap()
+}
+
+#[async_trait]
+impl Provider for ChargedWebSocketProvider {
+    fn name(&self) -> &'static str {
+        "openai"
+    }
+
+    fn catalog_generation(&self) -> ProviderCatalogGeneration {
+        ProviderCatalogGeneration::default()
+    }
+
+    async fn query_model_capabilities(
+        &self,
+    ) -> Result<Vec<ProviderModelCapabilities>, ProviderError> {
+        Ok(Vec::new())
+    }
+
+    async fn execute(
+        &self,
+        request: ProviderRequest,
+        _: AttemptContext,
+    ) -> Result<ProviderStream, ProviderError> {
+        let candidate = request.candidate();
+        let metadata = ProviderCallMetadata::new(
+            candidate.provider().clone(),
+            candidate.upstream_model().unwrap().clone(),
+            ProviderAccountId::new("acct_api_test").unwrap(),
+            UpstreamTransport::new("websocket").unwrap(),
+        );
+        let response = ResponseMeta::new("resp_ws_settlement", "model-a");
+        let events = [
+            ProviderEvent::canonical_with_wire(
+                vec![GatewayEvent::Started(response.clone())],
+                ProtocolWireEvent::json("openai", Some("response.created".to_owned()), json!({
+                    "type": "response.created",
+                    "response": {"id": "resp_ws_settlement", "model": "model-a", "status": "in_progress"}
+                })).unwrap(),
+            ),
+            ProviderEvent::canonical_with_wire(
+                vec![
+                    GatewayEvent::ProviderCost(
+                        ProviderReportedCost::from_usd_ticks(websocket_charge().scaled()).unwrap(),
+                    ),
+                    GatewayEvent::Completed(response),
+                ],
+                ProtocolWireEvent::json("openai", Some("response.completed".to_owned()), json!({
+                    "type": "response.completed",
+                    "response": {"id": "resp_ws_settlement", "model": "model-a", "status": "completed"}
+                })).unwrap(),
+            ),
+        ];
+        Ok(ProviderStream::new(
+            metadata,
+            futures::stream::iter(events.map(Ok)),
+            (),
+        ))
+    }
+}
+
+#[derive(Default)]
+struct SettlementConnectionLifecycle {
+    closed: Arc<tokio::sync::Notify>,
+}
+
+struct SettlementConnectionGuard(Arc<tokio::sync::Notify>);
+
+impl ConnectionGuard for SettlementConnectionGuard {}
+
+impl Drop for SettlementConnectionGuard {
+    fn drop(&mut self) {
+        self.0.notify_one();
+    }
+}
+
+impl ConnectionLifecycle for SettlementConnectionLifecycle {
+    fn try_register(&self) -> Result<Box<dyn ConnectionGuard>, ConnectionDraining> {
+        Ok(Box::new(SettlementConnectionGuard(self.closed.clone())))
+    }
+
+    fn cancellation(&self) -> CancellationToken {
+        CancellationToken::new()
+    }
+
+    fn is_draining(&self) -> bool {
+        false
+    }
+}
+
+#[tokio::test]
+async fn websocket_disconnect_during_core_settlement_finishes_charge_before_releasing_admission() {
+    let (release_settlement, gate) = tokio::sync::oneshot::channel();
+    let ports = Arc::new(SettlementPorts {
+        settlement_gate: Mutex::new(Some(gate)),
+        ..Default::default()
+    });
+    let execution = Arc::new(
+        DefaultExecutionService::new(
+            RuntimeSnapshotHandle::new(snapshot("sk_ws_settlement", "openai")),
+            ports.clone(),
+            ProviderRegistry::new([Arc::new(ChargedWebSocketProvider) as Arc<dyn Provider>])
+                .unwrap(),
+            ports.clone(),
+            ports.clone(),
+            Arc::new(UnusedContinuation),
+            Arc::new(IgnoredClientApiKeyUsage),
+        )
+        .with_budget(ports.clone()),
+    );
+    let lifecycle = Arc::new(SettlementConnectionLifecycle::default());
+    let admin = crate::admin::AdminTestFixture::new().await;
+    let app = gateway_api::initialize(
+        gateway_api::ApiConfig {
+            asset_directory: std::env::temp_dir(),
+            cors_allowed_origins: Vec::new(),
+            request_timeout_seconds: None,
+            request_id_header: "x-request-id".to_owned(),
+        },
+        execution,
+        admin.services,
+        Vec::new(),
+        Arc::new(EmptyWorkerHealth),
+        lifecycle.clone(),
+    )
+    .unwrap()
+    .router();
+    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() });
+    let mut request = format!("ws://{address}/v1/responses")
+        .into_client_request()
+        .unwrap();
+    request.headers_mut().insert(
+        AUTHORIZATION,
+        HeaderValue::from_static("Bearer sk_ws_settlement"),
+    );
+    let (mut socket, response) = connect_async(request).await.unwrap();
+    assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);
+    socket
+        .send(ClientMessage::Text(
+            json!({
+                "type": "response.create", "model": "model-a", "input": "hello"
+            })
+            .to_string()
+            .into(),
+        ))
+        .await
+        .unwrap();
+    tokio::time::timeout(Duration::from_secs(5), ports.settlement_started.notified())
+        .await
+        .expect("production Core reached settlement");
+    {
+        let finalizations = ports.finalizations.lock().unwrap();
+        assert_eq!(finalizations.len(), 1);
+        assert_eq!(
+            finalizations[0].outcome,
+            gateway_core::engine::ExecutionOutcome::Succeeded,
+            "unexpected execution error: {:?}",
+            finalizations[0].error,
+        );
+    }
+    assert!(ports.charges.lock().unwrap().is_empty());
+    assert_eq!(ports.releases.load(Ordering::SeqCst), 0);
+
+    // 等到生产连接 guard 释放，保证 forward 的 select 已因断连取消 next_event；
+    // 在此之前不能打开结算屏障，否则只会验证正常完成而错过取消窗口。
+    socket.close(None).await.unwrap();
+    tokio::time::timeout(Duration::from_secs(5), lifecycle.closed.notified())
+        .await
+        .expect("production WebSocket handler exited");
+    assert!(ports.active.load(Ordering::SeqCst));
+    release_settlement
+        .send(())
+        .expect("the original settlement future survived disconnect");
+    tokio::time::timeout(Duration::from_secs(5), ports.released.notified())
+        .await
+        .expect("detached Core cleanup released admission");
+    assert!(!ports.active.load(Ordering::SeqCst));
+    assert_eq!(ports.releases.load(Ordering::SeqCst), 1);
+    assert_eq!(ports.settlement_calls.load(Ordering::SeqCst), 1);
+    {
+        let charges = ports.charges.lock().unwrap();
+        assert_eq!(charges.len(), 1);
+        assert_eq!(charges[0].amount_usd, websocket_charge());
+        assert_eq!(charges[0].key_id.as_str(), "key_api_test");
+        assert_eq!(
+            Some(&charges[0].request_id),
+            ports.request_id.lock().unwrap().as_ref()
+        );
+    }
+    server.abort();
+    let _ = server.await;
+}
+
 fn upgrade_request(authorization: &str) -> Request<Body> {
     Request::get("/v1/responses")
         .header(AUTHORIZATION, authorization)

backend/crates/gateway-api/tests/openai/responses/websocket/protocol.rs

@@ -1,8 +1,53 @@
+use axum::http::{HeaderMap, HeaderValue};
+use base64::{Engine as _, engine::general_purpose::STANDARD};
+use gateway_api::openai::responses::{OpenAiRequestHeaders, decode_response_create_with_context};
 use gateway_core::operation::Operation;
 use serde_json::json;
 
 use super::decode_response_create;
 
+#[test]
+fn response_create_should_exclude_cloudflare_headers_on_every_frame() {
+    let mut headers = HeaderMap::new();
+    for (name, value) in [
+        ("CF-Visitor", r#"{"scheme":"https"}"#),
+        ("cdn-loop", "cloudflare; loops=1"),
+        ("cf-warp-tag-id", "downstream-warp"),
+        ("cf-ipcountry", "US"),
+        ("cf-worker", "worker.example"),
+        ("cf-ew-via", "15"),
+        ("cf-future-proxy-field", "downstream-only"),
+    ] {
+        headers.insert(name, HeaderValue::from_static(value));
+    }
+    headers.append("x-openai-future-mode", HeaderValue::from_static("first"));
+    headers.append("x-openai-future-mode", HeaderValue::from_static("second"));
+    let request_headers = OpenAiRequestHeaders::from_headers(&headers);
+
+    // 连接级头会用于同一 WebSocket 的每一帧，后续帧也不能恢复下游链路元数据。
+    for input in ["hello", "continue"] {
+        let decoded = decode_response_create_with_context(
+            &json!({"type": "response.create", "model": "smart-code", "input": input}).to_string(),
+            &request_headers,
+        )
+        .expect("decode response.create behind Cloudflare");
+        let Operation::Generate(request) = decoded.operation() else {
+            panic!("Responses must map to Generate");
+        };
+        assert_eq!(
+            request
+                .protocol_payload()
+                .context()
+                .get("opaque_request_headers"),
+            Some(&json!([
+                ["x-openai-future-mode", STANDARD.encode(b"first")],
+                ["x-openai-future-mode", STANDARD.encode(b"second")],
+            ])),
+        );
+        assert_eq!(request.protocol_payload().body()["input"], input);
+    }
+}
+
 #[test]
 fn latest_official_codex_response_create_fixture_decodes_unchanged() {
     // Audited against openai/codex main 94cbbddafc1776d5e377bca1b05932c697e82238.

backend/crates/gateway-api/tests/openai/router.rs

@@ -9,6 +9,106 @@ use super::models::ModelsExecution;
 
 const REMOVED_BODY_LIMIT_BYTES: usize = 16 * 1024 * 1024;
 
+#[tokio::test]
+async fn browser_origin_controls_http_admin_sessions_without_configuration() {
+    use axum::body::to_bytes;
+    use serde_json::{Value, json};
+    for (origins, secure) in [
+        (vec!["http://admin.example.test"], false),
+        (vec!["http://192.0.2.1:8080"], false),
+        (vec!["http://[::1]:8080"], false),
+        (vec!["https://admin.example.test"], true),
+        (vec![], true),
+        (vec!["null"], true),
+        (vec!["invalid-origin"], true),
+        (vec!["http://admin.example.test/path"], true),
+        (vec!["http://admin.example.test?https"], true),
+        (vec!["http://user@admin.example.test"], true),
+        (
+            vec!["http://admin.example.test", "https://admin.example.test"],
+            true,
+        ),
+    ] {
+        let app = api_router_with_origins(ModelsExecution::new(), Vec::new()).await;
+        let request = |path: &str| {
+            let mut builder = Request::post(path)
+                .header("content-type", "application/json")
+                .header("x-forwarded-proto", "http")
+                .header("forwarded", "proto=http");
+            for origin in &origins {
+                builder = builder.header("origin", *origin);
+            }
+            builder
+        };
+        let response = app
+            .clone()
+            .oneshot(
+                request("/api/admin/auth/login")
+                    .body(Body::from(
+                        json!({"username": "admin_1", "password": "strong-admin-password"})
+                            .to_string(),
+                    ))
+                    .unwrap(),
+            )
+            .await
+            .unwrap();
+        assert_eq!(response.status(), StatusCode::OK);
+        let cookie = response.headers()["set-cookie"].to_str().unwrap();
+        let session = cookie.split(';').next().unwrap().to_owned();
+        let attrs: Vec<_> = cookie.split(';').map(str::trim).collect();
+        assert_eq!(attrs.contains(&"Secure"), secure);
+        for attribute in ["Path=/", "HttpOnly", "SameSite=Lax"] {
+            assert!(attrs.contains(&attribute));
+        }
+
+        let response = app
+            .clone()
+            .oneshot(
+                Request::get("/api/admin/auth/status")
+                    .header("cookie", &session)
+                    .body(Body::empty())
+                    .unwrap(),
+            )
+            .await
+            .unwrap();
+        let body: Value =
+            serde_json::from_slice(&to_bytes(response.into_body(), 4096).await.unwrap()).unwrap();
+        assert_eq!(body["data"]["authenticated"], true);
+
+        let response = app
+            .clone()
+            .oneshot(
+                request("/api/admin/auth/logout")
+                    .header("cookie", &session)
+                    .body(Body::empty())
+                    .unwrap(),
+            )
+            .await
+            .unwrap();
+        assert_eq!(response.status(), StatusCode::OK);
+        let cookie = response.headers()["set-cookie"].to_str().unwrap();
+        assert!(cookie.starts_with("cpr_admin_session=;"));
+        let attrs: Vec<_> = cookie.split(';').map(str::trim).collect();
+        assert_eq!(attrs.contains(&"Secure"), secure);
+        for attribute in ["Path=/", "HttpOnly", "SameSite=Lax", "Max-Age=0"] {
+            assert!(attrs.contains(&attribute));
+        }
+
+        let response = app
+            .oneshot(
+                Request::get("/api/admin/auth/status")
+                    .header("cookie", &session)
+                    .body(Body::empty())
+                    .unwrap(),
+            )
+            .await
+            .unwrap();
+        let body: Value =
+            serde_json::from_slice(&to_bytes(response.into_body(), 4096).await.unwrap()).unwrap();
+        assert_eq!(body["data"]["authenticated"], false);
+    }
+}
+
 #[tokio::test]
 async fn removed_responses_review_route_should_not_reach_the_responses_handler() {
     let response = api_router_with_origins(ModelsExecution::new(), Vec::new())

backend/crates/gateway-api/tests/openai/search/mod.rs

@@ -171,6 +171,11 @@ async fn search_route_should_preserve_request_and_success_response_bytes() {
         .expect("search response");
 
     assert_eq!(response.status(), StatusCode::CREATED);
+    assert_eq!(response.headers()["x-request-id"], "req_search_test");
+    assert_eq!(
+        response.headers()["x-gateway-request-id"],
+        "req_search_test"
+    );
     assert_eq!(
         response.headers().get("x-search-rate-limit"),
         Some(&"42".parse().expect("header value"))
@@ -216,6 +221,11 @@ async fn search_route_should_return_the_exact_upstream_error_response() {
         .expect("search response");
 
     assert_eq!(response.status(), StatusCode::UNPROCESSABLE_ENTITY);
+    assert_eq!(response.headers()["x-request-id"], "req_search_test");
+    assert_eq!(
+        response.headers()["x-gateway-request-id"],
+        "req_search_test"
+    );
     assert_eq!(
         response.headers().get("content-type"),
         Some(&"application/problem+json".parse().expect("content type"))

backend/crates/gateway-core/src/diagnostics/capture.rs

@@ -1,4 +1,4 @@
-//! 诊断内容的统一筛选边界。未知字符串只保留长度和摘要。
+//! 诊断内容的统一筛选边界。未知键名与值只保留有界结构和摘要。
 
 use serde_json::{Map, Value, json};
 use sha2::{Digest, Sha256};
@@ -6,8 +6,12 @@ use sha2::{Digest, Sha256};
 /// 原始字节的长度与 SHA-256，不复制或保留正文。
 #[must_use]
 pub fn body_fingerprint(bytes: &[u8]) -> Value {
+    json!({"bytes": bytes.len(), "sha256": fingerprint_hex(bytes)})
+}
+
+fn fingerprint_hex(bytes: &[u8]) -> String {
     let digest = Sha256::digest(bytes);
-    let hex: String = digest
+    digest
         .iter()
         .flat_map(|byte| {
             let alphabet = b"0123456789abcdef";
@@ -16,17 +20,40 @@ pub fn body_fingerprint(bytes: &[u8]) -> Value {
                 char::from(alphabet[usize::from(byte & 15)]),
             ]
         })
-        .collect();
-    json!({"bytes": bytes.len(), "sha256": hex})
+        .collect()
 }
 
-/// 保留可诊断的协议结构；凭据永不进入普通日志或数据库。
+/// 仅保留有限协议骨架；任意 JSON（包括 headers 和 metadata）不能声明自己可信。
 #[must_use]
 pub fn diagnostic_json(value: &Value) -> Value {
-    capture(value, "", 0, &mut 96)
+    capture(value, "", Context::Protocol, 0, &mut 96)
 }
 
-fn capture(value: &Value, key: &str, depth: usize, budget: &mut usize) -> Value {
+/// 只有 transport 的上游 metadata / error 帧顶层才是受控头部边界。
+pub(super) fn diagnostic_event_json(value: &Value, stage: &str) -> Value {
+    let context = if stage == "upstream.event"
+        && value.get("headers").is_some_and(Value::is_object)
+        && matches!(
+            value.get("type").and_then(Value::as_str),
+            Some("response.metadata" | "codex.response.metadata" | "error")
+        ) {
+        Context::UpstreamEvent
+    } else {
+        Context::Protocol
+    };
+    capture(value, "", context, 0, &mut 96)
+}
+
+#[derive(Clone, Copy)]
+enum Context {
+    Protocol,
+    UpstreamEvent,
+    Opaque,
+    Headers,
+    HeaderValue,
+}
+
+fn capture(value: &Value, key: &str, context: Context, depth: usize, budget: &mut usize) -> Value {
     if *budget == 0 || depth > 6 {
         return json!({"omitted": true});
     }
@@ -42,7 +69,11 @@ fn capture(value: &Value, key: &str, depth: usize, budget: &mut usize) -> Value
                 if *budget == 0 {
                     break;
                 }
-                result.insert(bounded(name, 96), capture(value, name, depth + 1, budget));
+                let (captured_name, child_context) = field(context, name);
+                result.insert(
+                    captured_name,
+                    capture(value, name, child_context, depth + 1, budget),
+                );
             }
             if result.len() < object.len() {
                 result.insert(
@@ -55,16 +86,86 @@ fn capture(value: &Value, key: &str, depth: usize, budget: &mut usize) -> Value
         Value::Array(items) => json!({
             "length": items.len(),
             "sample": items.iter().take(4)
-                .map(|item| capture(item, key.as_str(), depth + 1, budget))
+                .map(|item| {
+                    // 受控头值只接受一层字符串数组；畸形嵌套不能继承头部放行规则。
+                    let context = if matches!(context, Context::HeaderValue) && !item.is_string() {
+                        Context::Opaque
+                    } else {
+                        context
+                    };
+                    capture(item, key.as_str(), context, depth + 1, budget)
+                })
                 .collect::<Vec<_>>()
         }),
         Value::String(text)
-            if safe_header(&key) || safe_value_key(&key) && protocol_label(text) =>
+            if matches!(context, Context::HeaderValue) && safe_header(&key)
+                || matches!(context, Context::Protocol | Context::UpstreamEvent)
+                    && protocol_value(&key, text) =>
         {
             Value::String(bounded(text, 256))
         }
         Value::String(text) => body_fingerprint(text.as_bytes()),
-        other => other.clone(),
+        Value::Number(number)
+            if matches!(context, Context::Protocol)
+                && key == "status"
+                && number
+                    .as_u64()
+                    .is_some_and(|status| (100..=599).contains(&status)) =>
+        {
+            value.clone()
+        }
+        other => body_fingerprint(other.to_string().as_bytes()),
+    }
+}
+
+fn field(context: Context, name: &str) -> (String, Context) {
+    let child = match (context, name) {
+        (Context::UpstreamEvent, "headers") => Some(Context::Headers),
+        (Context::Headers, _) if safe_header(&name.to_ascii_lowercase()) => {
+            Some(Context::HeaderValue)
+        }
+        (
+            Context::Protocol | Context::UpstreamEvent,
+            "response" | "error" | "input" | "output" | "item" | "part" | "content" | "type"
+            | "role" | "status",
+        ) => Some(Context::Protocol),
+        (
+            Context::Protocol | Context::UpstreamEvent,
+            "id" | "model" | "message" | "text" | "delta" | "code" | "metadata" | "headers",
+        ) => Some(Context::Opaque),
+        _ => None,
+    };
+    match child {
+        Some(context) => (name.to_owned(), context),
+        None => (
+            format!("field_{}", fingerprint_hex(name.as_bytes())),
+            Context::Opaque,
+        ),
+    }
+}
+
+fn protocol_value(key: &str, value: &str) -> bool {
+    match key {
+        "type" => {
+            known_event_type(value)
+                || matches!(
+                    value,
+                    "message"
+                        | "function_call"
+                        | "function_call_output"
+                        | "reasoning"
+                        | "input_text"
+                        | "output_text"
+                        | "input_image"
+                        | "refusal"
+                )
+        }
+        "role" => matches!(
+            value,
+            "system" | "developer" | "user" | "assistant" | "tool"
+        ),
+        "status" => matches!(value, "in_progress" | "completed" | "incomplete" | "failed"),
+        _ => false,
     }
 }
 
@@ -131,14 +232,6 @@ fn safe_header(key: &str) -> bool {
     )
 }
 
-fn safe_value_key(key: &str) -> bool {
-    safe_header(key)
-        || matches!(
-            key,
-            "type" | "event" | "status" | "code" | "model" | "role" | "object" | "service_tier"
-        )
-}
-
 pub(super) fn bounded(value: &str, limit: usize) -> String {
     value
         .chars()
@@ -147,11 +240,39 @@ pub(super) fn bounded(value: &str, limit: usize) -> String {
         .collect()
 }
 
-/// Event names/codes are protocol labels, never arbitrary upstream text.
-pub(super) fn protocol_label(value: &str) -> bool {
-    !value.is_empty()
-        && value.len() <= 128
-        && value
-            .bytes()
-            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'-' | b':'))
+pub(super) fn diagnostic_event_type(value: &str) -> Value {
+    if known_event_type(value) {
+        Value::String(value.to_owned())
+    } else {
+        body_fingerprint(value.as_bytes())
+    }
+}
+
+/// 这里只决定诊断可明文展示的阶段，不校验协议；未知事件仍采集摘要，不能按字符形状放行。
+fn known_event_type(value: &str) -> bool {
+    matches!(
+        value,
+        "error"
+            | "response.create"
+            | "response.created"
+            | "response.in_progress"
+            | "response.completed"
+            | "response.failed"
+            | "response.incomplete"
+            | "response.metadata"
+            | "codex.response.metadata"
+            | "codex.rate_limits"
+            | "response.output_item.added"
+            | "response.output_item.done"
+            | "response.content_part.added"
+            | "response.content_part.done"
+            | "response.output_text.delta"
+            | "response.output_text.done"
+            | "response.function_call_arguments.delta"
+            | "response.function_call_arguments.done"
+            | "response.reasoning_summary_text.delta"
+            | "response.reasoning_summary_text.done"
+            | "response.reasoning_text.delta"
+            | "response.reasoning_text.done"
+    )
 }

backend/crates/gateway-core/src/diagnostics/trace.rs

@@ -10,8 +10,8 @@ use base64::{Engine as _, engine::general_purpose::STANDARD};
 use serde::Serialize;
 use serde_json::{Value, json};
 
-use super::capture::bounded;
-use super::{body_fingerprint, diagnostic_headers, diagnostic_json};
+use super::capture::{bounded, diagnostic_event_json, diagnostic_event_type};
+use super::{body_fingerprint, diagnostic_headers};
 
 const MAX_EVENTS: usize = 128;
 const HEAD_EVENTS: usize = 8;
@@ -124,7 +124,7 @@ impl TraceContext {
     }
 
     /// 同一个头部边界只采集一次：默认脱敏，显式开启 dump 时另存完整字节。
-    /// facts 必须为调用方构造的安全对象；原始头值只进入独立 dump。
+    /// facts 必须为调用方构造的安全对象；仅受控诊断头可明文保留，完整头部另存 dump。
     pub fn headers<'a>(
         &self,
         stage: &'static str,
@@ -182,27 +182,27 @@ impl TraceContext {
             .as_ref()
             .and_then(|v| v.get("type"))
             .and_then(Value::as_str)
-            .or(name)
-            .filter(|kind| super::capture::protocol_label(kind));
+            .or(name);
+        // 后缀只用于观测合并，不授予明文权限；未知事件用摘要区分，避免合并成同一类。
         let delta = event_type.is_some_and(|kind| kind.ends_with(".delta"));
         let data = json!({
             "body": fingerprint,
-            "eventType": event_type.map(|kind| bounded(kind, 128)),
+            "eventType": event_type.map(diagnostic_event_type),
             "jsonValid": parsed.is_some(),
-            "metadata": parsed.as_ref().filter(|_| !delta).map(diagnostic_json),
+            "metadata": parsed.as_ref().filter(|_| !delta)
+                .map(|value| diagnostic_event_json(value, stage)),
         });
         self.push(stage, data, delta);
     }
 
     /// 只记录业务解析边界；metadata 已由 transport 在解析前捕获。
     pub fn wire_event(&self, protocol: &str, event_type: Option<&str>) {
-        let event_type = event_type.filter(|kind| super::capture::protocol_label(kind));
         let delta = event_type.is_some_and(|kind| kind.ends_with(".delta"));
         self.push(
             "provider.event",
             json!({
                 "protocol": protocol,
-                "eventType": event_type.map(|kind| bounded(kind, 128)),
+                "eventType": event_type.map(diagnostic_event_type),
             }),
             delta,
         );