Langflow 详细部署教程

Langflow 是一个强大的 AI 智能体与工作流构建平台，提供可视化开发界面，并内置 API 与 MCP 服务器，可将任意工作流转化为可集成的工具。本教程将涵盖四种主流部署方式，帮助你根据实际场景选择最合适的方案。

一、环境准备与前置条件

系统要求

  • Python：3.10–3.14（本地安装方式需要）
  • Docker：最新稳定版（Docker 方式需要）
  • uv：推荐的 Python 包管理器
  • 内存：建议至少 2 GB，生产环境建议 4 GB 以上
  • CPU：建议双核以上

安装 uv（如未安装）

1
2
3
4
5
# Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

二、方式一：Langflow Desktop（最简推荐）

这是官方推荐的最简单入门方式，所有依赖均已打包，无需管理 Python 环境。

安装步骤

  1. 访问 Langflow 官网的下载页面
  2. 下载适用于 Windows 或 macOS 的安装包
  3. 双击安装，启动即可使用

注意：Langflow Desktop 目前仅支持 Windows 和 macOS，Linux 用户请使用其他方式。

三、方式二：本地安装（uv 推荐）

适合希望在本地快速启动、进行开发测试的场景。

1. 创建并进入新目录

1
mkdir my-langflow && cd my-langflow

2. 安装 Langflow

1
uv pip install langflow -U

3. 启动 Langflow

1
uv run langflow run

启动后，Langflow 将运行在 http://127.0.0.1:7860，浏览器访问即可进入可视化界面。

四、方式三：Docker 快速部署

Docker 方式确保环境一致性，消除依赖冲突，是生产部署的首选。

4.1 快速启动（单容器，默认 SQLite）

1
docker run -p 7860:7860 langflowai/langflow:latest

访问 http://localhost:7860/ 即可使用。此方式使用默认 SQLite 数据库，适合快速体验和开发测试。

如果需要自动登录（本地开发便利）：

1
docker run -p 7860:7860 -e LANGFLOW_AUTO_LOGIN=true langflowai/langflow:latest

4.2 生产级部署（Docker Compose + PostgreSQL）

使用 Docker Compose 可获得更精细的控制，包括持久化 PostgreSQL 数据库和自定义环境变量。

步骤 1：克隆仓库

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

步骤 2：创建 .env 文件

在 docker_example 目录下创建 .env 文件，配置数据库凭据和管理员密码：

1
2
3
4
5
6
7
8
9
10
11
cat > .env <<'EOF'
# 数据库凭据
POSTGRES_USER=langflow
POSTGRES_PASSWORD=your-strong-password
POSTGRES_DB=langflow

# Langflow 配置
LANGFLOW_DATABASE_URL=postgresql://langflow:your-strong-password@postgres:5432/langflow
LANGFLOW_CONFIG_DIR=/app/langflow
LANGFLOW_SUPERUSER_PASSWORD=your-admin-password
EOF

关键说明：LANGFLOW_CONFIG_DIR 必须指向持久化卷挂载路径，否则容器重启后数据会丢失。

步骤 3：启动服务

1
docker compose up -d

步骤 4：验证

1
docker compose ps

访问 http://localhost:7860/ 即可。

推荐的 docker-compose.yml 配置要点

根据社区实践，以下配置可有效解决权限和数据持久化问题：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
services:
  langflow:
    image: langflowai/langflow:latest
    container_name: langflow
    ports:
      - "7860:7860"
    environment:
      - LANGFLOW_CONFIG_DIR=/app/langflow
      - LANGFLOW_SAVE_DB_IN_CONFIG_DIR=true
      - LANGFLOW_SECRET_KEY=your-64-char-hex-key
    volumes:
      - langflow_config:/app/langflow
      - langflow_data:/app/data
    depends_on:
      - postgres
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "timeout 20s bash -c ':> /dev/tcp/127.0.0.1/7860' || exit 1"]
      interval: 10s
      timeout: 30s
      retries: 15
      start_period: 90s

  postgres:
    image: postgres:16-trixie
    environment:
      - POSTGRES_USER=langflow
      - POSTGRES_PASSWORD=your-strong-password
      - POSTGRES_DB=langflow
    volumes:
      - langflow-postgres:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  langflow_config:
  langflow_data:
  langflow-postgres:

非 Root 用户的权限处理

Langflow Docker 镜像默认以 UID 1000 的非 root 用户运行。如果遇到权限错误，需在宿主机上预先设置目录权限：

1
2
3
mkdir -p ./langflow_config ./langflow_data
sudo chown -R 1000:1000 ./langflow_config ./langflow_data
sudo chmod -R 775 ./langflow_config ./langflow_data

如果仍无法解决，可在 docker-compose.yml 中临时取消 user: root 的注释作为回退方案。

五、方式四：远程服务器部署（生产环境）

对于需要公网访问的生产部署，建议使用反向代理提供 HTTPS 和认证保护。

5.1 使用 Caddy 作为反向代理

前置条件：一台双核 2GB 内存以上的服务器，已安装 Docker。

步骤 1：创建 docker-compose.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
services:
  langflow:
    image: langflowai/langflow:latest
    environment:
      - LANGFLOW_CONFIG_DIR=/app/langflow
    volumes:
      - langflow-data:/app/langflow
    restart: unless-stopped

  caddy:
    image: caddy:latest
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy-data:/data
      - caddy-config:/config
    restart: unless-stopped

volumes:
  langflow-data:
  caddy-data:
  caddy-config:

步骤 2：创建 Caddyfile

1
2
3
your-domain.com {
    reverse_proxy langflow:7860
}

Caddy 会自动申请并续期 Let’s Encrypt SSL 证书。

步骤 3：启动服务

1
docker compose up -d

步骤 4：配置域名解析

将域名的 A 记录指向服务器 IP，等待 DNS 生效后访问 https://your-domain.com。

5.2 使用 Traefik + PostgreSQL（完整生产配置）

对于需要持久化 PostgreSQL 和自动 HTTPS 的场景，可参考 Vultr 的完整部署指南，包含以下核心组件：

  • Traefik：终止 HTTPS，自动申请证书
  • Langflow：应用主体，连接 PostgreSQL
  • PostgreSQL：持久化存储 flows、用户和设置

关键环境变量：

1
2
3
4
5
6
LANGFLOW_AUTO_LOGIN=False
LANGFLOW_SUPERUSER=admin
LANGFLOW_SUPERUSER_PASSWORD=your-strong-password
LANGFLOW_NEW_USER_IS_ACTIVE=False
LANGFLOW_ENABLE_SUPERUSER_CLI=False
OPENAI_API_KEY=your-api-key

安全提醒：生产环境务必设置 LANGFLOW_AUTO_LOGIN=False 并配置强密码，避免未授权访问。

六、环境变量配置参考

核心变量

变量 说明 默认值
LANGFLOW_CONFIG_DIR 配置、日志、文件存储目录 /app/langflow
LANGFLOW_DATABASE_URL 数据库连接字符串 sqlite:///...
LANGFLOW_AUTO_LOGIN 是否允许自动登录 true
LANGFLOW_SUPERUSER 超级管理员用户名 langflow
LANGFLOW_SUPERUSER_PASSWORD 超级管理员密码 无
LANGFLOW_SECRET_KEY 凭据加密密钥（建议 64 位十六进制） 自动生成
LANGFLOW_HOST 绑定地址 0.0.0.0
LANGFLOW_PORT 服务端口 7860

生成 LANGFLOW_SECRET_KEY

1
openssl rand -hex 32

重要：如果不显式设置 LANGFLOW_SECRET_KEY，Langflow 会在启动时随机生成一个。容器重启后，加密的凭据将无法解密。

七、数据持久化与升级

7.1 数据持久化策略

Docker 容器默认是临时的，删除容器会导致数据丢失。必须使用持久化卷来保存数据。

方案 A：SQLite（简单场景）

1
2
3
4
5
volumes:
  - langflow_data:/app/langflow
environment:
  - LANGFLOW_DATABASE_URL=sqlite:////app/langflow/langflow.db
  - LANGFLOW_CONFIG_DIR=/app/langflow

方案 B：PostgreSQL（生产推荐）

1
2
3
environment:
  - LANGFLOW_DATABASE_URL=postgresql://user:pass@postgres:5432/langflow
  - LANGFLOW_CONFIG_DIR=/app/langflow

7.2 升级 Langflow

由于数据存储在独立卷中，升级时只需拉取新镜像并重启容器，数据不会丢失：

1
2
3
4
5
# 拉取新镜像
docker compose pull

# 重启服务
docker compose up -d

八、MCP 服务器集成（进阶）

Langflow 支持作为 MCP 服务器运行，使你的 flows 可被 MCP 客户端（如 Claude Desktop）调用。

8.1 前置条件

  • 运行中的 Langflow 实例
  • Langflow API Key
  • 安装 lfx：uv pip install lfx

8.2 配置 Claude Desktop

在 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）中添加：

1
2
3
4
5
6
7
8
9
10
11
12
{
  "mcpServers": {
    "lfx-mcp": {
      "command": "uvx",
      "args": ["--from", "lfx", "lfx-mcp"],
      "env": {
        "LANGFLOW_SERVER_URL": "http://localhost:7860",
        "LANGFLOW_API_KEY": "<your-api-key>"
      }
    }
  }
}

配置后，Claude Desktop 即可通过 MCP 协议与你的 Langflow 实例交互，执行创建 flow、连接组件等操作。

九、故障排查

问题 可能原因 解决方案
权限错误（Permission denied） 容器以非 root 用户运行，目录权限不足 预先 chown 1000:1000 设置目录权限，或临时使用 user: root
健康检查失败 / 容器 unhealthy CPU 环境下启动较慢 设置 start_period: 90s 并增加 retries
Nginx 504 超时 启动时间较长 在 Nginx 配置中添加 proxy_read_timeout 300s
容器重启后数据丢失 未使用持久化卷 配置 named volume 或绑定挂载，设置 LANGFLOW_CONFIG_DIR
PostgreSQL 排序规则警告 旧卷使用 Bookworm 初始化 执行 REINDEX DATABASE langflow; ALTER DATABASE langflow REFRESH COLLATION VERSION;

十、快速上手清单

  1. ✅ 选择部署方式：Desktop（最简）、本地 uv（开发）、Docker（生产）
  2. ✅ 安装 Langflow：根据所选方式执行对应命令
  3. ✅ 配置持久化：生产环境务必配置 PostgreSQL 或持久化卷
  4. ✅ 设置安全凭据：生成 LANGFLOW_SECRET_KEY，禁用自动登录
  5. ✅ 配置反向代理：公网访问时使用 Caddy 或 Traefik 提供 HTTPS
  6. ✅ 启动并验证：访问 http://localhost:7860 确认服务正常
  7. ✅ （可选）配置 MCP：如需与 Claude Desktop 等工具集成，配置 lfx-mcp

以上部署方案可根据实际需求灵活组合：个人开发推荐 Desktop 或本地 uv 方式，团队协作使用 Docker Compose + PostgreSQL，生产环境务必配置反向代理、HTTPS 和认证机制。