Skip to content

Commit 29277ac

Browse files
tbphptbphp
authored
Merge pull request #56 from tbphp/feat-proxy-key
feat: 认证Key分离-新增代理Key配置
2 parents 147693c + cf55b73 commit 29277ac

File tree

16 files changed

+239
-97
lines changed

16 files changed

+239
-97
lines changed

‎README.md‎

Lines changed: 48 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212

1313
## 功能特性
1414

15-
- **透明代理**: 完全保留原生 API 格式，支持 OpenAI、Google Gemini 和 Anthropic Claude 等多种格式（持续扩展中）
15+
- **透明代理**: 完全保留原生 API 格式，支持 OpenAI、Google Gemini 和 Anthropic Claude 等多种格式
1616
- **智能密钥管理**: 高性能密钥池，支持分组管理、自动轮换和故障恢复
1717
- **负载均衡**: 支持多上游端点的加权负载均衡，提升服务可用性
1818
- **智能故障处理**: 自动密钥黑名单管理和恢复机制，确保服务连续性
@@ -22,6 +22,7 @@
2222
- **全面监控**: 实时统计、健康检查、详细请求日志
2323
- **高性能设计**: 零拷贝流式传输、连接池复用、原子操作
2424
- **生产就绪**: 优雅关闭、错误恢复、完善的安全机制
25+
- **双重认证体系**: 管理端与代理端认证分离，代理认证支持全局和分组级别密钥
2526

2627
## 支持的 AI 服务
2728

@@ -30,7 +31,6 @@ GPT-Load 作为透明代理服务，完整保留各 AI 服务商的原生 API
3031
- **OpenAI 格式**: 官方 OpenAI API、Azure OpenAI、以及其他 OpenAI 兼容服务
3132
- **Google Gemini 格式**: Gemini Pro、Gemini Pro Vision 等模型的原生 API
3233
- **Anthropic Claude 格式**: Claude 系列模型，支持高质量的对话和文本生成
33-
- **扩展性**: 插件化架构设计，可快速集成新的 AI 服务提供商及其原生格式
3434

3535
## 快速开始
3636

@@ -153,9 +153,10 @@ GPT-Load 采用双层配置架构：
153153
- **配置优先级**：分组配置 > 系统设置
154154
- **特点**：支持热重载，修改后立即生效，无需重启应用
155155

156-
### 静态配置（环境变量）
156+
<details>
157+
<summary>静态配置（环境变量）</summary>
157158

158-
#### 服务器配置
159+
**服务器配置：**
159160

160161
| 配置项 | 环境变量 | 默认值 | 说明 |
161162
| ------------ | ---------------------------------- | --------------- | -------------------------- |
@@ -168,15 +169,15 @@ GPT-Load 采用双层配置架构：
168169
| 从节点模式 | `IS_SLAVE` | false | 集群部署时从节点标识 |
169170
| 时区 | `TZ` | `Asia/Shanghai` | 指定时区 |
170171

171-
#### 认证与数据库配置
172+
**认证与数据库配置：**
172173

173174
| 配置项 | 环境变量 | 默认值 | 说明 |
174175
| ---------- | -------------- | ------------------ | ------------------------------------ |
175-
| 认证密钥 | `AUTH_KEY` | `sk-123456` | 访问管理端以及请求代理的唯一认证密钥 |
176+
| 管理密钥 | `AUTH_KEY` | `sk-123456` | **管理端**的访问认证密钥 |
176177
| 数据库连接 | `DATABASE_DSN` | ./data/gpt-load.db | 数据库连接字符串 (DSN) 或文件路径 |
177178
| Redis 连接 | `REDIS_DSN` | - | Redis 连接字符串，为空时使用内存存储 |
178179

179-
#### 性能与跨域配置
180+
**性能与跨域配置：**
180181

181182
| 配置项 | 环境变量 | 默认值 | 说明 |
182183
| ------------ | ------------------------- | ----------------------------- | ------------------------ |
@@ -187,7 +188,7 @@ GPT-Load 采用双层配置架构：
187188
| 允许的头部 | `ALLOWED_HEADERS` | `*` | 允许的请求头，逗号分隔 |
188189
| 允许凭据 | `ALLOW_CREDENTIALS` | false | 是否允许发送凭据 |
189190

190-
#### 日志配置
191+
**日志配置：**
191192

192193
| 配置项 | 环境变量 | 默认值 | 说明 |
193194
| ------------ | ----------------- | --------------------- | ---------------------------------- |
@@ -196,37 +197,36 @@ GPT-Load 采用双层配置架构：
196197
| 启用文件日志 | `LOG_ENABLE_FILE` | false | 是否启用文件日志输出 |
197198
| 日志文件路径 | `LOG_FILE_PATH` | `./data/logs/app.log` | 日志文件存储路径 |
198199

199-
#### 代理配置
200+
**代理配置：**
200201

201202
GPT-Load 会自动从环境变量中读取代理设置，用于向上游 AI 服务商发起请求。
202203

203-
| 配置项 | 环境变量 | 默认值 | 说明 |
204-
| --- | --- | --- | --- |
205-
| HTTP 代理 | `HTTP_PROXY` | - | 用于 HTTP 请求的代理服务器地址 |
206-
| HTTPS 代理 | `HTTPS_PROXY` | - | 用于 HTTPS 请求的代理服务器地址 |
207-
| 无代理 | `NO_PROXY` | - | 不需要通过代理访问的主机或域名，逗号分隔 |
204+
| 配置项 | 环境变量 | 默认值 | 说明 |
205+
| ---------- | ------------- | ------ | ---------------------------------------- |
206+
| HTTP 代理 | `HTTP_PROXY` | - | 用于 HTTP 请求的代理服务器地址 |
207+
| HTTPS 代理 | `HTTPS_PROXY` | - | 用于 HTTPS 请求的代理服务器地址 |
208+
| 无代理 | `NO_PROXY` | - | 不需要通过代理访问的主机或域名，逗号分隔 |
208209

209-
**支持的代理协议格式：**
210+
支持的代理协议格式：
210211

211212
- **HTTP**: `http://user:pass@host:port`
212213
- **HTTPS**: `https://user:pass@host:port`
213214
- **SOCKS5**: `socks5://user:pass@host:port`
215+
</details>
214216

215-
### 动态配置（热重载）
217+
<details>
218+
<summary>动态配置（热重载）</summary>
216219

217-
动态配置存储在数据库中，支持通过 Web 管理界面进行实时修改，修改后立即生效无需重启。
220+
**基础设置：**
218221

219-
**配置优先级**：分组配置 > 系统设置
222+
| 配置项 | 字段名 | 默认值 | 分组可覆盖 | 说明 |
223+
| ------------ | ------------------------------------ | --------------------------- | ---------- | -------------------------------------- |
224+
| 项目地址 | `app_url` | `http://localhost:3001` | ❌ | 项目基础 URL |
225+
| 日志保留天数 | `request_log_retention_days` | 7 | ❌ | 请求日志保留天数，0 为不清理 |
226+
| 日志写入间隔 | `request_log_write_interval_minutes` | 1 | ❌ | 日志写入数据库周期（分钟） |
227+
| 全局代理密钥 | `proxy_keys` | 初始值为环境配置的 AUTH_KEY | ❌ | 全局生效的代理认证密钥，多个用逗号分隔 |
220228

221-
#### 基础设置
222-
223-
| 配置项 | 字段名 | 默认值 | 分组可覆盖 | 说明 |
224-
| ------------ | ------------------------------------ | ----------------------- | ---------- | ---------------------------- |
225-
| 项目地址 | `app_url` | `http://localhost:3001` | ❌ | 项目基础 URL |
226-
| 日志保留天数 | `request_log_retention_days` | 7 | ❌ | 请求日志保留天数，0 为不清理 |
227-
| 日志写入间隔 | `request_log_write_interval_minutes` | 1 | ❌ | 日志写入数据库周期（分钟） |
228-
229-
#### 请求设置
229+
**请求设置：**
230230

231231
| 配置项 | 字段名 | 默认值 | 分组可覆盖 | 说明 |
232232
| -------------------- | ------------------------- | ------ | ---------- | ------------------------------ |
@@ -237,7 +237,7 @@ GPT-Load 会自动从环境变量中读取代理设置，用于向上游 AI 服
237237
| 最大空闲连接数 | `max_idle_conns` | 100 | ✅ | 连接池最大空闲连接总数 |
238238
| 每主机最大空闲连接数 | `max_idle_conns_per_host` | 50 | ✅ | 每个上游主机最大空闲连接数 |
239239

240-
#### 密钥配置
240+
**密钥配置：**
241241

242242
| 配置项 | 字段名 | 默认值 | 分组可覆盖 | 说明 |
243243
| -------------- | --------------------------------- | ------ | ---------- | ------------------------------------------------ |
@@ -247,6 +247,8 @@ GPT-Load 会自动从环境变量中读取代理设置，用于向上游 AI 服
247247
| 密钥验证并发数 | `key_validation_concurrency` | 10 | ✅ | 后台定时验证无效 Key 时的并发数 |
248248
| 密钥验证超时 | `key_validation_timeout_seconds` | 20 | ✅ | 后台定时验证单个 Key 时的 API 请求超时时间（秒） |
249249

250+
</details>
251+
250252
## Web 管理界面
251253

252254
访问管理控制台：<http://localhost:3001>（默认地址）
@@ -270,7 +272,8 @@ Web 管理界面提供以下功能：
270272

271273
## API 使用说明
272274

273-
### 代理接口调用方式
275+
<details>
276+
<summary>代理接口调用方式</summary>
274277

275278
GPT-Load 通过分组名称路由请求到不同的 AI 服务。使用方式如下：
276279

@@ -285,11 +288,11 @@ http://localhost:3001/proxy/{group_name}/{原始API路径}
285288

286289
#### 2. 认证方式
287290

288-
作为透明代理服务，GPT-Load 完全保留各 AI 服务的原生认证格式：
291+
在 Web 管理界面中配置**代理密钥** (`Proxy Keys`)，可设置系统级别和分组级别的代理密钥。
289292

290-
- **OpenAI 格式**: 使用 `Authorization: Bearer {AUTH_KEY}` 头部认证
291-
- **Gemini 格式**: 使用 URL 参数 `key={AUTH_KEY}` 认证
292-
- **统一密钥**: 所有服务都使用环境变量 `AUTH_KEY` 中配置的统一密钥值
293+
- **认证方式**: 与原生 API 一致，但需将原始密钥替换为配置的代理密钥。
294+
- **密钥作用域**: 在系统设置配置的 **全局代理密钥** 可以在所有分组使用，在分组配置的 **分组代理密钥** 仅在当前分组有效。
295+
- **格式**: 多个密钥使用半角英文逗号分隔。
293296

294297
#### 3. OpenAI 接口调用示例
295298

@@ -308,15 +311,15 @@ curl -X POST https://api.openai.com/v1/chat/completions \
308311

309312
```bash
310313
curl -X POST http://localhost:3001/proxy/openai/v1/chat/completions \
311-
-H "Authorization: Bearer sk-123456" \
314+
-H "Authorization: Bearer your-proxy-key" \
312315
-H "Content-Type: application/json" \
313316
-d '{"model": "gpt-4.1-mini", "messages": [{"role": "user", "content": "Hello"}]}'
314317
```
315318

316319
**变更说明：**
317320

318321
- 将 `https://api.openai.com` 替换为 `http://localhost:3001/proxy/openai`
319-
- 将原始 API Key 替换为统一认证密钥 `sk-123456`（默认值）
322+
- 将原始 API Key 替换为**代理密钥**
320323

321324
#### 4. Gemini 接口调用示例
322325

@@ -333,15 +336,15 @@ curl -X POST https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-
333336
**代理调用方式：**
334337

335338
```bash
336-
curl -X POST http://localhost:3001/proxy/gemini/v1beta/models/gemini-2.5-pro:generateContent?key=sk-123456 \
339+
curl -X POST http://localhost:3001/proxy/gemini/v1beta/models/gemini-2.5-pro:generateContent?key=your-proxy-key \
337340
-H "Content-Type: application/json" \
338341
-d '{"contents": [{"parts": [{"text": "Hello"}]}]}'
339342
```
340343

341344
**变更说明：**
342345

343346
- 将 `https://generativelanguage.googleapis.com` 替换为 `http://localhost:3001/proxy/gemini`
344-
- 将 URL 参数中的 `key=your-gemini-key` 替换为统一认证密钥 `sk-123456`（默认值）
347+
- 将 URL 参数中的 `key=your-gemini-key` 替换为**代理密钥**
345348

346349
#### 5. Anthropic 接口调用示例
347350

@@ -361,7 +364,7 @@ curl -X POST https://api.anthropic.com/v1/messages \
361364

362365
```bash
363366
curl -X POST http://localhost:3001/proxy/anthropic/v1/messages \
364-
-H "x-api-key: sk-123456" \
367+
-H "x-api-key: your-proxy-key" \
365368
-H "anthropic-version: 2023-06-01" \
366369
-H "Content-Type: application/json" \
367370
-d '{"model": "claude-sonnet-4-20250514", "messages": [{"role": "user", "content": "Hello"}]}'
@@ -370,7 +373,7 @@ curl -X POST http://localhost:3001/proxy/anthropic/v1/messages \
370373
**变更说明：**
371374

372375
- 将 `https://api.anthropic.com` 替换为 `http://localhost:3001/proxy/anthropic`
373-
- 将 `x-api-key` 头部中的原始 API Key 替换为统一认证密钥 `sk-123456`（默认值）
376+
- 将 `x-api-key` 头部中的原始 API Key 替换为**代理密钥**
374377

375378
#### 6. 支持的接口
376379

@@ -402,7 +405,7 @@ curl -X POST http://localhost:3001/proxy/anthropic/v1/messages \
402405
from openai import OpenAI
403406

404407
client = OpenAI(
405-
api_key="sk-123456", # 使用统一认证密钥
408+
api_key="your-proxy-key", # 使用密钥
406409
base_url="http://localhost:3001/proxy/openai" # 使用代理端点
407410
)
408411

@@ -419,7 +422,7 @@ import google.generativeai as genai
419422

420423
# 配置 API 密钥和基础 URL
421424
genai.configure(
422-
api_key="sk-123456", # 使用统一认证密钥
425+
api_key="your-proxy-key", # 使用代理密钥
423426
client_options={"api_endpoint": "http://localhost:3001/proxy/gemini"}
424427
)
425428

@@ -433,7 +436,7 @@ response = model.generate_content("Hello")
433436
from anthropic import Anthropic
434437

435438
client = Anthropic(
436-
api_key="sk-123456", # 使用统一认证密钥
439+
api_key="your-proxy-key", # 使用代理密钥
437440
base_url="http://localhost:3001/proxy/anthropic" # 使用代理端点
438441
)
439442

@@ -443,7 +446,9 @@ response = client.messages.create(
443446
)
444447
```
445448

446-
> **重要提示**：作为透明代理服务，GPT-Load 完全保留各 AI 服务的原生 API 格式和认证方式，仅需要替换端点地址并使用统一密钥值即可无缝迁移。
449+
> **重要提示**：作为透明代理服务，GPT-Load 完全保留各 AI 服务的原生 API 格式和认证方式，仅需要替换端点地址并使用在管理端配置的**代理密钥**即可无缝迁移。
450+
451+
</details>
447452

448453
## 许可证
449454

0 commit comments

Comments
 (0)