# GPT-Load

中文文档 | [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)
![License](https://img.shields.io/badge/license-MIT-green.svg)

一个高性能的 OpenAI API 多密钥轮询代理服务器，支持负载均衡，使用 Go 语言开发。

## 功能特性

- **多密钥轮询**: 自动 API 密钥轮换和负载均衡
- **智能拉黑**: 区分永久性和临时性错误，智能密钥管理
- **实时监控**: 全面的统计信息、健康检查和黑名单管理
- **灵活配置**: 基于环境变量的配置，支持 .env 文件
- **CORS 支持**: 完整的跨域请求支持
- **结构化日志**: 详细的日志记录，包含响应时间和密钥信息
- **可选认证**: 项目级 Bearer token 认证
- **高性能**: 零拷贝流式传输、并发处理和原子操作
- **生产就绪**: 优雅关闭、错误恢复和内存管理

## 快速开始

### 环境要求

- Go 1.21+ (源码构建)
- Docker (容器化部署)

### 方式一：使用 Docker（推荐）

```bash
# 拉取最新镜像
docker pull ghcr.io/tbphp/gpt-load:latest

# 创建密钥文件，每行一个 OpenAI API 密钥
echo "sk-your-api-key-1" > keys.txt
echo "sk-your-api-key-2" >> keys.txt

# 运行容器
docker run -d -p 3000:3000 \
  -v $(pwd)/keys.txt:/app/keys.txt:ro \
  --name gpt-load \
  ghcr.io/tbphp/gpt-load:latest
```

### 方式二：使用 Docker Compose

```bash
# 启动服务
docker-compose up -d

# 停止服务
docker-compose down
```

### 方式三：源码构建

```bash
# 克隆并构建
git clone https://github.com/tbphp/gpt-load.git
cd gpt-load
go mod tidy

# 创建配置
cp .env.example .env
echo "sk-your-api-key" > keys.txt

# 运行
make run
```

## 配置说明

### 环境变量

复制示例配置文件并根据需要修改：

```bash
cp .env.example .env
```

### 主要配置选项

| 配置项 | 环境变量 | 默认值 | 说明 |
|--------|----------|--------|------|
| 服务器端口 | `PORT` | 3000 | 服务器监听端口 |
| 服务器主机 | `HOST` | 0.0.0.0 | 服务器绑定地址 |
| 密钥文件 | `KEYS_FILE` | keys.txt | API 密钥文件路径 |
| 起始索引 | `START_INDEX` | 0 | 密钥轮换起始索引 |
| 拉黑阈值 | `BLACKLIST_THRESHOLD` | 1 | 拉黑前的错误次数 |
| 上游地址 | `OPENAI_BASE_URL` | `https://api.openai.com` | OpenAI API 基础地址 |
| 请求超时 | `REQUEST_TIMEOUT` | 30000 | 请求超时时间（毫秒） |
| 认证密钥 | `AUTH_KEY` | - | 可选的认证密钥 |
| CORS | `ENABLE_CORS` | true | 启用 CORS 支持 |
| 最大连接数 | `MAX_SOCKETS` | 50 | 最大 HTTP 连接数 |

## API 密钥验证

项目包含高性能的 API 密钥验证工具：

```bash
# 自动验证密钥
make validate-keys

# 或直接运行
./scripts/validate-keys.py
```

## 监控端点

| 端点 | 方法 | 说明 |
|------|------|------|
| `/health` | GET | 健康检查和基本状态 |
| `/stats` | GET | 详细统计信息 |
| `/blacklist` | GET | 黑名单信息 |
| `/reset-keys` | GET | 重置所有密钥状态 |

## 开发

### 可用命令

```bash
# 构建
make build      # 构建二进制文件
make build-all  # 构建所有平台版本
make clean      # 清理构建文件

# 运行
make run        # 运行服务器
make dev        # 开发模式（启用竞态检测）

# 测试
make test       # 运行测试
make coverage   # 生成覆盖率报告
make bench      # 运行基准测试

# 代码质量
make lint       # 代码检查
make fmt        # 格式化代码
make tidy       # 整理依赖

# 管理
make health     # 健康检查
make stats      # 查看统计信息
make reset-keys # 重置密钥状态
make blacklist  # 查看黑名单

# 帮助
make help       # 显示所有命令
```

### 项目结构

```text
/
├── cmd/
│   └── main.go              # 主入口文件
├── internal/
│   ├── config/
│   │   └── config.go        # 配置管理
│   ├── keymanager/
│   │   └── keymanager.go    # 密钥管理器
│   └── proxy/
│       └── proxy.go         # 代理服务器核心
├── build/                   # 构建输出目录
├── .env.example            # 配置文件模板
├── Dockerfile              # Docker 构建文件
├── docker-compose.yml      # Docker Compose 配置
├── Makefile               # 构建脚本
├── go.mod                 # Go 模块文件
└── README.md              # 项目文档
```

## 架构

### 性能特性

- **并发处理**: 利用 Go 的 goroutine 实现高并发
- **内存效率**: 零拷贝流式传输，最小化内存分配
- **连接池**: HTTP/2 支持，优化连接复用
- **原子操作**: 无锁并发操作
- **预编译模式**: 启动时编译正则表达式模式

### 安全性与可靠性

- **内存安全**: Go 的内置内存安全防止缓冲区溢出
- **并发安全**: 使用 sync.Map 和原子操作保证线程安全
- **错误处理**: 全面的错误处理和恢复机制
- **资源管理**: 自动清理防止资源泄漏

## 许可证

MIT 许可证 - 详情请参阅 [LICENSE](LICENSE) 文件。