mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-04-22 17:11:04 +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.7 KiB
Markdown
223 lines
4.7 KiB
Markdown
# 4.1 Proxy Service
|
|
|
|
## Overview
|
|
|
|
The proxy service starts a local HTTP proxy through which all API requests are forwarded.
|
|
|
|
**Primary uses**:
|
|
- Record request logs
|
|
- Track API usage
|
|
- Support failover
|
|
- Centrally manage requests from multiple applications
|
|
|
|
## Start the Proxy
|
|
|
|
### Option 1: Main Interface Toggle
|
|
|
|
Click the **Proxy Toggle** button at the top of the main interface.
|
|
|
|
Toggle states:
|
|
- White: Proxy not running
|
|
- Green: Proxy running
|
|
|
|
|
|
|
|
### Option 2: Settings Page
|
|
|
|
1. Open "Settings > Advanced > Proxy Service"
|
|
2. Click the toggle in the top-right corner
|
|
|
|
|
|
|
|
## Proxy Configuration
|
|
|
|
### Basic Configuration
|
|
|
|
| Setting | Description | Default |
|
|
|---------|-------------|---------|
|
|
| Listen Address | IP address the proxy binds to | `127.0.0.1` |
|
|
| Listen Port | Port the proxy listens on | `15721` |
|
|
| Enable Logging | Whether to record request logs | Enabled |
|
|
|
|
### Modify Configuration
|
|
|
|
1. **Stop the proxy service** (must stop first)
|
|
2. Modify the listen address or port
|
|
3. Click "Save"
|
|
4. Restart the proxy
|
|
|
|
> Modifying address/port requires stopping the proxy service first
|
|
|
|
### Listen Address Options
|
|
|
|
| Address | Description |
|
|
|---------|-------------|
|
|
| `127.0.0.1` | Only accessible from local machine (recommended) |
|
|
| `0.0.0.0` | Allow LAN access |
|
|
|
|
## Running Status
|
|
|
|
When the proxy is running, the panel displays the following information:
|
|
|
|
### Service Address
|
|
|
|
```
|
|
http://127.0.0.1:15721
|
|
```
|
|
|
|
Click the "Copy" button to copy the address.
|
|
|
|
### Current Providers
|
|
|
|
Displays the currently used provider for each app:
|
|
|
|
```
|
|
Claude: PackyCode
|
|
Codex: AIGoCode
|
|
Gemini: Google Official
|
|
```
|
|
|
|
### Statistics
|
|
|
|
| Metric | Description |
|
|
|--------|-------------|
|
|
| Active Connections | Number of requests currently being processed |
|
|
| Total Requests | Total number of requests since startup |
|
|
| Success Rate | Percentage of successful requests (>90% green, <=90% yellow) |
|
|
| Uptime | How long the proxy has been running |
|
|
|
|
### Failover Queue
|
|
|
|
The proxy panel displays the failover queue by app type:
|
|
|
|
```
|
|
Claude
|
|
├── 1. PackyCode [Currently Using] ●
|
|
├── 2. AIGoCode ●
|
|
└── 3. Backup Provider ○
|
|
|
|
Codex
|
|
├── 1. AIGoCode [Currently Using] ●
|
|
└── 2. Backup Provider ●
|
|
```
|
|
|
|
Queue details:
|
|
- Numbers indicate priority order
|
|
- "Currently Using" label indicates the active provider
|
|
- Health badges show provider status:
|
|
- Green: Healthy (0 consecutive failures)
|
|
- Yellow: Degraded (1-2 consecutive failures)
|
|
- Red: Unhealthy (3+ consecutive failures)
|
|
|
|
## How It Works
|
|
|
|
### Request Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant CLI as CLI Tool (Claude)
|
|
participant Proxy as Local Proxy (CC Switch)
|
|
participant API as API Provider (Anthropic)
|
|
participant DB as Data Store (Logger)
|
|
|
|
CLI->>Proxy: Send API request
|
|
Proxy->>DB: Record request log / track usage
|
|
Proxy->>API: Forward request
|
|
API-->>Proxy: Return response
|
|
Proxy-->>CLI: Return response
|
|
```
|
|
|
|
### Configuration Changes
|
|
|
|
After starting the proxy and enabling app takeover, CC Switch modifies app configurations:
|
|
|
|
**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
|
|
```
|
|
|
|
## Stop the Proxy
|
|
|
|
### Option 1: Main Interface Toggle
|
|
|
|
Click the proxy toggle button to turn it off.
|
|
|
|
### Option 2: Settings Page
|
|
|
|
Turn off the toggle in the proxy service panel.
|
|
|
|
### Post-stop Processing
|
|
|
|
When stopping the proxy, CC Switch will:
|
|
|
|
1. Restore app configurations to their original state
|
|
2. Save request logs
|
|
3. Close all connections
|
|
|
|
## Log Recording
|
|
|
|
### Enable Logging
|
|
|
|
Enable the "Enable Logging" toggle in the proxy panel.
|
|
|
|
### Log Contents
|
|
|
|
Each request record includes:
|
|
|
|
| Field | Description |
|
|
|-------|-------------|
|
|
| Time | Request time |
|
|
| App | Claude / Codex / Gemini |
|
|
| Provider | Provider used |
|
|
| Model | Requested model |
|
|
| Tokens | Input/output token count |
|
|
| Latency | Request duration |
|
|
| Status | Success/failure |
|
|
|
|
### View Logs
|
|
|
|
View request logs in the "Settings > Usage" tab.
|
|
|
|
## FAQ
|
|
|
|
### Port Already in Use
|
|
|
|
Error message: `Address already in use`
|
|
|
|
Solution:
|
|
1. Change the port (e.g., to 5001)
|
|
2. Or close the program occupying the port
|
|
|
|
### Proxy Fails to Start
|
|
|
|
Check:
|
|
- Is the port occupied
|
|
- Are there sufficient permissions
|
|
- Is the firewall blocking it
|
|
|
|
### Request Timeout
|
|
|
|
Possible causes:
|
|
- Network issues
|
|
- Provider server issues
|
|
- Incorrect proxy configuration
|
|
|
|
Solutions:
|
|
- Check network connection
|
|
- Try accessing the provider API directly
|
|
- Check provider configuration
|