guide-proxy

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

代理管理指南

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

配置项详解

基本配置

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

认证配置详解

启用认证后，所有请求需要在 HTTP Header 中携带：

Authorization: Bearer your-token-here

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

目标供应商配置

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

路由策略详解

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

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

多供应商池（providerPool）

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

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

配置示例：

[
  { "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）会自动处理国内模型的协议差异。

代理使用示例

# 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
• 检查供应商配置是否正确
• 查看系统日志获取详细错误信息