# llm-proxy

**Repository Path**: hwlchina/llm-proxy

## Basic Information

- **Project Name**: llm-proxy
- **Description**: 基于LiteLLM构建的多账号负载功能
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-13
- **Last Updated**: 2026-04-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LLM Proxy - 高并发 LLM API 网关

## 特性

- **多账号负载均衡**: 支持多个 MaaS 账号，突破单账号限速
- **OpenAI 兼容 API**: `/v1/chat/completions` 等接口兼容
- **API Key 管理**: 分组、标签、限流配置
- **高并发支持**: 优化配置支持 3000+ RPM
- **健康检查**: 账号自动下线/恢复，与 LiteLLM Router 联动
- **限速控制**: RPM/TPM 双层限速
- **安全存储**: MaaS API Key 加密存储 (PBKDF2 + Fernet)
- **自定义 Headers**: 支持为 MaaS 账号配置自定义认证 Headers

## 快速启动

### 1. 安装依赖

```bash
uv sync
```

### 2. 配置环境变量

```bash
cp .env.example .env
# 编辑 .env 填入配置
```

### 3. 启动服务

**使用启动脚本 (推荐)**:

```bash
# 开发模式 (Linux/Mac)
./scripts/start_dev.sh

# 生产模式 (Linux/Mac)
./scripts/start_prod.sh

# Windows
scripts\start_dev.bat
```

**手动启动**:

```bash
# 开发模式 (自动检测 DEBUG 模式)
uv run python -m app.main

# 生产模式 (高并发 - 支持 3000+ RPM)
uv run python -m app.main
```

> 注: 优化参数在 `app/main.py` 的 `get_uvicorn_config()` 中配置，包括:
> - `workers`: 工作进程数
> - `limit_concurrency`: 最大并发连接
> - `loop: uvloop`: 高性能事件循环
> - `http: h11`: HTTP 协议解析器
> - `backlog: 2048`: 连接队列大小

## Docker 部署

### 构建镜像

```bash
# 构建镜像
docker build -t llm-proxy:latest .

# 查看镜像
docker images llm-proxy
```

### 本地开发 (带数据库)

```bash
# 启动所有服务 (PostgreSQL + Redis + App)
docker-compose up -d

# 查看日志
docker-compose logs -f app

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

### 生产部署

```bash
# 设置环境变量
export MASTER_KEY=sk-admin-your-production-key
export DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/llm_proxy
export REDIS_HOST=your-redis-host
export REDIS_PORT=6379
export REDIS_PASSWORD=your-redis-password

# 启动 (使用生产配置)
docker-compose -f docker-compose.prod.yml up -d
```

### Docker 环境变量

| 变量 | 说明 | 示例 |
|------|------|------|
| `MASTER_KEY` | Admin API 主密钥 | `sk-admin-xxx` |
| `DATABASE_URL` | PostgreSQL 连接字符串 | `postgresql+asyncpg://...` |
| `REDIS_HOST` | Redis 地址 | `redis` |
| `REDIS_PORT` | Redis 端口 | `6379` |
| `REDIS_PASSWORD` | Redis 密码 | (可选) |
| `LOG_LEVEL` | 日志级别 | `INFO`, `DEBUG` |

### 使用 Docker Compose 完整启动

```bash
# 使用启动脚本 (Linux/Mac)
./scripts/start_docker.sh up

# 或直接使用 docker-compose
docker-compose up -d

# 查看服务状态
./scripts/start_docker.sh ps

# 查看日志
./scripts/start_docker.sh logs

# 停止服务
./scripts/start_docker.sh down
```

### Docker 启动脚本

```bash
# 可用命令
./scripts/start_docker.sh up       # 启动所有服务
./scripts/start_docker.sh down     # 停止服务
./scripts/start_docker.sh restart  # 重启服务
./scripts/start_docker.sh logs     # 查看日志
./scripts/start_docker.sh ps       # 查看状态
./scripts/start_docker.sh build    # 重新构建镜像
./scripts/start_docker.sh exec ... # 在容器中执行命令
```

## 高并发配置 (3000 RPM)

针对 3000 RPM (~50 QPS, 峰值 ~150 QPS) 的推荐配置：

| 配置项 | 推荐值 | 说明 |
|--------|--------|------|
| `WORKERS` | 4 | CPU 核心数 |
| `LITELLM_MAX_PARALLEL_REQUESTS` | 500 | 每部署最大并发 |
| `DB_POOL_SIZE` | 50 | 数据库连接池 |
| `DB_MAX_OVERFLOW` | 30 | 连接池溢出 |
| `REDIS_MAX_CONNECTIONS` | 100 | Redis 连接数 |
| `BCRYPT_ROUNDS` | 10 | 降低验证延迟 |
| `API_KEY_CACHE_TTL` | 600 | 减少 DB 查询 |

## API 文档

启动服务后访问: http://localhost:8000/docs

### 主要 API

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/v1/chat/completions` | OpenAI 兼容聊天接口 |
| `POST` | `/admin/api-keys` | 创建 API Key |
| `GET` | `/admin/api-keys` | 列表 Key (支持 group/tags 过滤) |
| `POST` | `/admin/accounts` | 添加 MaaS 账号 |
| `GET` | `/admin/accounts` | 列表账号 |

### Admin API 认证

所有 `/admin/*` 接口需要 header:
```
X-Admin-Key: sk-admin-your-master-key
```

### 用户 API 认证

所有 `/v1/*` 接口需要 header:
```
Authorization: Bearer sk-llm-xxxx
```

## MaaS 账号管理

### 创建账号

```bash
# 最小请求（只有必填字段）
curl -X POST http://localhost:8000/admin/accounts \
  -H "X-Admin-Key: sk-admin-xxx" \
  -d '{
    "name": "简单账号",
    "api_base": "https://api.example.com/v1",
    "api_key": "sk-xxx",
    "model_name": "gpt-4"
  }'

# 带自定义 Headers（用于特殊认证）
curl -X POST http://localhost:8000/admin/accounts \
  -H "X-Admin-Key: sk-admin-xxx" \
  -d '{
    "name": "需要特殊认证",
    "api_base": "https://api.example.com/v1",
    "api_key": "sk-xxx",
    "model_name": "gpt-4",
    "headers": {
      "X-Auth-Token": "my-secret-token",
      "X-Custom-Header": "custom-value"
    }
  }'

# 完整参数
curl -X POST http://localhost:8000/admin/accounts \
  -H "X-Admin-Key: sk-admin-xxx" \
  -d '{
    "name": "完整账号",
    "api_base": "https://api.example.com/v1",
    "api_key": "sk-xxx",
    "model_name": "gpt-4",
    "weight": 1,
    "rpm_limit": 500,
    "headers": {"X-Auth-Token": "xxx"}
  }'
```

### 账号字段说明

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `name` | string | 是 | 账号名称 |
| `api_base` | string | 是 | OpenAI 兼容 API 地址 |
| `api_key` | string | 是 | API Key（加密存储） |
| `model_name` | string | 是 | 实际模型名称（如 `gpt-4`） |
| `alias` | string | 否 | 用户-facing 模型别名（如 `my-gpt4`），多个账号可用相同别名实现负载均衡 |
| `weight` | int | 否 | 负载均衡权重，默认 1 |
| `rpm_limit` | int | 否 | 每分钟请求限制，不传则不限制 |
| `tags` | list | 否 | 标签列表 |
| `headers` | dict | 否 | 自定义请求头，key-value 对 |

### 模型别名与负载均衡

**别名（alias）** 允许你为 MaaS 账号设置一个用户-facing 的模型名称：

```bash
# 账号 A - 提供 gpt-4，别名 my-gpt4
curl -X POST http://localhost:8000/admin/accounts \
  -H "X-Admin-Key: sk-admin-xxx" \
  -d '{
    "name": "MaaS A",
    "api_base": "https://api-a.example.com/v1",
    "api_key": "sk-key-a",
    "model_name": "gpt-4",
    "alias": "my-gpt4"
  }'

# 账号 B - 也提供 gpt-4，别名 my-gpt4
curl -X POST http://localhost:8000/admin/accounts \
  -H "X-Admin-Key: sk-admin-xxx" \
  -d '{
    "name": "MaaS B",
    "api_base": "https://api-b.example.com/v1",
    "api_key": "sk-key-b",
    "model_name": "gpt-4",
    "alias": "my-gpt4"
  }'
```

第三方用户调用时：

```bash
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer sk-llm-xxx" \
  -d '{
    "model": "my-gpt4",  # 使用别名
    "messages": [{"role": "user", "content": "hello"}]
  }'
```

LiteLLM Router 会自动在账号 A 和账号 B 之间做**加权轮询负载均衡**。

**规则**：
- 如果设置了 `alias`，则用户使用 `alias` 调用
- 如果没有设置 `alias`，则用户使用 `model_name` 调用
- 多个账号可以使用相同的 `alias`，它们会自动被负载均衡

### API Key 加密存储

MaaS 账号的 `api_key` 使用 **PBKDF2 + Fernet** 加密存储：

1. **加密**: 创建/更新账号时，API Key 自动加密存储到数据库
2. **解密**: Router 使用时自动解密，全程明文不在磁盘存储
3. **密钥派生**: 基于 `MASTER_KEY` 环境变量使用 PBKDF2 派生加密密钥
4. **向后兼容**: 未加密的旧数据可正常解密使用

### 自定义 Headers 用途

某些 MaaS 服务需要特殊的认证头，例如：
- `X-Auth-Token: xxx`
- `X-API-Key: xxx`
- `Authorization: Bearer xxx`

配置后，请求会自动携带这些 Headers 发送到对应的 MaaS 账号。

## 第三方用户 API Key 管理

### 创建用户 API Key

```bash
# 创建 API Key
curl -X POST http://localhost:8000/admin/api-keys \
  -H "X-Admin-Key: sk-admin-your-master-key" \
  -d '{
    "name": "用户A的Key",
    "group": "premium",
    "tags": ["gpt-4", "claude"],
    "rpm_limit": 60,
    "tpm_limit": 90000,
    "budget_limit": 100.0
  }'
```

**响应**（返回的 `api_key` 只会显示一次，请妥善保存）：

```json
{
  "id": "uuid",
  "api_key": "sk-llm-xxxxxx...",
  "name": "用户A的Key",
  "group": "premium",
  "tags": ["gpt-4", "claude"],
  "rpm_limit": 60,
  "tpm_limit": 90000,
  "budget_limit": 100.0,
  "created_at": "2026-04-12T10:00:00Z"
}
```

### 第三方用户使用 API Key

第三方用户拿到 `sk-llm-xxxx` 后，调用 API 时这样认证：

```bash
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer sk-llm-xxxxxx" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "hello"}]
  }'
```

### 列出用户 API Key

```bash
# 列出所有 Key
curl -X GET http://localhost:8000/admin/api-keys \
  -H "X-Admin-Key: sk-admin-xxx"

# 按 group 过滤
curl -X GET "http://localhost:8000/admin/api-keys?group=premium" \
  -H "X-Admin-Key: sk-admin-xxx"

# 按 tags 过滤
curl -X GET "http://localhost:8000/admin/api-keys?tags=gpt-4,claude" \
  -H "X-Admin-Key: sk-admin-xxx"
```

### 用户 API Key 字段说明

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `name` | string | 是 | Key 名称/用途描述 |
| `group` | string | 否 | 分组（如 `premium`、`trial`、`internal`） |
| `tags` | list | 否 | 标签列表（如 `["gpt-4", "claude"]`） |
| `rpm_limit` | int | 否 | 每分钟请求限制，默认 60 |
| `tpm_limit` | int | 否 | 每分钟 Token 限制，默认 90000 |
| `budget_limit` | float | 否 | 月预算上限 |

### 更新用户 Key 限流

```bash
# 更新 Key 的限流配置
curl -X PATCH http://localhost:8000/admin/api-keys/{key_id} \
  -H "X-Admin-Key: sk-admin-xxx" \
  -d '{
    "rpm_limit": 120,
    "tpm_limit": 180000,
    "is_active": true
  }'
```

### 删除用户 Key

```bash
curl -X DELETE http://localhost:8000/admin/api-keys/{key_id} \
  -H "X-Admin-Key: sk-admin-xxx"
```

## 架构

```
Client → FastAPI → Auth → Rate Limit → LiteLLM Router → MaaS Accounts
                           ↓
                    Redis (限速/缓存)
                    PostgreSQL (Keys/统计)
```