Lago 1.55.0 介绍与选型指南

目标：全面认识 Lago 这款开源计量与用量计费（Usage-Based Billing）平台，掌握其定位、技术架构、计费模型、功能特性与自托管形态，并能在与 Kill Bill、OpenMeter、Metronome 等同类产品之间做出量化选型。本文为认知溯源篇，全部信息来自官方仓库、官方文档与公开渠道实查，来源与查询日期（2026-10-23）均已在文中标注，未做本地实测；部署与命令实测见本专栏后续篇章。

一、环境信息

本文为认知与选型篇，内容以公开资料溯源为主，关键取证信息与查询日期如下：

• 软件名称：Lago（官方口号「Open Source Metering & Usage-Based Billing」，2026 年版 README 定位为「Agentic-first, open-source monetization infrastructure for AI products」）
• 开发与维护方：Lago 团队（GitHub 组织 getlago），主仓库 github.com/getlago/lago
• 官网：https://www.getlago.com；官方文档站：https://doc.getlago.com
• 最新稳定版本：v1.55.0（GitHub Releases 实查：2026-10-07 发布，非 pre-release、非 draft；与 Docker Hub 官方仓库 getlago/api、getlago/front 的 v1.55.0 标签相互印证，该标签构建于 2026-10-07。查询日期 2026-10-23）
• 主仓库创建时间：2022-02-28（GitHub 仓库元数据实查，查询日期 2026-10-23）
• 社区活跃度（GitHub API 实查，查询日期 2026-10-23）：Stars 10,710、Forks 773、Open Issues 35、Watch 53，最近一次代码推送 2026-10-23（与查询日期同日，说明仓库处于高频活跃状态）
• 版本节奏（GitHub Releases 时间线实查，查询日期 2026-10-23）：v1.48.0（2026-06-10）→ v1.48.1（2026-06-11）→ v1.49.0（2026-06-29）→ v1.50.0（2026-07-07）→ v1.51.0（2026-07-27）→ v1.52.0（2026-08-26）→ v1.52.1（2026-08-27）→ v1.53.0（2026-09-08）→ v1.54.0（2026-10-06）→ v1.55.0（2026-10-07）。近五个月连续发布 10 个版本，平均每月约 2 版，迭代节奏快且稳定，均无 pre-release
• 开源许可证：AGPL-3.0（平台主体，仓库 LICENSE 与 README 实查）；配套 Agent 工具（CLI、MCP Server、Agent SDK）为独立仓库、MIT 许可（README 实查，查询日期 2026-10-23）

二、软件概述

2.1 定位与身份

Lago 是一款开源的计量计费与用量计费平台，处于「产品使用量」与「收入」之间的可编程层。官方对其数据流的概括（README 实查，查询日期 2026-10-23）：

Usage events -> Metering -> Pricing and credits -> Entitlements -> Invoices -> Payments -> Revenue

即：应用发出用量事件 → Lago 实时计量 → 按定价模型折算费用并扣减预充值 → 校验功能权益 → 生成账单发票 → 对接收款 → 沉淀收入分析。产品、财务、运营团队可直接使用 Lago Web 界面，应用与智能体则通过 REST API、SDK、Webhook 与 MCP 接口操作同一套计费原语——官方称之为「headless、API-first」。

Lago 主打的使用场景（README 实查）：

• 按 token 计量的 AI 产品计费：可按模型、输入/输出 token、缓存 token、推理 token、工具调用等维度分别定价；
• 算力类用量计费：GPU、CPU、存储等资源消耗；
• API 调用、事务数、席位、活跃用户等自定义事件计量；
• 预充值积分（Prepaid Credits）与自动充值；
• 带额度、最低承诺与超额计费的订阅；
• 自助套餐与企业议价合同共存于同一系统。

💡 技术拓展：「计量计费（Usage-Based / Metering Billing）」与传统「订阅计费（Subscription Billing）」是现代计费系统的两大范式，常见同类产品对比——

范式	计费触发方式	典型产品	适用场景
订阅计费	按周期固定资费 + 升降级按比例折算	Kill Bill、Chargebee	SaaS 按月/年收费、席位制
用量计费	按实际消耗事件实时计量、周期出账	Lago、Metronome、OpenMeter	AI 按 token、云资源按量、API 按调用
混合计费	订阅底价 + 用量超额 + 预充值抵扣	Lago（hybrid charges）、Stripe Billing	最低承诺 + 超量付费的企业合同

Lago 的定位以用量计费为主、订阅与预充值能力齐备，官方将其计费定价模型归纳为 usage-based、recurring、prepaid、percentage、graduated、package、volume、minimum-commitment 与 hybrid 九类（README Platform 表实查）。

2.2 两种运营形态：Lago Direct 与 Lago Embedded

同一套 Lago 引擎支持两种运营模式（README 实查，查询日期 2026-10-23）：

两种模式都以 Lago 开源计费引擎为起点，可叠加官方付费的部署、定制、安全与支持服务。这一「核心开源 + 云服务与高级功能商业化」的结构，与大多数开源计费产品一致。

2.3 发展历程与商业化背景

• 主仓库创建于 2022 年 2 月（GitHub 元数据实查），五年间迭代到 v1.55.0，版本号演进密集；
• 官方 README 披露的规模化客户与数据（README 实查，查询日期 2026-10-23；公司经营数据来源以 README 所附外链为准）：Mistral AI（token 计量、预充值积分、发票、税费与收款）、Groq、Blacksmith（CI 算力用量计费）、Synthesia、PayPal（嵌入式用量计费）；README 称 Lago 每月开具约 8.29 亿美元发票；
• 官方对 Lago 与支付处理的关系定位：Lago 只负责计量与定价，不做支付通道，对接 Stripe、Adyen、GoCardless 等支付服务商完成扣款，避免支付商的产品目录成为计费事实源（README「How Lago fits into your stack」节实查）。

三、核心架构

3.1 总体架构：Rails API + Sidekiq Worker + Clock + 前端

Lago 服务端核心是 Ruby on Rails 应用（官方仓库 docs/architecture.md 实查，查询日期 2026-10-23；语言构成经 GitHub API 复核：getlago/lago-api 子模块 Ruby 约 22.7MB，getlago/lago-front 子模块 TypeScript 约 21.1MB）：

• 主 API：接收 REST 请求，把大部分工作量以 Sidekiq 任务投递到 Redis 队列异步处理；
• Sidekiq Worker：后台任务执行器，默认按优先级顺序消费 11 个队列——high_priority、default、mailers、clock、providers、webhook、invoices、wallets（已弃用，任务迁移至其他队列）、integrations、low_priority、long_running；并发默认 10（生产环境可由 SIDEKIQ_CONCURRENCY 调整）、任务超时 25 秒；
• Clock 进程：基于 Clockwork 的独立定时调度器（启动命令 bundle exec clockwork ./clock.rb），负责激活订阅、刷新草稿发票、终到期订阅、月度出账、逾期标记、钱包余额刷新等数十项周期任务；
• 前端：独立的 React/TypeScript 单页应用（getlago/front 镜像内含 Nginx 静态托管），供产品、财务、运营人员操作计费目录、客户、订阅、发票与收入报表。

官方支持为重负载任务启用「专用 Worker」：通过 SIDEKIQ_EVENTS、SIDEKIQ_PDF、SIDEKIQ_WEBHOOK、SIDEKIQ_BILLING、SIDEKIQ_ALERTS、SIDEKIQ_ANALYTICS、SIDEKIQ_PAYMENTS、SIDEKIQ_CLOCK、SIDEKIQ_AI_AGENT 等环境变量把对应任务路由到独立队列与独立进程，实现按任务类型的独立扩缩容（architecture.md「Dedicated Workers」节实查）。

3.2 数据与中间件栈

官方 Docker Compose 编排（主仓库 v1.55.0 标签 docker-compose.yml 实查，查询日期 2026-10-23）使用的组件与版本：

Redis 在 Lago 内部承担三种独立职责（architecture.md「Redis Architecture」节实查），官方支持用 Sentinel 高可用、并把连接地址与密码分离配置：

1. Primary Redis：Sidekiq 任务队列存储（REDIS_URL / REDIS_PASSWORD）；
2. Redis Cache：Rails 应用缓存（钱包余额、计算中间值等，LAGO_REDIS_CACHE_URL）；
3. Redis Store：事件处理专用存储（LAGO_REDIS_STORE_URL，事件数据与订阅刷新队列）。

💡 技术拓展：出站 Webhook 的防篡改签名，Lago 支持两种算法（architecture.md「Webhook Signing」节实查，按 webhook endpoint 逐个配置）——

算法	密钥类型	原理	适用场景
HMAC（signature_algo: :hmac）	对称密钥（组织级 hmac_key）	HMAC-SHA256 摘要，签名放 X-Lago-Signature 头	接收端可拿到密钥即可验签，配置简单
JWT（signature_algo: :jwt）	非对称密钥（平台 RSA 私钥）	RS256 签发 JWT，接收端用公钥离线验签	接收端不应持有私钥、需多方验签

对称方案实现成本低但密钥需两端共享；非对称方案私钥不出服务器、公钥可分发。Lago 实际同时内置两者，按接收端逐一选择。

3.3 高容量事件管线：Go 事件处理器 + Kafka + ClickHouse

对于超高事件量场景，Lago 提供独立于 Sidekiq 的事件处理管线（主仓库 events-processor/ 目录与 docs/architecture.md 实查）：

• events-processor：Go 编写的专用事件处理器（父仓库内 Go 代码的主体），从 Kafka 等消息队列消费事件并做聚合处理；
• connectors：官方提供 HTTP、AWS SQS、Kinesis 三种事件接入连接器配置；
• ClickHouse：仓库 extra/clickhouse/ 提供配套配置，用作事件分析存储；
• 该管线与 Sidekiq 体系并行：普通规模直接走 Sidekiq 队列，大规模事件流可切换为 Kafka 消费架构。Go 事件处理器当前不支持 Redis Sentinel（architecture.md 明确注记）。

3.4 安全与加密设计

Lago 的分层加密与签名机制（architecture.md「Encryption & Security」节实查，查询日期 2026-10-23）：

• Active Record 加密（数据库行级）：使用 LAGO_ENCRYPTION_PRIMARY_KEY、LAGO_ENCRYPTION_DETERMINISTIC_KEY、LAGO_ENCRYPTION_KEY_DERIVATION_SALT 三个密钥参数，加密集成凭据、支付服务商 API Key 等落库敏感数据，采用非确定性加密（官方注明 Lago 不使用确定性加密）；
• HMAC 组织级签名：每个组织有独立 hmac_key，用于 HMAC-SHA256 签发 Webhook；
• RSA 非对称签名：LAGO_RSA_PRIVATE_KEY（部署时必须生成）用于 JWT RS256 Webhook 签名；
• SECRET_KEY_BASE：Rails 主签名密钥，用于会话签名、防篡改 URL 与请求校验；
• 合规与认证：官方声明 Lago 通过 SOC 2 Type II 认证，并支持需要基础设施与数据管控的团队自托管（README「Production characteristics」节实查）。

3.5 官方生产资源配置参考

官方基于高负载生产集群数据给出了资源配置建议（docs/architecture.md「Resource Configuration Guide」节实查，查询日期 2026-10-23，为 Kubernetes 生产形态数据，可作容量规划参考）：

官方「最小生产形态」：API×2（1 核 2Gi）、默认 Worker×2（500m 1Gi）、Clock×1（100m 512Mi）、前端×1（100m 128Mi）；规模化后按 PDF → Webhook → Events → Billing 的顺序逐步启用专用 Worker（architecture.md「Minimal Production Setup」节实查）。

四、功能特性

4.1 平台能力总览

官方 README Platform 表完整列出平台分层能力（查询日期 2026-10-23）：

4.2 数据可靠性与生产特性

README「Production characteristics」节逐条列出（查询日期 2026-10-23）：

• 幂等接入：事件按 transaction_id 去重，重试不会重复计费——这是计费系统最关键的可靠性承诺；
• 原子批量：批量事件中若有一条非法，整批拒绝、全部不落库，避免半批入账；
• 异步处理：事件、计费、支付、发票、Webhook、PDF、告警、分析均可拆为独立 Worker，随量扩展；
• 可观测：暴露 Prometheus 指标，覆盖 API、队列、Worker、事件、计费、Webhook 与依赖项（官方 docs/monitoring.md）；
• 部署自由：可本地、自有云、自有基础设施运行，生产可独立伸缩有状态服务与 Worker。

4.3 Agentic-First 接口体系

2026 年版 Lago 把「面向智能体」作为一等公民能力（README「Agentic-first by design」表实查，查询日期 2026-10-23）：

官方同时给出四种语言 SDK：Node.js、Python、Ruby、Go（README「SDKs and developer resources」表实查）。

4.4 快速开始（官方最小示例）

以下为官方 README「Deploy Lago」节给出的自托管启动路径（原样转述，查询日期 2026-10-23；本文未实测，完整实测过程见本专栏部署篇）：

git clone --depth 1 https://github.com/getlago/lago.git
cd lago

echo "LAGO_RSA_PRIVATE_KEY=\"$(openssl genrsa 2048 | openssl base64 -A)\"" >> .env
docker compose up -d

官方说明：该编排会启动与当前检出版本一致的 Lago 服务栈；.env 中必须提供 LAGO_RSA_PRIVATE_KEY（用于 Webhook 的 JWT 签名）；前端默认 http://localhost:80，API 默认 http://localhost:3000。更大规模部署官方提供 Helm Charts（getlago/lago-helm-charts）与专用 Worker 配置指引。

💡 说明：官方 README 还维护了一个「AI 计费演示」脚本 ./examples/agentic-ai-demo/run.sh，其官方示例输出为——3 次 AI 请求、5,000 输入 token × $0.000002 + 1,250 输出 token × $0.000008，合计 $0.02；用于在本地完整演示「事件 → 计量 → 计价 → 账单」闭环。演示凭据为一次性本地凭据，不访问 Lago Cloud（README 实查）。

五、适用场景与限制

5.1 适用场景

• AI 产品计费（Lago 的 2026 年主打场景）：按模型/输入/输出/缓存 token 分别定价，配合预充值积分与自动充值；
• API 与开发者产品：按调用次数、事务数阶梯或打包计价；
• 算力/资源型服务：GPU 时长、CI 构建、存储用量计费（Blacksmith 案例）；
• 平台型业务：用 Lago Embedded 给平台客户提供白标计费（PayPal 案例）；
• 混合模式企业合同：订阅底价 + 最低承诺 + 用量超额 + 议价折扣共存。

5.2 限制与注意事项

• AGPL-3.0 许可：平台主体为 AGPLv3，对「修改后作为网络服务提供」的场景有开源传染义务；商用前需评估合规边界。官方另有博客《Why Lago chose AGPLv3》说明动机（README License 节实查）；
• 技术栈偏重：Rails + Sidekiq + PostgreSQL + Redis + Gotenberg 的完整栈在小规格机器上有明显资源开销（官方生产参考中仅 API 单副本即建议 4 核 4Gi），1C1G 规格不适合；
• 单机 Compose 形态无高可用：官方 docker-compose 适合评估与小规模生产，规模化需转 Helm/Kubernetes 并拆分专用 Worker；
• 高级能力闭源边界：Billing Assistant、部分企业集成、嵌入式场景属于付费能力，开源版不含；
• 自托管默认开启产品分析：README「Analytics and tracking」节明确自托管实例默认收集基础产品分析（官方声明不包含客户 PII 与财务数据），可通过官方文档 guide/lago-self-hosted/tracking-analytics 了解采集内容或关闭；
• Redis Sentinel 支持不完全：Go 事件处理器暂不支持 Sentinel（architecture.md 注记）。

六、同类选型对比

6.1 量化对比表

对比对象：同批已交付的开源订阅计费平台 Kill Bill、开源计量平台 OpenMeter、闭源商业用量计费 SaaS Metronome。数据来源与查询日期：Lago 与 OpenMeter 取自 GitHub API（2026-10-23），Kill Bill 数据取自本站《Kill Bill 0.24.22 介绍与选型指南》（shields.io 徽章接口，查询日期 2026-10-23），版本节奏取自各自 GitHub Releases 与 Docker Hub 时间线（2026-10-23）。

6.2 解读与选型建议

1. 按计费范式选：核心诉求是「按用量收费」（token、调用、算力）——Lago 与 Metronome 是同赛道；纯「订阅制收费」且需要深度账务（审计、逾期催收、分级税务）——Kill Bill 更成熟；只需要「把海量事件聚合成用量数据」、账单层自建——OpenMeter 的计量定位最轻。详见本站 《Kill Bill 0.24.22 介绍与选型指南》的选型章。
2. 星数 ≠ 计费深度：Lago 星数（10.7k）约为 Kill Bill（5.8k）的两倍，但 Kill Bill 自 2010 年代持续迭代，订阅状态机、催收与账务成熟度是其护城河；Lago 2022 年起步，胜在用量计费的原生设计、活跃的月均双版迭代与 Agentic 接口体系。
3. 按许可证合规选：Apache-2.0（Kill Bill、OpenMeter）对商用修改友好；AGPL-3.0（Lago）要求修改后网络服务同样开源，SaaS 化二次开发需法务评估。
4. 按运维复杂度选：三者自托管都以 Docker Compose 为最低门槛。Lago 的组件最多（API/Worker/Clock/前端/PDF/PostgreSQL/Redis），资源门槛最高，但也提供了最细粒度的 Worker 拆分能力；小团队起步建议直接用官方 Compose 三档形态中的 local 档，规模化再转 Helm。
5. 按生态与集成选：需要支付编排与 ERP/CRM 深度集成——Kill Bill 生态偏「电商订阅」；需要 AI 原生工具链（MCP Server、Agent SDK、按 token 定价模板）——Lago 当前最完整；Metronome 适合完全不想运维计费系统、预算充足的团队。

七、参考链接

• Lago 官网：https://www.getlago.com
• 官方文档站：https://doc.getlago.com
• 主仓库（v1.55.0 标签）：https://github.com/getlago/lago
• Releases 页：https://github.com/getlago/lago/releases
• Docker Hub（API 组件）：https://hub.docker.com/r/getlago/api
• 官方自托管部署指南：https://doc.getlago.com/guide/lago-self-hosted/docker
• OpenAPI 规范仓库：https://github.com/getlago/lago-openapi
• Lago CLI 仓库：https://github.com/getlago/lago-cli
• MCP Server 仓库：https://github.com/getlago/lago-agent-toolkit
• Helm Charts：https://github.com/getlago/lago-helm-charts
• AGPLv3 许可动机官方博客：https://www.getlago.com/blog/open-source-licensing-and-why-lago-chose-agplv3
• 本站关联文档：《Kill Bill 0.24.22 介绍与选型指南》