使用 Docker Compose 部署 Langflow：docker_example 目录完整实操与配置解析

Langflow 官方仓库中的 docker_example 目录提供了一套最小可运行的 Docker Compose 部署方案：一个基于 langflowai/langflow 官方镜像的服务加上一个 PostgreSQL 16 数据库，通过 .env 注入管理员密码即可在 http://localhost:7860/ 启动完整的 AI Agent 与工作流平台。本文基于 docker_example/README.md 的原始步骤展开，并结合 docker-compose.yml、Dockerfile 以及后端源码中超级用户初始化和配置目录的实现，逐一解释每个配置项的作用、默认值与常见坑（如 collation 版本警告、legacy 密码被拒绝等）。

docker_example 目录结构与各文件职责

进入 docker_example/ 目录，核心文件包括：

• docker-compose.yml：主部署编排文件，定义 langflow 与 postgres 两个服务及两个命名卷；
• Dockerfile：在官方镜像基础上显式指定启动命令的构建文件；
• pre.docker-compose.yml 与 pre.Dockerfile：切换到特定版本（1.0-alpha）的编排与构建文件，是“版本切换”一节的实际参照。

主 Dockerfile 内容非常简洁，只有两行：

FROM langflowai/langflow:latest

CMD ["python", "-m", "langflow", "run", "--host", "0.0.0.0", "--port", "7860"]

其中 python -m langflow run 对应后端入口 src/backend/base/langflow/main.py，--host 0.0.0.0 确保容器内服务可被外部端口映射访问，--port 7860 与 compose 文件中 "7860:7860" 的端口映射一一对应。

前置条件与快速启动步骤

按照 README 的操作顺序：

1. 安装好 Docker 与 Docker Compose；

2. 克隆仓库并进入示例目录：

   git clone https://github.com/langflow-ai/langflow.git
   cd langflow/docker_example
   

3. 创建 .env 文件并设置超级用户密码（compose 文件通过 ${VAR:?error} 语法强制要求该变量存在）：

   LANGFLOW_SUPERUSER_PASSWORD=SUPERUSER_PASSWORD
   

   将 SUPERUSER_PASSWORD 替换为你自定的强密码。默认管理员用户名是 langflow——这一点可以在源码常量中确认：src/lfx/src/lfx/services/settings/constants.py 中定义了 DEFAULT_SUPERUSER = "langflow"；

4. 启动：

   docker compose up
   

启动完成后访问 http://localhost:7860/，用 langflow + 你设置的密码登录。

深入解析 docker-compose.yml：完整配置与逐项说明

下面是 docker_example/docker-compose.yml 的完整内容，这是部署行为的事实来源：

services:
  langflow:
    image: langflowai/langflow:latest # or another version tag on https://hub.docker.com/r/langflowai/langflow
    pull_policy: always               # set to 'always' when using 'latest' image
    ports:
      - "7860:7860"
    depends_on:
      - postgres
    environment:
      - LANGFLOW_DATABASE_URL=postgresql://langflow:langflow@postgres:5432/langflow
      - LANGFLOW_SUPERUSER_PASSWORD=${LANGFLOW_SUPERUSER_PASSWORD:?set LANGFLOW_SUPERUSER_PASSWORD in .env}
      # This variable defines where the logs, file storage, monitor data and secret keys are stored.
      - LANGFLOW_CONFIG_DIR=/app/langflow
    volumes:
      - langflow-data:/app/langflow

  postgres:
    # Pinned to a specific Debian base (trixie) so the postgres:16 tag does not
    # silently roll its OS underneath us — that roll causes a glibc collation
    # version mismatch warning on existing volumes. Matches the langflow image
    # base.
    image: postgres:16-trixie
    environment:
      POSTGRES_USER: langflow
      POSTGRES_PASSWORD: langflow
      POSTGRES_DB: langflow
    ports:
      - "5432:5432"
    volumes:
      - langflow-postgres:/var/lib/postgresql/data

volumes:
  langflow-postgres:
  langflow-data:

langflow 服务

• 镜像与拉取策略：使用 langflowai/langflow:latest，并设置 pull_policy: always。注释中明确说明这是使用 latest 标签时的推荐做法，保证每次 docker compose up 都会检查最新镜像，而不是复用本地缓存；
• 端口：7860:7860，即 Langflow 的 Web 服务端口；
• 依赖关系：depends_on: postgres 保证数据库容器先启动；
• 数据卷：langflow-data 挂载到容器内 /app/langflow。

三个环境变量分别解释如下：

LANGFLOW_DATABASE_URL —— PostgreSQL 连接串，本例硬编码为 postgresql://langflow:langflow@postgres:5432/langflow（用户名/密码/库名均为 langflow，主机名为 compose 服务名 postgres）。它必须与 postgres 服务中 POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_DB 的取值保持一致，否则 Langflow 启动时数据库连接会失败。

LANGFLOW_SUPERUSER_PASSWORD —— 初始管理员密码，是本示例中唯一必须在 .env 中提供的值。${VAR:?set LANGFLOW_SUPERUSER_PASSWORD in .env} 是 compose 的强制展开语法：如果 .env 缺少该变量，docker compose up 会直接报错终止，而不是带着空密码启动。源码层面，首次启动时后端会执行超级用户初始化流程：src/backend/base/langflow/services/utils.py 中的 setup_superuser 以 auth_settings.SUPERUSER or DEFAULT_SUPERUSER（即 langflow）为用户名创建管理员；同一文件中还有对 legacy 默认密码的显式拒绝逻辑（L227-L232）——若密码等于历史默认值（SecretStr("langflow")，见 constants.py），初始化会直接报错而不是静默接受，这正是 README 强调“请替换为强密码”的底层原因。

LANGFLOW_CONFIG_DIR —— 指定日志、文件存储、monitor 数据与 secret key 的存放目录，本例设为 /app/langflow，并与 langflow-data 卷的挂载点一致。从源码结构看，该目录还承担 MCP 服务器配置等持久化数据（services/utils.py 附近有对该目录的 MCP 配置恢复逻辑，L300-L316 中会读取 settings.config_dir 并按用户目录组织数据），因此将其落到命名卷上、而不是容器可写层，是保证数据在容器重建后不丢失的关键。

postgres 服务与镜像基础系统钉选（pinned base）

postgres 服务使用 postgres:16-trixie 镜像（trixie 即 Debian 13），端口 5432:5432，数据卷 langflow-postgres 映射到 /var/lib/postgresql/data。

这里有一个值得注意的工程决策：为什么不直接用 postgres:16？ compose 文件中的注释给出了原因：postgres:16 这个 tag 的底层 Debian 系统会随时间悄悄滚动（最初是 Bookworm / glibc 2.36，后来是 Trixie / glibc 2.41）。一旦底层 glibc 版本变化，已初始化过的数据卷就会触发 PostgreSQL 的 collation 版本不匹配警告。钉选 postgres:16-trixie 是为了让数据库镜像的基础系统版本与 langflowai/langflow 镜像的基础系统保持一致，杜绝这种“静默换系统”行为。

从 bookworm 卷升级：清除 collation 版本警告

如果你早期用过本示例的旧版本（当时是 postgres:16，Bookworm / glibc 2.36 基础），首次切换到钉选的 Trixie 镜像后，PostgreSQL 会在启动日志中打印一次性警告：

WARNING: database "langflow" has a collation version mismatch
DETAIL: The database was created using collation version 2.36, but the operating system provides version 2.41.

按 README 的说明，这是一次性问题，在运行中的数据库上刷新 collation 版本即可消除（在典型规模的 Langflow 数据库上只需几秒）：

docker compose exec postgres \
  psql -U langflow -d langflow \
  -c "REINDEX DATABASE langflow;" \
  -c "ALTER DATABASE langflow REFRESH COLLATION VERSION;"

注意 psql 的用户名和数据库名都取自 compose 中 POSTGRES_USER: langflow / POSTGRES_DB: langflow，如果你的部署改过这些值，命令中的 -U 与 -d 参数也要相应替换。全新安装（从未用过 Bookworm 卷）不受此问题影响。

切换到特定 Langflow 版本

如果你不想追 latest，可以修改 langflow 服务下的 image 字段。README 给出的例子是把 langflowai/langflow:latest 改为 langflowai/langflow:1.0-alpha。仓库里已经提供了一个现成的对照版本：

• pre.docker-compose.yml：与主 compose 结构相同，image 改为 langflowai/langflow:1.0-alpha，同样钉选了 postgres:16-trixie；
• pre.Dockerfile：FROM langflowai/langflow:1.0-alpha + 相同的 python -m langflow run 启动命令。

从这两份 pre 文件与主 compose 的差异还能看到一个版本间细节：pre 版（较早）的 LANGFLOW_CONFIG_DIR 写的是相对路径 app/langflow，且未包含 LANGFLOW_SUPERUSER_PASSWORD 注入；当前主 compose 使用的是绝对路径 /app/langflow 并强制要求 .env 提供密码。可以推断，绝对路径 + 强制密码是后来收敛出的更稳妥写法，自行切换版本时建议以 docker-compose.yml 的写法为准。

启动后的验证清单

启动过程中可以按以下顺序快速确认各组件状态：

1. 容器状态：docker compose ps 应看到 langflow 与 postgres 均为 running；depends_on 只保证启动顺序，不保证数据库就绪，因此偶发的首次连接重试属于正常现象；
2. 访问入口：浏览器打开 http://localhost:7860/，使用 langflow + .env 中设置的密码登录；若看到登录页但登录失败，先核对密码是否恰好等于历史默认值（该值会被 setup_superuser 主动拒绝）；
3. 数据落盘：docker volume ls 应能列出 langflow-data 与 langflow-postgres 两个命名卷，分别承载 Langflow 配置/文件数据与 PostgreSQL 数据，二者都独立于容器生命周期，重建容器不会丢数据；
4. 查看日志：docker compose logs langflow 与 docker compose logs postgres，postgres 日志中重点确认是否出现上文所述的 collation 警告，必要时执行 REINDEX + REFRESH 命令清除。

小结与延伸

docker_example 方案的价值在于用最少配置给出了一条“可复制、可验证”的部署基线：镜像钉选、密码强制注入、数据卷持久化、glibc 版本对齐四个细节都直接对应真实运行中可能踩到的问题。如果你需要面向生产环境的部署（多 worker、反向代理、SSL、Kubernetes 等），仓库的 docs/docs/Deployment/ 目录下有完整文档（如 deployment-docker.mdx、deployment-multi-worker.mdx），仓库根目录下的 deploy/ 与 docker/ 目录则提供了更完整的编排与镜像构建脚本，可在理解本文的基础配置后按需深入。