taiji-AI-PAD/plans/计费系统修复完成报告.md

计费系统修复完成报告

版本: v1.0.0
完成时间: 2026-01-09
状态: ✅ 已完成

---

📋 修复概述

根据《计费系统代码修复指南.md》，已成功完成所有P0优先级问题的修复，并实现了完整的LiteLLM Token计费系统。

✅ 已完成的修复

1. Dashboard EU显示为0问题 (P0) ✅

问题: Dashboard查询billing_records表，但Agent计费写入agent_billing_records表

修复文件: services/mcp-server/monitoring.py

修改内容:

• ✅ 修改_get_tenant_eu_consumption_24h方法
• ✅ 将查询从billing_records改为agent_billing_records
• ✅ 字段映射: eu → eu_consumed, timestamp → start_time, tenant_id → user_id
• ✅ 合并Agent运行时长计费和模型Token计费数据

影响:

• Dashboard现在能正确显示EU消耗
• 支持Agent运行时长计费统计
• 支持模型Token计费统计（需要LiteLLM webhook）

2. 平台Agent分配时未计费 (P0) ✅

问题: 渠道分配平台Agent给租户时，Pod启动但没有创建计费记录

修复文件: services/mcp-server/app/routes/platform_agent_quota.py

修改内容:

• ✅ 在allocate_platform_agent_to_tenant函数中添加计费记录创建
• ✅ 在stop_platform_agent函数中添加计费结束逻辑
• ✅ 计算运行时长、EU消耗和成本

代码位置:

• 分配逻辑: 第540-580行
• 停止逻辑: 第987-1068行

影响:

• 平台Agent启动时自动创建计费记录
• 停止时自动计算运行时长和费用
• 支持EU消耗统计

3. LiteLLM Token计费实现 (P0) ✅ 🚨 最重要

问题: 缺少基于Token的精确模型调用计费

实现内容:

3.1 数据库迁移

文件: services/mcp-server/migrations/012_add_model_billing_records.sql

• ✅ 创建model_billing_records表
• ✅ 包含Token用量、成本、EU消耗等字段
• ✅ 创建必要的索引

3.2 数据模型

文件: services/mcp-server/models.py

• ✅ 添加ModelBillingRecord模型
• ✅ 支持LiteLLM回调数据存储
• ✅ 关联租户和渠道

3.3 Webhook路由

文件: services/mcp-server/app/routes/billing_webhook.py

• ✅ 实现/api/v1/billing/litellm-callback端点
• ✅ 解析LiteLLM回调数据
• ✅ 计算EU消耗
• ✅ 幂等性处理（避免重复计费）
• ✅ 健康检查端点

3.4 路由注册

文件: services/mcp-server/app/routes/__init__.py

• ✅ 导入billing_webhook模块
• ✅ 注册到FastAPI应用

3.5 LiteLLM配置

文件: services/model-gateway/config/litellm.yaml

• ✅ 配置success_callback: ["langfuse", "webhook"]
• ✅ 配置webhook_url: "http://mcp-server:8002/api/v1/billing/litellm-callback"
• ✅ 添加webhook headers配置

3.6 Dashboard查询增强

文件: services/mcp-server/monitoring.py

• ✅ 修改_get_tenant_model_usage方法使用model_billing_records
• ✅ 在_get_tenant_eu_consumption_24h中合并两种计费数据
• ✅ 返回agentEU和modelEU分别统计

影响:

• 🎯 精确的Token计费（按实际使用量）
• 🎯 模型使用统计（GPT-4、Claude等）
• 🎯 成本控制（根据不同模型定价）
• 🎯 用户配额管理（防止超额使用）

---

📁 修改文件清单

文件	修改类型	说明
services/mcp-server/monitoring.py	✏️ 修改	Dashboard查询修复和增强
services/mcp-server/app/routes/platform_agent_quota.py	✏️ 修改	添加计费记录创建和结束逻辑
services/mcp-server/migrations/012_add_model_billing_records.sql	➕ 新建	模型Token计费表迁移
services/mcp-server/models.py	➕ 新增	ModelBillingRecord模型
services/mcp-server/app/routes/billing_webhook.py	➕ 新建	LiteLLM Webhook路由
services/mcp-server/app/routes/__init__.py	✏️ 修改	注册webhook路由
services/model-gateway/config/litellm.yaml	✏️ 修改	配置webhook回调

---

🚀 部署步骤

⚠️ Azure云数据库特别说明

本系统使用Azure PostgreSQL云数据库，迁移步骤略有不同：

Azure数据库迁移方式

方式1: 使用专用迁移脚本（推荐）

# 设置Azure数据库连接信息
export DB_HOST=your-server.postgres.database.azure.com
export DB_USER=your-username@your-server
export PGPASSWORD=your-password

# 执行迁移
./scripts/migrate_azure_db.sh

方式2: 手动执行迁移

psql -h your-server.postgres.database.azure.com \
     -U your-username@your-server \
     -d taiji \
     -f services/mcp-server/migrations/012_add_model_billing_records.sql

详细说明: 参见 docs/AZURE-DB-MIGRATION.md

方式1: 使用自动化脚本（推荐）

# 1. 先执行Azure数据库迁移（见上方）

# 2. 构建并重启服务
docker compose build mcp-server
docker compose restart mcp-server

# 3. 执行验证测试
python3 ./scripts/test_billing_fix.py

方式2: 手动部署

步骤1: 备份数据库

docker exec -i taiji-postgres pg_dump -U postgres taiji > backup_$(date +%Y%m%d_%H%M%S).sql

步骤2: 执行数据库迁移

docker exec -i taiji-postgres psql -U postgres taiji < services/mcp-server/migrations/012_add_model_billing_records.sql

步骤3: 验证表创建

docker exec taiji-postgres psql -U postgres taiji -c "\d model_billing_records"

步骤4: 重启服务

docker-compose restart mcp-server

步骤5: 测试Webhook

curl http://localhost:8002/api/v1/billing/litellm-callback/health

---

🧪 测试验证

测试1: Webhook健康检查

curl http://localhost:8002/api/v1/billing/litellm-callback/health

预期结果: {"status":"ok","endpoint":"/api/v1/billing/litellm-callback"}

测试2: 数据库表验证

# 检查agent_billing_records
docker exec taiji-postgres psql -U postgres taiji -c "SELECT COUNT(*) FROM agent_billing_records;"

# 检查model_billing_records
docker exec taiji-postgres psql -U postgres taiji -c "SELECT COUNT(*) FROM model_billing_records;"

测试3: 模拟Token计费回调

curl -X POST http://localhost:8002/api/v1/billing/litellm-callback \
  -H "Content-Type: application/json" \
  -d '{
    "id": "test_call_123",
    "model": "gpt-4",
    "usage": {
      "prompt_tokens": 100,
      "completion_tokens": 50,
      "total_tokens": 150
    },
    "response_cost": 0.0045,
    "status": "success"
  }'

测试4: 验证计费记录

# 查看最新的模型计费记录
docker exec taiji-postgres psql -U postgres taiji -c "
SELECT model_name, input_tokens, output_tokens, total_cost, eu_consumed, created_at 
FROM model_billing_records 
ORDER BY created_at DESC 
LIMIT 5;
"

---

⚙️ 配置要点

LiteLLM生产环境配置

需要确保LiteLLM能访问mcp-server的webhook端点：

Docker环境

# docker-compose.yml
services:
  mcp-server:
    ports:
      - "8002:8002"
    environment:
      - PORT=8002

网络连通性验证

# 从LiteLLM容器测试（如果在Docker内）
docker exec -it litellm-container curl http://mcp-server:8002/api/v1/billing/litellm-callback/health

# 或从外部测试（如果LiteLLM是外部服务）
curl http://your-mcp-server-ip:8002/api/v1/billing/litellm-callback/health

---

📊 计费系统架构

两种计费模式

1. Agent运行时长计费

• 数据表: agent_billing_records
• 计费单位: EU (1 EU = 10秒)
• 触发点: Agent启动/停止
• 适用于:
  • 自定义Agent（用户创建）
  • 平台Agent（渠道分配）

2. 模型Token计费

• 数据表: model_billing_records
• 计费单位: Token数量
• 触发点: LiteLLM模型调用完成
• 数据来源: LiteLLM success_callback webhook
• 适用于:
  • GPT-4, GPT-3.5-turbo
  • Claude系列
  • 其他LLM模型

Dashboard数据流

┌─────────────────────┐
│  Dashboard Query    │
└──────────┬──────────┘
           │
    ┌──────▼──────┐
    │ monitoring.py│
    └──────┬──────┘
           │
    ┌──────┴────────────────────┐
    │                           │
┌───▼────────────────┐  ┌──────▼───────────────┐
│agent_billing_records│  │model_billing_records│
│ (容器运行计费)      │  │ (Token使用计费)     │
└────────────────────┘  └─────────────────────┘

---

🔍 故障排查

问题1: Dashboard仍显示EU为0

可能原因:

• mcp-server未重启
• 数据库迁移未执行

解决方案:

# 检查表是否存在
docker exec taiji-postgres psql -U postgres taiji -c "\d agent_billing_records"

# 重启服务
docker-compose restart mcp-server

问题2: Webhook端点不可访问

可能原因:

• 端口未暴露
• 路由未注册

解决方案:

# 检查端口
docker ps | grep mcp-server

# 检查日志
docker logs mcp-server | grep billing

问题3: LiteLLM回调失败

可能原因:

• 网络不通
• webhook_url配置错误

解决方案:

# 测试网络连通性
docker exec litellm-container curl http://mcp-server:8002/api/v1/billing/litellm-callback/health

# 检查LiteLLM日志
docker logs litellm-gateway | grep webhook

---

📈 后续优化建议

短期优化

1. ✅ 添加计费告警（超额使用提醒）
2. ✅ 实现配额管理（自动停止超额服务）
3. ✅ 优化查询性能（添加更多索引）

中期优化

1. ⏳ 实现计费报表（月度/季度账单）
2. ⏳ 支持多币种（USD/EUR/CNY）
3. ⏳ 实现成本优化建议

长期优化

1. 📋 ML预测（成本预估）
2. 📋 异常检测（异常用量识别）
3. 📋 自动化成本优化

---

📝 注意事项

⚠️ 重要提示

1. 数据库备份: 修改前务必备份数据库
2. 逐步部署: 建议先在测试环境验证
3. 监控日志: 修改后密切监控应用日志
4. 网络配置: 确保LiteLLM能访问mcp-server的8002端口

🔐 安全考虑

1. API Key脱敏: billing_webhook.py中已实现
2. 幂等性保证: 使用litellm_call_id防止重复计费
3. 错误处理: 所有关键操作都有try-catch

---

📞 支持

如有问题，请检查：

1. 日志: docker logs mcp-server | grep -E "计费|billing"
2. 数据库: docker exec taiji-postgres psql -U postgres taiji
3. 测试脚本: python3 ./scripts/test_billing_fix.py

---

最后更新: 2026-01-09
状态: ✅ 已完成并测试通过