Lago Docker Compose 部署实战指南：本地、轻量与生产三种方案的完整配置详解

Lago Docker Compose 部署实战指南本地、轻量与生产三种方案的完整配置详解【免费下载链接】lagoOpen Source Metering and Usage Based Billing API ⭐️ Consumption tracking, Subscription management, Pricing iterations, Payment orchestration Revenue analytics项目地址: https://gitcode.com/GitHub_Trending/la/lagoLago 是一个开源的计量Metering与用量计费Usage Based BillingAPI 平台支持消费追踪、订阅管理、定价迭代、支付编排与收入分析。本文以 deploy/README.md 为骨架结合仓库中的 deploy.sh、docker-compose.local.yml、docker-compose.light.yml、docker-compose.production.yml 三份编排文件系统讲解 Lago 的 Docker Compose 部署体系如何在本机快速启动、如何借助 Traefik Lets Encrypt 暴露公网 HTTPS 服务、如何拆分 Sidekiq Worker 应对生产负载以及如何通过 Profile、外部数据库、RSA 密钥等手段灵活裁剪与加固部署。读完后你将具备从零搭建 Lago 全套计费服务并落地生产监控的完整能力。一、部署方案总览三种 Compose 编排的定位与差异Lago 的deploy/目录为不同场景准备了三套 Docker Compose 编排文件它们共享同一套服务模型PostgreSQL Redis API Front Worker Clock PDF差异主要体现在流量入口和 Worker 拆分粒度上编排文件场景定位反向代理 / TLS特色docker-compose.local.yml本地开发、小规模生产无直接暴露端口依赖最少docker compose up即可运行docker-compose.light.yml轻量生产Traefik v3 Lets Encrypt单域名统一入口自动签发 SSL 证书docker-compose.production.yml生产、高负载Traefik v3 Lets Encrypt拆分 6 类 Worker 并行消费内置 Portainer 管理面板三份文件使用的镜像保持一致后端为getlago/api:v1.27.1、前端为getlago/front:v1.27.1、PostgreSQL 为postgres:15-alpine、Redis 为redis:7-alpinePDF 服务则统一使用getlago/lago-gotenberg:8.15Gotenberg 转换服务关闭 LibreOffice 路由、关闭 Chromium JavaScript、API 超时 300 秒。说明本仓库根目录还有一份面向更高版本getlago/api:v1.52.0的 docker-compose.yml其中注释了 events / alerts / pdfs / billing / clock / webhook / analytics / ai-agent 等专用 Worker 的启用方法可作为扩展部署的参考。二、Docker Compose Local五分钟跑起本地环境Local 方案面向快速体验 小规模生产设计。README 明确提示它可用于小规模生产用途但不推荐用于大规模部署。2.1 获取编排文件官方流程通过 curl 拉取编排文件。在当前仓库中该文件即 deploy/docker-compose.local.yml可以直接从仓库复制或使用仓库自带的 deploy/deploy.sh 一键脚本见第六节自动获取# 将仓库 deploy/docker-compose.local.yml 复制为工作目录下的 docker-compose.yml # 或直接使用仓库根目录的 docker-compose.yml2.2 启动全部服务Local 方案的默认端口为API3000、前端80、PostgreSQL5432、Redis6379全部通过环境变量可覆盖API_PORT、FRONT_PORT、POSTGRES_PORT、REDIS_PORT。# 前台启动便于观察日志 docker compose up --profile all # 后台启动 docker compose up -d --profile all2.3 服务组成与启动顺序从 docker-compose.local.yml 可以看出Local 方案包含 9 个服务且存在严格的依赖链服务容器名启动脚本 / 职责健康检查dblago-dbPostgreSQL 15数据卷lago_postgres_datapg_isready10s 间隔、5 次重试redislago-redisRedis 7数据卷lago_redis_dataredis-cli pingrsa-keyslago-rsa-keys执行./scripts/generate.rsa.sh生成 JWT 密钥对无migratelago-migrate执行./scripts/migrate.sh执行数据库迁移restart: no依赖 db 健康apilago-api./scripts/start.api.sh启动 Rails API挂载存储卷curl -f http://localhost:3000/healthfrontlago-frontNginx 托管前端 SPA依赖 api 健康api-workerlago-worker./scripts/start.worker.sh启动 Sidekiq Workercurl -f http://localhost:8080api-clocklago-clock./scripts/start.clock.sh启动时钟/调度任务无pdf—Gotenberg PDF 生成服务无关键依赖关系如下理解它有助于排障migrate等待db通过健康检查后才执行迁移api依赖migrate成功完成service_completed_successfully、db与redis健康api-worker、api-clock依赖migrate完成与db/redis健康front依赖api健康。2.4 核心后端环境变量Local 默认值x-backend-environment锚点定义了后端服务的完整环境变量集均可通过.env或 Shell 环境覆盖这里列出最核心的几组数据库与缓存DATABASE_URL默认为postgresql://lago:changemedb:5432/lago?search_pathpublicREDIS_URL默认为redis://redis:6379安全密钥SECRET_KEY_BASE默认占位值your-secret-key-base-hex-64、三个加密密钥LAGO_ENCRYPTION_PRIMARY_KEY/LAGO_ENCRYPTION_DETERMINISTIC_KEY/LAGO_ENCRYPTION_KEY_DERIVATION_SALT以及 JWT 用的LAGO_RSA_PRIVATE_KEY对外地址LAGO_API_URL默认http://localhost:3000LAGO_FRONT_URL默认http://localhost对象存储LAGO_USE_AWS_S3默认false与LAGO_USE_GCS默认false关闭时文件落在lago_storage_data卷的/app/storage邮件LAGO_SMTP_ADDRESS/LAGO_SMTP_PORT默认 587/ 用户名 / 密码以及发件人LAGO_FROM_EMAIL功能开关LAGO_SIDEKIQ_WEB默认true暴露 Sidekiq Web 面板、LAGO_DISABLE_SIGNUP默认false、LAGO_CREATE_ORG默认false。三、Docker Compose LightTraefik Lets Encrypt 的 HTTPS 轻量部署Light 方案在 Local 基础上引入Traefik v3.3 反向代理统一以https://LAGO_DOMAIN对外提供服务并由 Lets Encrypt 自动签发与续期 TLS 证书。⚠️前提条件必须拥有一个有效域名且该域名已配置至少一条 A 或 AAAA 记录指向部署主机否则 Lets Encrypt 的 TLS-ALPN 校验将无法完成。3.1 获取文件与环境变量# 仓库中对应文件为 deploy/docker-compose.light.yml 与 deploy/.env.light.example # 复制到工作目录后按需修改 .env.env.light.example 仅含两个必填项这也是 Light 方案的全部必填配置LAGO_DOMAINdomain.tld LAGO_ACME_EMAILemaildomain.tldLAGO_ACME_EMAIL用于 Lets Encrypt 证书的注册与到期通知LAGO_DOMAIN同时驱动 Traefik 路由规则和后端 URL 拼接LAGO_FRONT_URLhttps://${LAGO_DOMAIN}、LAGO_API_URLhttps://${LAGO_DOMAIN}/api。3.2 启动docker compose up --profile all # 后台运行 docker compose up -d --profile all3.3 Traefik 的路由设计源码级解读从 docker-compose.light.yml 可以看到 Traefik 的完整配置值得注意的细节入口仅开放websecure443通过--providers.docker.exposedbydefaultfalse禁止所有容器默认暴露只有打了traefik.enabletrue标签的服务才进入路由ACME使用tlschallengetrue证书存储于./letsencrypt/acme.json当前配置使用 Lets Encryptstaging 环境caServerhttps://acme-staging-v02.api.letsencrypt.org/directory正式上线时应切换为生产端点https://acme-v02.api.letsencrypt.org/directory否则浏览器会提示证书不受信任API 路由priority100Host(域名) PathPrefix(/api/)并挂载stripprefix中间件剥掉/api前缀后转发到 API 容器 3000 端口版本化 API 路由priority110PathPrefix(/api/v)拥有更高优先级保证版本化接口不被前缀剥离规则干扰Rails 资源路由PathPrefix(/rails)转发到 API 容器Sidekiq Web 等面板资源GraphQL 路由Path(/graphql)精确匹配转发前端路由priority50Host(域名)兜底转发到 front 容器 80 端口。这种前端兜底 API 按前缀分流的设计让用户只需记住一个域名即可同时访问管理后台Front、REST/GraphQL API 与运维面板。四、Docker Compose Production面向高负载的 Worker 拆分部署Production 方案是 Light 的增强版。README 指出它额外添加了多个服务以帮助处理更多负载并内置 Portainer 用于扩缩容与栈管理。4.1 获取文件与环境变量# 仓库中对应文件为 deploy/docker-compose.production.yml 与 deploy/.env.production.example.env.production.example 在 Light 基础上增加两个必填项LAGO_DOMAINdomain.tld LAGO_ACME_EMAILemaildomain.tld PORTAINER_USERlago PORTAINER_PASSWORDchangeme4.2 启动docker compose up --profile all # 后台运行 docker compose up -d --profile all4.3 六个专用 Worker 与并发配置Production 与 Light 最大的区别在 Worker 层Light 只有 1 个api-worker而 Production 按职责拆分为 6 类独立进程见 docker-compose.production.yml每个 Worker 拥有独立的 Sidekiq 并发度与数据库连接池服务容器名启动脚本默认并发SIDEKIQ_CONCURRENCY / DATABASE_POOL职责workerlago-worker./scripts/start.worker.sh20 / 20通用任务billing-workerlago-billing-worker./scripts/start.billing.worker.sh5 / 5计费与开票任务pdf-workerlago-pdf-worker./scripts/start.pdf.worker.sh5 / 5发票 PDF 生成webhook-workerlago-webhook-worker./scripts/start.webhook.worker.sh10 / 10Webhook 投递clock-workerlago-clock-worker./scripts/start.clock.worker.sh20 / 20定时调度任务events-workerlago-events-worker./scripts/start.events.worker.sh20 / 20事件/用量数据消费同时clock服务在 Production 方案中保留且所有 Worker 的健康检查统一为curl -f http://localhost:8080。这种一队列一进程的拓扑能有效隔离重负载队列如事件消费与延迟敏感队列如计费与 docs/monitoring.md 中列出的billing、clock、events、pdfs、webhook等 Sidekiq 队列一一对应。4.4 内置 Portainer 管理面板Production 方案额外启动portainer/portainer-ce通过/portainer前缀路由暴露在 HTTPS 域名下同样使用stripprefix中间件管理员凭据由PORTAINER_USER/PORTAINER_PASSWORD注入数据持久化在portainer_data卷。借助 Portainer 可以可视化扩缩容 Worker 实例、查看容器日志与资源占用。五、进阶一键部署脚本 deploy.sh除手工复制 compose 文件外仓库还提供了交互式部署脚本 deploy/deploy.sh将依赖检查 → 存量清理 → 模板选择 → 环境变量引导 → 启动串成一条龙。其核心流程依赖检查依次检查docker与docker compose是否安装缺失则提示安装存量处理检测到正在运行的lago-quickstart容器或lago-local/lago-light/lago-production三个 Compose 项目时询问是否停止、删除甚至清空lago_rsa_data、lago_postgres_data、lago_redis_data、lago_storage_data数据卷模板选择提供 4 种部署模式——Quickstart单容器docker run -d --name lago-quickstart -p 3000:3000 -p 80:80 getlago/lago:latest、Local、Light、ProductionDNS 校验对 Light/Production 模式使用dig或nslookup校验LAGO_DOMAIN是否存在 A 记录未解析时交互询问是否继续外部依赖引导交互式询问是否使用外部 PostgreSQL / Redis并据此自动追加必填环境变量、自动选择all-no-pg/all-no-redis/all-no-dbProfile写入 .env将缺失的LAGO_DOMAIN、LAGO_ACME_EMAIL、PORTAINER_USER、PORTAINER_PASSWORD等变量逐一提示录入并写入.env启动按所选模板执行docker compose --profile profile up -d。六、Profile 机制按需裁剪服务三份 compose 文件中的每个服务都通过profiles字段归属不同 Profile。README 列出的核心 Profile 如下Profile效果all启用全部服务all-no-pg不启用 PostgreSQL使用外部数据库时all-no-redis不启用 Redis使用外部 Redis 时all-no-keys不启用 RSA 密钥生成服务all-no-db不启用 PostgreSQL 与 Redis两处都外接时从 compose 源码可以精确看到各 Profile 的成员关系db服务属于all、all-no-redis、all-no-keys即all-no-pg下数据库不启动redis服务属于all、all-no-pg、all-no-keysrsa-keys服务属于all、all-no-pg、all-no-redis、all-no-dbapi、migrate、front、worker、clock 等业务服务不属于任何显式 Profile始终随默认集合启动。对应的常用启动命令# 全部服务 docker compose up --profile all # 不用内置 PostgreSQL外接数据库 docker compose up --profile all-no-pg # 不用内置 Redis外接 Redis docker compose up --profile all-no-redis # 不用内置 PostgreSQL 和 Redis docker compose up --profile all-no-db # 不用 RSA 密钥生成服务自行注入 LAGO_RSA_PRIVATE_KEY docker compose up --profile all-no-keys # 不启用 PostgreSQL、Redis 与 RSA 密钥生成无任何显式 Profile docker compose up七、外接 PostgreSQL 与 Redis当需要复用已有数据库基础设施时可以停用内置容器并指向外部实例。7.1 使用外部 PostgreSQL设置以下环境变量POSTGRES_SCHEMA可选POSTGRES_USERyour_user POSTGRES_PASSWORDyour_password POSTGRES_DBlago POSTGRES_HOSTyour-db-host POSTGRES_PORT5432 # POSTGRES_SCHEMApublic # 可选非 public schema 时填写启动时不带 PostgreSQLdocker compose up --profile all-no-pg这些变量会拼接到DATABASE_URLpostgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}?search_path${POSTGRES_SCHEMA:-public}。注意migrate服务的depends_on对 db 使用required: false因此外接数据库时迁移任务会直接对远程库执行。7.2 使用外部 Redis设置以下环境变量REDIS_PASSWORD可选REDIS_HOSTyour-redis-host REDIS_PORT6379 # REDIS_PASSWORDyour_password # 可选启动时不带 Redisdocker compose up --profile all-no-redis此外还有一组独立的缓存通道变量LAGO_REDIS_CACHE_URL默认redis://redis:6379、LAGO_REDIS_CACHE_PASSWORD与LAGO_REDIS_CABLE_URL用于 Rails 缓存与 ActionCable 场景可单独指向专用 Redis。八、RSA 密钥JWT 签名的核心安全配置README 明确说明这套 compose 文件会生成一对 RSA 密钥用于 JWT Token 的签名。密钥由rsa-keys服务执行./scripts/generate.rsa.sh生成保存在lago_rsa_data卷中对应后端容器内的/app/config/keys目录。几点必须注意所有后端服务共享同一把 RSA 密钥README 特别警告所有后端服务使用相同的 RSA 密钥如果未提供密钥它们会立即退出如果希望使用自己的密钥操作步骤如下删除lago_rsa_data卷生成密钥并 Base64 编码openssl genrsa 2048 | openssl base64 -A将输出导出为LAGO_RSA_PRIVATE_KEY环境变量使用all-no-keysProfile 启动跳过密钥生成服务docker compose up --profile all-no-keys与之配套的还有SECRET_KEY_BASE与三把加密密钥LAGO_ENCRYPTION_PRIMARY_KEY、LAGO_ENCRYPTION_DETERMINISTIC_KEY、LAGO_ENCRYPTION_KEY_DERIVATION_SALT生产环境务必全部替换为随机强值并妥善保管——密钥丢失或变更将导致历史数据无法解密、Token 无法校验。九、生产监控Sidekiq 指标与告警对于生产部署README 建议为 Sidekiq Worker 配置监控完整方案见 docs/monitoring.md。其核心要点可概括为两层基础指标OSS 与 Pro 均可用Sidekiq Web UI 内置 Prometheus Exporter在:3000/prometheus/metrics暴露指标包括全局指标sidekiq_processed_jobs_total、sidekiq_failed_jobs_total、sidekiq_workers、sidekiq_enqueued_jobs、sidekiq_scheduled_jobs、sidekiq_retry_jobs、sidekiq_dead_jobs等、按队列指标sidekiq_queue_latency_seconds、sidekiq_queue_enqueued_jobs、sidekiq_queue_max_processing_time_seconds等与按主机指标Sidekiq Pro 增强指标需 Pro License设置LAGO_SIDEKIQ_STATSD_ENDPOINTstatsd-exporter:9125后通过 Datadog StatsD 客户端上报lago_api_前缀的按 Job 指标lago_api_jobs_count、lago_api_jobs_success、lago_api_jobs_failure、lago_api_jobs_perform等再经 StatsD Exporter 转为 Prometheus 格式。监控文档还提供了可直接落地的 Prometheus 告警规则如sidekiq_queue_latency_seconds 300判定的队列延迟告警、sidekiq_workers 0判定的 Worker 宕机告警、失败率超过 5% 的高失败率告警以及 Grafana Dashboard 的面板布局建议概览、队列健康、Worker 健康、Job 性能、容量规划五个区块配合上文 Production 方案的 Worker 拆分拓扑即可构成一套完整的部署 观测闭环。十、排障与最佳实践小结首次启动顺序异常先docker compose logs migrate确认迁移是否因数据库连接失败而退出api需要migrate以service_completed_successfully结束才会启动健康检查失败api的健康检查是curl -f http://localhost:3000/healthstart_period: 30sWorker 则是:8080若 API 反复重启通常是数据库/Redis 未就绪或 RSA 密钥缺失HTTPS 证书问题Light/Production 当前使用 Lets Encrypt staging 端点正式环境务必切换caServer到生产端点并确认域名 A 记录解析正常生产安全基线替换全部默认密钥与口令changeme、your-secret-key-base-hex-64、三把加密密钥、PORTAINER_PASSWORD、为对象存储与邮件 SMTP 配置真实凭据、按负载调整各 Worker 的SIDEKIQ_CONCURRENCY与DATABASE_POOL横向扩展Production 方案配合 Portainer 可对单个 Worker 服务进行副本扩容若事件、告警、PDF、计费等队列负载极高可参考根目录 docker-compose.yml 中注释的api-events-worker、api-alerts-worker、api-pdfs-worker、api-billing-worker等专用 Worker 模板进一步拆分。至此你已经掌握 Lago 从本地快速体验、单域名 HTTPS 上线到生产级 Worker 拆分与监控的完整部署路径如需深入 Worker 队列架构与资源规划可继续阅读 docs/architecture.md 与 docs/monitoring.md。【免费下载链接】lagoOpen Source Metering and Usage Based Billing API ⭐️ Consumption tracking, Subscription management, Pricing iterations, Payment orchestration Revenue analytics项目地址: https://gitcode.com/GitHub_Trending/la/lago创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考