feat: readme

2025-06-08 16:50:32 +08:00
parent d46840c2c9
commit a5c40ac22e
2 changed files with 322 additions and 167 deletions
--- a/README_CN.md
+++ b/README_CN.md
@@ -0,0 +1,194 @@
+# 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) 文件。