API Key 计费功能实现总结

概述

为 SaasKit 项目添加了完整的 API Key 计费功能，支持余额管理、使用量记录、费用计算、充值和统计等功能。

新增文件

1. `backlin/module_saas/billing_utils.py`

计费工具模块，提供核心计费功能：

calculate_cost() - 计算 API 调用费用
check_balance() - 检查余额和配额
deduct_balance() - 扣费并记录使用量
recharge_balance() - 充值余额
get_usage_stats() - 获取使用统计
PRICING - 价格配置字典

2. `backlin/middleware/billing.py`

计费中间件（可选使用）：

BillingMiddleware - 自动拦截和计费的中间件
record_usage_background() - 后台记录任务
manual_record_usage() - 手动记录使用量

3. `test_billing.py`

测试脚本，包含完整的测试流程

4. `API_BILLING_GUIDE.md`

详细的使用指南

修改的文件

1. `backlin/module_saas/schema.py`

扩展数据模型：

ApiKey 新增字段：

balance - 账户余额
quota_limit - 配额限制
total_usage - 累计使用金额
total_tokens - 累计使用 tokens
关系：usages、billings

Billing 扩展字段：

api_key_id - 关联 API Key
order_no - 订单号
payment_method - 支付方式
payment_time - 支付时间
remark - 备注

新增 Usage 模型：

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

2. `backlin/module_saas/api_require.py`

增强 API Key 验证：

添加余额检查
添加配额检查
返回 402 状态码当余额不足
将 API Key 存储到 request.state

3. `backlin/module_saas/api_v1.py`

新增计费相关接口：

GET /api/v1/usage/stats - 获取使用量统计
GET /api/v1/usage/history - 获取使用历史
POST /api/v1/usage/record - 手动记录使用量
POST /api/v1/billing/recharge - 充值余额
GET /api/v1/billing/history - 获取充值历史

4. `backlin/module_saas/route_apikey.py`

导入 Usage 和 UsageModel
添加 app_usage 路由器

5. `backlin/backend.py`

导入 api_v1 模块
注册 app_usage 路由
注册 api_v1 路由

数据库变更

运行应用时会自动创建以下表结构变更：

sys_api_key 表新增列：

ALTER TABLE sys_api_key ADD COLUMN balance FLOAT DEFAULT 0.0;
ALTER TABLE sys_api_key ADD COLUMN quota_limit FLOAT;
ALTER TABLE sys_api_key ADD COLUMN total_usage FLOAT DEFAULT 0.0;
ALTER TABLE sys_api_key ADD COLUMN total_tokens INTEGER DEFAULT 0;

sys_billing 表新增列：

ALTER TABLE sys_billing ADD COLUMN api_key_id INTEGER NOT NULL;
ALTER TABLE sys_billing ADD COLUMN order_no VARCHAR UNIQUE;
ALTER TABLE sys_billing ADD COLUMN payment_method VARCHAR;
ALTER TABLE sys_billing ADD COLUMN payment_time TIMESTAMP;
ALTER TABLE sys_billing ADD COLUMN remark TEXT;

新建 sys_usage 表：

CREATE TABLE sys_usage (
    id SERIAL PRIMARY KEY,
    api_key_id INTEGER NOT NULL REFERENCES sys_api_key(id) ON DELETE CASCADE,
    model VARCHAR,
    prompt_tokens INTEGER DEFAULT 0,
    completion_tokens INTEGER DEFAULT 0,
    total_tokens INTEGER DEFAULT 0,
    cost FLOAT DEFAULT 0.0,
    request_path VARCHAR,
    request_method VARCHAR,
    status_code INTEGER,
    error_message TEXT,
    create_time TIMESTAMP DEFAULT NOW(),
    create_by VARCHAR,
    update_time TIMESTAMP,
    update_by VARCHAR,
    name VARCHAR,
    remark TEXT
);

功能特性

1. 余额管理

✅ 初始余额为 0
✅ 支持充值
✅ 自动扣费
✅ 余额不足时拒绝请求

2. 配额限制

✅ 可选的配额限制
✅ 超出配额时拒绝请求
✅ 支持无限配额

3. 使用量记录

✅ 自动记录每次 API 调用
✅ 记录 tokens 使用量
✅ 记录费用
✅ 记录请求详情

4. 费用计算

✅ 按模型计费
✅ 区分输入/输出 tokens
✅ 支持自定义价格
✅ 精确到 6 位小数

5. 统计分析

✅ 使用量统计
✅ 按模型分组统计
✅ 历史记录查询
✅ 充值记录查询

6. 安全性

✅ 数据库事务保证一致性
✅ API Key 验证
✅ 权限控制
✅ 错误处理和回滚

使用流程

1. 启动服务

cd backend/backlin
backlin --env dev --recreate-db

注意：使用 --recreate-db 会重建数据库表结构。

2. 创建 API Key

通过管理后台或 API 创建：

curl -X POST http://localhost:8000/system/apikey/create_auth \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "我的API Key"}'

3. 充值

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

4. 使用 API

curl http://localhost:8000/your-api-endpoint \
  -H "X-API-Key: sk-your-key"

5. 查看统计

curl http://localhost:8000/api/v1/usage/stats \
  -H "X-API-Key: sk-your-key"

测试

运行测试脚本：

python test_billing.py

该脚本会执行完整的测试流程：

管理员登录
创建 API Key
充值
记录使用量
查看统计和历史

价格配置

在 billing_utils.py 中修改 PRICING 字典：

PRICING = {
    "gpt-4": {
        "prompt": 0.21,      # ¥0.21/1K tokens
        "completion": 0.42,   # ¥0.42/1K tokens
    },
    "gpt-3.5-turbo": {
        "prompt": 0.01,
        "completion": 0.02,
    },
    # 添加更多模型...
}

权限配置

需要在系统菜单管理中添加以下权限标识：

client:apikey:* - API Key 管理
client:billing:* - 充值管理
client:usage:* - 使用记录管理

API 文档

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

可以看到所有接口的详细文档和在线测试功能。

注意事项

数据迁移：首次部署需要重建数据库或手动执行 SQL 迁移
并发安全：扣费操作使用数据库事务，确保并发安全
价格变更：修改价格不影响历史记录
日志记录：所有重要操作都有日志记录
错误恢复：扣费失败会自动回滚

后续优化建议

异步处理：使用 Celery 等异步任务队列处理计费
缓存优化：使用 Redis 缓存 API Key 信息
批量计费：支持批量处理计费记录
通知提醒：余额不足时发送通知
报表功能：生成使用报表和账单
支付集成：集成真实的支付平台
配额策略：支持更复杂的配额策略（如按时间周期）

技术栈

FastAPI - Web 框架
SQLAlchemy - ORM
PostgreSQL - 数据库
Pydantic - 数据验证

版本信息

初始版本：v1.0.0
创建日期：2025-10-19
作者：GitHub Copilot

概述​

新增文件​

1. backlin/module_saas/billing_utils.py​

2. backlin/middleware/billing.py​

3. test_billing.py​

4. API_BILLING_GUIDE.md​

修改的文件​

1. backlin/module_saas/schema.py​

2. backlin/module_saas/api_require.py​

3. backlin/module_saas/api_v1.py​

4. backlin/module_saas/route_apikey.py​

5. backlin/backend.py​

数据库变更​

sys_api_key 表新增列：​

sys_billing 表新增列：​

新建 sys_usage 表：​

功能特性​

1. 余额管理​

2. 配额限制​

3. 使用量记录​

4. 费用计算​

5. 统计分析​

6. 安全性​

使用流程​

1. 启动服务​

2. 创建 API Key​

3. 充值​

4. 使用 API​

5. 查看统计​

测试​

价格配置​

权限配置​

API 文档​

注意事项​

后续优化建议​

技术栈​

版本信息​

概述