# 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 配置备份