mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-04-09 20:42:28 +08:00
ec6e113cf2
- 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)
166 lines
5.1 KiB
Markdown
166 lines
5.1 KiB
Markdown
# 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 会：
|
||
|
||
1. 安全关闭代理服务器
|
||
2. 自动恢复所有应用的原始配置
|
||
3. 清除代理状态
|
||
|
||
## 自动故障转移
|
||
|
||
### 工作原理
|
||
|
||
代理功能内置了智能故障转移机制：
|
||
|
||
1. **健康监控** - 实时监控每个供应商的响应状态
|
||
2. **熔断器** - 连续失败 5 次后触发熔断，暂停使用该供应商
|
||
3. **自动切换** - 熔断后自动切换到列表中的下一个供应商
|
||
4. **自动恢复** - 30 秒后尝试恢复熔断的供应商
|
||
|
||
### 配置故障转移
|
||
|
||
要使用故障转移功能，你需要：
|
||
|
||
1. 在对应应用下添加多个供应商（至少 2 个）
|
||
2. 启动代理并启用接管
|
||
3. 当主供应商故障时，代理会自动切换到备用供应商
|
||
|
||
### 健康状态指示
|
||
|
||
在供应商卡片上可以看到健康状态指示：
|
||
|
||
- **绿色** - 供应商正常
|
||
- **红色** - 供应商故障/熔断中
|
||
- **灰色** - 未使用代理或未检测
|
||
|
||
## 按应用接管
|
||
|
||
v3.9.0 新增了按应用分粒度控制功能：
|
||
|
||
- 你可以只接管 Claude，而让 Codex 使用原始配置
|
||
- 每个应用的接管状态独立管理
|
||
- 启用/禁用不会影响其他应用
|
||
|
||
### 接管状态检测
|
||
|
||
CC Switch 通过检测配置备份来判断接管状态：
|
||
|
||
- 存在备份 = 已接管
|
||
- 无备份 = 未接管
|
||
|
||
这确保了即使 CC Switch 异常退出，重新启动后也能正确识别状态。
|
||
|
||
## 代理配置
|
||
|
||
在代理面板中，你可以配置以下参数：
|
||
|
||
| 参数 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| 监听地址 | 127.0.0.1 | 代理服务器绑定地址 |
|
||
| 监听端口 | 15721 | 代理服务器端口 |
|
||
| 最大重试 | 3 | 请求失败时的最大重试次数 |
|
||
| 请求超时 | 120 秒 | 单个请求的超时时间 |
|
||
| 启用日志 | 是 | 是否记录请求日志 |
|
||
|
||
## 常见问题
|
||
|
||
### Q: 代理启动失败，提示端口被占用？
|
||
|
||
A: 默认端口 15721 可能被其他程序占用。你可以：
|
||
- 关闭占用该端口的程序
|
||
- 在代理配置中修改端口号
|
||
|
||
### Q: 启用接管后 CLI 无法使用？
|
||
|
||
A: 请检查：
|
||
1. 代理服务器是否正常运行（查看代理面板状态）
|
||
2. 供应商配置是否正确（API Key 等）
|
||
3. 网络连接是否正常
|
||
|
||
### Q: 如何恢复原始配置？
|
||
|
||
A: 点击 **停止代理** 按钮，CC Switch 会自动恢复所有应用的原始配置。
|
||
|
||
如果 CC Switch 异常退出，重新启动后会检测到之前的备份，你可以：
|
||
- 点击停止代理来恢复配置
|
||
- 或继续使用代理功能
|
||
|
||
### Q: 故障转移没有生效？
|
||
|
||
A: 请确保：
|
||
1. 配置了至少 2 个供应商
|
||
2. 代理已启动且接管已启用
|
||
3. 故障转移只在代理模式下工作
|
||
|
||
### Q: 代理会影响性能吗？
|
||
|
||
A: 本地代理的延迟开销非常小（通常 < 1ms）。但如果启用了请求日志，在高频请求场景下可能会有少量性能影响。
|
||
|
||
## 技术细节
|
||
|
||
### 配置文件位置
|
||
|
||
启用接管后，CC Switch 会修改以下配置文件：
|
||
|
||
| 应用 | 配置文件 | 修改内容 |
|
||
|------|----------|----------|
|
||
| Claude | `~/.claude/settings.json` | `apiBaseUrl` 指向代理 |
|
||
| Codex | `~/.codex/config.toml` | `[api] baseUrl` 指向代理 |
|
||
| Gemini | `~/.gemini/.env` | `GEMINI_BASE_URL` 指向代理 |
|
||
|
||
原始配置备份在 CC Switch 数据库中，停止代理时自动恢复。
|
||
|
||
### 代理模式
|
||
|
||
代理服务器运行在接管模式下，会：
|
||
|
||
1. 接收来自 CLI 的 HTTPS 请求
|
||
2. 根据当前供应商配置转发到真实 API 端点
|
||
3. 返回响应给 CLI
|
||
4. 记录请求日志和健康状态
|
||
|
||
### 数据库表
|
||
|
||
代理功能使用以下数据库表：
|
||
|
||
- `proxy_config` - 代理配置
|
||
- `provider_health` - 供应商健康状态
|
||
- `proxy_request_logs` - 请求日志
|
||
- `circuit_breaker_config` - 熔断器配置
|
||
- `proxy_live_backup` - Live 配置备份
|