希望平台自带API Key的生成，管理和计费功能

[lypzcgf]

---

📘 产品需求文档（PRD）

一、产品概述

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 合法性。

验证流程：

1. 前端或客户端在请求 Header 中携带 Authorization: Bearer <API_KEY>；

2. 系统根据 Key 查询数据库；

3. 验证：

   • Key 是否存在；
   • 是否处于 active 状态；
   • 是否在有效期内；
   • 当日调用次数是否超限；

4. 若通过，记录一次调用日志；

5. 若失败，返回标准错误码（见下）。

返回示例：

{
  "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 池（可选）

---

八、验收标准

验收项	验收标准
API Key 创建成功	返回可用的 Key 且数据库中有记录
调用验证正确	合法 Key 能通过，非法 Key 被拒绝
调用计数正确	每次调用计数 +1
限额生效	超过 daily limit 拒绝请求
模块可复用	可独立启动，也可嵌入其他服务
安全合规	Key 加密存储，无明文泄露

---