API Key 计费功能使用指南

概述

本系统实现了完整的 API Key 计费功能，包括：

• 余额管理
• 使用量记录
• 费用计算
• 充值功能
• 使用统计

数据库表结构

1. sys_api_key (API Key 表)

新增字段：

• balance: 账户余额（人民币）
• quota_limit: 配额限制（人民币），为空表示无限制
• total_usage: 累计使用金额（人民币）
• total_tokens: 累计使用 tokens

2. sys_billing (充值记录表)

字段：

• api_key_id: 关联的 API Key ID
• amount: 充值金额
• status: 支付状态（待支付、已支付、已取消、已退款）
• order_no: 订单号
• payment_method: 支付方式
• payment_time: 支付时间
• remark: 备注

3. sys_usage (使用记录表)

字段：

• api_key_id: 关联的 API Key ID
• model: 使用的模型
• prompt_tokens: 输入 tokens
• completion_tokens: 输出 tokens
• total_tokens: 总 tokens
• cost: 本次调用费用
• request_path: 请求路径
• request_method: 请求方法
• status_code: 响应状态码
• error_message: 错误信息

API 接口

1. 获取使用量统计

GET /api/v1/usage/stats?days=30
Headers:
  X-API-Key: sk-{your_api_key}

响应：

{
  "code": 200,
  "data": {
    "balance": 100.0,
    "quota_limit": null,
    "total_usage": 25.5,
    "total_tokens": 123456,
    "total_requests": 500,
    "avg_cost": 0.051,
    "by_model": [
      {
        "model": "gpt-4",
        "count": 100,
        "tokens": 50000,
        "cost": 15.5
      }
    ]
  }
}

2. 获取使用历史

GET /api/v1/usage/history?page=1&page_size=20
Headers:
  X-API-Key: sk-{your_api_key}

3. 手动记录使用量

POST /api/v1/usage/record
Headers:
  X-API-Key: sk-{your_api_key}
Content-Type: application/json

{
  "model": "gpt-4",
  "prompt_tokens": 100,
  "completion_tokens": 50,
  "request_path": "/api/v1/chat/completions",
  "request_method": "POST"
}

4. 充值余额

POST /api/v1/billing/recharge
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "api_key_id": 1,
  "amount": 100.0,
  "payment_method": "支付宝",
  "remark": "充值100元"
}

5. 获取充值历史

GET /api/v1/billing/history?api_key_id=1&page=1&page_size=20
Authorization: Bearer {admin_token}

价格配置

当前价格配置（人民币/1K tokens）：

模型	输入 tokens	输出 tokens
gpt-4	¥0.21	¥0.42
gpt-4-turbo	¥0.07	¥0.14
gpt-3.5-turbo	¥0.01	¥0.02
text-embedding-ada-002	¥0.0007	¥0

可在 backlin/module_saas/billing_utils.py 中的 PRICING 字典修改价格。

使用流程

1. 创建 API Key

通过管理后台创建 API Key，默认余额为 0。

2. 充值

管理员为 API Key 充值：

curl -X POST http://localhost:8000/api/v1/billing/recharge \
  -H "Authorization: Bearer {admin_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key_id": 1,
    "amount": 100.0,
    "payment_method": "支付宝"
  }'

3. 使用 API

调用 API 时，系统会：

1. 验证 API Key 有效性
2. 检查余额是否充足
3. 检查是否超出配额限制
4. 调用成功后自动扣费并记录使用量

4. 查看统计

用户可以查看自己的使用统计和历史记录。

余额和配额检查

余额检查

• 每次 API 调用前会检查余额是否充足
• 余额不足时返回 402 Payment Required 错误

配额限制

• 可为 API Key 设置配额限制（quota_limit）
• 累计使用金额超过配额时禁止使用
• 配额为 null 表示无限制

手动记录使用量

在某些场景下（如代理其他 API），可能无法自动拦截响应并记录使用量。此时可以使用手动记录接口：

# 在你的代理逻辑中
response = requests.post(
    "https://api.openai.com/v1/chat/completions",
    headers={"Authorization": f"Bearer {openai_key}"},
    json=payload
)

# 提取 token 使用量
usage = response.json().get("usage", {})

# 手动记录
requests.post(
    "http://localhost:8000/api/v1/usage/record",
    headers={"X-API-Key": user_api_key},
    json={
        "model": payload["model"],
        "prompt_tokens": usage.get("prompt_tokens", 0),
        "completion_tokens": usage.get("completion_tokens", 0),
        "total_tokens": usage.get("total_tokens", 0)
    }
)

管理员操作

查看所有 API Key

GET /system/apikey/page

查看所有充值记录

GET /system/billing/page

查看所有使用记录

GET /system/usage/page

为用户充值

POST /api/v1/billing/recharge

设置配额限制

PATCH /system/apikey/{id}
Content-Type: application/json

{
  "quota_limit": 1000.0
}

权限配置

需要在系统中添加以下权限：

• client:apikey:list - 查看 API Key 列表
• client:apikey:query - 查看 API Key 详情
• client:apikey:add - 添加 API Key
• client:apikey:edit - 编辑 API Key
• client:apikey:remove - 删除 API Key
• client:apikey:export - 导出 API Key
• client:billing:list - 查看充值记录
• client:billing:query - 查看充值详情
• client:usage:list - 查看使用记录
• client:usage:query - 查看使用详情
• client:usage:export - 导出使用记录

注意事项

1. 数据库迁移：首次部署需要重新创建数据库或执行迁移
2. 价格更新：修改价格后不会影响历史记录
3. 并发安全：扣费操作使用数据库事务保证一致性
4. 日志记录：所有计费操作都会记录日志
5. 错误处理：扣费失败会自动回滚事务

测试

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

可以看到所有新增的 API 接口及其文档。