LangFlow 1.x 系列【2】源码安装

文章目录

[1. 环境要求](#1. 环境要求)
[2. 安装依赖工具](#2. 安装依赖工具)
- [2.1 安装 Python](#2.1 安装 Python)
- [2.2 安装 uv（Python 包管理器）](#2.2 安装 uv（Python 包管理器）)
- [2.3 安装 Node.js 和 npm](#2.3 安装 Node.js 和 npm)
- [2.4 安装 make（仅 Windows 需要）](#2.4 安装 make（仅 Windows 需要）)
[3. 克隆仓库](#3. 克隆仓库)
[4. 安装后端](#4. 安装后端)
- [4.1 方式一：使用 Make（推荐）](#4.1 方式一：使用 Make（推荐）)
- [4.2 方式二：手动使用 uv](#4.2 方式二：手动使用 uv)
- [4.3 安装说明](#4.3 安装说明)
[5. 安装前端](#5. 安装前端)
- [5.1 方式一：使用 Make（推荐）](#5.1 方式一：使用 Make（推荐）)
- [5.2 方式二：手动执行](#5.2 方式二：手动执行)
- [5.3 清理前端构建缓存](#5.3 清理前端构建缓存)
[6. 配置环境变量](#6. 配置环境变量)
- [6.1 创建 .env 文件](#6.1 创建 .env 文件)
- [6.2 常用配置项](#6.2 常用配置项)
[7. 启动应用](#7. 启动应用)
- [7.1 一键启动](#7.1 一键启动)
- [7.2 步骤分解](#7.2 步骤分解)
- [7.3 清理构建后启动](#7.3 清理构建后启动)
[8. 开发模式（热重载）](#8. 开发模式（热重载）)
- [8.1 终端 1：启动后端（FastAPI，端口 7860）](#8.1 终端 1：启动后端（FastAPI，端口 7860）)
- [8.2 终端 2：启动前端（Vite，端口 3000）](#8.2 终端 2：启动前端（Vite，端口 3000）)
- [8.3 WebSocket 通信说明](#8.3 WebSocket 通信说明)
[9. 常用命令速查](#9. 常用命令速查)
- [9.1 安装与初始化](#9.1 安装与初始化)
- [9.2 启动](#9.2 启动)
- [9.3 测试](#9.3 测试)
- [9.4 代码质量](#9.4 代码质量)
- [9.5 数据库](#9.5 数据库)
- [9.6 清理](#9.6 清理)
- [9.7 文档](#9.7 文档)
[10. 安装流程总结](#10. 安装流程总结)

1. 环境要求

依赖	最低版本	推荐版本	说明
Python	3.10	3.11 / 3.12	3.13 也支持，部分包可能有兼容问题
uv	0.4+	最新版	Python 包管理器，替代 pip
Node.js	20.19.0	22.12 LTS	前端构建和开发
npm	10.9+	随 Node.js 附带	前端包管理
make	任意	系统自带	构建编排（Windows 需单独安装）
Git	任意	最新版	克隆仓库

2. 安装依赖工具

2.1 安装 Python

确保安装 Python 3.10--3.13 版本。

Linux (Ubuntu/Debian):

bash 复制代码

sudo add-apt-repository ppa:deadsnakes/ppa -y
sudo apt update
sudo apt install python3.11 python3.11-venv python3.11-dev -y

macOS (Homebrew):

bash 复制代码

brew install python@3.11

Windows：从 python.org 下载安装包，或使用 WSL2。

验证安装：

bash 复制代码

python3 --version   # 应输出 3.10.x ~ 3.13.x

2.2 安装 uv（Python 包管理器）

bash 复制代码

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

# 或使用 pipx
pipx install uv

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

验证安装：

bash 复制代码

uv --version   # 应输出 0.4.x 或更高

2.3 安装 Node.js 和 npm

推荐使用 nvm (Node Version Manager) 管理 Node.js 版本。

安装 nvm:

bash 复制代码

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
# 重新加载 shell 配置
source ~/.bashrc   # 或 source ~/.zshrc

安装 Node.js 22 LTS:

bash 复制代码

nvm install 22
nvm use 22

验证安装：

bash 复制代码

node --version   # 应输出 v22.x.x
npm --version    # 应输出 10.9.x 或更高

2.4 安装 make（仅 Windows 需要）

Linux 和 macOS 自带 make。Windows 用户推荐以下几种方式：

WSL2（推荐）： 在 WSL2 中执行所有操作
Chocolatey： choco install make
GnuWin32： 从 gnuwin32.sourceforge.net 下载

3. 克隆仓库

bash 复制代码

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

仓库目录结构概览：

text 复制代码

langflow/
├── src/
│   ├── backend/          # 后端代码
│   │   ├── base/         # langflow-base 核心包
│   │   └── tests/        # 后端测试
│   ├── frontend/         # React 前端
│   └── lfx/              # 轻量级执行器
├── scripts/              # 辅助脚本
├── Makefile              # 主构建文件
├── Makefile.frontend     # 前端构建文件
├── pyproject.toml        # Python 项目配置
└── .env                  # 环境变量（需手动创建）

4. 安装后端

4.1 方式一：使用 Make（推荐）

安装所有后端 Python 依赖：

bash 复制代码

make install_backend

如果需要 PostgreSQL 支持（默认已包含）：

bash 复制代码

# 默认安装即包含 postgresql extra
make install_backend

# 如需强制重装
make reinstall_backend

4.2 方式二：手动使用 uv

bash 复制代码

# 同步 langflow-base 依赖
cd src/backend/base
uv sync --frozen

# 回到根目录，同步主包依赖
cd ../../..
uv sync --frozen --extra "postgresql"

4.3 安装说明

uv sync 会根据 uv.lock 文件精确安装锁定版本的依赖
--frozen 标志确保不修改 lock 文件
默认安装 langflow-base[complete]，包含 200+ 可选集成（OpenAI、Anthropic、各种向量数据库等）
如需最小化安装，可仅安装所需 extras，详见 src/backend/base/pyproject.toml 中的 [project.optional-dependencies]

5. 安装前端

5.1 方式一：使用 Make（推荐）

bash 复制代码

# 安装 Node.js 依赖
make install_frontend

# 构建前端静态资源
make build_frontend

build_frontend 会执行以下操作：

运行 npm run build 进行 Vite 生产构建
将构建产物复制到 src/backend/base/langflow/frontend/ 目录

5.2 方式二：手动执行

bash 复制代码

# 进入前端目录
cd src/frontend

# 安装依赖
npm install

# 构建生产版本
npm run build

# 复制构建产物到后端静态目录
cd ../..
mkdir -p src/backend/base/langflow/frontend
cp -r src/frontend/build/. src/backend/base/langflow/frontend/

# 回到根目录
cd ../..

5.3 清理前端构建缓存

如果遇到前端问题，可以清理后重新构建：

bash 复制代码

make clean_frontend_build   # 清理构建产物
make install_frontend       # 重新安装依赖
make build_frontend         # 重新构建

6. 配置环境变量

Langflow 使用 .env 文件管理配置。

6.1 创建 .env 文件

bash 复制代码

make setup_env      # 自动创建 .env 文件（如果不存在）
# 或手动
touch .env

6.2 常用配置项

bash 复制代码

# .env 文件示例

# ========== 基础配置 ==========
LANGFLOW_HOST=0.0.0.0
LANGFLOW_PORT=7860
LANGFLOW_LOG_LEVEL=debug          # debug | info | warning | error

# ========== 数据库 ==========
# SQLite（默认，无需配置）: 数据存储在用户目录
# PostgreSQL:
# LANGFLOW_DATABASE_URL=postgresql://user:password@localhost:5432/langflow

# ========== 认证 ==========
LANGFLOW_AUTO_LOGIN=true          # 开发环境跳过登录（正式环境应为 false）
LANGFLOW_SUPERUSER=admin
LANGFLOW_SUPERUSER_PASSWORD=admin123
LANGFLOW_SECRET_KEY=your-secret-key-change-me
LANGFLOW_ALGORITHM=HS256

# ========== AI 服务 API Key（可选） ==========
# OPENAI_API_KEY=sk-xxxx
# ANTHROPIC_API_KEY=sk-ant-xxxx
# GOOGLE_API_KEY=xxxx

# ========== 其他 ==========
LANGFLOW_REMOVE_API_KEYS=false    # 设为 true 移除日志中的 API Key
LANGFLOW_STORE_ENABLED=true       # 是否启用组件商店

安全提示： LANGFLOW_AUTO_LOGIN=true 仅适用于本地开发环境，生产部署务必设为 false。

7. 启动应用

7.1 一键启动

安装完所有依赖并构建前端后，直接启动：

bash 复制代码

make run_cli

或自定义参数：

bash 复制代码

make run_cli port=8080 host=0.0.0.0 log_level=debug

启动后访问：http://localhost:7860

7.2 步骤分解

make run_cli 等价于以下命令：

bash 复制代码

# 1. 确保依赖已安装
make install_frontend
make install_backend

# 2. 构建前端
make build_frontend

# 3. 启动 Langflow
uv run langflow run \
    --frontend-path src/backend/base/langflow/frontend \
    --log-level debug \
    --host 0.0.0.0 \
    --port 7860 \
    --env-file .env

7.3 清理构建后启动

如果遇到前端页面异常，使用 run_clic 完全清理后重新构建：

bash 复制代码

make run_clic

8. 开发模式（热重载）

开发组件或修改代码时，建议使用前后端分离的热重载模式。

8.1 终端 1：启动后端（FastAPI，端口 7860）

bash 复制代码

make backend

带组件动态加载（修改组件代码时推荐）：

bash 复制代码

LFX_DEV=1 make backend

只加载特定模块（加快启动速度）：

bash 复制代码

LFX_DEV=openai,anthropic make backend

8.2 终端 2：启动前端（Vite，端口 3000）

bash 复制代码

make frontend

开发模式下访问：http://localhost:3000 （前端请求自动代理到后端 7860 端口）

8.3 WebSocket 通信说明

前后端分离模式下端口映射：

模式	前端地址	后端地址	说明
生产/CLI	`:7860`	`:7860`	单端口，前端静态文件由后端提供
开发模式	`:3000`	`:7860`	双端口，Vite 代理 API 请求到后端

9. 常用命令速查

9.1 安装与初始化

命令	说明
`make init`	一键初始化（安装所有依赖 + pre-commit hooks）
`make install_backend`	安装后端 Python 依赖
`make install_frontend`	安装前端 Node.js 依赖
`make build_frontend`	构建前端静态资源
`make check_tools`	检查所需工具是否安装

9.2 启动

命令	说明
`make run_cli`	构建并启动 Langflow
`make run_clic`	清理构建缓存后启动
`make backend`	仅启动后端（开发模式）
`make frontend`	仅启动前端（开发模式）

9.3 测试

命令	说明
`make unit_tests`	运行后端单元测试
`make test_frontend`	运行前端 Jest 测试
`make tests_frontend`	运行 Playwright E2E 测试
`make lint`	运行 mypy 类型检查
`make format`	格式化前后端代码

9.4 代码质量

命令	说明
`make format_backend`	格式化 Python 代码（ruff）
`make format_frontend`	格式化前端代码（biome）

9.5 数据库

命令	说明
`make alembic-revision message="说明"`	创建新的数据库迁移
`make alembic-upgrade`	升级到最新数据库版本
`make alembic-downgrade`	回滚一个迁移版本
`make alembic-current`	查看当前数据库版本

9.6 清理

命令	说明
`make clean_frontend_build`	清理前端构建产物
`make clean_python_cache`	清理 Python 缓存
`make clean_npm_cache`	清理 npm 缓存
`make clean_all`	清理所有缓存和临时文件

9.7 文档

命令	说明
`make docs`	启动文档开发服务器 (端口 3030)
`make docs_build`	构建文档静态站点

10. 安装流程总结

bash 复制代码

# 1. 克隆仓库
git clone https://github.com/langflow-ai/langflow.git
cd langflow

# 2. 一键初始化（首次推荐）
make init

# 3. 构建前端
make build_frontend

# 4. 创建环境配置
make setup_env

# 5. 启动应用
make run_cli

# 6. 打开浏览器访问
# http://localhost:7860