Skip to content

feat(apikey): 增加 混合轮转(聚合 API 优先)选项 - #454

Merged
qxcnm merged 4 commits into
qxcnm:mainfrom
xcosmosbox:main
Sep 2, 2026
Merged

feat(apikey): 增加 混合轮转(聚合 API 优先)选项#454
qxcnm merged 4 commits into
qxcnm:mainfrom
xcosmosbox:main

Conversation

@xcosmosbox

Copy link
Copy Markdown
Contributor

变更摘要

  • 新增第四种平台密钥轮转策略「混合轮转(聚合优先)」(存储值 hybrid_aggregate_first_rotation):与现有「混合轮转(账号优先)」完全对称——优先走聚合 API,聚合候选全部失败且请求未被消费时,回落账号池兜底
  • 动机:账号优先策略适合“聚合兜底”;对称地,部分场景希望优先消耗聚合 API、将账号池留作兜底(如账号额度更珍贵、聚合按量更便宜等)
  • 数据库无需迁移(api_keys.rotation_strategy 为自由 TEXT 列,新值直接写入)
  • 账号计划筛选 / 账号分组筛选对新策略同样生效(决定兜底账号池的范围)

改动范围

  • Frontend
  • Desktop / Tauri
  • Service
  • Gateway / Protocol Adapter
  • Docs / Governance
  • Workflow / Release

主要文件

网关路由核心:

  • crates/service/src/gateway/upstream/protocol/aggregate_api.rs:新增 AggregateFailurePolicy / AggregateAttemptOutcomeReleaseRequest 策略下候选为空或全部候选失败时归还 request(保留失败 trace 日志)
  • crates/service/src/gateway/upstream/proxy.rs:主流程聚合分支支持失败回落账号路径;RouteKind 各判断函数新增 HybridAggregateFirst 分支
  • crates/service/src/gateway/upstream/executor/mod.rsGatewayUpstreamRouteKind 新增 HybridAggregateFirst 变体

API Key 配置:

  • crates/service/src/apikey/apikey_profile.rs:常量 + normalize_rotation_strategy 别名
  • crates/service/src/apikey/apikey_create.rs / apikey_update_model.rs:筛选条件扩展
  • crates/service/src/gateway/mod.rs:websocket 支持判断排除新策略(与现有 hybrid 一致)

前端:

  • apps/src/components/modals/api-key-modal.tsx:下拉新增选项 + 说明文案
  • apps/src/app/apikeys/page.tsx / models/page.tsx / platform-mode/page-sections.tsx:策略标签
  • apps/src/lib/i18n/messages/{en,ko,ru}.ts:文案翻译

测试: apikey_profile_tests.rsexecutor/mod_tests.rscodex_profile_tests.rs

验证

  • pnpm -C apps run test
  • pnpm -C apps run build
  • pnpm -C apps run test:ui
  • cargo test --workspace
  • 其他本地验证已说明

已执行的实际验证:

1. fork 仓库 ci workflow 全绿(commit b7cb250f):
   cargo fmt --check、cargo check --workspace --all-targets、
   websocket 回归测试、前端 pnpm build:desktop、cargo test -p codexmanager-web
   运行记录:https://github.com/xcosmosbox/Codex-Manager/actions/runs/33472285413
2. release-all(build-artifacts)构建 Linux x86_64 产物成功:
   https://github.com/xcosmosbox/Codex-Manager/actions/runs/33472965267
3. 已部署至生产环境实测:Web 界面可正常创建/切换新策略密钥,
   路由行为符合预期(聚合优先 → 账号兜底)

未执行的验证与原因:

- pnpm test / test:ui、cargo test --workspace 未在本地完整执行:
  本地为低配 VPS(2 vCPU / 1.9GB RAM),无法承担全量编译测试资源开销,
  依赖 CI 验证(本 PR 也会触发相同的 ci workflow)。
  新增 Rust 单测已随 cargo check --workspace --all-targets 完成编译检查。

风险与影响面

  • 现有三种策略行为零变更:所有 match 仅新增分支;proxy_aggregate_request 现有两个调用点以 RespondError 策略调用,行为与改动前一致
  • 回落语义与账号优先对称:聚合候选全部非 2xx / 无候选 / 解析失败 → 回落账号池;任一候选成功桥接后不再回落;deadline 超时仍直接响应 504
  • proxy_aggregate_request 返回类型变化(Result<(), String>Result<AggregateAttemptOutcome, String>)为结构性改动,仅影响内部 3 个调用点,均已适配
  • 回滚兼容:旧版本二进制读到新值时按 fallback 走账号轮转(安全降级);无数据库迁移、无 API 协议变更、无新增依赖

@xcosmosbox

Copy link
Copy Markdown
Contributor Author

All ready for reviewing and merge @qxcnm

@qxcnm

qxcnm commented Sep 2, 2026

Copy link
Copy Markdown
Owner

审查结论:暂不合并。虽然当前 CI 全绿,而且在当前主线缓存修复上做的合并态验证中,prompt-cache / cache-affinity 专项 12/12 通过,但仍有功能边界 blocker:HybridAggregateFirst 允许模型只配置 aggregate route;聚合失败后却通过 ReleaseRequest 无条件进入全局账号候选,未再次约束该模型必须启用 account_pool/default,因此 aggregate-only 模型可能绕过 source-route 配置调用账号池。另一个问题是回落前已经记录 aggregate 失败的 outcome/final,账号兜底完成后还会再记录一次最终结果,可能污染成功率和 trace 终态。请让账号兜底受模型 account-pool route 约束,修正重复 final/outcome,并补“聚合成功、双路由失败回落、aggregate-only 禁止回落、流式/非流式及 tools”的真实网关测试后再复审。

@qxcnm
qxcnm merged commit c84ac6e into qxcnm:main Sep 2, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants