Skip to content

feat: 支持 API 429 (Too Many Requests) 自动故障转移与轮询#79

Open
QuickLAW wants to merge 19 commits intoBiFangKNT:devfrom
QuickLAW:tauri
Open

feat: 支持 API 429 (Too Many Requests) 自动故障转移与轮询#79
QuickLAW wants to merge 19 commits intoBiFangKNT:devfrom
QuickLAW:tauri

Conversation

@QuickLAW
Copy link
Copy Markdown

@QuickLAW QuickLAW commented Mar 12, 2026

变更目的

为代理系统引入多端点轮询(Round-Robin)与 429 自动故障转移机制,旨在提升在高并发或多账号场景下的服务稳定性,避免因单一节点触发频率限制而导致服务中断。

使用变更与说明

1. 配置多 API 节点

系统现在会自动聚合所有“配置组”中已启用的 API 节点。

  • 操作:在 API 配置页面创建多个配置组(例如:配置组 A 使用 DeepSeek,配置组 B 使用 SiliconFlow)。
  • 生效:只要配置组处于启用状态,其对应的 api_urlapi_key 就会被纳入负载均衡池。

2. 开启转发策略

设置面板 > 应用设置 中新增了“转发策略”配置区:

  • 启用多节点轮询与自动故障转移
    • 关闭(默认):仅使用当前激活的单一配置组。
    • 开启:请求将在所有已启用的配置组间进行轮询(Round-Robin)分发。
  • 节点冷却周期 (秒)
    • 当某个节点返回 429 (Too Many Requests) 时,该节点将进入冷却状态。
    • 在冷却时间内,系统将跳过该节点并自动切换至下一个可用节点。
    • 你可以根据不同供应商的频率限制策略,自定义冷却时长(默认为 10 秒)。

3. 智能适配与日志

  • SiliconFlow 适配:若检测到 SiliconFlow 节点,系统会自动适配其 thinking 参数,确保思维链功能正常。
  • 实时反馈:故障转移发生时,你可以在后端日志或前端状态栏查看到节点切换的提示信息。

影响范围

  • 后端逻辑
    • proxy_app.py:实现多端点轮询调度及基于 429 状态码的自动切换逻辑。
    • proxy_config.py:新增 ProxyApiEndpoint 结构,支持从配置组加载多个 API 节点。
    • config_service.py:扩展全局配置,新增故障转移开关及自定义冷却时间字段。
  • 前端 UI
    • SettingsPanel.vue:在设置面板新增“转发策略”区域,提供故障转移开关及节点冷却时间输入控件。
  • 其他适配:兼容了 SiliconFlow 的 thinking 相关参数解析。

验证方式

  1. 多节点配置:在设置中配置多个 API 节点,确认请求能够按轮询顺序分发。
  2. 故障转移测试:模拟并测试上游返回 429 错误,确认系统能自动跳过当前节点并切换至下一可用节点。
  3. 冷却机制验证:验证触发 429 后节点进入冷却期,在设定的 failover_429_cooldown_seconds 时间内不被再次调度。
  4. UI 交互:确认设置面板的开关及数值保存功能正常。

UI 变更截图

image

修复与优化 (针对 AI 审查反馈) [日期3.13]

  • 轮询健壮性:修复了在非 429 错误(如连接失败)时游标卡死的问题,确保故障转移能覆盖更多异常场景。
  • 路由兼容性:支持每个 API 端点配置独立的 middle_route,适配 OpenAI、Azure 等混合部署。
  • 解析安全性:对冷却时间配置增加了类型检查和异常捕获,防止非法输入导致崩溃。

QuickLAW and others added 11 commits March 11, 2026 16:14
- 在代理配置中引入 `api_endpoints` 列表,支持配置多个上游API端点和密钥
- 当上游返回429(请求过多)状态码时,自动切换到列表中的下一个可用端点
- 修改 `ProxyConfig` 结构,将单 `api_url` 和 `api_key` 替换为 `api_endpoints` 元组
- 在 `ProxyApp` 中实现端点轮询逻辑,并在请求失败时更新游标
- 优化 `user_data_service.py` 中的 `max` 函数调用,使用 `os.path.basename` 直接作为 key
- 确保在HTTP错误和请求结束时正确关闭响应连接,避免资源泄漏
在收到上游 429 状态码时,现在会检查并记录 `retry-after` 头信息,以便于调试。同时,将节点切换逻辑移至 429 条件块内部,使逻辑更清晰,避免不必要的节点切换。
- 新增端点级429冷却机制,通过 `_endpoint_429_until` 字典记录冷却时间
- 当启用 `enable_429_failover` 且配置多个端点时,自动跳过冷却中的节点
- 适配 SiliconFlow 的 thinking 参数,将其转换为 enable_thinking 和 thinking_budget
- 在单端点或未启用故障转移时保持原有轮询逻辑
- 添加400错误时的请求参数日志以便调试
扩展ProxyApiEndpoint类以包含target_model_id字段,并新增enable_429_failover配置选项。重构_parse_api_endpoints函数,使其支持从全局配置的config_groups中读取故障转移端点列表,并在启用故障转移时进行去重处理。调整build_proxy_config中的调用顺序以适配新的参数传递。
在load_global_config和save_config_groups方法中新增enable_429_failover布尔字段,以支持在遇到HTTP 429状态码时启用故障转移逻辑。
更新函数调用以解构三元组,忽略新增的布尔标志位,保持现有逻辑不变。
在 SaveConfigPayload 模型中新增 enable_429_failover 布尔字段,用于控制是否启用 429 状态码的失败转移机制。同时更新了 load_config 和 save_config 函数以支持该配置的加载和保存。
在配置类型和状态管理中新增 `enable_429_failover` 选项,并在设置面板提供对应的 UI 开关。
启用后,请求将在配置组间轮询分发,并在遇到 429 状态码时自动切换到下一个节点,避免因请求限制导致服务中断。
- 在全局配置中添加 `failover_429_cooldown_seconds` 字段,允许用户自定义触发429后的节点冷却时长
- 前端设置面板增加对应数值输入控件,支持秒级调整
- 代理逻辑使用配置的冷却时间,替代之前硬编码的10秒
- 修复SSE事件解析以同时支持 `\n\n` 和 `\r\n\r\n` 分隔符
- 重构配置保存逻辑,使用字典统一处理全局配置更新
将“高级策略”改为“转发策略”,明确功能定位
将“API 调度与故障转移”改为“负载均衡与自动容错”,更准确描述功能
调整相关开关和说明文案,使描述更清晰易懂
优化冷却时间输入框样式,提升视觉一致性
@dosubot dosubot bot added size:L This PR changes 100-499 lines, ignoring generated files. UI labels Mar 12, 2026
@BiFangKNT
Copy link
Copy Markdown
Owner

@codex 审查

Repository owner deleted a comment from chatgpt-codex-connector bot Mar 12, 2026
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 481309fe0f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

- 移除全局 middle_route 变量,改为使用端点级别的配置
- 修复端点游标计算逻辑,避免不必要的偏移
- 增强错误处理:对网络异常和特定状态码(400、401、403等)进行故障转移
- 优化模型替换逻辑,保留原始模型名用于日志记录
- 仅当启用路由且请求成功时才更新游标,确保负载均衡
- 改进端点唯一标识,包含 middle_route 信息
- 在 ProxyApiEndpoint 中新增 middle_route 字段,支持为每个端点配置中间路由
- 在解析配置时,使用 normalize_middle_route 函数处理中间路由值,确保格式统一
- 新增 _parse_cooldown_seconds 函数,集中处理 429 失败转移冷却时间的解析逻辑,提高代码可读性和健壮性
- 在端点去重逻辑中,加入对 middle_route 字段的比对,避免重复添加相同配置的端点
@dosubot dosubot bot added size:XL This PR changes 500-999 lines, ignoring generated files. and removed size:L This PR changes 100-499 lines, ignoring generated files. labels Mar 13, 2026
@BiFangKNT
Copy link
Copy Markdown
Owner

我觉得得再加一个可选配置组的功能,有时候不会希望所有配置组都走轮询

@QuickLAW
Copy link
Copy Markdown
Author

我觉得得再加一个可选配置组的功能,有时候不会希望所有配置组都走轮询

很可行,我刚刚就在考虑这个问题了,最好前端分组展示也需要调整下

@BiFangKNT
Copy link
Copy Markdown
Owner

另外,我认为你还需要考虑一下 #48,这两个需求之间会存在竟态,需要设计一个统一的架构

@QuickLAW
Copy link
Copy Markdown
Author

另外,我认为你还需要考虑一下 #48,这两个需求之间会存在竟态,需要设计一个统一的架构

ok,我研究下

@BiFangKNT BiFangKNT added enhancement New feature or request good first issue Good for newcomers labels Mar 13, 2026
Repository owner deleted a comment from chatgpt-codex-connector bot Mar 14, 2026
@BiFangKNT
Copy link
Copy Markdown
Owner

请先稍等,我对未来的架构设计有了初步想法

- 为配置组添加唯一ID字段,支持配置组的稳定标识和更新
- 在前端设置面板中添加轮询配置组选择功能,允许用户指定参与轮询的配置组
- 优化代理配置解析逻辑,支持基于选中组的轮询分发策略
- 当开启429故障转移且未选择任何组时,回退到仅使用当前激活配置
@QuickLAW
Copy link
Copy Markdown
Author

QuickLAW commented Mar 16, 2026

请先稍等,我对未来的架构设计有了初步想法

那挺好,因为我加了区分配置组功能后觉得,配置组和设置这些真需要修改下

@BiFangKNT
Copy link
Copy Markdown
Owner

是要大改的,且是持续数个版本的改动,本pr应该不会太快合并

@BiFangKNT
Copy link
Copy Markdown
Owner

你有空的话,可以先把我设计中的前置功能写一下,通过独立pr的形式

@QuickLAW
Copy link
Copy Markdown
Author

你有空的话,可以先把我设计中的前置功能写一下,通过独立pr的形式

ok,这可行

@BiFangKNT
Copy link
Copy Markdown
Owner

BiFangKNT commented Mar 16, 2026

路线图总述
这份路线图的目标不是一次性定义所有实现细节,而是先固定未来三个版本的稳定边界,避免社区贡献继续沿着当前“单当前映射 + 配置组兼任路由对象”的旧心智扩展。

版本计划

  • v2.4.0 只解决“多供应商上游适配”,不改核心配置模型。
  • v2.5.0 先把代理日志改成结构化 trace,并同步引入代理并发能力。
  • v2.6.0 一次性完成路由模型重构,前端页名统一为“模型路由”。
  • v2.6.0 的稳定对象模型为:
targets:
  - id: claude-main
    provider: anthropic
    api_base: https://example.com

    api_key: xxx
    middle_route: /v1
    upstream_model: claude-3-7-sonnet

failover_pools:
  - id: claude-failover
    trigger_statuses: [429]
    cooldown_seconds: 10
    members:
      - target_id: claude-backup-1
      - target_id: claude-backup-2

published_models:
  - name: sonnet-proxy
    enabled: true
    primary_target_id: claude-main
    failover_pool_id: claude-failover
  • 同一个 target 可被多个 published_model、多个 failover_pool 复用,不做限制。
  • 不做模型能力自动识别与兼容性校验,风险由用户自行承担。
  • “多对一”的真实需求收敛为“主目标 + 故障转移池”,不单独设计主池多成员。

当前主要落点

v2.4.0:LiteLLM 接入
目标

  • proxy_app 中引入 LiteLLM,支持将 OpenAI Chat Completions 请求转发到 Anthropic、Google 等上游。
  • 保持当前 UI、当前配置格式、当前 /models 语义基本不变。
  • v2.5.0 的 trace 和 v2.6.0 的动态路由埋下可扩展的上游适配接口。

范围

  • 抽出“上游调用适配层”,把供应商差异从 proxy_app 主流程里分离。
  • 保持现有“单当前映射”模式。
  • 兼容流式和非流式请求。
  • 保留现有系统提示词处理链路。

明确不做

  • 不做多发布模型。
  • 不做新的配置 schema。
  • 不做故障转移。
  • 不做日志页重构。

建议拆分 issue

  1. 后端:引入 LiteLLM 依赖并封装供应商适配入口。
  2. 后端:统一上游请求构造与响应归一化接口。
  3. 后端:补充 Anthropic、Google 等最小可用 provider 适配。
  4. 测试:补足流式、非流式、异常响应的回归测试。
  5. 文档:补充支持的 provider 范围与限制。

验收标准

  • 在不改现有配置页的前提下,可完成至少 2 个非 OpenAI 上游的对话转发。
  • SSE 与非 SSE 行为不回退。
  • 现有 pnpm py:check 通过。

v2.5.0:代理日志页 + 并发
目标

  • 将代理日志从普通字符串日志升级为结构化 trace
  • 新增“代理日志”页,放在导航栏“主要流程”下方。
  • 让同一发布模型在当前架构下支持并发请求。
  • 现有右侧日志区只保留代理请求摘要,其余日志行为不变。

trace 设计原则

  • 一条代理请求对应一条 trace。
  • trace 必须可唯一定位并发请求。
  • trace 详情必须能支撑后续 v2.6.0 的动态路由调试。
  • 第一版优先做内存环形缓冲,不要求重启持久化。

建议 trace 字段

type ProxyTrace = {
  trace_id: string;
  request_id: string;
  request_path: string;
  request_model?: string;
  resolved_target_label?: string;
  target_api_base_url?: string;
  upstream_model?: string;
  is_stream: boolean;
  status_code?: number;
  started_at: string;
  ended_at?: string;
  duration_ms?: number;
  request_body?: unknown;
  response_body?: unknown;
  error?: string;
  events?: string[];
};

范围

  • 后端新增 trace 总线或 trace 存储,不再复用现有纯字符串 log_bus 作为代理详情载体。
  • 前端新增“代理日志”页,UI 参考“系统提示词”页的列表区。
  • 右侧运行日志区只记录一行摘要,例如“收到代理请求”或“已转发到上游”。
  • 代理运行时改造成可并发处理请求。
  • 这一版并发只解决“当前单映射模型下的并发处理”,不提前引入多发布模型路由。

明确不做

建议拆分 issue

  1. 后端:定义 ProxyTrace 数据结构与生命周期。
  2. 后端:新增 trace 查询接口,至少包含列表、详情、清空。
  3. 后端:把 proxy_app 中请求处理打点为 trace。
  4. 后端:升级代理运行时以支持并发处理。
  5. 前端:新增“代理日志”页的列表视图。
  6. 前端:新增 trace 详情视图,显示请求体、响应体、状态码、耗时、错误。
  7. 前端:调整右侧日志区,仅保留代理摘要。
  8. 测试:增加并发请求、trace 完整性、清理逻辑测试。
  9. 文档:解释 trace 字段、并发范围、内存保留策略。

验收标准

  • 同一模型可同时处理多个请求,不互相阻塞。
  • 并发请求在“代理日志”页中可独立追踪。
  • 日志页能定位单次请求的完整请求体与响应体。
  • 现有 pnpm py:checkpnpm app:check 通过。

v2.6.0:模型路由
目标

  • 引入新路由架构:published_model + primary_target + optional failover_pool
  • /models 返回全部启用的发布模型。
  • 请求按 request.model 动态路由,不再依赖线程内固定单一映射。
  • 合并“代理配置组”页和“全局配置”页,统一为“模型路由”。
  • 编辑保存“模型路由”配置后,沿用现有热切换能力对运行中代理生效,无需重启线程;代理未运行时则在下次启动时生效。

范围

  • 后端配置 schema 从旧的 config_groups + current_config_index + mapped_model_id 迁移到新结构。
  • 前端“模型路由”页负责管理:
    • targets
    • failover_pools
    • published_models
  • 每个 published_model 只能绑定一个 primary_target_id
  • 每个 published_model 可选一个 failover_pool_id
  • 故障转移第一阶段只要求支持 429 冷却切换。
  • 冷却状态应以 target_id 为键,而不是 pool member 局部状态。
  • /models 只返回启用的 published_model.name
  • 允许同一 target 被多个模型、多处故障转移池复用。
  • 路由配置保存后应直接热应用到运行中代理,仅影响后续新请求;已在处理中的请求继续沿用各自请求开始时解析出的路由。

明确不做

  • 不做模型能力自动探测。
  • 不做无限级故障转移链。
  • 不做复杂流量调度策略。
  • 不做“主目标多成员”的另一套语义。
  • 不接受继续扩展旧 config_group 语义来模拟新模型路由。

建议拆分 issue

  1. 后端:定义新配置 schema 与类型。
  2. 后端:实现旧 schema 到新 schema 的迁移逻辑。
  3. 后端:实现 request.model -> published_model -> primary_target/failover_pool 解析器。
  4. 后端:把现有运行中配置应用能力扩展到整套模型路由配置,保存后自动热切换。
  5. 后端:实现 /models 返回全部启用发布模型。
  6. 后端:实现基于 target_id 的 429 冷却状态管理。
  7. 后端:实现故障转移池按顺序尝试的执行器。
  8. 前端:设计“模型路由”页信息架构。
  9. 前端:实现 targets 管理。
  10. 前端:实现 failover_pools 管理。
  11. 前端:实现 published_models 管理。
  12. 前端:移除旧“代理配置组”页与“全局配置”页入口。
  13. 测试:覆盖迁移、动态路由、热切换、429 故障转移、复用 target 等行为。
  14. 文档:补充术语解释、迁移说明、故障转移风险说明。

验收标准

  • 用户无需重启代理,即可通过不同发布模型命中不同上游目标。
  • 编辑并保存运行中的“模型路由”配置后,无需重启代理线程即可对后续请求生效。
  • /models 可列出全部启用发布模型。
  • 主目标返回 429 时,可按配置切换到故障转移池中的下一个可用目标。
  • 同一 target 复用于多个模型和多个池时行为一致。
  • 现有 pnpm py:checkpnpm app:check 通过。

社区协作规则

  • 单个 PR 只覆盖一个里程碑,不跨 v2.4.0v2.5.0v2.6.0
  • 设计型 PR 必须先在 issue 中确认术语和边界,再进入实现。
  • 涉及 Python 的变更必须运行 pnpm py:check
  • 涉及 JS/TS/Vue 的变更必须运行 pnpm app:check
  • 涉及配置 schema 的 PR 必须写迁移说明。
  • 涉及日志/trace 的 PR 必须说明数据保留策略和内存上限。
  • 涉及代理并发的 PR 必须给出至少一个并发行为测试。
  • 涉及 UI 的 PR 必须附截图或录屏。

对现有 PR 的处理建议

  • PR feat: 支持 API 429 (Too Many Requests) 自动故障转移与轮询 #79 不建议按当前“配置组轮询/全局开关”语义直接合并。
  • 欢迎把其中可复用部分拆出来单独贡献:
    • 429 冷却内核
    • 目标切换执行逻辑
    • 每目标独立 middle_route 支持
  • 这些成果应服务 v2.6.0target + failover_pool 结构,而不是继续强化旧 config_group

暂不接受的贡献方向

  • 继续把 config_group 扩展成多模型路由核心对象。
  • v2.5.0 之后仍把代理详情日志做成纯字符串拼接。
  • 未完成并发 trace 设计就先做复杂日志 UI。
  • 在安全边界未明确前,仅做“允许空鉴权 key”的放宽而不讨论监听策略。

建议的公开发布方式

  • 新增一份 GitHub Projects - Roadmap。
  • v2.4.0v2.5.0v2.6.0 各建立 milestone。
  • 所有相关 issue 打上统一标签,例如:
    • roadmap:v2.4.0
    • roadmap:v2.5.0
    • roadmap:v2.6.0
    • area:proxy
    • area:frontend
    • area:config
    • area:trace
    • needs-design

@QuickLAW
Copy link
Copy Markdown
Author

路线图总述 这份路线图的目标不是一次性定义所有实现细节,而是先固定未来三个版本的稳定边界,避免社区贡献继续沿着当前“单当前映射 + 配置组兼任路由对象”的旧心智扩展。

版本计划

  • v2.4.0 只解决“多供应商上游适配”,不改核心配置模型。
  • v2.5.0 先把代理日志改成结构化 trace,并同步引入代理并发能力。
  • v2.6.0 一次性完成路由模型重构,前端页名统一为“模型路由”。
  • v2.6.0 的稳定对象模型为:
targets:
  - id: claude-main
    provider: anthropic
    api_base: https://example.com

    api_key: xxx
    middle_route: /v1
    upstream_model: claude-3-7-sonnet

failover_pools:
  - id: claude-failover
    trigger_statuses: [429]
    cooldown_seconds: 10
    members:
      - target_id: claude-backup-1
      - target_id: claude-backup-2

published_models:
  - name: sonnet-proxy
    enabled: true
    primary_target_id: claude-main
    failover_pool_id: claude-failover
  • 同一个 target 可被多个 published_model、多个 failover_pool 复用,不做限制。
  • 不做模型能力自动识别与兼容性校验,风险由用户自行承担。
  • “多对一”的真实需求收敛为“主目标 + 故障转移池”,不单独设计主池多成员。

当前主要落点

v2.4.0:LiteLLM 接入 目标

  • proxy_app 中引入 LiteLLM,支持将 OpenAI Chat Completions 请求转发到 Anthropic、Google 等上游。
  • 保持当前 UI、当前配置格式、当前 /models 语义基本不变。
  • v2.5.0 的 trace 和 v2.6.0 的动态路由埋下可扩展的上游适配接口。

范围

  • 抽出“上游调用适配层”,把供应商差异从 proxy_app 主流程里分离。
  • 保持现有“单当前映射”模式。
  • 兼容流式和非流式请求。
  • 保留现有系统提示词处理链路。

明确不做

  • 不做多发布模型。
  • 不做新的配置 schema。
  • 不做故障转移。
  • 不做日志页重构。

建议拆分 issue

  1. 后端:引入 LiteLLM 依赖并封装供应商适配入口。
  2. 后端:统一上游请求构造与响应归一化接口。
  3. 后端:补充 Anthropic、Google 等最小可用 provider 适配。
  4. 测试:补足流式、非流式、异常响应的回归测试。
  5. 文档:补充支持的 provider 范围与限制。

验收标准

  • 在不改现有配置页的前提下,可完成至少 2 个非 OpenAI 上游的对话转发。
  • SSE 与非 SSE 行为不回退。
  • 现有 pnpm py:check 通过。

v2.5.0:代理日志页 + 并发 目标

  • 将代理日志从普通字符串日志升级为结构化 trace
  • 新增“代理日志”页,放在导航栏“主要流程”下方。
  • 让同一发布模型在当前架构下支持并发请求。
  • 现有右侧日志区只保留代理请求摘要,其余日志行为不变。

trace 设计原则

  • 一条代理请求对应一条 trace。
  • trace 必须可唯一定位并发请求。
  • trace 详情必须能支撑后续 v2.6.0 的动态路由调试。
  • 第一版优先做内存环形缓冲,不要求重启持久化。

建议 trace 字段

type ProxyTrace = {
  trace_id: string;
  request_id: string;
  request_path: string;
  request_model?: string;
  resolved_target_label?: string;
  target_api_base_url?: string;
  upstream_model?: string;
  is_stream: boolean;
  status_code?: number;
  started_at: string;
  ended_at?: string;
  duration_ms?: number;
  request_body?: unknown;
  response_body?: unknown;
  error?: string;
  events?: string[];
};

范围

  • 后端新增 trace 总线或 trace 存储,不再复用现有纯字符串 log_bus 作为代理详情载体。
  • 前端新增“代理日志”页,UI 参考“系统提示词”页的列表区。
  • 右侧运行日志区只记录一行摘要,例如“收到代理请求”或“已转发到上游”。
  • 代理运行时改造成可并发处理请求。
  • 这一版并发只解决“当前单映射模型下的并发处理”,不提前引入多发布模型路由。

明确不做

建议拆分 issue

  1. 后端:定义 ProxyTrace 数据结构与生命周期。
  2. 后端:新增 trace 查询接口,至少包含列表、详情、清空。
  3. 后端:把 proxy_app 中请求处理打点为 trace。
  4. 后端:升级代理运行时以支持并发处理。
  5. 前端:新增“代理日志”页的列表视图。
  6. 前端:新增 trace 详情视图,显示请求体、响应体、状态码、耗时、错误。
  7. 前端:调整右侧日志区,仅保留代理摘要。
  8. 测试:增加并发请求、trace 完整性、清理逻辑测试。
  9. 文档:解释 trace 字段、并发范围、内存保留策略。

验收标准

  • 同一模型可同时处理多个请求,不互相阻塞。
  • 并发请求在“代理日志”页中可独立追踪。
  • 日志页能定位单次请求的完整请求体与响应体。
  • 现有 pnpm py:checkpnpm app:check 通过。

v2.6.0:模型路由 目标

  • 引入新路由架构:published_model + primary_target + optional failover_pool
  • /models 返回全部启用的发布模型。
  • 请求按 request.model 动态路由,不再依赖线程内固定单一映射。
  • 合并“代理配置组”页和“全局配置”页,统一为“模型路由”。
  • 编辑保存“模型路由”配置后,沿用现有热切换能力对运行中代理生效,无需重启线程;代理未运行时则在下次启动时生效。

范围

  • 后端配置 schema 从旧的 config_groups + current_config_index + mapped_model_id 迁移到新结构。

  • 前端“模型路由”页负责管理:

    • targets
    • failover_pools
    • published_models
  • 每个 published_model 只能绑定一个 primary_target_id

  • 每个 published_model 可选一个 failover_pool_id

  • 故障转移第一阶段只要求支持 429 冷却切换。

  • 冷却状态应以 target_id 为键,而不是 pool member 局部状态。

  • /models 只返回启用的 published_model.name

  • 允许同一 target 被多个模型、多处故障转移池复用。

  • 路由配置保存后应直接热应用到运行中代理,仅影响后续新请求;已在处理中的请求继续沿用各自请求开始时解析出的路由。

明确不做

  • 不做模型能力自动探测。
  • 不做无限级故障转移链。
  • 不做复杂流量调度策略。
  • 不做“主目标多成员”的另一套语义。
  • 不接受继续扩展旧 config_group 语义来模拟新模型路由。

建议拆分 issue

  1. 后端:定义新配置 schema 与类型。
  2. 后端:实现旧 schema 到新 schema 的迁移逻辑。
  3. 后端:实现 request.model -> published_model -> primary_target/failover_pool 解析器。
  4. 后端:把现有运行中配置应用能力扩展到整套模型路由配置,保存后自动热切换。
  5. 后端:实现 /models 返回全部启用发布模型。
  6. 后端:实现基于 target_id 的 429 冷却状态管理。
  7. 后端:实现故障转移池按顺序尝试的执行器。
  8. 前端:设计“模型路由”页信息架构。
  9. 前端:实现 targets 管理。
  10. 前端:实现 failover_pools 管理。
  11. 前端:实现 published_models 管理。
  12. 前端:移除旧“代理配置组”页与“全局配置”页入口。
  13. 测试:覆盖迁移、动态路由、热切换、429 故障转移、复用 target 等行为。
  14. 文档:补充术语解释、迁移说明、故障转移风险说明。

验收标准

  • 用户无需重启代理,即可通过不同发布模型命中不同上游目标。
  • 编辑并保存运行中的“模型路由”配置后,无需重启代理线程即可对后续请求生效。
  • /models 可列出全部启用发布模型。
  • 主目标返回 429 时,可按配置切换到故障转移池中的下一个可用目标。
  • 同一 target 复用于多个模型和多个池时行为一致。
  • 现有 pnpm py:checkpnpm app:check 通过。

社区协作规则

  • 单个 PR 只覆盖一个里程碑,不跨 v2.4.0v2.5.0v2.6.0
  • 设计型 PR 必须先在 issue 中确认术语和边界,再进入实现。
  • 涉及 Python 的变更必须运行 pnpm py:check
  • 涉及 JS/TS/Vue 的变更必须运行 pnpm app:check
  • 涉及配置 schema 的 PR 必须写迁移说明。
  • 涉及日志/trace 的 PR 必须说明数据保留策略和内存上限。
  • 涉及代理并发的 PR 必须给出至少一个并发行为测试。
  • 涉及 UI 的 PR 必须附截图或录屏。

对现有 PR 的处理建议

  • PR feat: 支持 API 429 (Too Many Requests) 自动故障转移与轮询 #79 不建议按当前“配置组轮询/全局开关”语义直接合并。

  • 欢迎把其中可复用部分拆出来单独贡献:

    • 429 冷却内核
    • 目标切换执行逻辑
    • 每目标独立 middle_route 支持
  • 这些成果应服务 v2.6.0target + failover_pool 结构,而不是继续强化旧 config_group

暂不接受的贡献方向

  • 继续把 config_group 扩展成多模型路由核心对象。
  • v2.5.0 之后仍把代理详情日志做成纯字符串拼接。
  • 未完成并发 trace 设计就先做复杂日志 UI。
  • 在安全边界未明确前,仅做“允许空鉴权 key”的放宽而不讨论监听策略。

建议的公开发布方式

  • 新增一份 GitHub Projects - Roadmap。

  • v2.4.0v2.5.0v2.6.0 各建立 milestone。

  • 所有相关 issue 打上统一标签,例如:

    • roadmap:v2.4.0
    • roadmap:v2.5.0
    • roadmap:v2.6.0
    • area:proxy
    • area:frontend
    • area:config
    • area:trace
    • needs-design

ok,感谢,收到

@BiFangKNT
Copy link
Copy Markdown
Owner

BiFangKNT commented Mar 16, 2026

ROADMAP.md

这份文档是用于快速确定路线图的,到时候会创建一份 GitHub Projects - Roadmap 方便编辑查阅

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request good first issue Good for newcomers size:XL This PR changes 500-999 lines, ignoring generated files. UI

Projects

Status: Todo

Development

Successfully merging this pull request may close these issues.

2 participants