Langflow Docker Compose 部署指南：从单命令启动到完整生产级编排

本文基于 Langflow 仓库中的 deploy/ 目录，系统讲解如何用 Docker Compose 一键启动 Langflow 全栈服务（前端、后端、Celery 异步任务、数据库、消息队列），并深入解读 deploy/docker-compose.yml 中 Traefik 反向代理的路由划分、deploy/.env.example 的全部关键配置项，以及附带的 Prometheus/Grafana 与 Loki 可观测性子栈。读完本文，你将能够独立拉起 Langflow 部署环境、按环境调整端口与域名、并理解每个服务在整套编排中的职责与依赖关系。

一、快速开始：三步启动

按照 deploy/README.md 的说明，前提条件是机器上已安装 Docker 与 Docker Compose。由于 compose 文件中的 Langflow 镜像使用的是 latest 标签，官方建议先拉取最新镜像再启动：

# 1. 拉取最新镜像
docker compose pull

# 2. 启动全部服务
docker compose up

启动完成后，访问 http://localhost:80 即可进入 Langflow 服务入口。README 同时提示：修改端口或其他配置，需要编辑 .env 文件（compose 文件通过 env_file 加载它，仓库提供 deploy/.env.example 作为模板）。

需要说明的两个前提限制：

1. 基础版 deploy/docker-compose.yml 是为 Docker Swarm 场景编写的：proxy 服务带有 node.role == manager 的调度约束，db 服务带有 node.labels.app-db-data == true 的节点标签约束。在单机非 Swarm 环境下直接使用，建议依赖仓库中同时提供的 deploy/docker-compose.override.yml——Docker Compose 会自动合并该文件，移除对外部 Traefik 网络的依赖（external: false），并把 Traefik Dashboard、pgAdmin、Flower 等端口直接映射到宿主机，更适合本地与单机部署。
2. 各服务当前配置的健康检查均为 test: "exit 0"（占位写法），Compose 编排层面并不做真实就绪探测，backend 的启动顺序由 depends_on: [db, broker, result_backend] 保证。

二、服务全景：docker-compose.yml 中的九个服务

deploy/docker-compose.yml 定义了完整的 Langflow 运行时拓扑，可归纳为四类：

服务	镜像	职责
proxy	traefik:v3.0	反向代理，统一入口、HTTP→HTTPS 重定向、Let's Encrypt 自动签发证书
frontend	langflowai/langflow-frontend:latest	Langflow 前端静态服务（Nginx 容器），对外路由 PathPrefix('/')，容器端口 80
backend	langflowai/langflow-backend:latest	Langflow 后端 API，容器端口 7860，对外路由 /api/v1、/api/v2、/docs、/health
celeryworker	复用 backend 镜像（YAML 锚点 <<: *backend）	Celery 异步任务消费者，启动命令为 python -m celery -A langflow.worker.celery_app worker --loglevel=INFO --concurrency=1 -n lf-worker@%h -P eventlet
flower	复用 backend 镜像	Celery 监控面板，监听 5555 端口，路由到 flower.${DOMAIN}
db	postgres:15.4	PostgreSQL 15.4，数据卷 app-db-data 挂载到 /var/lib/postgresql/data/pgdata
broker	rabbitmq:3-management	Celery 消息 broker，默认账号 admin/admin（可由 RABBITMQ_DEFAULT_USER/PASS 覆盖），映射 5672（AMQP）与 15672（管理台）
result_backend	redis:6.2.5	Celery 结果后端，同时承担 Langflow 的 Redis 缓存角色
pgadmin	dpage/pgadmin4	数据库管理界面，路由到 pgadmin.${DOMAIN}，容器端口 5050
prometheus / grafana	prom/prometheus:v2.37.9 / grafana/grafana:8.2.6	指标采集与可视化，分别路由到 /metrics 与 /grafana

几个值得注意的实现细节：

• celeryworker 与 flower 通过 YAML 锚点继承 backend 的定义（compose 文件第 69 行的 backend: &backend 与第 134 行的 <<: *backend），只是重写了 command，从而保证三者共享同一镜像与 env_file，降低配置漂移风险。
• 持久化卷统一在文件末尾声明：grafana_data、app-db-data、rabbitmq_data、rabbitmq_log、pgadmin-data，容器重建不会丢失数据库与队列数据。
• 网络只声明了一个 traefik-public 网络，基础文件注释 external: false 并标注“允许在测试时设置为 false”，即默认预期该网络由外部（Swarm 集群级 Traefik）提供。
• prometheus 与 grafana 的 ports 段被注释掉，说明官方意图是只通过 Traefik 路由（/metrics、/grafana）访问它们，而非直接暴露宿主机端口。

三、Traefik 路由与域名规则

proxy 服务的启动参数决定了整套入口行为（见 deploy/docker-compose.yml 第 11–24 行）：

command:
  - --providers.docker                    # 从 Docker 服务标签读取路由
  - --providers.docker.constraints=Label(`traefik.constraint-label-stack`, `${TRAEFIK_TAG?Variable not set}`)
  - --providers.docker.exposedbydefault=false   # 未显式标注的服务一律不暴露
  - --accesslog                            # 开启访问日志
  - --log                                  # 开启 Traefik 自身日志
  - --api                                  # 开启 Dashboard 与 API

?Variable not set 是 Compose 的严格变量校验语法：变量缺失时 compose 直接报错退出，而不是静默使用空值，这保证了 DOMAIN、STACK_NAME、TRAEFIK_TAG 等必填项必须提前在 .env 中配置。

路由划分如下表（全部为 Traefik 标签驱动）：

路由规则	转发目标（容器端口）	说明
PathPrefix('/')（frontend）	frontend:80	前端兜底路由，最后匹配
PathPrefix('/api/v1') || PathPrefix('/api/v2') || PathPrefix('/docs') || PathPrefix('/health')（backend）	backend:7860	后端 API 与 OpenAPI 文档
Host('pgadmin.${DOMAIN}')	pgadmin:5050	子域名直达 pgAdmin
Host('flower.${DOMAIN}')	flower:5555	子域名直达 Flower
PathPrefix('/metrics')	prometheus:9090	Prometheus UI
PathPrefix('/grafana')	grafana:3000	Grafana 仪表盘

域名相关的 middleware 做了三件事：HTTP 到 HTTPS 的永久重定向（redirectscheme）；www 与非 www 域名的归一化重定向（redirectregex，compose 文件第 54–67 行给出了启用/禁用的注释指引）；HTTPS 路由绑定 tls.certresolver=le 由 Let's Encrypt 自动签发证书。若你只是内网或本地使用，可以删掉 TLS 相关标签，仅保留 HTTP 路由。

四、.env 配置项详解

deploy/.env.example 是部署配置的唯一事实来源，所有服务都通过 env_file: .env 加载它。按用途可分为五组：

1. 代理与命名空间变量（Traefik 强依赖）

DOMAIN=localhost
STACK_NAME=langflow-stack
TRAEFIK_PUBLIC_NETWORK=traefik-public
TRAEFIK_TAG=langflow-traefik
TRAEFIK_PUBLIC_TAG=traefik-public

• DOMAIN：对外域名。本地用 localhost；生产环境填正式域名后，子域名服务（pgadmin.DOMAIN、flower.DOMAIN）与 Let's Encrypt 签发才生效。
• STACK_NAME：所有 Traefik router/service 名称的前缀，用于多栈共存时避免路由命名冲突。
• TRAEFIK_TAG：本栈服务必须携带的约束标签（traefik.constraint-label-stack），使公共 Traefik 只接管本栈。
• TRAEFIK_PUBLIC_TAG：pgAdmin 与 Flower 使用的公共约束标签。

2. Langflow 后端

LANGFLOW_LOG_LEVEL=debug
LANGFLOW_SUPERUSER=superuser
LANGFLOW_SUPERUSER_PASSWORD=superuser
LANGFLOW_NEW_USER_IS_ACTIVE=False
BACKEND_URL=http://backend:7860

示例中 superuser/superuser 是弱口令，生产环境务必修改。BACKEND_URL 是前端容器访问后端的内网地址，False 表示新用户注册后不自动激活。更完整的 Langflow 服务端可选项（如 LANGFLOW_DATABASE_URL、LANGFLOW_PORT、LANGFLOW_HOST、限流、SSRF 防护等）可参考仓库根目录的 .env.example。

3. 数据库（PostgreSQL）

DB_USER=langflow
DB_PASSWORD=langflow
DB_HOST=db
DB_PORT=5432
DB_NAME=langflow
POSTGRES_USER=langflow
POSTGRES_PASSWORD=langflow
POSTGRES_DB=langflow
POSTGRES_PORT=5432

两套变量名分别服务于不同组件：POSTGRES_* 供 postgres:15.4 官方镜像初始化用户与库；DB_* 供 Langflow 后端连接（DB_HOST=db 正是 compose 中的服务名）。注意 db 服务的数据目录被显式设为 PGDATA=/var/lib/postgresql/data/pgdata 并挂载到命名卷 app-db-data。

4. 消息队列与结果后端（RabbitMQ / Redis / Celery）

RABBITMQ_DEFAULT_USER=langflow
RABBITMQ_DEFAULT_PASS=langflow
BROKER_URL=amqp://langflow:langflow@broker:5672
RESULT_BACKEND=redis://result_backend:6379/0
LANGFLOW_REDIS_HOST=result_backend
LANGFLOW_REDIS_PORT=6379
LANGFLOW_REDIS_DB=0
LANGFLOW_REDIS_EXPIRE=3600
LANGFLOW_REDIS_PASSWORD=
FLOWER_UNAUTHENTICATED_API=True
C_FORCE_ROOT="true"

• BROKER_URL 与 RESULT_BACKEND 是 Celery 的标准配置：任务经 RabbitMQ 调度、结果写入 Redis；celeryworker 的启动命令正是基于 langflow.worker.celery_app。
• LANGFLOW_REDIS_* 组让 Langflow 自身（缓存等能力）复用同一个 result_backend Redis 实例。
• FLOWER_UNAUTHENTICATED_API=True 表示 Flower 监控 API 免鉴权，公网暴露 flower 子域名前应关闭。
• 文件中被注释的 #LANGFLOW_CACHE_TYPE=redis 及其 PR 备注，说明缓存类型开关在版本演进中曾处于灰度状态，配置前建议以你所用镜像版本实际支持为准。

5. pgAdmin

PGADMIN_DEFAULT_EMAIL=[e-mail]
PGADMIN_DEFAULT_PASSWORD=admin

五、本地/单机部署的覆盖层：docker-compose.override.yml

deploy/docker-compose.override.yml 在自动合并后主要做了两类修改：

1. 端口直达（绕过 Traefik 域名解析，方便本地访问）：

服务	宿主端口映射
proxy	80:80、8090:8080（Traefik Dashboard，配合 --api.insecure=true）
result_backend	6379:6379
pgadmin	5050:5050
flower	5555:5555

2. 去 Swarm 化：覆盖 proxy 的 command（保留 --api.insecure=true 本地 Dashboard）、将 traefik-public 网络显式声明为 external: false，并为 backend、celeryworker、frontend 补齐与基础文件一致的路由标签，确保合并后路由规则完整。

因此，README 中 http://localhost:80 的访问路径实际由 override 层的 80:80 端口映射实现；Traefik Dashboard 则可在 http://localhost:8090 查看实时路由树，便于排查 404 与路由冲突。

六、可观测性：Prometheus + Grafana 与 Loki 日志栈

主栈内置监控

deploy/prometheus.yml 挂载到 Prometheus 容器内，仅两个采集任务、15 秒间隔：

global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: prometheus
    static_configs:
      - targets: ["prometheus:9090"]
  - job_name: flower
    static_configs:
      - targets: ["flower:5555"]

其中 flower 目标暴露的是 Celery 任务队列指标（积压、任务耗时等），Grafana 服务（/grafana 路由）作为可视化面板展示。

可选的 Loki 日志子栈

deploy/ 下还有一个独立子栈 deploy/observability/grafana-loki/docker-compose.yml，包含三个服务：

• loki（grafana/loki:3.2.0）：日志聚合，暴露 3100 端口，就绪探针为 http://localhost:3100/ready；
• promtail（grafana/promtail:3.2.0）：以只读方式挂载 ${LANGFLOW_LOG_DIR:-./logs} 到容器内 /var/log/langflow，抓取 Langflow 的 JSON 日志文件——需通过 LANGFLOW_LOG_DIR 环境变量指向真实日志目录；
• grafana（grafana/grafana:11.3.0）：预置了 Loki 数据源与 Langflow 生产日志仪表盘（grafana/provisioning/ 与 grafana/dashboards/ 目录），管理员账号由 GF_ADMIN_USER / GF_ADMIN_PASSWORD 控制，默认 admin/admin。

该子栈独立于主 deploy 目录运行（cd deploy/observability/grafana-loki && docker compose up -d），适合在主栈生产环境之外单独部署日志观测面。

七、落地检查清单

• 启动前：cp deploy/.env.example deploy/.env（deploy 目录内的 .env 由 .gitignore 忽略，不入库），修改 DOMAIN、STACK_NAME、超级用户与数据库口令。
• 确认目标机装有 Docker + Compose v2；非 Swarm 单机环境依赖 override 层自动生效。
• 生产暴露公网时：为 DOMAIN 配置真实域名并保留 Let's Encrypt 标签；修改 superuser、RabbitMQ、Postgres、pgAdmin、Flower 的全部默认口令；评估关闭 FLOWER_UNAUTHENTICATED_API。
• 端口冲突：README 提示“修改 .env 调整端口”；若 80 端口被占用，可同步调整 override 文件中 proxy 的 "80:80" 映射或改用 Traefik 端口重定向（redirectport middleware）实现 80→8443 类跳转。
• 数据保留：app-db-data、rabbitmq_data、rabbitmq_log、grafana_data、pgadmin-data 五个命名卷承载全部持久化状态，迁移或备份时以 docker volume 为准。

小结

Langflow 的 deploy/ 目录提供了一套“单命令可启动、多环境可裁剪”的 Docker Compose 方案：基础文件面向 Swarm 集群并以 Traefik 标签驱动全量路由与自动 TLS；override 文件面向单机/本地并开放直达端口；.env 是全部行为的控制平面，覆盖代理命名空间、Langflow 认证、PostgreSQL、RabbitMQ、Redis 与 Flower；Prometheus+Grafana 内置于主栈，另有独立的 Loki+Promtail 子栈承担日志观测。理解这套编排后，你可以按部署环境（本地开发、内网单机、公网生产）裁剪对应的服务与路由，而无需改动任何服务镜像本身。