API Key 管理与计费系统模块（API Gateway 模块）需求文档
一、产品概述
1.1 背景
在开放平台或 AI 服务中，开发者通常需要使用 API Key 来访问系统的各项接口。为了确保调用安全、进行计费统计、以及支持多租户或多开发者场景，系统需要一个统一的 API Key 管理与验证模块。
该模块将实现：
- API Key 的创建、查询、修改、删除；
- API 调用合法性验证；
- API Key 调用次数、费用统计；
- 提供 REST API 接口供外部系统（如 AI 应用、工作流平台、Coze 插件等）使用；
- 模块化封装，可嵌入任意 FastAPI / Flask / Django 等后端项目。
二、目标与范围
| 模块 | 目标 |
|---|---|
| API Key 管理 | 提供标准的增删查改功能，支持按用户、按应用、按权限分级管理 |
| 安全验证 | 确保每次 API 请求的 Key 合法、未过期、未封禁 |
| 计费统计 | 按调用次数、Token 数或请求类型计费 |
| 复用封装 | 提供模块化 SDK 与 REST API 两种调用方式 |
| 可扩展性 | 支持接入 Stripe、支付宝、微信支付等结算模块（后续版本） |
三、用户角色与使用场景
| 角色 | 行为 | 场景 |
|---|---|---|
| 平台管理员 | 管理开发者账号、审核API Key、查看调用统计 | 内部控制台 |
| AI 开发者 | 创建自己的 API Key，用于调用平台 API | 第三方应用调用 |
| API 服务模块 | 通过该模块验证 Key、统计调用次数、计算费用 | 内部依赖模块 |
四、功能需求
4.1 API Key 管理功能
| 功能 | 描述 | 接口路径 | 权限 |
|---|---|---|---|
| 创建 API Key | 为指定用户生成一个新的 Key，可设定有效期、调用限额 | POST /api/v1/apikeys | 管理员/用户 |
| 查询 API Key | 查询自己或指定用户的所有 Key | GET /api/v1/apikeys | 管理员/用户 |
| 修改 API Key | 可更新 Key 状态（启用/停用）、备注、限额等 | PUT /api/v1/apikeys/{key_id} | 管理员/用户 |
| 删除 API Key | 删除某个 Key（逻辑删除） | DELETE /api/v1/apikeys/{key_id} | 管理员/用户 |
| 校验 API Key | 校验 Key 是否有效（由系统自动完成） | 内部调用 | 系统 |
字段设计：
| 字段名 | 类型 | 描述 |
|---|---|---|
id | string (UUID) | 主键 |
key | string | 实际 API Key（加密存储） |
user_id | string | 所属用户 |
status | enum(active, disabled, revoked) | 状态 |
limit_per_day | int | 每日调用上限 |
usage_today | int | 当日调用次数 |
total_usage | int | 累计调用次数 |
expire_at | datetime | 过期时间 |
created_at | datetime | 创建时间 |
remark | string | 备注 |
4.2 API 调用验证
目标：
每个外部 API 请求都需通过中间件或装饰器验证 API Key 合法性。
验证流程：
-
前端或客户端在请求 Header 中携带
Authorization: Bearer <API_KEY>； -
系统根据 Key 查询数据库；
-
验证：
- Key 是否存在；
- 是否处于 active 状态；
- 是否在有效期内；
- 当日调用次数是否超限；
-
若通过，记录一次调用日志；
-
若失败，返回标准错误码（见下）。
返回示例：
{"success": false,"error": "Invalid API Key","code": 401
}
4.3 计费与统计功能
| 功能 | 描述 |
|---|---|
| 调用计数 | 每次通过验证的调用自动+1 |
| 日调用上限 | 超出上限自动拒绝请求 |
| Token 计费（可选） | 可按大模型返回的 token 数或请求次数计算费用 |
| 月度账单汇总 | 按 Key 汇总调用量与费用 |
调用日志表设计：
| 字段 | 类型 | 描述 |
|---|---|---|
id | string | 主键 |
api_key_id | string | 对应 API Key |
endpoint | string | 调用接口路径 |
timestamp | datetime | 调用时间 |
response_time_ms | int | 接口耗时 |
token_usage | int | 可选，用于大模型接口 |
cost | decimal | 本次调用费用 |
五、API 设计规范（RESTful）
5.1 示例：创建 API Key
POST /api/v1/apikeys
{"user_id": "u123","limit_per_day": 1000,"expire_at": "2026-12-31T00:00:00Z","remark": "用于AI模型测试"
}
返回：
{"id": "k_abc123","api_key": "sk_live_8f3a9b2...","status": "active","created_at": "2025-10-28T10:00:00Z"
}
5.2 示例：校验 Key 合法性（内部使用）
GET /api/v1/apikeys/validate
Header:
Authorization: Bearer sk_live_8f3a9b2...
返回：
{"valid": true,"user_id": "u123","limit_remaining": 785
}
六、安全策略
| 策略 | 说明 |
|---|---|
| API Key 加密存储 | 使用 AES + Base64 存储，避免明文泄露 |
| Key 生成规则 | 采用 UUIDv4 + 随机盐，前缀如 sk_live_ 或 sk_test_ |
| 速率限制 | 支持 per-key 速率限制（如每秒不超过10次） |
| 白名单与封禁 | 支持快速封禁 Key |
| 日志审计 | 所有创建、删除操作记录操作人与时间戳 |
七、非功能性需求
| 维度 | 说明 |
|---|---|
| 性能 | 单节点支持 1000+ QPS 验证 |
| 可扩展性 | 模块化，可接入任意后端项目 |
| 可观测性 | 提供 Prometheus 指标：调用数、错误率、延迟 |
| 安全性 | HTTPS 传输 + JWT 用户认证 + Key 加密 |
| 多租户 | 支持按 tenant_id 区分 Key 池（可选） |
八、技术实现建议
| 项目 | 建议实现方式 |
|---|---|
| 框架 | FastAPI / Flask |
| ORM | SQLAlchemy / Prisma |
| 数据库 | PostgreSQL / MySQL |
| 缓存 | Redis（用于计数器） |
| 日志 | Elastic Stack / Loki |
| 鉴权装饰器 | @require_api_key 中间件 |
| 模块封装 | api_key_manager Python 包，含验证中间件、计数逻辑、REST接口 |
九、后续迭代方向（V2+）
- ✅ 支持按模型（如 GPT、Whisper）区分计费；
- ✅ 接入支付结算（Stripe / 支付宝）；
- ✅ 支持开发者控制台前端页面；
- ✅ 提供 SDK（Python / Node.js）；
- ✅ 接入 OAuth2 + JWT 登录系统。
十、验收标准
| 验收项 | 验收标准 |
|---|---|
| API Key 创建成功 | 返回可用的 Key 且数据库中有记录 |
| 调用验证正确 | 合法 Key 能通过，非法 Key 被拒绝 |
| 调用计数正确 | 每次调用计数 +1 |
| 限额生效 | 超过 daily limit 拒绝请求 |
| 模块可复用 | 可独立启动，也可嵌入其他服务 |
| 安全合规 | Key 加密存储，无明文泄露 |
是否希望我 进一步生成对应的项目结构（FastAPI版）与数据库模型定义（SQLAlchemy）？
那样你可以直接基于这个 PRD 启动开发。