fork-it/gpt-load
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: v1 readme

Browse Source
This commit is contained in:
tbphp
2025-07-15 14:16:42 +08:00
parent a84a13e1f2
commit 2bc29b6676
6 changed files with 561 additions and 581 deletions
Download Patch File Download Diff File Expand all files Collapse all files

454
README_CN.md
View File

@@ -2,60 +2,79 @@
中文文档 | [English](README.md)
![Docker Build](https://github.com/tbphp/gpt-load/actions/workflows/docker-build.yml/badge.svg)
![Go Version](https://img.shields.io/badge/Go-1.21+-blue.svg)
[![Release](https://img.shields.io/github/v/release/tbphp/gpt-load)](https://github.com/tbphp/gpt-load/releases)
[![Build Docker Image](https://github.com/tbphp/gpt-load/actions/workflows/docker-build.yml/badge.svg)](https://github.com/tbphp/gpt-load/actions/workflows/docker-build.yml)
![Go Version](https://img.shields.io/badge/Go-1.23+-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)
一个高性能的 OpenAI 兼容 API 多密钥轮询代理服务器，支持负载均衡，使用 Go 语言开发。
一个高性能、企业级的 AI 接口透明代理服务，专门为需要集成多种 AI 服务的企业和开发者设计。采用 Go 语言开发，具备智能密钥管理、负载均衡和完善的监控功能，专为高并发生产环境而设计。
详细请查看[官方文档](https://www.gpt-load.com/docs)
## 功能特性
- **多密钥轮询**: 自动 API 密钥轮换和负载均衡
- **多目标负载均衡**: 支持轮询多个上游 API 地址
- **智能拉黑**: 区分永久性和临时性错误，智能密钥管理
- **实时监控**: 全面的统计信息、健康检查和黑名单管理
- **灵活配置**: 基于环境变量的配置，支持 .env 文件
- **CORS 支持**: 完整的跨域请求支持
- **结构化日志**: 详细的日志记录，包含响应时间和密钥信息
- **可选认证**: 项目级 Bearer token 认证
- **高性能**: 零拷贝流式传输、并发处理和原子操作
- **生产就绪**: 优雅关闭、错误恢复和内存管理
- **透明代理**: 完全保留原生 API 格式，支持 OpenAI 和 Google Gemini 等多种格式（持续扩展中）
- **智能密钥管理**: 高性能密钥池，支持分组管理、自动轮换和故障恢复
- **负载均衡**: 支持多上游端点的加权负载均衡，提升服务可用性
- **智能故障处理**: 自动密钥黑名单管理和恢复机制，确保服务连续性
- **动态配置**: 系统设置和分组配置支持热重载，无需重启即可生效
- **企业级架构**: 分布式主从部署，支持水平扩展和高可用
- **现代化管理**: 基于 Vue 3 的 Web 管理界面，直观易用
- **全面监控**: 实时统计、健康检查、详细请求日志
- **高性能设计**: 零拷贝流式传输、连接池复用、原子操作
- **生产就绪**: 优雅关闭、错误恢复、完善的安全机制
## 支持的 AI 服务
GPT-Load 作为透明代理服务，完整保留各 AI 服务商的原生 API 格式：
- **OpenAI 格式**: 官方 OpenAI API、Azure OpenAI、以及其他 OpenAI 兼容服务
- **Google Gemini 格式**: Gemini Pro、Gemini Pro Vision 等模型的原生 API
- **扩展性**: 插件化架构设计，可快速集成新的 AI 服务提供商及其原生格式
## 快速开始
### 环境要求
- Go 1.21+ (源码构建)
- Go 1.23+ (源码构建)
- Docker (容器化部署)
- MySQL 8.2+ (数据库存储)
- Redis (缓存和分布式协调，可选)
### 方式一：使用 Docker（推荐）
### 方式一：使用 Docker Compose（推荐）
```bash
# 拉取最新镜像
docker pull ghcr.io/tbphp/gpt-load:latest
# 下载配置文件
wget https://raw.githubusercontent.com/tbphp/gpt-load/refs/heads/main/docker-compose.yml
wget -O .env https://raw.githubusercontent.com/tbphp/gpt-load/refs/heads/main/.env.example
# 创建密钥文件，每行一个 API 密钥
echo "sk-your-api-key-1" > keys.txt
echo "sk-your-api-key-2" >> keys.txt
# 编辑配置文件（根据需要修改服务端口和认证Key等）
vim .env
# 运行容器
docker run -d -p 3000:3000 \
-v $(pwd)/keys.txt:/app/keys.txt:ro \
--name gpt-load \
ghcr.io/tbphp/gpt-load:latest
# 启动服务（包含 MySQL 和 Redis）
docker compose up -d
# 查看服务状态
docker compose ps
# 查看日志
docker compose logs -f gpt-load
# 常用操作
docker compose restart gpt-load # 重启服务
docker compose pull && docker compose down && docker compose up -d # 更新到最新版本
```
### 方式二：使用 Docker Compose
部署完成后：
```bash
# 启动服务
docker-compose up -d
- 访问 Web 管理界面：<http://localhost:3001>
- API 代理地址：<http://localhost:3001/proxy>
# 停止服务
docker-compose down
```
> 使用默认的认证 Key `sk-123456` 登录管理端，认证 Key 可以在 .env 中修改 AUTH_KEY。
### 方式三：源码构建
### 方式二：源码构建
源码构建需要本地已安装 MySQL 和 Redis（可选）。
```bash
# 克隆并构建
@@ -65,207 +84,270 @@ go mod tidy
# 创建配置
cp .env.example .env
echo "sk-your-api-key" > keys.txt
# 修改 .env 中 DATABASE_DSN 和 REDIS_DSN 配置
# REDIS_DSN 为可选，如果不配置则启用内存存储
# 运行
make run
```
## 配置说明
部署完成后：
### 支持的 API 提供商
- 访问 Web 管理界面：<http://localhost:3001>
- API 代理地址：<http://localhost:3001/proxy>
此代理服务器支持任何 OpenAI 兼容的 API，包括：
> 使用默认的认证 Key `sk-123456` 登录管理端，认证 Key 可以在 .env 中修改 AUTH_KEY。
- **OpenAI**: `https://api.openai.com`
- **Azure OpenAI**: `https://your-resource.openai.azure.com`
- **Anthropic Claude**: `https://api.anthropic.com` (兼容端点)
- **第三方提供商**: 任何实现 OpenAI API 格式的服务
### 方式三：集群部署
### 环境变量
集群部署需要所有节点都连接同一个 MySQL 和 Redis，并且 Redis 是必须要求。建议使用统一的分布式 MySQL 和 Redis 集群。
复制示例配置文件并根据需要修改：
**部署要求：**
```bash
cp .env.example .env
```
- 所有节点必须配置相同的 `AUTH_KEY`、`DATABASE_DSN`、`REDIS_DSN`
- 一主多从架构，从节点必须配置环境变量：`IS_SLAVE=true`
### 主要配置选项
详细请参考[集群部署文档](https://www.gpt-load.com/docs/cluster)
| 配置项 | 环境变量 | 默认值 | 说明 |
| -------------- | ---------------------------------- | --------------------------- | -------------------------------------------------- |
| 服务器端口 | `PORT` | 3000 | 服务器监听端口 |
| 服务器主机 | `HOST` | 0.0.0.0 | 服务器绑定地址 |
| 密钥文件 | `KEYS_FILE` | keys.txt | API 密钥文件路径 |
| 起始索引 | `START_INDEX` | 0 | 密钥轮换起始索引 |
| 拉黑阈值 | `BLACKLIST_THRESHOLD` | 1 | 拉黑前的错误次数 |
| 最大重试次数 | `MAX_RETRIES` | 3 | 使用不同密钥的最大重试次数 |
| 上游地址 | `OPENAI_BASE_URL` | `https://api.openai.com` | OpenAI 兼容 API 基础地址。支持多个地址，用逗号分隔 |
| 最大并发请求数 | `MAX_CONCURRENT_REQUESTS` | 100 | 最大并发请求数 |
| 启用 Gzip 压缩 | `ENABLE_GZIP` | true | 启用响应 Gzip 压缩 |
| 认证密钥 | `AUTH_KEY` | - | 可选的认证密钥 |
| 启用 CORS | `ENABLE_CORS` | true | 启用 CORS 支持 |
| 允许的来源 | `ALLOWED_ORIGINS` | \* | CORS 允许的来源（逗号分隔，\* 表示允许所有） |
| 允许的方法 | `ALLOWED_METHODS` | GET,POST,PUT,DELETE,OPTIONS | CORS 允许的 HTTP 方法 |
| 允许的头部 | `ALLOWED_HEADERS` | \* | CORS 允许的头部（逗号分隔，\* 表示允许所有） |
| 允许凭证 | `ALLOW_CREDENTIALS` | false | CORS 允许凭证 |
| 日志级别 | `LOG_LEVEL` | info | 日志级别（debug, info, warn, error） |
| 日志格式 | `LOG_FORMAT` | text | 日志格式（text, json） |
| 启用文件日志 | `LOG_ENABLE_FILE` | false | 启用文件日志 |
| 日志文件路径 | `LOG_FILE_PATH` | logs/app.log | 日志文件路径 |
| 启用请求日志 | `LOG_ENABLE_REQUEST` | true | 启用请求日志（生产环境可设为 false 以提高性能） |
| 服务器读取超时 | `SERVER_READ_TIMEOUT` | 120 | HTTP 服务器读取超时时间（秒） |
| 服务器写入超时 | `SERVER_WRITE_TIMEOUT` | 1800 | HTTP 服务器写入超时时间（秒） |
| 服务器空闲超时 | `SERVER_IDLE_TIMEOUT` | 120 | HTTP 服务器空闲超时时间（秒） |
| 优雅关闭超时 | `SERVER_GRACEFUL_SHUTDOWN_TIMEOUT` | 60 | 服务器优雅关闭超时时间（秒） |
| 请求超时 | `REQUEST_TIMEOUT` | 30 | 请求超时时间（秒） |
| 响应超时 | `RESPONSE_TIMEOUT` | 30 | 响应超时时间（秒）- 控制 TLS 握手和响应头接收 |
| 空闲连接超时 | `IDLE_CONN_TIMEOUT` | 120 | 空闲连接超时时间（秒） |
## 配置系统
### 配置示例
### 配置架构概述
#### OpenAI（默认）
GPT-Load 采用双层配置架构：
```bash
OPENAI_BASE_URL=https://api.openai.com
# 使用 OpenAI API 密钥: sk-...
```
#### 1. 静态配置（环境变量）
#### Azure OpenAI
- **特点**：应用启动时读取，运行期间不可修改，需重启应用生效
- **用途**：基础设施配置，如数据库连接、服务器端口、认证密钥等
- **管理方式**：通过 `.env` 文件或系统环境变量设置
```bash
OPENAI_BASE_URL=https://your-resource.openai.azure.com
# 使用 Azure API 密钥，根据需要调整端点
```
#### 2. 动态配置（热重载）
#### 第三方提供商
- **系统设置**：存储在数据库中，为整个应用提供统一的行为基准
- **分组配置**：为特定分组定制的行为参数，可覆盖系统设置
- **配置优先级**：分组配置 > 系统设置
- **特点**：支持热重载，修改后立即生效，无需重启应用
```bash
OPENAI_BASE_URL=https://api.your-provider.com
# 使用提供商特定的 API 密钥
```
### 静态配置（环境变量）
#### 多目标负载均衡
#### 服务器配置
```bash
# 使用逗号分隔多个目标地址
OPENAI_BASE_URL=https://gateway.ai.cloudflare.com/v1/.../openai,https://api.openai.com/v1,https://api.another-provider.com/v1
```
| 配置项 | 环境变量 | 默认值 | 说明 |
| ------------ | ---------------------------------- | --------------- | -------------------------- |
| 服务端口 | `PORT` | 3001 | HTTP 服务器监听端口 |
| 服务地址 | `HOST` | 0.0.0.0 | HTTP 服务器绑定地址 |
| 读取超时 | `SERVER_READ_TIMEOUT` | 60 | HTTP 服务器读取超时（秒） |
| 写入超时 | `SERVER_WRITE_TIMEOUT` | 600 | HTTP 服务器写入超时（秒） |
| 空闲超时 | `SERVER_IDLE_TIMEOUT` | 120 | HTTP 连接空闲超时（秒） |
| 优雅关闭超时 | `SERVER_GRACEFUL_SHUTDOWN_TIMEOUT` | 10 | 服务优雅关闭等待时间（秒） |
| 从节点模式 | `IS_SLAVE` | false | 集群部署时从节点标识 |
| 时区 | `TZ` | `Asia/Shanghai` | 指定时区 |
## API 密钥验证
#### 认证与数据库配置
项目包含高性能的 API 密钥验证工具：
| 配置项 | 环境变量 | 默认值 | 说明 |
| ---------- | -------------- | ----------- | ------------------------------------ |
| 认证密钥 | `AUTH_KEY` | `sk-123456` | 访问管理端以及请求代理的唯一认证密钥 |
| 数据库连接 | `DATABASE_DSN` | - | MySQL 数据库连接字符串 |
| Redis 连接 | `REDIS_DSN` | - | Redis 连接字符串，为空时使用内存存储 |
```bash
# 自动验证密钥
make validate-keys
#### 性能与跨域配置
# 或直接运行
./scripts/validate-keys.py
```
| 配置项 | 环境变量 | 默认值 | 说明 |
| ------------ | ------------------------- | ----------------------------- | ------------------------ |
| 最大并发请求 | `MAX_CONCURRENT_REQUESTS` | 100 | 系统允许的最大并发请求数 |
| 启用 CORS | `ENABLE_CORS` | true | 是否启用跨域资源共享 |
| 允许的来源 | `ALLOWED_ORIGINS` | `*` | 允许的来源，逗号分隔 |
| 允许的方法 | `ALLOWED_METHODS` | `GET,POST,PUT,DELETE,OPTIONS` | 允许的 HTTP 方法 |
| 允许的头部 | `ALLOWED_HEADERS` | `*` | 允许的请求头，逗号分隔 |
| 允许凭据 | `ALLOW_CREDENTIALS` | false | 是否允许发送凭据 |
## 监控端点
#### 日志配置
| 端点 | 方法 | 说明 |
| ------------- | ---- | ------------------ |
| `/health` | GET | 健康检查和基本状态 |
| `/stats` | GET | 详细统计信息 |
| `/blacklist` | GET | 黑名单信息 |
| `/reset-keys` | GET | 重置所有密钥状态 |
| 配置项 | 环境变量 | 默认值 | 说明 |
| ------------ | ----------------- | -------------- | ---------------------------------- |
| 日志级别 | `LOG_LEVEL` | `info` | 日志级别：debug, info, warn, error |
| 日志格式 | `LOG_FORMAT` | `text` | 日志格式：text, json |
| 启用文件日志 | `LOG_ENABLE_FILE` | false | 是否启用文件日志输出 |
| 日志文件路径 | `LOG_FILE_PATH` | `logs/app.log` | 日志文件存储路径 |
## 开发
### 动态配置（热重载）
### 可用命令
动态配置存储在数据库中，支持通过 Web 管理界面进行实时修改，修改后立即生效无需重启。
```bash
# 构建
make build # 构建二进制文件
make build-all # 构建所有平台版本
make clean # 清理构建文件
**配置优先级**：分组配置 > 系统设置
# 运行
make run # 运行服务器
make dev # 开发模式（启用竞态检测）
#### 基础设置
# 测试
make test # 运行测试
make coverage # 生成覆盖率报告
make bench # 运行基准测试
| 配置项 | 字段名 | 默认值 | 分组可覆盖 | 说明 |
| ------------ | ------------------------------------ | ----------------------- | ---------- | ---------------------------- |
| 项目地址 | `app_url` | `http://localhost:3001` | ❌ | 项目基础 URL |
| 日志保留天数 | `request_log_retention_days` | 7 | ❌ | 请求日志保留天数，0 为不清理 |
| 日志写入间隔 | `request_log_write_interval_minutes` | 5 | ❌ | 日志写入数据库周期（分钟） |
# 代码质量
make lint # 代码检查
make fmt # 格式化代码
make tidy # 整理依赖
#### 请求设置
# 管理
make health # 健康检查
make stats # 查看统计信息
make reset-keys # 重置密钥状态
make blacklist # 查看黑名单
| 配置项 | 字段名 | 默认值 | 分组可覆盖 | 说明 |
| -------------------- | ------------------------- | ------ | ---------- | ------------------------------ |
| 请求超时 | `request_timeout` | 600 | ✅ | 转发请求完整生命周期超时（秒） |
| 连接超时 | `connect_timeout` | 15 | ✅ | 与上游服务建立连接超时（秒） |
| 空闲连接超时 | `idle_conn_timeout` | 120 | ✅ | HTTP 客户端空闲连接超时（秒） |
| 响应头超时 | `response_header_timeout` | 15 | ✅ | 等待上游响应头超时（秒） |
| 最大空闲连接数 | `max_idle_conns` | 100 | ✅ | 连接池最大空闲连接总数 |
| 每主机最大空闲连接数 | `max_idle_conns_per_host` | 50 | ✅ | 每个上游主机最大空闲连接数 |
# 帮助
make help # 显示所有命令
```
#### 密钥配置
### 项目结构
| 配置项 | 字段名 | 默认值 | 分组可覆盖 | 说明 |
| -------------- | --------------------------------- | ------ | ---------- | ------------------------------------------------ |
| 最大重试次数 | `max_retries` | 3 | ✅ | 单个请求使用不同密钥的最大重试次数 |
| 黑名单阈值 | `blacklist_threshold` | 3 | ✅ | 密钥连续失败多少次后进入黑名单 |
| 密钥验证间隔 | `key_validation_interval_minutes` | 60 | ✅ | 后台定时验证密钥周期（分钟） |
| 密钥验证并发数 | `key_validation_concurrency` | 10 | ✅ | 后台定时验证无效 Key 时的并发数 |
| 密钥验证超时 | `key_validation_timeout_seconds` | 20 | ✅ | 后台定时验证单个 Key 时的 API 请求超时时间（秒） |
## Web 管理界面
访问管理控制台：<http://localhost:3001>（默认地址）
Web 管理界面提供以下功能：
- **仪表盘**: 实时统计信息和系统状态概览
- **密钥管理**: 创建和配置 AI 服务商分组，添加、删除和监控 API 密钥
- **请求日志**: 详细的请求历史记录和调试信息
- **系统设置**: 全局配置管理和热重载
## API 使用说明
### 代理接口调用方式
GPT-Load 通过分组名称路由请求到不同的 AI 服务。使用方式如下：
#### 1. 代理端点格式
```text
/
├── cmd/
│ └── gpt-load/
│ └── main.go # 主入口文件
├── internal/
│ ├── config/
│ │ └── manager.go # 配置管理
│ ├── errors/
│ │ └── errors.go # 自定义错误类型
│ ├── handler/
│ │ └── handler.go # HTTP 处理器
│ ├── keymanager/
│ │ └── manager.go # 密钥管理器
│ ├── middleware/
│ │ └── middleware.go # HTTP 中间件
│ └── proxy/
│ └── server.go # 代理服务器核心
├── pkg/
│ └── types/
│ └── interfaces.go # 通用接口和类型
├── scripts/
│ └── validate-keys.py # 密钥验证脚本
├── .github/
│ └── workflows/
│ └── docker-build.yml # GitHub Actions CI/CD
├── build/ # 构建输出目录
├── .env.example # 配置文件模板
├── Dockerfile # Docker 构建文件
├── docker-compose.yml # Docker Compose 配置
├── Makefile # 构建脚本
├── go.mod # Go 模块文件
├── LICENSE # MIT 许可证
└── README.md # 项目文档
http://localhost:3001/proxy/{group_name}/{原始API路径}
```
## 架构
- `{group_name}`: 在管理界面创建的分组名称
- `{原始API路径}`: 保持与原始 AI 服务完全一致的路径
### 性能特性
#### 2. 认证方式
- **并发处理**: 利用 Go 的 goroutine 实现高并发
- **内存效率**: 零拷贝流式传输，最小化内存分配
- **连接池**: HTTP/2 支持，优化连接复用
- **原子操作**: 无锁并发操作
- **预编译模式**: 启动时编译正则表达式模式
作为透明代理服务，GPT-Load 完全保留各 AI 服务的原生认证格式：
### 安全性与可靠性
- **OpenAI 格式**: 使用 `Authorization: Bearer {AUTH_KEY}` 头部认证
- **Gemini 格式**: 使用 URL 参数 `key={AUTH_KEY}` 认证
- **统一密钥**: 所有服务都使用环境变量 `AUTH_KEY` 中配置的统一密钥值
- **内存安全**: Go 的内置内存安全防止缓冲区溢出
- **并发安全**: 使用 sync.Map 和原子操作保证线程安全
- **错误处理**: 全面的错误处理和恢复机制
- **资源管理**: 自动清理防止资源泄漏
#### 3. OpenAI 接口调用示例
## 🌟 Star History
假设创建了名为 `openai` 的分组：
[![Stargazers over time](https://starchart.cc/tbphp/gpt-load.svg?variant=adaptive)](https://starchart.cc/tbphp/gpt-load)
**原始调用方式：**
```bash
curl -X POST https://api.openai.com/v1/chat/completions \
-H "Authorization: Bearer sk-your-openai-key" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-4.1-mini", "messages": [{"role": "user", "content": "Hello"}]}'
```
**代理调用方式：**
```bash
curl -X POST http://localhost:3001/proxy/openai/v1/chat/completions \
-H "Authorization: Bearer sk-123456" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-4.1-mini", "messages": [{"role": "user", "content": "Hello"}]}'
```
**变更说明：**
- 将 `https://api.openai.com` 替换为 `http://localhost:3001/proxy/openai`
- 将原始 API Key 替换为统一认证密钥 `sk-123456`（默认值）
#### 4. Gemini 接口调用示例
假设创建了名为 `gemini` 的分组：
**原始调用方式：**
```bash
curl -X POST https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-pro:generateContent?key=your-gemini-key \
-H "Content-Type: application/json" \
-d '{"contents": [{"parts": [{"text": "Hello"}]}]}'
```
**代理调用方式：**
```bash
curl -X POST http://localhost:3001/proxy/gemini/v1beta/models/gemini-2.5-pro:generateContent?key=sk-123456 \
-H "Content-Type: application/json" \
-d '{"contents": [{"parts": [{"text": "Hello"}]}]}'
```
**变更说明：**
- 将 `https://generativelanguage.googleapis.com` 替换为 `http://localhost:3001/proxy/gemini`
- 将 URL 参数中的 `key=your-gemini-key` 替换为统一认证密钥 `sk-123456`（默认值）
#### 5. 支持的接口
**OpenAI 格式：**
- `/v1/chat/completions` - 聊天对话
- `/v1/completions` - 文本补全
- `/v1/embeddings` - 文本嵌入
- `/v1/models` - 模型列表
- 以及其他所有 OpenAI 兼容接口
**Gemini 格式：**
- `/v1beta/models/*/generateContent` - 内容生成
- `/v1beta/models` - 模型列表
- 以及其他所有 Gemini 原生接口
#### 6. 客户端 SDK 配置
**OpenAI Python SDK：**
```python
from openai import OpenAI
client = OpenAI(
api_key="sk-123456", # 使用统一认证密钥
base_url="http://localhost:3001/proxy/openai" # 使用代理端点
)
response = client.chat.completions.create(
model="gpt-4.1-mini",
messages=[{"role": "user", "content": "Hello"}]
)
```
**Google Gemini SDK (Python)：**
```python
import google.generativeai as genai
# 配置 API 密钥和基础 URL
genai.configure(
api_key="sk-123456", # 使用统一认证密钥
client_options={"api_endpoint": "http://localhost:3001/proxy/gemini"}
)
model = genai.GenerativeModel('gemini-2.5-pro')
response = model.generate_content("Hello")
```
> **重要提示**：作为透明代理服务，GPT-Load 完全保留各 AI 服务的原生 API 格式和认证方式，仅需要替换端点地址并使用统一密钥值即可无缝迁移。
## 许可证
MIT 许可证 - 详情请参阅 [LICENSE](LICENSE) 文件。
## Star History
[![Stargazers over time](https://starchart.cc/tbphp/gpt-load.svg?variant=adaptive)](https://starchart.cc/tbphp/gpt-load)