Lago 1.55.0 常用 CLI 命令详解

目标：系统掌握 Lago 1.55.0 服务端运维工具链——bundle exec rake 任务体系（诊断、迁移、数据修复）与 bundle exec rails 管理命令（路由表、一次性脚本、迁移状态），全部命令在 Ubuntu 22.04 实测环境逐条执行并回显；另附 v1.55.0 lago:version 任务崩溃的排障实录。部署与配置背景见《Lago 1.55.0 Docker Compose 部署指南》与《Lago 1.55.0 配置参数详解》。

一、环境信息

操作系统：Ubuntu 22.04（x86_64）
Lago 版本：v1.55.0（诊断报告实测确认：Lago version : v1.55.0）
运行时栈（诊断报告实测回显）：Ruby 4.0.7（x86_64-linux-gnu）、Rails 8.0.5.1、PostgreSQL 15.0、Redis 7.4.11、Rake 13.4.2、Bundler 4.0.19
执行位置：部署目录 /opt/lago/stack/，命令经 docker compose exec api <命令> 送入 Lago 后端应用运行环境执行（下文命令块均省略该前缀写法说明，按完整形态给出）
应用数据库：lago（182 张业务表、1188 条已执行迁移记录，见 5.3 节实测）
示例管理员：admin@lago.local / q1w2e3r4

二、工具概览

Lago 服务端没有独立的 /usr/bin/lago 式命令行程序，运维工具链由 Ruby on Rails 标准任务体系构成，实测环境可用工具如下：

工具	形态	典型用途
`bundle exec rake <task>`	Rake 任务	自托管诊断（lago:diagnostics）、数据库迁移（db:）、数据修复回填（events: / invoices:* / customers:* 等）
`bundle exec rails <command>`	Rails 命令	路由表（routes）、一次性脚本（runner）、迁移状态（db:migrate:status）、交互式控制台（console）与数据库终端（dbconsole）
`LAGO_ORG_*` + seeding	首启任务	自动建组织（配置参数篇 5.4 节已实测）

💡 说明：Lago 官方另提供一个面向 REST API 的终端客户端 Lago CLI（独立仓库 github.com/getlago/lago-cli，MIT 许可），用于在任意终端调 API 编排计费资源；它不属于服务端安装产物，本文聚焦服务端自带工具链。两类工具的分界：改服务端状态（迁移/修复/诊断）用本文的 rake/rails，调业务接口（建客户/订阅/发票）优先走 API。

三、前置条件

已按部署指南完成 Lago 1.55.0 安装，api 实例处于 healthy 状态：

cd /opt/lago/stack && docker compose ps api

NAME       IMAGE                COMMAND                   SERVICE   CREATED         STATUS                    PORTS
lago-api   getlago/api:v1.55.0  "./scripts/start.api…"   api       9 minutes ago   Up 9 minutes (healthy)   0.0.0.0:8129->3000/tcp, [::]:8129->3000/tcp

本文所有命令的执行形态：在部署目录内通过 docker compose exec api 进入应用运行环境执行 rake/rails 命令，例如：

cd /opt/lago/stack
docker compose exec api bundle exec rake lago:diagnostics

任务执行会真实读写生产数据库，破坏性任务（第六章红线表）执行前必须备份。

四、rake 任务体系详解

4.1 任务清单总览（rake -T）

列出全部 Rake 任务：

docker compose exec api bundle exec rake -T

输出共 103 条任务（实测 rake -T | wc -l），按命名空间统计（实测）：

命名空间	任务数	代表任务
db	23	db:migrate、db:rollback、db:seed、db:prepare
migrations	11	迁移辅助（维护 pg_partman 分区等）
recipes	8	数据迁移菜谱（ClickHouse 事件存储切换等）
invoices	5	发票修复（fill_customer、generate_number 等）
action_mailbox / action_text / active_storage	10	Rails 组件安装辅助
upgrade / graphql / events / filters / customers / subscriptions / entitlements / cache / coupons 等	33	数据修复回填与特性辅助
lago	2	lago:diagnostics、lago:version

清单节选（实测原文）：

rake cache:expire_subscription_cache        # Expire cache for a given subscription
rake coupons:fill_expiration_date           # Populate expiration_date for coupons
rake customers:generate_slug                # Generate Slug for Customers
rake db:migrate                             # Migrate the database (options: VERSION=x, VERBOSE=false, SCOPE=blog)
rake db:migrate:redo                        # Roll back the database one migration and re-migrate up (options: STEP=x, VERSION=x)
rake db:migrate:status                      # Display status of migrations
rake db:prepare                             # Run setup if database does not exist, or run migrations if it does
rake db:rollback                            # Roll the schema back to the previous version (specify steps w/ STEP=n)
rake db:seed                                # Load the seed data from db/seeds.rb
rake events:fill_subscription               # Fill missing subscription_id
rake events:fill_timestamp                  # Fill missing timestamps for events
rake events:reprocess                       # Detect and optionally reprocess events for subscriptions needing re-enrichment
rake invoices:fill_customer                 # Fill missing customer_id
rake invoices:generate_number               # Generate Number for Invoices
rake lago:diagnostics                       # Print a diagnostic report for self-hosted deployments
rake lago:version                           # Print the current version of Lago

4.2 lago:diagnostics：自托管诊断报告（核心运维命令）

一条命令产出十节自检报告，是排查自托管 Lago 的第一入口：

docker compose exec api bundle exec rake lago:diagnostics

实测输出节选（完整报告约 320 行，以下按节摘录实测原文）：

========================================================================
  LAGO DIAGNOSTICS
  Generated : 2026-10-23T19:07:16Z
========================================================================

  1. VERSION AND BUILD
  Lago version   : v1.55.0
  Commit SHA     : (not available, version tag build)
  Build date     : 2026-10-23T18:36:16Z

  2. ENVIRONMENT
  Ruby           : 4.0.7 (x86_64-linux-gnu)
  Rails          : 8.0.5.1
  Deployment     : docker/container
  Memory limit   : unlimited
  CPU quota      : unlimited

  4. DATABASE
  PostgreSQL     : PostgreSQL 15.0 on x86_64-pc-linux-musl
  DB schema ver  : 20261006134840

  ## DB Connection Pool
    size: 10
    connections: 1
    busy: 1
    dead: 0
    idle: 0
    waiting: 0
    checkout_timeout: 5.0

  ## Migrations
    Pending migrations        : none

  5. REDIS
  Redis          : 7.4.11

  ## Redis Memory
    used_memory_human: 1.81M
    used_memory_peak_human: 2.00M
    maxmemory_human: 0B

  ## Sidekiq Queues
    clock                  size=0        latency=0.00s

  Retry set size : 0
  Dead set size  : 0

  ## Sidekiq Processes
    Running workers : 1
    502ece172539 pid=1 concurrency=10 busy=0 beat=2026-10-23T19:07:16Z queues=high_priority,default,mailers,clock,providers,webhook,invoices,integrations,low_priority,long_running

  ## Sidekiq Stats
    processed: 50
    failed: 0
    enqueued: 0

  8. SMTP
  Enabled        : false

  9. DATA SHAPE
  ## Key Table Row Counts (estimated)
    Organizations   : 1
    Customers       : 0
    Subscriptions   : 0
    Invoices        : 0
    Fees            : 0
    Charges         : 0
    Events          : 0

  10. RECENT ERRORS
  Logs go to stdout (RAILS_LOG_TO_STDOUT=true), not to /app/log/production.log.
  Check the container logs via:
    docker logs <container>
    kubectl logs <pod> -n <namespace>

========================================================================
  END OF DIAGNOSTIC
========================================================================

报告逐节用途：第 1–2 节确认版本与运行时基线；第 3 节回显全部环境变量（敏感项自动打码为 ***，可安全贴到工单）；第 4 节数据库版本、schema 版本、连接池水位与待执行迁移；第 5 节 Redis 内存、Sidekiq 队列延迟（latency 超过数秒即积压）与死信队列；第 6–8 节 ClickHouse/Kafka/SMTP 三大可选组件的启用状态；第 9 节核心表行数与近 24 小时摄入速率；第 10 节指向日志出口。日常巡检关注四项：Pending migrations、Sidekiq latency、Dead set size、连接池 waiting。

4.3 lago:version：v1.55.0 实测崩溃排障实录

rake -T 声称该任务打印版本号，实测在 v1.55.0 直接崩溃：

docker compose exec api bundle exec rake lago:version

rake aborted!
NoMethodError: undefined method 'migration_context' for an instance of ActiveRecord::ConnectionAdapters::PostgreSQLAdapter (NoMethodError)

      schema_version: ApplicationRecord.connection.migration_context.current_version
                                                  ^^^^^^^^^^^^^^^^^^
/app/lib/tasks/lago.rake:9:in 'block (2 levels) in <main>'
Tasks: TOP => lago:version
(See full trace by running task with --trace)

定位：任务源码 /app/lib/tasks/lago.rake 第 9 行调用 connection.migration_context.current_version，该内部 API 在本版本捆绑的 Rails 8.0.5.1 + ActiveRecord 组合中已不存在（v1.55.0 引入的回归缺陷），与部署配置无关——任何 v1.55.0 实例执行该任务都会复现。

解决方案（替代取值途径，均实测）：

# 方案一：健康端点（含版本号）
curl -s http://localhost:8129/health

{"version":"v1.55.0","github_url":"https://github.com/getlago/lago-api/tree/v1.55.0","message":"Success"}

# 方案二：诊断报告第 1 节（4.2 节实测：Lago version : v1.55.0）
docker compose exec api bundle exec rake lago:diagnostics | head -8

⚠️ 注意：升级到 v1.55.0 之后的版本时，可重试 lago:version 验证官方是否已修复；在 v1.55.0 上请直接使用健康端点取版本号。

4.4 数据库迁移族（db:*）

升级 Lago 版本后由编排的 migrate 服务自动执行增量迁移；手工场景下常用任务与实测：

docker compose exec api bundle exec rails db:migrate:status | head -6

database: lago

 Status   Migration ID    Migration Name
   up     20261005112941  Add pending started at index to contracts
   up     20261006134840  Make x402 settlement uniqueness global

实测全表 1192 行（db:migrate:status | wc -l），1188 条迁移全部 up，与诊断报告 Pending migrations: none 一致。常用迁移任务速查（rake -T 原文）：

任务	作用
`db:migrate`（可带 `VERSION=x`）	执行待迁移；回退到指定版本
`db:migrate:status`	迁移状态清单（本节实测）
`db:rollback`（可带 `STEP=n`）	回滚最近 n 个迁移
`db:migrate:redo`	回滚并重放
`db:prepare`	库不存在则初始化，存在则迁移

⚠️ 注意：db:rollback/db:migrate:redo 属危险操作，Lago 生产库含分区表与加密列，回滚可能导致数据不可逆；生产排障以「前滚修复」为原则，回滚仅限迁移本身失败的场景。

4.5 数据修复与回填任务族

Lago 为升级兼容与异常自愈提供了一批幂等修复任务，均为「补齐缺失字段/重算派生数据」性质，实测清单（rake -T 原文）：

任务	修复内容
`events:fill_subscription`	补齐事件缺失的 subscription_id
`events:fill_timestamp`	补齐事件缺失时间戳
`events:reprocess`	检测并可选重处理需再富化的事件
`events:recover_pay_in_advance_fees`	恢复未后处理的预付费费用
`invoices:fill_customer` / `invoices:fill_taxes_rate` / `invoices:fill_expected_finalization_date` / `invoices:generate_number`	发票字段补齐与编号重生成
`customers:generate_slug` / `customers:backfill_eu_auto_taxes[organization_id]`	客户 slug 生成 / 欧盟自动税率回填
`coupons:fill_expiration_date`	优惠券过期日补齐
`cache:expire_subscription_cache` / `cache:remove_group_usage_cache`	订阅用量缓存失效清理
`recipes:clickhouse:enable_clickhouse_events_store`	交互式把组织事件存储切换到 ClickHouse（官方提供的安全切换菜谱）

带 [参数] 的任务需传入组织 ID 等实参（方括号写法即 rake 传参语法），执行前先用 rails runner 查得实参（见 5.2 节）。

五、rails 管理命令详解

5.1 rails routes：路由表审计

docker compose exec api bundle exec rails routes

实测输出 659 行。按业务域过滤审计（示例：organizations 相关路由实测）：

docker compose exec api bundle exec rails routes | grep -i organization

                         api_v1_organizations GET    /api/v1/organizations(.:format)          api/v1/organizations#show
                                              PUT    /api/v1/organizations(.:format)          api/v1/organizations#update
              api_v1_organizations_grpc_token GET    /api/v1/organizations/grpc_token(.:format)  api/v1/organizations#grpc_token
                         api_v2_organizations GET    /api/v2/organizations(.:format)          api/v1/organizations#show
                                              PUT    /api/v2/organizations(.:format)          api/v1/organizations#update
              api_v2_organizations_grpc_token GET    /api/v2/organizations/grpc_token(.:format)  api/v1/organizations#grpc_token

用途：对接 Webhook 前核实回调路径（/webhooks/stripe/:organization_id 等 6 个支付商路由）；安全审计时确认无预期外的公开写路由（如配置参数篇实测确认 v1.55.0 开源版无公开注册端点）。

5.2 rails runner：一次性运维脚本

在应用运行环境直接执行 Ruby 片段，适合快速查数与取实参（实测）：

docker compose exec api bundle exec rails runner 'puts "orgs=" + Organization.count.to_s; puts "org_name=" + Organization.first.name.to_s'

orgs=1
org_name=Main

💡 说明：runner 与 rails console 同源（console 是交互式 runner），差别仅在于是否保持会话；批量修复任务执行前，推荐先以 runner 只读查询确认影响面。注意 runner 会启动完整 Rails 应用，生产大实例上启动需数十秒，不宜放监控轮询。

5.3 交互式终端（console / dbconsole）

docker compose exec api bundle exec rails console      # Rails 控制台（完整应用上下文）
docker compose exec api bundle exec rails dbconsole    # 直连 PostgreSQL 的 psql 终端

二者为交互式会话，本文以 runner/routes 等非交互命令为主；dbconsole 等价于以 DATABASE_URL 凭据进入 psql，与部署指南中 psql -U lago -d lago 的核验路径同源。

六、注意事项（破坏性任务红线）

以下任务实测存在于任务清单，会清空或重建数据，生产环境执行前必须备份 PostgreSQL 数据卷：

任务	危险动作
`db:reset`	删库重建并灌 seed
`db:truncate`	清空全部业务表（保留迁移状态）
`db:seed:replant`	清空后重灌 seed
`db:rollback` / `db:migrate:redo`	回滚已执行迁移（见 4.4 节）
`recipes:clickhouse:enable_clickhouse_events_store`	切换组织事件存储（虽为官方菜谱，切换前必须完成事件回填核验）

其余注意事项：

所有 rake/rails 命令都在应用运行环境执行（第三章形态），直接在宿主机执行会报 bundle: command not found；
诊断报告对环境变量敏感值自动打码（***），但会显示 URL 中的主机与端口，外发工单时无需手工脱敏主机名以外的内容；
任务启动时间与 Rails 应用一致（数十秒级），脚本化调用建议设置 ≥120 秒超时。

七、常见问题

Q1：rake lago:version 报 NoMethodError 是我部署坏了吗？ 不是。4.3 节实测定位为 v1.55.0 任务源码与捆绑 Rails 8.0.5.1 的 API 兼容性回归，属版本自身缺陷；用健康端点或诊断报告取版本号即可，升级新版本后可复查。

Q2：rake 任务执行到一半连接数据库超时？ 先看诊断报告第 4 节连接池：waiting > 0 说明池已耗尽。任务会临时占用 1 个连接，与业务高峰叠加时可能等待超时（默认 checkout_timeout 5.0 秒）；低峰执行或临时调大 DATABASE_POOL（需重启实例生效，见配置参数篇）。

Q3：如何确认某条修复任务是否已经跑过/是否需要再跑？ 修复任务均幂等（重复执行无副作用），无法从迁移状态表判断；用 rails runner 查目标字段是否仍有空值（如 Event.where(subscription_id: nil).count），为 0 即无需再跑。

Q4：Sidekiq 队列积压怎么从命令行确认？ 诊断报告第 5 节 ## Sidekiq Queues 逐队列给出 size 与 latency（实测正常态 clock size=0 latency=0.00s）；latency 持续增长表示任务消费不及时，按配置参数篇 5.6 节拆专用 Worker。

八、参考链接

官方自托管文档（诊断与维护）：https://doc.getlago.com/guide/lago-self-hosted/docker
官方仓库任务源码位置：https://github.com/getlago/lago（服务端任务定义于 api 子模块 lib/tasks/）
Lago CLI 独立仓库：https://github.com/getlago/lago-cli
本站关联文档：《Lago 1.55.0 介绍与选型指南》、《Lago 1.55.0 Docker Compose 部署指南》、《Lago 1.55.0 配置参数详解》