不用docker部署dify1.4时依赖环境如何配置？

Question

在不使用Docker部署Dify 1.4时，常见的问题是Python依赖环境配置复杂导致服务启动失败。由于Dify依赖特定版本的Python（如3.9+）及大量第三方库（如FastAPI、SQLAlchemy、Redis等），手动配置时易出现版本冲突或缺失依赖。特别是在CentOS或Ubuntu系统中，系统自带Python版本较低，需手动升级并配置虚拟环境，若未正确安装psycopg2、libpq等数据库相关依赖，会导致数据库连接失败。此外，前端构建依赖Node.js环境（v16+），npm包安装缓慢或版本不兼容也常引发构建错误。如何准确配置Python虚拟环境、管理依赖包版本并确保前后端依赖协同工作，成为部署过程中的关键难点。

Answer 1

1. 问题背景与部署挑战概述

Dify 1.4 是一个基于大语言模型的低代码开发平台，其核心服务依赖于 Python 3.9+ 及一系列高性能 Web 框架（如 FastAPI）和数据库 ORM 工具（如 SQLAlchemy）。在不使用 Docker 的裸机部署场景中，开发者需手动搭建完整的运行环境。然而，不同操作系统（如 CentOS 7/8、Ubuntu 20.04/22.04）默认 Python 版本通常为 3.6 或更低，无法满足 Dify 的最低要求。

此外，Dify 的后端依赖大量第三方库，包括：

• FastAPI（v0.100+）
• SQLAlchemy（v2.0+）
• psycopg2-binary（用于 PostgreSQL 连接）
• redis-py（v5.0+）
• celery（异步任务队列）
• PyJWT、passlib、uvicorn 等安全与运行时组件

这些库之间存在复杂的版本依赖关系，若未通过虚拟环境隔离或依赖锁定机制管理，极易引发冲突。例如，旧版 SQLAlchemy 不兼容 Pydantic v2，而 FastAPI 新版本又强依赖 Pydantic v2，形成“依赖地狱”。

2. 核心难点分解：Python 环境配置与依赖管理

在 CentOS 和 Ubuntu 上部署时，首要任务是升级 Python 至 3.9 或更高版本。以 CentOS 为例，系统自带 Python 多为 3.6，需通过源码编译或启用 Software Collections (SCL) 来安装高版本。

# CentOS 安装 Python 3.9 示例
sudo yum install -y centos-release-scl
sudo yum install -y rh-python39
scl enable rh-python39 bash

Ubuntu 用户可通过 deadsnakes PPA 添加高版本 Python：

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

随后必须创建独立的虚拟环境以避免全局包污染：

python3.9 -m venv dify-env
source dify-env/bin/activate

3. 数据库驱动与系统级依赖缺失问题

即使 Python 环境就绪，psycopg2 的安装常因缺少底层 C 库而失败。这是因为 psycopg2 编译需要 libpq-dev 和 gcc 工具链支持。

操作系统	所需系统依赖包
CentOS/RHEL	postgresql-devel, gcc, python39-devel
Ubuntu/Debian	libpq-dev, build-essential, python3.9-dev

正确安装方式如下：

# Ubuntu
sudo apt install libpq-dev build-essential
pip install psycopg2-binary

# 或直接使用预编译包避免编译
pip install psycopg2-binary

推荐优先使用 psycopg2-binary 以规避编译问题，但在生产环境中建议使用源码构建以优化性能。

4. 前端构建依赖：Node.js 与 npm 生态协同

Dify 前端基于 Vue 3 或 React 构建，依赖 Node.js v16+ 和 npm/yarn 包管理器。Node.js 版本过低会导致 esbuild、vite 等现代构建工具无法运行。

# 使用 nvm 安装 Node.js v18
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 18
nvm use 18

国内用户常面临 npm 包下载缓慢的问题，应配置镜像源：

npm config set registry https://registry.npmmirror.com
yarn config set registry https://registry.npmmirror.com

建议使用 pnpm 替代 npm/yarn 以提升依赖解析效率和磁盘利用率。

5. 依赖版本协同与锁定策略

为确保前后端依赖协同工作，必须采用依赖锁定机制。Python 端推荐使用 pip-tools 或 poetry 生成确定性依赖列表。

# 使用 pip-tools 示例
pip install pip-tools
# 编写 requirements.in
echo "fastapi>=0.100" > requirements.in
echo "sqlalchemy>=2.0" >> requirements.in
echo "psycopg2-binary>=2.9" >> requirements.in
pip-compile requirements.in
pip-sync requirements.txt

前端则应使用 package-lock.json 或 yarn.lock 固化依赖树，并定期审计漏洞：

npm audit --audit-level high

6. 全流程自动化部署流程图

graph TD A[准备操作系统] --> B{判断系统类型} B -->|CentOS| C[启用 SCL 安装 Python 3.9] B -->|Ubuntu| D[添加 deadsnakes PPA] C --> E[创建虚拟环境] D --> E E --> F[激活环境并安装 pip-tools] F --> G[编译并同步 requirements.txt] G --> H[安装 Node.js v16+ via nvm] H --> I[配置 npm 镜像源] I --> J[执行前端构建: npm run build] J --> K[启动后端服务: uvicorn app:app] K --> L[验证 API 与页面访问]