mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-04-19 09:52:56 +08:00
bbed2a1fe1
Reorganize docs/user-manual/ from flat structure to language subdirectories (zh/, en/, ja/) with shared assets/. Move existing Chinese docs into zh/, fix image paths, add multilingual navigation README, and translate all 23 markdown files (~4500 lines each) to English and Japanese.
223 lines
4.4 KiB
Markdown
223 lines
4.4 KiB
Markdown
# 4.1 代理服务
|
||
|
||
## 功能说明
|
||
|
||
代理服务在本地启动一个 HTTP 代理，所有 API 请求都通过代理转发。
|
||
|
||
**主要用途**：
|
||
- 记录请求日志
|
||
- 统计 API 用量
|
||
- 支持故障转移
|
||
- 集中管理多个应用的请求
|
||
|
||
## 启动代理
|
||
|
||
### 方式一：主界面开关
|
||
|
||
点击主界面顶部的 **代理开关** 按钮。
|
||
|
||
开关状态：
|
||
- 🔴 白色：代理未运行
|
||
- 🟢 绿色：代理运行中
|
||
|
||
|
||
|
||
### 方式二：设置页面
|
||
|
||
1. 打开「设置 → 高级 → 代理服务」
|
||
2. 点击右上角的开关
|
||
|
||
|
||
|
||
## 代理配置
|
||
|
||
### 基础配置
|
||
|
||
| 配置项 | 说明 | 默认值 |
|
||
|--------|------|--------|
|
||
| 监听地址 | 代理绑定的 IP 地址 | `127.0.0.1` |
|
||
| 监听端口 | 代理监听的端口 | `15721` |
|
||
| 启用日志 | 是否记录请求日志 | 开启 |
|
||
|
||
### 修改配置
|
||
|
||
1. **停止代理服务**（必须先停止）
|
||
2. 修改监听地址或端口
|
||
3. 点击「保存」
|
||
4. 重新启动代理
|
||
|
||
> ⚠️ 修改地址/端口需要先停止代理服务
|
||
|
||
### 监听地址说明
|
||
|
||
| 地址 | 说明 |
|
||
|------|------|
|
||
| `127.0.0.1` | 仅本机可访问（推荐） |
|
||
| `0.0.0.0` | 允许局域网访问 |
|
||
|
||
## 运行状态
|
||
|
||
代理运行时，面板显示以下信息：
|
||
|
||
### 服务地址
|
||
|
||
```
|
||
http://127.0.0.1:15721
|
||
```
|
||
|
||
点击「复制」按钮可复制地址。
|
||
|
||
### 当前供应商
|
||
|
||
显示各应用当前使用的供应商：
|
||
|
||
```
|
||
Claude: PackyCode
|
||
Codex: AIGoCode
|
||
Gemini: Google 官方
|
||
```
|
||
|
||
### 统计数据
|
||
|
||
| 指标 | 说明 |
|
||
|------|------|
|
||
| 活跃连接 | 当前正在处理的请求数 |
|
||
| 总请求数 | 启动以来的总请求数 |
|
||
| 成功率 | 请求成功的百分比（>90% 绿色，≤90% 黄色） |
|
||
| 运行时间 | 代理已运行的时长 |
|
||
|
||
### 故障转移队列
|
||
|
||
代理面板会按应用类型显示故障转移队列：
|
||
|
||
```
|
||
Claude
|
||
├── 1. PackyCode [当前使用] ●
|
||
├── 2. AIGoCode ●
|
||
└── 3. 备用供应商 ○
|
||
|
||
Codex
|
||
├── 1. AIGoCode [当前使用] ●
|
||
└── 2. 备用供应商 ●
|
||
```
|
||
|
||
队列说明：
|
||
- 数字表示优先级顺序
|
||
- 「当前使用」标签表示正在使用的供应商
|
||
- 健康徽章显示供应商状态：
|
||
- 🟢 绿色：健康（连续失败 0 次）
|
||
- 🟡 黄色：降级（连续失败 1-2 次）
|
||
- 🔴 红色：不健康（连续失败 ≥3 次）
|
||
|
||
## 工作原理
|
||
|
||
### 请求流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant CLI as CLI 工具 (Claude)
|
||
participant Proxy as 本地代理 (CC Switch)
|
||
participant API as API 供应商 (Anthropic)
|
||
participant DB as 数据存储 (Logger)
|
||
|
||
CLI->>Proxy: 发送 API 请求
|
||
Proxy->>DB: 记录请求日志/统计用量
|
||
Proxy->>API: 转发请求
|
||
API-->>Proxy: 返回响应
|
||
Proxy-->>CLI: 返回响应
|
||
```
|
||
|
||
### 配置修改
|
||
|
||
启动代理并开启应用接管后，CC Switch 会修改应用配置：
|
||
|
||
**Claude**：
|
||
```json
|
||
{
|
||
"env": {
|
||
"ANTHROPIC_BASE_URL": "http://127.0.0.1:15721"
|
||
}
|
||
}
|
||
```
|
||
|
||
**Codex**：
|
||
```toml
|
||
base_url = "http://127.0.0.1:15721/v1"
|
||
```
|
||
|
||
**Gemini**：
|
||
```
|
||
GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
|
||
```
|
||
|
||
## 停止代理
|
||
|
||
### 方式一：主界面开关
|
||
|
||
点击代理开关按钮关闭。
|
||
|
||
### 方式二：设置页面
|
||
|
||
在代理服务面板中关闭开关。
|
||
|
||
### 停止后的处理
|
||
|
||
停止代理时，CC Switch 会：
|
||
|
||
1. 恢复应用配置到原始状态
|
||
2. 保存请求日志
|
||
3. 关闭所有连接
|
||
|
||
## 日志记录
|
||
|
||
### 开启日志
|
||
|
||
在代理面板中开启「启用日志」开关。
|
||
|
||
### 日志内容
|
||
|
||
每条请求记录包含：
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| 时间 | 请求时间 |
|
||
| 应用 | Claude / Codex / Gemini |
|
||
| 供应商 | 使用的供应商 |
|
||
| 模型 | 请求的模型 |
|
||
| Token | 输入/输出 token 数 |
|
||
| 延迟 | 请求耗时 |
|
||
| 状态 | 成功/失败 |
|
||
|
||
### 查看日志
|
||
|
||
在「设置 → 用量」Tab 中查看请求日志。
|
||
|
||
## 常见问题
|
||
|
||
### 端口被占用
|
||
|
||
错误信息：`Address already in use`
|
||
|
||
解决方法：
|
||
1. 更换端口（如 5001）
|
||
2. 或关闭占用端口的程序
|
||
|
||
### 代理启动失败
|
||
|
||
检查：
|
||
- 端口是否被占用
|
||
- 是否有足够权限
|
||
- 防火墙是否阻止
|
||
|
||
### 请求超时
|
||
|
||
可能原因：
|
||
- 网络问题
|
||
- 供应商服务器问题
|
||
- 代理配置错误
|
||
|
||
解决方法：
|
||
- 检查网络连接
|
||
- 尝试直接访问供应商 API
|
||
- 检查供应商配置
|