Lago 1.55.0 Docker Compose 部署指南

在 Ubuntu 22.04 服务器上以官方 Docker Compose 编排从零部署 Lago 1.55.0 计量计费平台：8 服务拓扑、密钥生成与 .env 配置、首启自动初始化、数据持久化与销毁重建恢复闭环及 one-click 单命令形态实测。

LagoLago用量计费自托管2026/10/24

Lago 1.55.0 Docker Compose 部署指南

目标：在 Ubuntu 22.04 服务器上，用官方 Docker Compose 编排从零部署 Lago 1.55.0 开源计量计费平台，覆盖服务拓扑、密钥生成、.env 配置、首启自动初始化、数据持久化与销毁重建恢复闭环。全部命令与回显均在 Ubuntu 22.04（内核 x86_64，Docker 28+ / Docker Compose v2）实测通过；产品定位与选型背景见 《Lago 1.55.0 介绍与选型指南》。

一、环境信息

本次部署实测环境与关键信息如下：

  • 操作系统：Ubuntu 22.04（x86_64）
  • Docker：Docker Engine 28.x + Docker Compose v2（docker compose 子命令形态）
  • Lago 版本：v1.55.0（2026-10-07 发布的官方最新稳定版）
  • 编排来源：官方仓库 getlago/lago v1.55.0 标签的 docker-compose.yml
  • 部署目录：/opt/lago/stack/（含 docker-compose.yml 与 .env 两个文件）
  • 服务端口规划：API 8129、Web 前端 8130、PostgreSQL 8137、Redis 8146（均为宿主机端口，可按需修改）
  • 部署后服务拓扑：8 个服务（db、redis、migrate、api、api-worker、api-clock、front、pdf），其中 6 个常驻运行，migrate 初始化完成后退出
  • 示例管理账号：admin@lago.local / q1w2e3r4（由首启自动创建，见 4.5 节）

二、镜像选型说明

官方 docker-compose.yml 引用 5 个镜像，全部来自 Docker Hub 官方仓库（getlago 组织），版本对应关系实测如下：

服务镜像与标签大小（实测）角色
api / api-worker / api-clock / migrategetlago/api:v1.55.0692MB同一镜像的四种启动形态（API 服务、后台任务 Worker、定时调度 Clock、数据库迁移），见 4.4 节说明
frontgetlago/front:v1.55.0195MBReact 管理界面（Nginx 静态托管）
dbgetlago/postgres-partman:15.0-alpine328MBPostgreSQL 15 + pg_partman 分区扩展（Lago 定制构建，事件表按时间分区依赖它）
redisredis:7-alpine57.8MBSidekiq 任务队列 + Rails 缓存
pdfgetlago/lago-gotenberg:7.8.22.31GB官方重打包的 Gotenberg，发票/贷记单 PDF 渲染

💡 说明：getlago/postgres-partman:15.0-alpine 不是社区原版 postgres:15-alpine——Lago 的事件存储在 PostgreSQL 内大量使用 pg_partman 做原生时间分区，官方将该扩展预置进镜像；换用原版镜像会导致建库迁移失败。镜像版本与 Lago 版本的对应关系以官方仓库 docker-compose.yml 为准，官方明确建议避免使用 latest 标签（见官方自托管文档 Version 一节），本文全部锁定 v1.55.0。

选型建议：评估与小规模生产直接用上表官方组合；生产化时官方建议自带 PostgreSQL 与 Redis（移除编排中的 db、redis 两个服务，改连外部实例），API/Worker/Clock 仍用 getlago/api 镜像按需扩副本。

三、前置条件

  1. 服务器已安装 Docker Engine 与 Docker Compose v2，验证命令与实测回显：
docker --version && docker compose version

Docker version 28.1.1, build 4eba374
Docker Compose version v2.35.0
  1. 服务器可访问 Docker Hub（拉取镜像约 3.5GB；国内网络慢时可为 Docker 守护进程配置镜像加速或 HTTP 代理）。
  2. 端口规划确认：本示例使用 8129/8130/8137/8146 四个宿主端口，部署前确认未被占用：
ss -ltn | grep -E ':(8129|8130|8137|8146)\b' || echo 'ports free'

ports free
  1. 磁盘余量 ≥ 8GB（镜像 3.5GB + 数据卷与日志余量）。

四、部署步骤

4.1 获取官方编排文件

从官方仓库 v1.55.0 标签取 docker-compose.yml（锁定版本，避免 main 分支漂移）：

mkdir -p /opt/lago/stack && cd /opt/lago/stack
wget -O docker-compose.yml https://raw.githubusercontent.com/getlago/lago/v1.55.0/docker-compose.yml

--2026-10-24 03:00:12--  https://raw.githubusercontent.com/getlago/lago/v1.55.0/docker-compose.yml
Resolving raw.githubusercontent.com... 185.199.108.133
HTTP request sent, awaiting response... 200 OK
Length: 12504 (12K) [text/plain]
Saving to: 'docker-compose.yml'
docker-compose.yml                100%[=========================>]  12.21K  --.-KB/s    in 0.01s

该编排文件定义了 8 个服务，实测确认：

docker compose config --services

db
migrate
pdf
redis
api
api-clock
api-worker
front

💡 说明：8 个服务中 pdf 没有显式 container_name，其余 7 个在编排里固定命名；api、api-worker、api-clock、migrate 四个服务复用同一个 getlago/api:v1.55.0 镜像，仅启动脚本不同（start.api.sh / start.worker.sh / start.clock.sh / migrate.sh），这正是 Lago「一套 Rails 应用、多运行形态」的架构设计。

4.2 生成必备密钥

Lago 首次启动要求 .env 中必须提供 LAGO_RSA_PRIVATE_KEY（用于 Webhook 的 JWT 签名），官方同时建议替换全部默认密钥。逐条执行以下命令生成（生成结果直接写入 .env，无需手工复制）：

cd /opt/lago/stack
# 1. RSA 私钥（Webhook JWT 签名，必填）
echo "LAGO_RSA_PRIVATE_KEY=\"$(openssl genrsa 2048 | openssl base64 -A)\"" >> .env
# 2. Rails 会话签名密钥
echo "SECRET_KEY_BASE=$(openssl rand -hex 64)" >> .env
# 3. 数据库行级加密三件套
echo "LAGO_ENCRYPTION_PRIMARY_KEY=$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1)" >> .env
echo "LAGO_ENCRYPTION_DETERMINISTIC_KEY=$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1)" >> .env
echo "LAGO_ENCRYPTION_KEY_DERIVATION_SALT=$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1)" >> .env

本环境实测生成的密钥值（读者环境应自行生成，勿照抄本文密钥）：

SECRET_KEY_BASE=45e4802c2b5a99b0e5b811f4d03d18eb229fd0aaf1b48944b725f36266b379ca
LAGO_ENCRYPTION_PRIMARY_KEY=0cbac6ea4c2a772d41a712ee3269bd7dae1fc6235187a9cef263ca89b9b8363e
LAGO_ENCRYPTION_DETERMINISTIC_KEY=f5a84005228e6aad53a5a3867f62cea7e33257c29fa17b758e32e7e1441ff09a
LAGO_ENCRYPTION_KEY_DERIVATION_SALT=f707a5f7e5c482f627e0ec13ff894cd7350f5f999ffc31546903e9dfbf4533da

4.3 编写 .env 配置文件

在 /opt/lago/stack/.env 中补齐端口、数据库凭据与首启自动建组织配置。本环境完整 .env 实测内容如下（LAGO_RSA_PRIVATE_KEY 一行为 4.2 节命令自动写入的 base64 私钥，此处省略其超长值）：

# ---- 端口规划 ----
FRONT_PORT=8130
API_PORT=8129
POSTGRES_PORT=8137
REDIS_PORT=8146
# ---- 数据库凭据 ----
POSTGRES_USER=lago
POSTGRES_PASSWORD=q1w2e3r4
POSTGRES_DB=lago
# ---- Lago 核心密钥（4.2 节命令生成） ----
LAGO_RSA_PRIVATE_KEY="<4.2 节 openssl 命令生成的 base64 私钥>"
SECRET_KEY_BASE=45e4802c2b5a99b0e5b811f4d03d18eb229fd0aaf1b48944b725f36266b379ca
LAGO_ENCRYPTION_PRIMARY_KEY=0cbac6ea4c2a772d41a712ee3269bd7dae1fc6235187a9cef263ca89b9b8363e
LAGO_ENCRYPTION_DETERMINISTIC_KEY=f5a84005228e6aad53a5a3867f62cea7e33257c29fa17b758e32e7e1441ff09a
LAGO_ENCRYPTION_KEY_DERIVATION_SALT=f707a5f7e5c482f627e0ec13ff894cd7350f5f999ffc31546903e9dfbf4533da
# ---- 首启自动创建管理员组织 ----
LAGO_CREATE_ORG=true
LAGO_ORG_USER_EMAIL=admin@lago.local
LAGO_ORG_USER_PASSWORD=q1w2e3r4
LAGO_ORG_NAME=Main

逐项说明：

参数实测值作用
FRONT_PORT / API_PORT8130 / 8129Web 界面与 REST API 的宿主机端口
POSTGRES_PORT / REDIS_PORT8137 / 8146数据库与 Redis 的宿主机暴露端口（仅便于外部核验，应用内部走内网直连）
POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DBlago / q1w2e3r4 / lago编排内 PostgreSQL 的初始化账号、密码、库名；应用侧由编排拼接为 DATABASE_URL，无需单独设置
SECRET_KEY_BASE64 位 hexRails 会话签名密钥，更换后已登录会话全部失效
LAGO_ENCRYPTION_* 三项32 位随机串加密落库的第三方凭据（支付服务商 API Key 等）；⚠️ 上线后不可更换，否则已加密数据无法解密
LAGO_CREATE_ORG=true—首启迁移完成后自动创建管理员组织，免去手动注册
LAGO_ORG_USER_EMAIL / LAGO_ORG_USER_PASSWORD / LAGO_ORG_NAMEadmin@lago.local / q1w2e3r4 / Main自动创建的登录账号与组织名

4.4 启动服务栈

cd /opt/lago/stack
docker compose up -d

[+] Running 10/10
 ✔ Network lago-1550-stack_default    Created
 ✔ Volume "lago-1550-stack_lago_postgres_data"  Created
 ✔ Volume "lago-1550-stack_lago_redis_data"     Created
 ✔ Volume "lago-1550-stack_lago_storage_data"   Created
 ✔ Container lago-db      Healthy
 ✔ Container lago-redis   Healthy
 ✔ Container lago-migrate Exited
 ✔ Container lago-api     Healthy
 ✔ Container lago-worker  Healthy
 ✔ Container lago-front   Started

⚠️ 注意：编排内 name: lago-1.55.0-stack 会被 Compose 规范化为项目名 lago-1550-stack（点号被去除），所有数据卷、网络均以该前缀命名。若同时维护多套 Lago 环境，注意区分项目名避免误操作。

4.5 首启初始化机制（migrate 与自动建组织）

首次 up 时，migrate 服务先于应用启动：它执行数据库全量迁移（创建 182 张表）并运行 seeding，完成后即退出（退出码 0 属正常，不是故障）。实测首启迁移日志：

docker logs lago-migrate

Sidekiq Pro is not installed. Reliability features will not be available.
Sidekiq Pro is not installed. Reliability features will not be available.
Sidekiq Pro is not installed. Reliability features will not be available.
Sidekiq Pro is not installed. Reliability features will not be available.
"starting seeding environment"
"ending seeding environment"

初始化结果可从数据库侧核验：自动建组织开关生效，1 个组织、1 个管理员账号、1 个 API Key 已就位，业务表共 182 张：

docker exec lago-db psql -U lago -d lago -t -c "select count(*) from organizations;" \
  -c "select email from users;" -c "select value from api_keys;" \
  -c "select count(*) from information_schema.tables where table_schema='public';"

     1

 admin@lago.local

 6dcdbc79-9ce2-4f47-8146-9efdb1064968

   182

💡 说明：Sidekiq Pro 提示为开源版正常输出（Sidekiq Pro 是商业版任务可靠性组件，开源版不含，不影响功能）。LAGO_CREATE_ORG=true 时组织在 seeding 阶段创建，API Key 同步生成于 api_keys 表；若不开启该开关，则需在 Web 页面完成注册后 API Key 才会生成。

4.6 部署验证

应用就绪判定以 API 健康端点为准（编排内置健康检查也基于它）。实测：

curl -s http://localhost:8129/health

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

Web 界面验证（HTTP 200 即就绪）：

curl -sI http://localhost:8130 | head -6

HTTP/1.1 200 OK
Server: nginx/1.31.6
Date: Fri, 23 Oct 2026 18:48:23 GMT
Content-Type: text/html
Content-Length: 1347
Last-Modified: Wed, 07 Oct 2026 16:04:47 GMT

浏览器打开 http://<服务器IP>:8130，用 admin@lago.local / q1w2e3r4 登录即可进入管理界面。最终服务状态一览：

docker compose ps

NAME                    IMAGE                                  COMMAND                   SERVICE      CREATED          STATUS                    PORTS
lago-1550-stack-pdf-1   getlago/lago-gotenberg:7.8.2           "/usr/bin/tini -- go…"   pdf          11 minutes ago   Up 11 minutes             3000/tcp
lago-api                getlago/api:v1.55.0                    "./scripts/start.api…"   api          11 minutes ago   Up 11 minutes (healthy)   0.0.0.0:8129->3000/tcp, [::]:8129->3000/tcp
lago-clock              getlago/api:v1.55.0                    "./scripts/start.clo…"   api-clock    11 minutes ago   Up 11 minutes
lago-db                 getlago/postgres-partman:15.0-alpine   "docker-entrypoint.s…"   db           11 minutes ago   Up 11 minutes (healthy)   5432/tcp, 0.0.0.0:8137->8137/tcp, [::]:8137->8137/tcp
lago-front              getlago/front:v1.55.0                  "/bin/bash -c './.en…"   front        11 minutes ago   Up 6 minutes              0.0.0.0:8130->80/tcp, [::]:8130->80/tcp
lago-redis              redis:7-alpine                         "docker-entrypoint.s…"   redis        11 minutes ago   Up 11 minutes (healthy)   6379/tcp, 0.0.0.0:8146->8146/tcp, [::]:8146->8146/tcp
lago-worker             getlago/api:v1.55.0                    "./scripts/start.wor…"   api-worker   11 minutes ago   Up 11 minutes (healthy)

7 个常驻实例中 api、api-worker、db、redis 带 healthy 标记（编排内置健康检查生效），clock 无健康检查但随栈启动，migrate 已按预期退出。pdf 在内网 3000 端口供 PDF Worker 调用，未对外暴露。

五、数据持久化说明

编排声明了 3 个命名数据卷，实测卷清单：

docker volume ls | grep lago-1550

local     lago-1550-stack_lago_postgres_data
local     lago-1550-stack_lago_redis_data
local     lago-1550-stack_lago_storage_data
数据卷挂载点内容
lago_postgres_datadb 内 /data/postgres全量业务数据（组织/客户/订阅/发票/事件等 182 张表）
lago_redis_dataredis 内 /dataSidekiq 队列与缓存（可丢失性数据，重建后自动恢复）
lago_storage_dataapi/worker 内 /app/storage本地文件存储（未配置 S3/GCS 时上传的文件落这里）

5.1 重启存活实测（down → up 数据保留）

先通过 API 创建一笔业务数据作为「金丝雀」：

API_KEY=6dcdbc79-9ce2-4f47-8146-9efdb1064968
curl -s -X POST http://localhost:8129/api/v1/customers \
  -H "Authorization: Bearer $API_KEY" -H 'Content-Type: application/json' \
  -d '{"customer":{"external_id":"cus-001","name":"Acme Corp","email":"billing@acme.test","currency":"USD"}}'

输出节选（实测）：

{"customer":{"lago_id":"efeebf28-5496-49bc-a8bc-82b77140510c","billing_entity_code":"main","external_id":"cus-001","account_type":"customer","name":"Acme Corp","firstname":null,"lastname":null,"customer_type":null,"sequential_id":1,"slug":"MAI-397C-001","created_at":"2026-10-23T18:50:06Z","updated_at":"2026-10-23T18:50:06Z", ...}}

整栈停止（不带 -v，数据卷保留）后再拉起：

docker compose down && docker compose up -d

等待约 60 秒让健康检查通过，复查服务与数据：

docker compose ps
curl -s http://localhost:8129/health
curl -s http://localhost:8129/api/v1/customers/cus-001 -H "Authorization: Bearer $API_KEY"

lago-api     Up 59 seconds (healthy)
lago-worker  Up 59 seconds (healthy)
lago-db      Up About a minute (healthy)
lago-redis   Up About a minute (healthy)
{"version":"v1.55.0","github_url":"https://github.com/getlago/lago-api/tree/v1.55.0","message":"Success"}
{"customer":{"lago_id":"efeebf28-5496-49bc-a8bc-82b77140510c", ...（external_id=cus-001，lago_id 与停机前一致）}}

结论：down + up 全程保留数据，客户记录 lago_id=efeebf28-5496-49bc-a8bc-82b77140510c 停机前后完全一致；api 在 60 秒内恢复 healthy。

5.2 销毁重建实测（down -v → 全新初始化恢复）

模拟最严重的故障场景——数据卷全毁后从零重建。⚠️ 本节操作会永久删除全部业务数据，仅在演练环境执行：

docker compose down -v

销毁后核验，服务实例、数据卷、网络全部清空：

docker ps -a --format '{{.Names}}\t{{.Status}}' | grep lago; \
docker volume ls | grep lago-1550; docker network ls | grep lago-1550

（无任何输出——lago 全部实例/卷/网络均已删除）

重新拉起后整套初始化流程自动重放：

docker compose up -d
# 等待健康检查通过后核验
curl -s http://localhost:8129/health
docker logs lago-migrate
docker exec lago-db psql -U lago -d lago -t -c "select count(*) from organizations;" -c "select value from api_keys;"

{"version":"v1.55.0","github_url":"https://github.com/getlago/lago-api/tree/v1.55.0","message":"Success"}
Sidekiq Pro is not installed. Reliability features will not be available.
Sidekiq Pro is not installed. Reliability features will not be available.
Sidekiq Pro is not installed. Reliability features will not be available.
Sidekiq Pro is not installed. Reliability features will not be available.
"starting seeding environment"
"ending seeding environment"
     1

 6dcdbc79-9ce2-4f47-8146-9efdb1064968

结论：down -v 后从零重建，数据库迁移 + seeding 自动重放，LAGO_CREATE_ORG 重新创建组织与管理员；由于 .env 中密钥未变，重建后的 API Key 与销毁前一致（seeding 以组织密钥派生规则重建）。原业务数据（cus-001）已随卷删除——这正是「数据卷必须纳入备份策略」的原因，生产环境请对 lago_postgres_data 对应的 PostgreSQL 实例做定期逻辑备份。

六、环境变量表

官方编排通过 .env 支持的主要变量如下（默认值来自官方 v1.55.0 编排文件，实测值取自本环境）：

变量默认值实测值/说明
FRONT_PORT808130，Web 界面端口
API_PORT30008129，REST API 端口
POSTGRES_PORT54328137，数据库对外端口
REDIS_PORT63798146，Redis 对外端口
POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DBlago / changeme / lagolago / q1w2e3r4 / lago，官方强烈建议改掉 changeme
POSTGRES_SCHEMApublic保持默认；多应用共库时可隔离到独立 schema
SECRET_KEY_BASEyour-secret-key-base-hex-64实测以 openssl rand -hex 64 生成
LAGO_RSA_PRIVATE_KEY（无默认，必填）openssl genrsa 2044 不存在，正确命令为 openssl genrsa 2048 | openssl base64 -A
LAGO_ENCRYPTION_PRIMARY_KEY 等 3 项your-encryption-*32 位随机串，上线后不可更换
LAGO_CREATE_ORGfalsetrue 时首启自动建组织
LAGO_ORG_USER_EMAIL / LAGO_ORG_USER_PASSWORD / LAGO_ORG_NAME / LAGO_ORG_API_KEY空自动建组织的账号、密码、组织名、固定 API Key
LAGO_API_URL / LAGO_FRONT_URLhttp://localhost:3000 / http://localhost部署到远程时改为实际访问地址（影响 CORS 与回调）
LAGO_PDF_URLhttp://pdf:3000PDF 服务内网地址，一般不动
LAGO_DISABLE_PDF_GENERATIONfalsetrue 时关闭发票 PDF 生成
LAGO_DISABLE_SIGNUPfalsetrue 时关闭自助注册
LAGO_RAILS_STDOUTtrueRails 日志输出到 stdout
LAGO_USE_AWS_S3 / LAGO_USE_GCSfalse对象存储开关，配套 LAGO_AWS_S3_* / LAGO_GCS_* 变量
REDIS_PASSWORD / LAGO_REDIS_CACHE_PASSWORD空Redis 未设密码时留空
SIDEKIQ_*（注释态）—专用 Worker 拆分开关，高负载场景启用

以上为部署高频变量；Lago 全部 70+ 环境变量的逐项实测与生效验证见 《Lago 1.55.0 配置参数详解》。

七、编排配置参数说明

官方编排中有几处机制值得部署者理解，均摘自实测编排文件原文：

  1. 启动依赖链：migrate 依赖 db healthy；api/api-worker/api-clock 依赖 migrate: condition: service_completed_successfully + db/redis healthy——因此首次 up 时应用会等迁移跑完才启动，若 migrate 失败，应用不会带病启动。
  2. 健康检查：api 用 curl -f http://localhost:3000/health（10 秒间隔、30 秒起步等待期）；worker 用 curl -f http://localhost:8080（Sidekiq 内置探针端口）；db 用 pg_isready；redis 用 redis-cli ping。
  3. 重启策略：全部常驻服务 restart: unless-stopped，宿主机重启后自动拉起（migrate 无此策略，仅一次性运行）。
  4. 镜像锚点复用：编排用 YAML 锚点（x-backend-image、x-backend-environment 等）让 4 个应用服务共享同一镜像与环境变量模板，改 .env 一处即可作用于全部应用实例。
  5. 存储卷共享：api 与 api-worker 挂载同一 lago_storage_data 卷（PDF/上传文件由 Worker 生成、API 读取），扩副本时需注意本地卷的共享语义，对象存储场景则无此约束。

八、配置文件挂载（可选）

官方编排预留了两类挂载点（默认注释态），按需启用：

  1. Web 前端 HTTPS：自签证书用仓库 extra/init-selfsigned.sh 生成到 ./extra/ssl/，然后取消注释 front 服务的以下挂载：
volumes:
  - ./extra/nginx-selfsigned.conf:/etc/nginx/conf.d/default.conf
  - ./extra/ssl/nginx-selfsigned.crt:/etc/ssl/certs/nginx-selfsigned.crt
  - ./extra/ssl/nginx-selfsigned.key:/etc/ssl/private/nginx-selfsigned.key
  - ./extra/ssl/dhparam.pem:/etc/ssl/certs/dhparam.pem

Let's Encrypt 方案则启用 extra/init-letsencrypt.sh 脚本与 certbot 服务的注释段（编排名为 certbot 的服务块），证书落到 ./extra/certbot/ 持久化。

  1. GCS 凭据文件：启用 LAGO_USE_GCS=true 时，需把服务账号 JSON 挂进 api 与 api-worker：
volumes:
  - gcs_keyfile.json:/app/gcs_keyfile.json

S3 及 S3 兼容端点（MinIO 等）无需挂载文件，全部通过 LAGO_AWS_S3_* 环境变量配置，其中 S3 兼容端点必须显式设置 LAGO_AWS_S3_REGION（如 us-east-1），AWS SDK 强制要求。

九、等价 docker run：官方 one-click 单命令形态

官方为最快体验提供了一体化镜像 getlago/lago（内部自带数据库与 Redis，单实例跑通全部组件），一条命令即可启动：

docker run -d --name lago -p 80:80 -p 3000:3000 getlago/lago:latest

本环境实测（宿主 80/3000 已被占用，改用 8148/8149 映射，镜像 2.19GB）：

docker run -d --name lago-1550-oneclick -p 8148:80 -p 8149:3000 getlago/lago:latest

b1979139ef3fc35191724be382bb6dcd77707fe81a01f1c34ad3a687009dd9d2

约 45 秒后验证，API 与 Web 均就绪：

curl -s http://localhost:8149/health
curl -sI http://localhost:8148 | head -3

{"version":"production","github_url":"https://github.com/getlago/lago-api","message":"Success"}
HTTP/1.1 200 OK
Server: nginx
Date: Fri, 23 Oct 2026 18:55:02 GMT

⚠️ 注意：one-click 形态的健康端点返回 "version":"production"（一体化镜像未注入版本号），与 Compose 形态的 "version":"v1.55.0" 不同，属正常现象。one-click 适合快速体验与冒烟测试，数据落实例内部可写层；正式部署请用 Compose 编排（数据落独立卷、可升级可备份），两条路线不要混用。

十、常用运维命令

以下命令均在 /opt/lago/stack 目录内执行：

# 服务状态一览（含健康检查结果）
docker compose ps

# 跟踪某服务日志（如 api）
docker compose logs -f api

# 重启单个服务（改 .env 后需 recreate 才能生效）
docker compose up -d --force-recreate api

# 整栈停止/启动（数据保留）
docker compose stop
docker compose start

# 整栈停止并删除实例（数据卷保留，重新 up 后数据还在）
docker compose down

# 整栈彻底销毁（含数据卷，慎重）
docker compose down -v

# 拉取新版本镜像并滚动升级（改 .env 中镜像标签后执行）
docker compose pull && docker compose up -d

💡 说明：升级版本时只修改 .env/编排中的镜像标签（如 v1.55.0 → 新版本号），up -d 后 migrate 会自动执行新版本的增量迁移，无需手工跑迁移；跨大版本升级前先阅读官方 Migration 指南并备份 PostgreSQL 数据卷。

十一、常见问题

Q1：启动时刷屏 The "LAGO_AWS_S3_ENDPOINT" variable is not set. Defaulting to a blank string. 这类警告？ 正常现象。官方编排引用了少量未在示例 .env 中列出的变量（实测出现 4 个：LAGO_AWS_S3_ENDPOINT、LAGO_DISABLE_SEGMENT、LAGO_REDIS_CACHE_PASSWORD、LAGO_DISABLE_WALLET_REFRESH），未设置时 Compose 以空字符串代入，功能上等价于「未启用该特性」，可忽略；介意刷屏可在 .env 中显式赋空值。

Q2：docker compose up -d 卡在 api 不启动？ 先查 migrate 是否成功退出：docker compose ps 看到 migrate 为 Exited (0) 属正常；若为 Exited (1)，用 docker logs lago-migrate 查看迁移报错（常见原因是数据库连接失败或密钥未配置）。api 的启动依赖 migrate 成功完成，这是编排设计而非故障。

Q3：端口绑定失败 Bind for 0.0.0.0:8131 failed: port is already allocated？ 宿主端口已被其他服务占用。本环境实测复现：one-click 首次尝试 8131 端口即报此错，改用空闲端口（ss -ltn 核查后换 8148/8149）并删除创建失败的实例（docker rm -f lago-1550-oneclick）后成功。Compose 形态同理，改 .env 中对应端口变量后 up -d 即可。

Q4：首启后 Web 页面让注册，有没有免注册的自动化方式？ 有。本环境即采用 LAGO_CREATE_ORG=true + LAGO_ORG_USER_EMAIL/LAGO_ORG_USER_PASSWORD/LAGO_ORG_NAME（见 4.3 节），首启 seeding 阶段自动创建管理员组织；还可通过 LAGO_ORG_API_KEY 固定 API Key，便于自动化场景。

Q5：API Key 在哪里取？ Web 界面左侧 Developer → API keys 页可复制；数据库侧可直接查证：docker exec lago-db psql -U lago -d lago -c "select value from api_keys;"（本环境实测返回 6dcdbc79-9ce2-4f47-8146-9efdb1064968）。

Q6：down -v 和 down 怎么选？ down 只删实例与网络，三个数据卷保留，重启后业务数据原样恢复（5.1 节实测）；down -v 连数据卷一起删除，仅用于演练或确认数据可弃（5.2 节实测）。生产环境永远禁用 -v，备份走 PostgreSQL 逻辑备份。

十二、参考链接

  • 官方仓库（含 docker-compose.yml）：https://github.com/getlago/lago
  • 官方自托管 Docker 指南：https://doc.getlago.com/guide/lago-self-hosted/docker
  • Docker Hub（API 组件）：https://hub.docker.com/r/getlago/api
  • Docker Hub（Front 组件）：https://hub.docker.com/r/getlago/front
  • 本站关联文档：《Lago 1.55.0 介绍与选型指南》