mirror of https://github.com/farion1231/cc-switch.git synced 2026-03-22 15:08:22 +08:00

Files

Jason ec6e113cf2 chore: bump version to 3.9.0-beta.1

- Update version in package.json, Cargo.toml, tauri.conf.json
- Add CHANGELOG entry for v3.9.0-beta.1 with:
  - Local Proxy Server feature
  - Auto Failover with circuit breaker
  - Skills multi-app support
  - Provider icon colors
  - 25+ bug fixes
- Add proxy feature guide documentation (Chinese)

2025-12-18 20:53:02 +08:00

5.1 KiB

Raw Blame History

CC Switch 代理功能使用指南

功能介绍

CC Switch 的代理功能是一个本地 HTTP 代理服务器，可以统一管理 Claude Code、Codex 和 Gemini CLI 的 API 请求。主要特性包括：

统一代理入口 - 所有 CLI 应用的请求通过本地代理转发
自动故障转移 - 当前供应商故障时自动切换到备用供应商
按应用控制 - 可独立控制每个应用是否启用代理
配置保护 - 自动备份原始配置，停止代理时安全恢复

快速开始

1. 启动代理

在 CC Switch 主界面，点击右上角的 Proxy 按钮，可以看到代理控制面板。

点击 启动代理 按钮启动本地代理服务器。代理默认监听 127.0.0.1:15721。

2. 启用应用接管

代理启动后，你可以选择让哪些应用的请求通过代理：

Claude - 接管 Claude Code 的 API 请求
Codex - 接管 Codex CLI 的 API 请求
Gemini - 接管 Gemini CLI 的 API 请求

点击对应应用的开关即可启用/禁用接管。

注意：启用接管后，CC Switch 会自动修改对应应用的配置文件，将 API 端点指向本地代理。原始配置会被安全备份。

3. 正常使用 CLI

启用接管后，你可以正常使用各个 CLI 工具。所有请求都会经过 CC Switch 代理转发到配置的供应商。

4. 停止代理

当你不再需要代理时，点击 停止代理 按钮。CC Switch 会：

安全关闭代理服务器
自动恢复所有应用的原始配置
清除代理状态

自动故障转移

工作原理

代理功能内置了智能故障转移机制：

健康监控 - 实时监控每个供应商的响应状态
熔断器 - 连续失败 5 次后触发熔断，暂停使用该供应商
自动切换 - 熔断后自动切换到列表中的下一个供应商
自动恢复 - 30 秒后尝试恢复熔断的供应商

配置故障转移

要使用故障转移功能，你需要：

在对应应用下添加多个供应商（至少 2 个）
启动代理并启用接管
当主供应商故障时，代理会自动切换到备用供应商

健康状态指示

在供应商卡片上可以看到健康状态指示：

绿色 - 供应商正常
红色 - 供应商故障/熔断中
灰色 - 未使用代理或未检测

按应用接管

v3.9.0 新增了按应用分粒度控制功能：

你可以只接管 Claude，而让 Codex 使用原始配置
每个应用的接管状态独立管理
启用/禁用不会影响其他应用

接管状态检测

CC Switch 通过检测配置备份来判断接管状态：

存在备份 = 已接管
无备份 = 未接管

这确保了即使 CC Switch 异常退出，重新启动后也能正确识别状态。

代理配置

在代理面板中，你可以配置以下参数：

参数	默认值	说明
监听地址	127.0.0.1	代理服务器绑定地址
监听端口	15721	代理服务器端口
最大重试	3	请求失败时的最大重试次数
请求超时	120 秒	单个请求的超时时间
启用日志	是	是否记录请求日志

常见问题

Q: 代理启动失败，提示端口被占用？

A: 默认端口 15721 可能被其他程序占用。你可以：

关闭占用该端口的程序
在代理配置中修改端口号

Q: 启用接管后 CLI 无法使用？

A: 请检查：

代理服务器是否正常运行（查看代理面板状态）
供应商配置是否正确（API Key 等）
网络连接是否正常

Q: 如何恢复原始配置？

A: 点击 停止代理 按钮，CC Switch 会自动恢复所有应用的原始配置。

如果 CC Switch 异常退出，重新启动后会检测到之前的备份，你可以：

点击停止代理来恢复配置
或继续使用代理功能

Q: 故障转移没有生效？

A: 请确保：

配置了至少 2 个供应商
代理已启动且接管已启用
故障转移只在代理模式下工作

Q: 代理会影响性能吗？

A: 本地代理的延迟开销非常小（通常 < 1ms）。但如果启用了请求日志，在高频请求场景下可能会有少量性能影响。

技术细节

配置文件位置

启用接管后，CC Switch 会修改以下配置文件：

应用	配置文件	修改内容
Claude	`~/.claude/settings.json`	`apiBaseUrl` 指向代理
Codex	`~/.codex/config.toml`	`[api] baseUrl` 指向代理
Gemini	`~/.gemini/.env`	`GEMINI_BASE_URL` 指向代理

原始配置备份在 CC Switch 数据库中，停止代理时自动恢复。

代理模式

代理服务器运行在接管模式下，会：

接收来自 CLI 的 HTTPS 请求
根据当前供应商配置转发到真实 API 端点
返回响应给 CLI
记录请求日志和健康状态

数据库表

代理功能使用以下数据库表：

proxy_config - 代理配置
provider_health - 供应商健康状态
proxy_request_logs - 请求日志
circuit_breaker_config - 熔断器配置
proxy_live_backup - Live 配置备份

5.1 KiB Raw Blame History Unescape Escape