┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ 客户端 │ │ Gateway │ │ 数据库 │ │Provider │
└────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘
│ │ │ │
│ │ │ │
═══════════════════════════════════════════════════════════════════════════
阶段 1: 系统初始化
═══════════════════════════════════════════════════════════════════════════
│ │ │ │
│ 1. 健康检查 │ │ │
├───────────────────>│ │ │
│ GET /health │ │ │
│ │ │ │
│<───────────────────┤ │ │
│ 200 OK │ │ │
│ │ │ │
═══════════════════════════════════════════════════════════════════════════
阶段 2: 配置 Provider 凭据
═══════════════════════════════════════════════════════════════════════════
│ │ │ │
│ 2. 创建 Provider │ │ │
│ 凭据 │ │ │
├───────────────────>│ │ │
│ POST /admin/ │ 加密凭据 │ │
│ providers ├───────────────────>│ │
│ │ INSERT │ │
│ │<───────────────────┤ │
│<───────────────────┤ Success │ │
│ 201 Created │ │ │
│ {id, provider} │ │ │
│ │ │ │
│ 3. 列出 Provider │ │ │
│ 凭据 │ │ │
├───────────────────>│ │ │
│ GET /admin/ │ SELECT │ │
│ providers ├───────────────────>│ │
│ │<───────────────────┤ │
│<───────────────────┤ [credentials] │ │
│ 200 OK │ │ │
│ [providers] │ │ │
│ │ │ │
═══════════════════════════════════════════════════════════════════════════
阶段 3: 创建 API Key
═══════════════════════════════════════════════════════════════════════════
│ │ │ │
│ 4. 创建 API Key │ │ │
├───────────────────>│ │ │
│ POST /admin/ │ 生成 Key Hash │ │
│ api-keys │ 设置配额 │ │
│ ├───────────────────>│ │
│ │ INSERT │ │
│ │<───────────────────┤ │
│<───────────────────┤ Success │ │
│ 201 Created │ │ │
│ {id, api_key} │ │ │
│ ⚠️ 保存 api_key! │ │ │
│ │ │ │
│ 5. 列出 API Keys │ │ │
├───────────────────>│ │ │
│ GET /admin/ │ SELECT │ │
│ api-keys ├───────────────────>│ │
│ │<───────────────────┤ │
│<───────────────────┤ [api_keys] │ │
│ 200 OK │ │ │
│ [keys] │ │ │
│ │ │ │
═══════════════════════════════════════════════════════════════════════════
阶段 4: 调用生成接口
═══════════════════════════════════════════════════════════════════════════
│ │ │ │
│ 6. 统一生成接口 │ │ │
├───────────────────>│ │ │
│ POST /generate │ 1) 验证 API Key │ │
│ Header: ├───────────────────>│ │
│ X-API-Key: xxx │ SELECT api_key │ │
│ │<───────────────────┤ │
│ Body: │ api_key_info │ │
│ {provider, │ │ │
│ model, │ 2) 检查授权 │ │
│ prompt} │ (allowed_providers) │
│ │ │ │
│ │ 3) 检查配额 │ │
│ ├───────────────────>│ │
│ │ SELECT usage │ │
│ │<───────────────────┤ │
│ │ quota_ok │ │
│ │ │ │
│ │ 4) 获取 Provider │ │
│ │ 凭据 │ │
│ ├───────────────────>│ │
│ │ SELECT credential │ │
│ │<───────────────────┤ │
│ │ 解密凭据 │ │
│ │ │ │
│ │ 5) 调用 Provider │ │
│ ├───────────────────────────────────────>│
│ │ HTTP Request │ │
│ │<───────────────────────────────────────┤
│ │ Response │ │
│ │ │ │
│ │ 6) 记录用量 │ │
│ ├───────────────────>│ │
│ │ INSERT usage │ │
│ │<───────────────────┤ │
│<───────────────────┤ Success │ │
│ 200 OK │ │ │
│ {request_id, │ │ │
│ text, usage} │ │ │
│ │ │ │
│ 7. OpenAI 兼容 │ │ │
│ 接口 │ │ │
├───────────────────>│ │ │
│ POST /chat/ │ 转换为统一格式 │ │
│ completions │ 调用 generate() │ │
│ │ (同上流程) │ │
│<───────────────────┤ │ │
│ 200 OK │ 转换为 OpenAI │ │
│ OpenAI 格式 │ 格式返回 │ │
│ │ │ │
═══════════════════════════════════════════════════════════════════════════
阶段 5: 查询任务状态（异步任务）
═══════════════════════════════════════════════════════════════════════════
│ │ │ │
│ 8. 查询任务状态 │ │ │
├───────────────────>│ │ │
│ GET /tasks/ │ 1) 验证 API Key │ │
│ {task_id} ├───────────────────>│ │
│ │ SELECT usage │ │
│ │<───────────────────┤ │
│ │ usage_record │ │
│ │ │ │
│ │ 2) 查询 Provider │ │
│ ├───────────────────────────────────────>│
│ │ GET task status │ │
│ │<───────────────────────────────────────┤
│<───────────────────┤ Task status │ │
│ 200 OK │ │ │
│ {status, result} │ │ │
│ │ │ │
═══════════════════════════════════════════════════════════════════════════
阶段 6: 查询用量和配额
═══════════════════════════════════════════════════════════════════════════
│ │ │ │
│ 9. 查询配额状态 │ │ │
├───────────────────>│ │ │
│ GET /usage/quota │ 1) 验证 API Key │ │
│ ├───────────────────>│ │
│ │ SELECT api_key │ │
│ │<───────────────────┤ │
│ │ │ │
│ │ 2) 统计用量 │ │
│ ├───────────────────>│ │
│ │ SELECT SUM(usage) │ │
│ │<───────────────────┤ │
│<───────────────────┤ usage_stats │ │
│ 200 OK │ │ │
│ {daily_used, │ │ │
│ daily_limit, │ │ │
│ remaining} │ │ │
│ │ │ │
│ 10. 查询用量统计 │ │ │
├───────────────────>│ │ │
│ GET /usage/stats │ 聚合查询 │ │
│ ?provider=xxx ├───────────────────>│ │
│ &start_time=xxx │ SELECT │ │
│ │ SUM, AVG, COUNT │ │
│ │<───────────────────┤ │
│<───────────────────┤ aggregated_stats │ │
│ 200 OK │ │ │
│ {total_calls, │ │ │
│ total_tokens, │ │ │
│ avg_time} │ │ │
│ │ │ │
│ 11. 查询用量记录 │ │ │
├───────────────────>│ │ │
│ GET /usage/ │ 分页查询 │ │
│ records ├───────────────────>│ │
│ ?limit=10 │ SELECT │ │
│ &offset=0 │ LIMIT OFFSET │ │
│ │<───────────────────┤ │
│<───────────────────┤ [records] │ │
│ 200 OK │ │ │
│ [usage_records] │ │ │
│ │ │ │
═══════════════════════════════════════════════════════════════════════════
阶段 7: 管理和维护
═══════════════════════════════════════════════════════════════════════════
│ │ │ │
│ 12. 更新 API Key │ │ │
├───────────────────>│ │ │
│ PUT /admin/ │ UPDATE │ │
│ api-keys/{id} ├───────────────────>│ │
│ │<───────────────────┤ │
│<───────────────────┤ Success │ │
│ 200 OK │ │ │
│ │ │ │
│ 13. 更新 Provider │ │ │
│ 凭据 │ │ │
├───────────────────>│ │ │
│ PUT /admin/ │ 加密新凭据 │ │
│ providers/{id} │ UPDATE │ │
│ ├───────────────────>│ │
│ │<───────────────────┤ │
│<───────────────────┤ Success │ │
│ 200 OK │ │ │
│ │ │ │
│ 14. 禁用 API Key │ │ │
├───────────────────>│ │ │
│ PUT /admin/ │ UPDATE │ │
│ api-keys/{id} │ is_active=false │ │
│ {is_active:false} ├───────────────────>│ │
│ │<───────────────────┤ │
│<───────────────────┤ Success │ │
│ 200 OK │ │ │
│ │ │ │
│ 15. 删除资源 │ │ │
├───────────────────>│ │ │
│ DELETE /admin/ │ DELETE │ │
│ api-keys/{id} ├───────────────────>│ │
│ │<───────────────────┤ │
│<───────────────────┤ Success │ │
│ 204 No Content │ │ │
│ │ │ │
- 所有生成和用量接口都需要在请求头中携带
X-API-Key - Gateway 通过 API Key Hash 验证身份
- 验证通过后获取 API Key 的配置信息（配额、允许的 Provider 等）
- 检查 API Key 是否允许访问指定的 Provider
- 如果
allowed_providers为空，则允许访问所有 Provider
- 每次请求前检查配额（调用次数和 token 数）
- 支持每日和每月两个维度的限制
- 配额不足时返回 429 错误
- 根据请求中的
provider参数选择对应的适配器 - 如果未指定，使用默认 Provider（配置文件中设置）
- 获取并解密 Provider 凭据
- 每次请求完成后记录用量信息
- 包括 token 数、响应时间、状态等
- 用于配额统计和用量分析
- 所有错误响应都包含标准格式：
error_code: 错误代码error_message: 错误消息request_id: 请求 ID（用于追踪）details: 详细信息（可选）
如果只想快速验证系统功能，按以下顺序测试：
- 健康检查 → 确认服务正常运行
- 创建 Provider 凭据 → 配置至少一个 Provider
- 创建 API Key → 获取访问凭证
- 调用生成接口 → 测试核心功能
- 查询配额状态 → 验证配额管理
按照上述时序图中的 15 个步骤依次测试，覆盖所有功能。
使用提供的测试脚本：
# Python 脚本（推荐）
python test_api_sequence.py
# Shell 脚本
./test_api.shA: 检查 Provider 凭据是否配置正确，是否是真实有效的 API Key。
A: 确保在请求头中正确设置了 X-API-Key，且 API Key 处于启用状态。
A: 查询配额状态接口，检查当前用量，必要时更新配额限制。
A: 检查 Provider 凭据是否存在且处于启用状态（is_active=true）。