Langflow 保姆级部署教程：从零到一完整搭建可视化 AI 智能体工作流

Langflow 是一个开源的 AI 智能体与工作流可视化编排平台，GitHub 星数约 15.6 万，采用 MIT 协议，仓库（langflow-ai/langflow）保持极高的提交频率（最近提交就在今天）。它把"拖拽搭积木"的交互带给了大模型应用开发：左边拖一个模型节点、右边拖一个知识库节点，连上线就能跑，还能一键把整条工作流发布成 REST API 或 MCP Server。对于不想写一堆胶水代码、又希望快速把"多 Agent + 工具调用 + RAG"跑起来的个人和小团队来说，Langflow 是目前自托管体验最完整的选择之一。

本文严格对照 Langflow 官方 README 与官方文档（docs.langflow.org）给出全部部署命令，零基础照着敲即可完成。

一、项目介绍与适用场景

Langflow 定位是"构建和部署 AI 驱动的智能体与工作流的平台"，同时提供两种使用方式：可视化拖拽编排，以及查看/编辑任意组件底层 Python 源码。它内置了 Playground（交互式调试台）、API 发布能力、MCP Server 能力，并原生支持 LangSmith、LangFuse 等观测链路。

典型适用场景：

• 个人开发者：本地起一个实例，把 OpenAI、DeepSeek、Ollama 本地模型接进去，几分钟搭一个带检索的问答机器人。
• 小团队 / 工作室：用 Docker 部署在内网服务器，把工作流暴露成 API 给业务系统调用，避免把数据交给第三方 SaaS。
• 企业 PoC：在不写业务代码的前提下快速验证"多 Agent 协作 + 工具调用 + 知识库"的可行性，验证通过后再用源码节点二次开发。

官方同时提供 Windows / macOS 的桌面版（Langflow Desktop），所有依赖打包好，不需要自己管 Python 环境，适合完全不想碰命令行的用户。

二、核心功能逐条拆解

1. 可视化 Builder：画布式拖拽编排，连接模型、提示词、知识库、工具节点；入口为启动后浏览器打开的主画布。
2. 组件源码可编辑：任意组件都能切换到 Python 源码视图二次开发，官方称"Source code access lets you customize any component"。
3. 交互式 Playground：每条流程右侧可以直接对话调试，逐步查看每一步的中间结果。
4. 多 Agent 编排：内置会话管理与检索能力，支持多智能体协作。
5. 一键发布为 API：把 flow 直接变成 REST 接口，或导出 JSON 给 Python 程序加载。
6. 发布为 MCP Server：把工作流变成 MCP 工具，供 Claude Desktop、Cursor 等 MCP 客户端调用。
7. 可观测集成：原生对接 LangSmith、LangFuse 等链路追踪。
8. 企业级安全：官方发行版镜像默认开启登录鉴权（通过 LANGFLOW_SUPERUSER_PASSWORD 配置）。

三、全套官方链接

四、硬件与环境前置要求

官方 README 明确要求：Python 3.10–3.14，并推荐使用 uv 作为包管理器。

最低配置建议（官方未给出硬性硬件门槛，以下为运行经验值，非官方要求）：

• CPU：2 核及以上；
• 内存：8 GB 起步，加载向量库和较大模型时建议 16 GB；
• 磁盘：10 GB 以上可用空间（依赖包 + 上传的知识库文件）；
• 系统：Windows 10/11、macOS 12+、主流 Linux 发行版；
• 网络：需要能访问 PyPI / Docker Hub（国内用户可配置镜像源）。

如使用 Docker 部署，则无需本机 Python 环境，但需预装 Docker Engine 或 Docker Desktop。

五、多平台部署步骤

5.1 桌面版安装（官方推荐的最省事方式）

官方 README 提供 Langflow Desktop，"所有依赖都打包好了，不需要自己管 Python 环境或手动装包"，支持 Windows 与 macOS。

步骤：

1. 浏览器打开官方下载页 https://www.langflow.org/desktop ；
2. 下载对应系统的安装包（.exe / .dmg）；
3. 双击安装，启动后在浏览器打开 7860 端口即可使用。

官方未提供 Linux 桌面版的安装包，本文不展开 Linux 桌面版部署。

5.2 本地源码包安装（官方推荐的命令行方式）

官方原文：在一个全新目录中运行 uv pip install langflow -U 安装最新版 Langflow 包。出处：官方 README "Install locally (recommended)" 小节。

第一步：安装 uv（如已安装可跳过）。

curl -LsSf https://astral.sh/uv/install.sh | sh

这条命令从 Astral 官方脚本地址下载并安装 uv，安装完成后按提示把 uv 加入 PATH（通常是 source ~/.bashrc 或重开终端）。

第二步：新建一个空目录并进入（官方要求"from a fresh directory"），安装 Langflow：

mkdir -p ~/langflow-app && cd ~/langflow-app
uv pip install langflow -U

uv pip install 会把 langflow 及其全部依赖装入当前环境；-U 表示升级到最新版。预期输出最后会出现 Installed N packages 之类的成功提示。

第三步：启动前设置管理员密码（官方发行版默认关闭自动登录，必须先设密码）：

export LANGFLOW_SUPERUSER_PASSWORD="你的强密码"

官方 README 说明：官方发布的安装包与带 tag 的源码包默认禁用自动登录，启动前必须设置 LANGFLOW_SUPERUSER_PASSWORD，之后用用户名 langflow（或你自定义的 LANGFLOW_SUPERUSER）登录；只有开发分支才默认自动登录。

第四步：启动：

uv run langflow run

预期：终端打印启动日志，最后出现类似 Langflow is running on http://127.0.0.1:7860 的提示。浏览器打开 http://127.0.0.1:7860 ，用 langflow + 你刚设置的密码登录即进入画布。

5.3 Docker 部署（官方推荐的服务器方式）

官方 README 给出的 Docker 命令原文如下（出处：README "Docker" 小节）：

read -rsp "Langflow administrator password: " LANGFLOW_SUPERUSER_PASSWORD; echo
export LANGFLOW_SUPERUSER_PASSWORD
docker run -p 7860:7860 -e LANGFLOW_SUPERUSER_PASSWORD langflowai/langflow:latest

逐条解释：

• read -rsp "..." LANGFLOW_SUPERUSER_PASSWORD：静默读取（不回显）你输入的管理员密码并存入环境变量；
• export：把变量导出给子进程，让后面的 docker 容器能读到；
• docker run -p 7860:7860：把容器内 7860 端口映射到宿主机 7860；
• -e LANGFLOW_SUPERUSER_PASSWORD：把密码传给容器；
• langflowai/langflow:latest：官方镜像名。

预期：容器拉取镜像后启动，终端显示 Uvicorn 监听日志，浏览器访问 http://localhost:7860/ ，用户名 langflow + 你输入的密码登录。官方 Docker 镜像默认开启鉴权。如需配置持久化目录、反向代理等，见官方 Docker 部署指南 https://docs.langflow.org/deployment-docker 。

5.4 源码编译部署（贡献者方式）

官方 README 说明：如果你 clone 了仓库并想参与贡献，在仓库根目录运行：

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

出处：README "Run from source" 小节。更多细节见仓库内 DEVELOPMENT.md。普通自托管用户不需要走这条路。

六、配置文件全部参数解释

Langflow 的运行时配置主要通过环境变量完成（官方文档：https://docs.langflow.org/api-keys-and-authentication ）。以下为官方 README 明确出现的参数：

其他模型 Key（如 OpenAI、DeepSeek、Ollama 的连接串）在 Langflow 画布的模型节点里通过表单填写，官方 README 未统一给出 .env 模板；官方未明确说明的其他环境变量请查阅 docs.langflow.org 对应章节，本文不臆造。

七、启动、后台常驻与开机自启

7.1 前台启动

cd ~/langflow-app
uv run langflow run

预期日志中出现监听 127.0.0.1:7860 的行；按 Ctrl+C 停止。

7.2 后台常驻（systemd，Linux 服务器）

新建 /etc/systemd/system/langflow.service：

[Unit]
Description=Langflow
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/langflow-app
Environment="LANGFLOW_SUPERUSER_PASSWORD=你的强密码"
ExecStart=/home/ubuntu/.local/bin/uv run langflow run --host 0.0.0.0
Restart=on-failure

[Install]
WantedBy=multi-user.target

说明：--host 0.0.0.0 表示监听所有网卡以便局域网访问；该参数为常见 FastAPI/Uvicorn 系参数，若你的版本未识别，请以 uv run langflow run --help 官方输出为准。

7.3 开机自启

sudo systemctl daemon-reload
sudo systemctl enable --now langflow
sudo systemctl status langflow

看到 active (running) 即成功。

7.4 修改端口

默认端口为 7860（官方 README 明确：Langflow starts at http://127.0.0.1:7860 ）。如需改端口，在启动命令后追加对应端口参数（以 langflow run --help 官方输出为准），或在 Docker 启动时把 -p 7860:7860 左侧的宿主机端口改掉，例如 -p 8080:7860，改完浏览器访问新端口验证。

八、功能实操教程

第 1 步：登录后进入空白画布，点击右上角 "New Flow" 新建一个流程。

第 2 步：在左侧组件库（Components）中找到一个 LLM 节点（如 OpenAI 或兼容 OpenAI 接口的模型），拖到画布上，在节点右侧填入你的 API Key 或本地模型地址（如 Ollama 的 http://localhost:11434/v1）。

第 3 步：再拖一个 Chat Output（对话输出）节点，把 LLM 节点的输出口连到 Chat Output 的输入口。

第 4 步：点击画布右上角的 Playground，在输入框里问一句话，预期右侧逐字返回模型回答；这说明整条链路（模型 Key → 节点 → 输出）已通。

第 5 步：在 Playground 顶部可把该 Flow "Deploy as API" 或导出 JSON；官方 README 原话："Deploy as an API or export as JSON for Python apps"，以及 "Deploy as an MCP server"。

第 6 步（可选）：在组件库加入 Document Loader、Vector Store 节点，上传一份 PDF，即可搭出一个 RAG 问答流。

九、全套报错故障排查

1. 报错：浏览器打开 7860 端口无响应 / This site can't be reached。 原因：服务没起来，或只监听了 127.0.0.1 而你从别的机器访问。 解决：① 先在服务器本机 curl http://127.0.0.1:7860 看是否通；② 不通则看 systemctl status langflow 日志；③ 从局域网访问时确认启动参数绑定了 0.0.0.0 且防火墙放行端口。

2. 报错：启动后浏览器一直转圈，日志里大量 Python 3.xx is not supported。 原因：Python 版本不在官方要求的 3.10–3.14 区间。 解决：用 uv 切换 Python 版本（uv python install 3.12），在 3.12 环境里重装 langflow。

3. 报错：登录页要求密码，但你不知道密码。 原因：官方发行版默认开启鉴权，必须设置 LANGFLOW_SUPERUSER_PASSWORD。 解决：按 5.2/5.3 重新设置环境变量后重启服务；用户名默认 langflow。

4. 报错：模型节点测试时 401 Unauthorized 或 Connection refused。 原因：API Key 填错，或本地模型（Ollama）没起 / 地址填错。 解决：核对 Key；本地模型先在终端 curl http://localhost:11434/api/tags 确认 Ollama 在线。

5. 报错：uv pip install 超时或报网络错误。 原因：PyPI 访问慢。 解决：配置国内镜像（uv pip install langflow -U --index-url https://pypi.tuna.tsinghua.edu.cn/simple）后重试。

十、升级、回滚与卸载

• 升级：官方 README 给出升级命令 uv pip install langflow -U（与安装同命令）；Docker 用户 docker pull langflowai/langflow:latest 后重建容器。升级前建议导出关键 Flow 的 JSON 备份。
• 回滚：pip 方式可 uv pip install langflow==<上一个版本号> 回退；Docker 方式把 tag 换成旧镜像版本号。
• 卸载：停止 systemd 服务并删除 unit 文件；uv pip uninstall langflow；Docker 用户 docker rm -f <容器名> 并按需 docker rmi langflowai/langflow；删除工作目录 ~/langflow-app。

十二、进阶：多模型接入与生产加固

接入本地 Ollama 模型：在 Langflow 画布中新建 OpenAI 模型节点，把 base_url 改成 http://localhost:11434/v1，API Key 任意填（Ollama 不校验），model 名填你 ollama list 里的模型名（如 qwen2.5:7b），保存后即可在 Playground 用本地模型，零 token 费用。

接 DeepSeek：同样在 OpenAI 兼容节点里把 base_url 改成 https://api.deepseek.com/v1，Key 填 DeepSeek 控制台的 sk 即可，模型名 deepseek-chat。

生产加固清单：① 不要把 7860 直接暴露公网，前面套 Nginx + HTTPS；② 务必设置强 LANGFLOW_SUPERUSER_PASSWORD；③ 用 Docker 命名卷把数据目录（默认在容器内）持久化，避免升级丢 flow；④ 定期在画布右上角把重要 Flow 导出 JSON 备份。

常见误区：很多人把 Langflow 当"线上产品"用，但官方定位是开发与编排工具；真要给终端用户提供服务，应该走"Flow 发布为 API"那一路，由你的后端服务去调用 API，而不是把画布本身暴露给最终用户。

十一、商用许可与合规风险提示

Langflow 采用 MIT License（README 徽章明确标注 license-MIT）。MIT 协议允许商用、修改、分发，仅需保留版权声明，传染性弱，是对商用最友好的开源协议之一。需要注意：Langflow 本身只提供编排框架，你接入的具体模型（OpenAI、Claude、通义、DeepSeek 等）有各自的服务条款与数据合规要求，自托管模型（如 Ollama 跑开源权重）时还需单独核对模型权重协议。官方同时提供 Langflow Cloud 商业版，自托管 OSS 版与云版功能边界以官网为准。

参考链接

• 官方 README：https://github.com/langflow-ai/langflow
• 安装与运行 OSS 包：https://docs.langflow.org/get-started-installation
• Docker 部署指南：https://docs.langflow.org/deployment-docker
• 鉴权配置：https://docs.langflow.org/api-keys-and-authentication