30分钟上手Lago：开发者必备的开源计费API集成指南

你还在为SaaS产品的计费系统头疼？使用商业解决方案被抽成 revenue share？自建又面临复杂的计量、定价和发票管理？Lago作为开源的用量计费系统，可帮你30分钟内搭建企业级计费能力。本文将从环境搭建到API调用，带你零门槛掌握Lago的核心功能，最终实现基于用量的计费流程自动化。

读完本文你将获得：

• 本地Lago环境的一键部署方法
• 核心计费概念与架构解析
• 完整的API集成示例（用户创建→事件计量→发票生成）
• 生产环境部署的最佳实践

为什么选择Lago？

传统商业计费系统存在三大痛点：按收入抽成的定价模式、数据隐私风险、功能定制受限。Lago作为开源替代方案，采用事件驱动架构，支持用量计费、订阅计费及混合模式，且部署完全自主可控。其核心优势包括：

• 模块化设计：通过connectors/支持HTTP、SQS等多种事件接入方式
• 灵活定价模型：支持按量计费、阶梯定价、预付费额度等20+定价策略
• 企业级特性：包含优惠券、预付额度、附加组件等完整功能

图1：Lago系统架构图，展示事件处理、计量、计费核心流程

环境搭建：3步启动本地开发环境

准备工作

确保已安装Docker和Git，通过以下命令验证环境：

docker --version  # 需20.10+版本
git --version     # 需2.30+版本

一键部署

使用官方提供的Docker Compose配置，3分钟完成部署：

# 克隆仓库（使用国内镜像）
git clone --depth 1 https://gitcode.com/GitHub_Trending/la/lago.git
cd lago

# 生成加密密钥并配置环境变量
echo "LAGO_RSA_PRIVATE_KEY=\"`openssl genrsa 2048 | openssl base64 -A`\"" >> .env
source .env

# 启动服务集群
docker compose -f deploy/docker-compose.local.yml up -d

部署配置说明：

• docker-compose.local.yml：本地开发环境配置
• docker-compose.production.yml：生产环境配置（含HTTPS和监控）
• 默认服务端口：Web UI(80)、API(3000)、数据库(5432)

验证安装

访问http://localhost 打开Lago管理界面，使用默认账号（[e-mail]/password）登录。进入Developer→API Keys页面，复制生成的API密钥备用。

图2：Lago管理界面的API密钥生成位置

核心概念与数据流程

Lago采用事件驱动架构，核心流程包括事件采集→用量计量→账单生成三阶段，涉及以下关键实体：

实体	作用说明	数据示例
Customer	客户账户，关联定价计划与支付方式	{"id":"cust_123","name":"Acme"}
Subscription	客户订阅关系，关联定价计划	{"plan_code":"pro_monthly"}
Event	用量事件记录，触发计费计量	{"code":"api_calls","value":100}
Invoice	自动生成的账单，包含汇总费用	{"amount_cents":9900,"status":"pending"}

表1：Lago核心业务实体说明

事件处理流程详解：

1. 应用系统通过API发送事件数据至Lago
2. events-processor服务进行事件验证和转换
3. 计量模块根据billable_metrics.go定义的规则计算用量
4. 计费模块在结算周期生成发票并触发支付流程

API集成实战：实现用量计费完整流程

以下示例使用curl命令演示API调用，实际开发中可使用官方SDK（支持Go/JS/Python等语言）。

1. 创建客户

curl -X POST http://localhost:3000/api/v1/customers \
  -H "Authorization: Bearer $LAGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "external_id": "user_456",
      "name": "Example Corp",
      "email": "[e-mail]"
    }
  }'

响应示例：

{
  "customer": {
    "id": "cust_123456",
    "external_id": "user_456",
    "created_at": "2023-10-23T08:15:30Z"
  }
}

2. 创建定价计划

curl -X POST http://localhost:3000/api/v1/plans \
  -H "Authorization: Bearer $LAGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": {
      "name": "API调用套餐",
      "code": "api_package",
      "interval": "monthly",
      "billable_metrics": [
        {
          "code": "api_requests",
          "name": "API请求次数",
          "aggregation_type": "count"
        }
      ],
      "pricing_rules": [
        {
          "billable_metric_code": "api_requests",
          "price_per_unit": 0.01,
          "tier_mode": "graduated"
        }
      ]
    }
  }'

3. 上报用量事件

当用户使用服务时，实时发送事件至Lago：

curl -X POST http://localhost:3000/api/v1/events \
  -H "Authorization: Bearer $LAGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": {
      "transaction_id": "tx_789",
      "external_customer_id": "user_456",
      "code": "api_requests",
      "timestamp": "2023-10-23T10:30:00Z",
      "properties": {
        "endpoint": "/v1/data",
        "status": 200
      }
    }
  }'

事件处理逻辑在event_producer_service.go中实现，支持批量事件和异步处理。

4. 查看生成的发票

在结算周期结束后（默认每月1日），系统自动生成发票：

curl -X GET http://localhost:3000/api/v1/invoices \
  -H "Authorization: Bearer $LAGO_API_KEY" \
  -d "external_customer_id=user_456"

开发调试技巧：

• 使用事件调试工具验证事件格式
• 通过./scripts/create-topics.sh手动创建Kafka主题（如需修改事件处理流程）

生产环境部署最佳实践

架构设计

生产环境推荐采用分布式部署，关键组件包括：

• 应用层：Lago API服务（水平扩展3+实例）
• 数据层：PostgreSQL（主从架构）+ Redis（缓存）
• 消息队列：Kafka（事件处理）
• 监控：Prometheus + Grafana（监控配置）

安全配置

1. 加密敏感数据：

   • 数据库加密：配置pgcrypto扩展
   • API通信：启用HTTPS（使用init-letsencrypt.sh自动配置证书）

2. 访问控制：

   # 限制容器网络访问
   docker network create --internal lago_backend
   docker network connect --alias db lago_backend postgres
   

运维监控

通过以下命令监控系统状态：

# 查看服务状态
docker compose -f deploy/docker-compose.production.yml ps

# 查看API服务日志
docker compose -f deploy/docker-compose.production.yml logs -f api

# 监控数据库性能
docker exec -it postgres pg_stat_activity

常见问题与解决方案

事件丢失排查

若事件未被正确处理，检查以下位置：

1. Kafka消费者日志
2. 事件验证规则：event.go
3. 数据库连接：database.go

性能优化建议

• 批量事件处理：通过bulk API减少请求次数
• 缓存配置：调整Redis缓存策略（redis.conf）
• 数据库索引：为events.external_customer_id添加索引

总结与进阶学习

通过本文你已掌握Lago的核心功能和集成方法，实现从事件采集到发票生成的完整计费流程。进阶学习建议：

1. 深入代码：

   • 事件处理流程：processors.go
   • 计费逻辑：subscriptions.go

2. 扩展功能：

   • 自定义支付网关：参考connectors/目录示例
   • 多语言SDK开发：基于OpenAPI规范

3. 社区资源：

   • 贡献指南
   • Slack社区
   • 视频教程

关注项目GitHub Releases获取最新功能更新，下一版本将支持多租户隔离和自定义报表功能。

本文档配套代码示例已上传至examples/目录，包含Python/Java集成样例。