CC Switch v3.9.0 版本解析：本地 API 代理、自动故障转移与统一供应商的完整落地

本文基于 CC Switch 仓库中的 v3.9.0 英文版发布说明（另见 中文版 与 日文版）展开，系统梳理 v3.9.0 这一稳定版本引入的三大核心能力：面向 Claude Code / Codex / Gemini CLI 的本地 API 代理（含逐应用接管）、基于熔断器的自动故障转移（Auto Failover），以及跨应用共享配置的统一供应商（Universal Provider）。读完本文，你不仅掌握各功能的使用方式，还能对照仓库源码理解代理服务器、熔断器状态机与统一供应商数据模型的实现细节，从而更可靠地配置与排障。

版本概览

CC Switch v3.9.0 是 v3.9 beta 系列（3.9.0-1、3.9.0-2、3.9.0-3）的正式稳定版，发布日期为 2026-01-07。该版本在一套统一代理之上完成了跨应用工作流的补全，主要亮点包括：

• Claude Code / Codex / Gemini CLI 的本地 API 代理（Local API Proxy）
• 带熔断器（Circuit Breaker）与逐应用故障转移队列的自动故障转移
• 统一供应商（Universal Provider）：一份共享配置同步到多个应用，特别适合 NewAPI 这类多协议 API 网关
• Skills 管理增强：多应用支持、SSOT + React Query 的统一管理架构
• 通用配置片段（Common Config Snippets）：从编辑器或当前供应商提取可复用片段
• MCP 导入：从已安装应用导入 MCP 服务器
• 用量统计改进：自动刷新、缓存命中/创建指标、时区修复
• Linux 打包：新增 RPM 与 Flatpak 制品

本地 API 代理：Axum 实现与逐应用接管

v3.9.0 引入了本地高性能 HTTP 代理服务器，由 Rust 的 Axum 框架构建，统一承接 Claude Code、Codex 与 Gemini CLI 三类应用的请求。其关键设计点如下：

• 逐应用接管（Per-app takeover）：你可以独立决定哪个应用走代理，哪个应用直连上游。只有被接管（enabled=true）的应用才会被代理路由，故障转移切换也仅在被接管的应用上生效（见下文 failover_switch.rs 中的 app_enabled 校验）。
• 实时配置接管（Live config takeover）：开启接管后，CC Switch 会先备份 CLI 的实时配置文件，再将其指向本地代理地址；若需回退，关闭接管/停止代理后从备份恢复即可。
• 监控与排障：代理记录请求日志与用量统计，便于调试与成本追踪。此外针对 #401（感谢 @yovinchen），代理会为失败请求保留详细错误日志，显著简化排障。

从源码结构看，代理服务器定义在 server.rs。文件头部注释说明了一个实现细节：它采用手动的 hyper HTTP/1.1 accept 循环并开启 preserve_header_case(true)，将 CLI 客户端原始 header 命名大小写捕获进 HeaderCaseMap 扩展，再经由 hyper 客户端转发给上游，从而保证线上 header 大小写与"直连（非代理）请求"完全一致——这对部分对 header 大小写敏感的上游服务是重要的兼容性保证。

ProxyState 结构（server.rs）集中持有代理运行所需的共享状态：数据库连接、代理配置与状态、每个应用当前使用的 provider 映射（app_type -> (provider_id, provider_name)）、跨请求保持的 ProviderRouter（内含熔断器状态）、FailoverSwitchManager 故障转移切换管理器，以及面向 Gemini/Codex 的桥接存储（GeminiShadowStore、CodexChatHistoryStore）。围绕该状态构建的完整模块树位于 src-tauri/src/proxy/,包括协议适配（providers/ 下的 claude/codex/gemini 等转换与流式实现）、用量计算（usage/）与熔断、转发、模型映射等核心组件。

自动故障转移：熔断器状态机与逐应用队列

v3.9.0 的 Auto Failover 会自动检测供应商故障并触发熔断保护：当前供应商不健康时自动切换到备用供应商，实时跟踪供应商健康状态，并为每个应用维护独立的故障转移队列；关闭故障转移后，超时/重试相关设置不再影响正常请求流。

熔断器状态与参数

熔断器实现位于 circuit_breaker.rs，采用经典的三态模型（CircuitState）：

状态	含义
Closed	正常放行，计数失败
Open	熔断激活，拒绝请求
HalfOpen	熔断超时后进入，允许部分探测请求通过

CircuitBreakerConfig（circuit_breaker.rs）定义了五个可调参数，其默认值来自 Default 实现：

参数	含义	默认值
failure_threshold	连续失败多少次后打开熔断器	4
success_threshold	半开状态下连续成功多少次后关闭熔断器	2
timeout_seconds	熔断打开后多久进入半开试探	60 秒
error_rate_threshold	错误率超过该值（0.0–1.0）时打开熔断器	0.6
min_requests	计算错误率前的最小请求数	10

这些配置与 AppProxyConfig 中的 circuit_* 字段一一对应（见 From<&AppProxyConfig> 实现），并且配置支持热更新而不重置状态。半开状态下还通过 half_open_requests 计数对放行请求限流，避免探测风暴。

故障转移切换的去重机制

切换动作由 failover_switch.rs 中的 FailoverSwitchManager 执行。从源码可以看到两层保护：

1. 去重控制：以 "app_type:provider_id" 为键维护 pending_switches 集合，相同切换已在进行中时直接跳过（try_switch），避免并发请求同时触发多次切换；
2. 接管校验：只有该应用的代理配置 enabled=true（即已被接管）时才允许执行故障转移切换（do_switch），未接管的应用不受影响。

切换成功后，管理器会更新托盘菜单并向前端发射事件，使 UI 直观反映当前实际使用的供应商。前端侧对应组件包括 FailoverQueueManager.tsx 与 AutoFailoverConfigPanel.tsx，分别负责逐应用队列展示与熔断参数配置面板；整体代理入口为 ProxyPanel.tsx。

统一供应商：一份配置同步多应用

统一供应商（Universal Provider）面向支持多协议的 API 网关（例如 NewAPI）：只维护一份 baseUrl + apiKey 配置，按需同步到 Claude / Codex / Gemini 各应用，并支持在单个供应商下为每个应用分别映射默认模型（对应 #348，感谢 @Calcium-Ion）。

数据模型

后端数据模型定义在 provider.rs。核心结构 UniversalProvider 的字段与取值如下：

字段	说明
id / name	唯一标识与显示名称
providerType	供应商类型，如 "newapi"、"custom"
apps	逐应用启用开关：claude / codex / gemini（布尔值，默认关闭）
baseUrl / apiKey	API 基础地址与密钥
models.claude	Claude 模型映射：model（主模型）、haikuModel、sonnetModel、opusModel
models.codex	Codex 模型映射：model、reasoningEffort（推理强度）
models.gemini	Gemini 模型映射：model
websiteUrl / notes	可选的网站链接与备注

可以看到，"逐应用默认模型映射"是通过嵌套的 UniversalProviderModels 结构实现的：Claude 侧细分了 Haiku/Sonnet/Opus 三档默认模型（贴合 Claude Code 的多模型调用形态），Codex 侧额外携带 reasoningEffort，Gemini 侧仅单模型。所有字段对缺省值使用 skip_serializing_if，序列化结果保持紧凑。

持久化方面，universal_providers.rs 将全部统一供应商以 JSON 形式存入 settings 表的 universal_providers 键下，提供 get_all_universal_providers / get_universal_provider / save_universal_provider / delete_universal_provider 四个 CRUD 操作。前端管理界面由 src/components/universal/ 下的 UniversalProviderPanel.tsx、UniversalProviderFormModal.tsx 等组件构成。

Skills 管理增强

• 面向 Claude Code 与 Codex 的多应用 Skills 支持，并从旧版技能布局平滑迁移（#365、#378，感谢 @yovinchen）；
• 统一 Skills 管理架构：SSOT + React Query，保证更一致的状态与刷新行为；
• 发现（discovery）体验与性能改进：
  • 发现过程跳过隐藏目录
  • 对可发现技能使用长生命周期缓存，加速发现
  • 更清晰的加载指示器，头部操作（导入/刷新）更易发现
  • 修复技能仓库分支错误（#505，感谢 @kjasn）

通用配置片段（Common Config Snippets）

v3.9.0 允许维护可复用的"common config"片段，并将其合并/追加到启用该功能的供应商中。新增的提取工作流支持两种来源：

1. 从编辑器内容提取——提取你当前正在编辑的内容；
2. 从当前激活供应商提取——编辑器未提供内容时的回退来源。

针对 Codex，提取逻辑做了安全性处理：

• 移除供应商特定小节，如 model_provider、model 以及整个 [model_providers] 表；
• 保留 [mcp_servers.*] 下的 base_url，避免误伤 MCP 配置。

这一点很关键：Codex 的 config.toml 中 [model_providers] 与具体供应商强绑定，若片段里混入这些字段，同步到其他供应商时会直接破坏其 provider 定义；而 [mcp_servers.*] 下的 base_url 是 MCP 服务器自身的定位信息，必须原样保留。

MCP 管理

• 支持从已安装应用导入 MCP 服务器；
• 健壮性改进：目标 CLI 应用未安装时跳过同步；优雅处理非法的 Codex config.toml（#461，感谢 @majiayu000）；
• Windows 兼容：MCP 导出时将 npx/npm 命令用 cmd /c 包装。

用量与定价改进

• 用量与定价改进：自动刷新、缓存命中/创建（cache hit/creation）指标、时区处理修复、内置定价表更新（#508，感谢 @yovinchen）；
• DeepLink 支持：通过 deeplink 导入用量查询配置（#400，感谢 @qyinter）；
• 用量统计的模型提取（#455，感谢 @yovinchen）；
• 用量查询凭证可回退到供应商配置（#360，感谢 @Sirhexs）。

代理侧的用量计算实现位于 src-tauri/src/proxy/usage/（calculator.rs、logger.rs、parser.rs），配合请求日志完成用量统计落库。

UX 改进一览

• 供应商搜索过滤：按名称快速定位供应商（#435，感谢 @TinsFox）
• 供应商图标配色：自定义图标颜色，便于视觉识别（#385，感谢 @yovinchen）
• 快捷键 Cmd/Ctrl + , 打开设置页（#436，感谢 @TinsFox）
• 可选跳过 Claude Code 首运确认对话框
• Toast 可关闭：切换 toast 与所有成功 toast 增加关闭按钮（#350，感谢 @ForteScarlet）
• 更新徽章点击后导航到 About 页签
• 设置页 Tab 样式改进（#342，感谢 @wenyuanw）
• 更平滑的过渡：应用/视图切换的淡入淡出、面板退出动画
• 代理接管主题：接管激活时应用 emerald 主题
• 深色模式下表单与标签可读性改进
• 全屏面板的窗口拖拽区域优化（#525，感谢 @zerob13）

平台说明

Windows

• 版本检查时避免弹出终端窗口
• 改善窗口尺寸默认值（最小宽/高）
• 使用系统标题栏修复启动黑屏
• 为旧版 WebView 增加 crypto.randomUUID() 回退

macOS

• 自启动改用 .app 捆绑包路径，避免终端窗口弹出（#462，感谢 @majiayu000）
• 改善托盘/图标行为与标题栏对齐

打包：Linux 新增 RPM 与 Flatpak

v3.9.0 起，Linux 的 RPM 与 Flatpak 打包目标可用于构建发布制品。仓库中 flatpak/ 目录包含完整的 Flatpak 工程文件，包括 com.ccswitch.desktop.yml（构建配方）、com.ccswitch.desktop.desktop 与 com.ccswitch.desktop.metainfo.xml，并附有 Flatpak 说明文档。

安全与注意事项

• JavaScript 执行器安全加固：针对 JS 执行器与用量脚本执行做了安全改进（#151，感谢 @luojiyin1987）；
• SQL 导入限制：仅允许导入 CC Switch 自身导出的备份，降低导入不安全或不兼容 SQL dump 的风险；
• 代理接管影响面：代理接管会修改 CLI 实时配置。CC Switch 在重定向到本地代理前会先备份实时配置；如需还原，关闭接管/停止代理后从备份恢复。

下载与安装

前往项目官方发布页面下载对应版本的制品（详见项目仓库 README 与 中文版 README）。

系统要求

系统	最低版本	架构
Windows	Windows 10 或更高	x64
macOS	macOS 10.15 (Catalina) 或更高	Intel (x64) / Apple Silicon (arm64)
Linux	见下表	x64

Windows

文件	说明
CC-Switch-v3.9.0-Windows.msi	推荐 - 支持自动更新的 MSI 安装器
CC-Switch-v3.9.0-Windows-Portable.zip	便携版，无需安装

macOS

文件	说明
CC-Switch-v3.9.0-macOS.zip	推荐 - 解压后拖入 Applications，Universal Binary
CC-Switch-v3.9.0-macOS.tar.gz	用于 Homebrew 安装与自动更新

注意：由于作者没有 Apple 开发者账号，首次启动时可能看到"未知开发者"警告。关闭应用后前往"系统设置" → "隐私与安全性" → 点击"仍要打开"，之后即可正常启动。

Homebrew（macOS）

brew tap farion1231/ccswitch
brew install --cask cc-switch

更新：

brew upgrade --cask cc-switch

Linux

发行版	推荐格式	安装方式
Ubuntu / Debian / Linux Mint / Pop!_OS	.deb	sudo dpkg -i CC-Switch-*.deb 或 sudo apt install ./CC-Switch-*.deb
Fedora / RHEL / CentOS / Rocky Linux	.rpm	sudo rpm -i CC-Switch-*.rpm 或 sudo dnf install ./CC-Switch-*.rpm
openSUSE	.rpm	sudo zypper install ./CC-Switch-*.rpm
Arch Linux / Manjaro	.AppImage	赋予可执行权限直接运行，或使用 AUR
其他发行版 / 不确定	.AppImage	chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage
沙盒安装	.flatpak	flatpak install CC-Switch-*.flatpak

参考路径索引

内容	路径
本版本发布说明（英/中/日）	docs/release-notes/v3.9.0-en.md、v3.9.0-zh.md、v3.9.0-ja.md
代理服务器（Axum + hyper accept loop）	src-tauri/src/proxy/server.rs
熔断器与默认参数	src-tauri/src/proxy/circuit_breaker.rs
故障转移切换（去重 + 接管校验）	src-tauri/src/proxy/failover_switch.rs
统一供应商数据模型	src-tauri/src/provider.rs
统一供应商持久化 DAO	src-tauri/src/database/dao/universal_providers.rs
前端代理面板/故障转移队列	src/components/proxy/ProxyPanel.tsx、FailoverQueueManager.tsx
前端统一供应商面板	src/components/universal/UniversalProviderPanel.tsx
Flatpak 打包工程	flatpak/com.ccswitch.desktop.yml