---
name: guide-proxy
description: 代理管理指南，包括创建代理、路由策略、协议转换、启动停止
trigger: 用户询问怎么创建代理、代理启动失败、端口配置、路由策略、协议转换、代理怎么用、监听端口
---

# 代理管理指南

代理是系统提供 API 服务的端口，每个代理可以配置独立的转发规则和安全策略。

## 配置项详解

### 基本配置

| 配置项 | 含义 | 示例/说明 |
|--------|------|----------|
| **代理名称** | 代理的显示名称，方便识别 | `OpenAI 代理`、`生产环境 API` |
| **监听端口** | 本地监听端口，范围 1000-65535 | `8080`、`3000`，确保端口未被占用 |
| **认证** | 是否启用 Bearer Token 认证 | `不启用`：任何人都可以访问<br>`启用`：需要携带 Token |

### 认证配置详解

启用认证后，所有请求需要在 HTTP Header 中携带：
```
Authorization: Bearer your-token-here
```

| 场景 | 是否需要认证 | 建议 |
|------|-------------|------|
| 仅本机访问 | 可不启用 | 测试环境、本地开发 |
| 局域网访问 | 建议启用 | 团队内部使用 |
| 公网访问 | **必须启用** | 生产环境、对外开放 |

### 目标供应商配置

| 配置项 | 含义 | 说明 |
|--------|------|------|
| **供应商** | 转发请求的目标供应商 | 必须选择一个已创建的供应商 |
| **默认模型** | 不指定模型时使用的默认模型 | 可选，不填则使用请求中的模型 |

### 路由策略详解

| 策略 | 含义 | 适用场景 |
|------|------|----------|
| **主备切换** | 优先使用主供应商，失败时切换到备选 | 高可用要求，主备冗余 |
| **轮询** | 依次使用所有配置的供应商 | 负载分散，公平使用 |
| **加权随机** | 按配置的权重比例随机选择 | 多供应商权重分配 |
| **最快优先** | 选择历史响应最快的供应商 | 优化延迟，追求速度 |

| 配置项 | 含义 | 说明 |
|--------|------|------|
| **权重** | 该代理的权重，用于加权随机策略 | 数字越大，被选中的概率越高 |

### 多供应商池（providerPool）

多供应商池是现代路由策略的核心配置，用于实现负载均衡和多供应商调度：

| 配置项 | 含义 | 说明 |
|--------|------|------|
| **providerPool** | 多供应商池配置数组 | 每个元素包含 `providerId`（供应商ID）、`model`（模型名）、`weight`（权重） |
| **权重** | 该池成员的使用权重 | 数字越大，在 `weighted` 策略中被选中的概率越高；`fastest` 策略下权重不影响 |

**配置示例**：
```json
[
  { "providerId": "openai", "model": "gpt-4o", "weight": 2 },
  { "providerId": "deepseek", "model": "deepseek-chat", "weight": 1 }
]
```

> **注意**：providerPool 与路由策略配合使用。`primary_fallback` 策略下主供应商为 `providerId`，池中其余为备选；`round_robin`、`weighted`、`fastest` 策略下则按对应逻辑在池中调度。

## 创建代理

1. 点击左侧菜单「**代理管理**」
2. 点击「**新建代理**」按钮
3. 填写配置（见上方配置项详解）
4. 点击「**保存**」

## 启动/停止代理

代理创建后默认是**停止**状态：

| 操作 | 方式 |
|------|------|
| **单代理启动** | 点击代理卡片上的「**启动**」按钮 |
| **单代理停止** | 点击代理卡片上的「**停止**」按钮 |
| **批量启动** | 点击工具栏「**全部启动**」按钮 |
| **批量停止** | 点击工具栏「**全部停止**」按钮 |

## 修改和删除代理

- **修改**：点击代理卡片上的「**编辑**」按钮，可修改所有配置项
- **删除**：点击代理卡片上的「**删除**」按钮，确认后永久删除

## 代理状态说明

| 状态 | 含义 | 说明 |
|------|------|------|
| **已停止** | 代理未运行 | 需要手动启动 |
| **启动中** | 正在启动 | 请稍候 |
| **运行中** | 代理正常监听 | 可接受请求 |
| **异常** | 启动失败 | 检查端口、配置，查看系统日志 |

## 协议自动转换

Protocol Proxy 支持不同协议之间的自动转换：

| 请求格式 | 转发处理 |
|----------|----------|
| OpenAI 格式 → Anthropic 供应商 | 自动转换为 Claude API 格式 |
| Anthropic 格式 → OpenAI 供应商 | 自动转换为 Chat Completions 格式 |
| OpenAI 格式 → Gemini 供应商 | 自动转换为 Gemini API 格式 |
| Gemini 格式 → OpenAI 供应商 | 自动转换为 Chat Completions 格式 |

这样可以用统一的 OpenAI 客户端访问各种 AI 后端。适配器（adapter）会自动处理国内模型的协议差异。

## 代理使用示例

```bash
# OpenAI 格式请求（不带认证）
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "messages": [{"role": "user", "content": "Hello"}]}'

# 带认证的请求
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-proxy-token" \
  -d '{"model": "gpt-4", "messages": [{"role": "user", "content": "Hello"}]}'
```

## 查看代理信息

在「**总览**」页面可以看到所有运行中的代理：
- 代理名称和端口
- 运行状态
- 配置的供应商

点击代理卡片可以看到：
- 当前运行状态
- 配置的供应商和模型
- 请求统计
- 最近请求日志

## 常见问题

### Q: 如何让外部设备访问代理？
确保防火墙允许对应端口入站，代理监听 `0.0.0.0` 所以局域网内可直接访问。

### Q: 代理启动失败怎么办？
- 检查端口是否被占用：`netstat -ano | findstr :8080`
- 检查供应商配置是否正确
- 查看系统日志获取详细错误信息
