保姆级教程：在Ubuntu 23.10虚拟机上，从零部署Dify源码（含PostgreSQL 17与Redis配置）

保姆级教程Ubuntu 23.10虚拟机环境下的Dify全栈部署实战在开发者的日常工作中本地隔离环境的搭建往往是最容易被忽视却又至关重要的环节。想象一下这样的场景你正在为一个重要客户开发基于大语言模型的智能应用突然某个依赖库的更新导致生产环境出现兼容性问题而你的本地开发环境却因为长期未维护早已无法复现线上问题。这种时候一个干净、可控的虚拟机开发环境就显得尤为珍贵。本文将带你从零开始在VMware Workstation Pro 17.6.0和Ubuntu 23.10构建的虚拟环境中完整部署Dify的全栈开发环境。不同于简单的安装指南我们会深入每个组件的配置细节特别关注高版本Ubuntu下的特殊适配问题确保你能够获得一个真正可用的隔离开发环境。1. 环境准备与系统优化1.1 虚拟机基础配置首先确保你的主机满足以下硬件要求CPU支持虚拟化的64位处理器建议4核以上内存至少8GB推荐16GB磁盘空间50GB以上SSD存储安装VMware Workstation Pro 17.6.0后创建新虚拟机时需特别注意# 检查VMware虚拟化支持 egrep -c (vmx|svm) /proc/cpuinfo # 应返回大于0的数字Ubuntu 23.10安装时建议选择最小化安装并勾选OpenSSH server选项。安装完成后立即执行sudo apt update sudo apt upgrade -y sudo apt install open-vm-tools-desktop -y1.2 系统深度清理Ubuntu默认安装了许多开发者不需要的服务和软件包我们可以通过以下步骤进行精简服务清理清单# 禁用不必要的定时服务 sudo systemctl disable apt-daily-upgrade.timer sudo systemctl disable apt-daily.timer sudo systemctl mask geoclue.service # 移除不需要的软件包 sudo apt purge -y thunderbird libreoffice* ubuntu-report whoopsie磁盘空间优化# 清理旧内核和缓存 sudo apt autoremove --purge sudo apt clean sudo journalctl --vacuum-time3d提示执行清理操作前建议使用snap list查看已安装的snap应用保留必要的开发工具即可。2. 核心依赖安装与配置2.1 PostgreSQL 17与pgvector扩展PostgreSQL 17是部署Dify的关键组件我们需要特别注意权限管理和扩展安装安装步骤# 添加官方源 sudo sh -c echo deb https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main /etc/apt/sources.list.d/pgdg.list wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add - sudo apt update # 安装PostgreSQL 17及pgvector扩展 sudo apt install -y postgresql-17 postgresql-17-pgvector关键配置修改# 允许远程连接 sudo nano /etc/postgresql/17/main/postgresql.conf # 修改以下参数 listen_addresses * max_connections 100 # 配置访问权限 sudo nano /etc/postgresql/17/main/pg_hba.conf # 添加以下行 host all all 0.0.0.0/0 scram-sha-256数据库初始化-- 以postgres用户登录 sudo -u postgres psql -- 创建Dify专用用户和数据库 CREATE USER dify WITH PASSWORD dify123 CREATEDB; CREATE DATABASE dify_db OWNER dify; CREATE DATABASE dify_vector OWNER dify; -- 安装pgvector扩展需超级用户权限 \c dify_vector CREATE EXTENSION vector;2.2 Redis配置优化Redis作为Dify的缓存和消息队列需要调整默认配置以获得更好性能安全配置sudo nano /etc/redis/redis.conf # 修改以下参数 bind 0.0.0.0 protected-mode no maxmemory 1gb maxmemory-policy allkeys-lru性能调优# 启用持久化 appendonly yes appendfsync everysec # 重启服务生效 sudo systemctl restart redis-server验证Redis连接redis-cli 127.0.0.1:6379 PING # 应返回 PONG3. 开发工具链配置3.1 Node.js环境搭建Dify的Web前端基于Next.js需要正确配置Node.js环境安装Node.js 20.xcurl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs # 验证安装 node -v npm -v优化npm配置# 禁用不必要的npm行为 npm config set fund false npm config set audit false npm config set update-notifier false # 安装pnpm npm install -g pnpm3.2 Python工具链Dify后端使用Python开发需要配置隔离的Python环境安装Python 3.11sudo apt install -y python3.11 python3.11-venv python3.11-dev sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 1配置uv工具python3 -m pip install --user uv export PATH$PATH:~/.local/bin注意Ubuntu 23.10默认可能已安装Python 3.11但仍需确认pip版本与虚拟环境工具是否正常。4. Dify组件部署与联调4.1 源码获取与准备# 克隆所有必要仓库 git clone https://github.com/langgenius/dify git clone https://github.com/langgenius/dify-plugin-daemon git clone https://github.com/langgenius/dify-sandbox # 创建统一工作目录 mkdir -p ~/dify_workspace mv dify dify-plugin-daemon dify-sandbox ~/dify_workspace/4.2 API服务部署环境配置cd ~/dify_workspace/dify/api cp .env.example .env # 生成安全密钥 SECRET_KEY$(openssl rand -hex 32) sed -i s/SECRET_KEY.*/SECRET_KEY$SECRET_KEY/ .env关键环境变量设置# 数据库配置 DB_USERNAMEdify DB_PASSWORDdify123 DB_HOSTlocalhost DB_DATABASEdify_db # Redis配置 REDIS_HOSTlocalhost REDIS_PASSWORD # 向量存储配置 VECTOR_STOREpgvector PGVECTOR_HOSTlocalhost PGVECTOR_PORT5432 PGVECTOR_USERdify PGVECTOR_PASSWORDdify123 PGVECTOR_DATABASEdify_vector启动服务# 安装依赖 uv sync # 数据库迁移 uv run flask db upgrade # 启动API服务开发模式 uv run flask run --host 0.0.0.0 --port5001 --debug # 另开终端启动Celery worker uv run celery -A app.celery worker -P gevent -c 4 --loglevel INFO -Q dataset,generation,mail4.3 Web前端部署cd ~/dify_workspace/dify/web # 安装依赖 pnpm install --frozen-lockfile # 配置环境变量 cp .env.example .env.local nano .env.local关键前端配置NEXT_PUBLIC_API_PREFIXhttp://localhost:5001 NEXT_PUBLIC_PUBLIC_API_PREFIXhttp://localhost:5001启动命令pnpm build pnpm run start --host0.0.0.04.4 插件守护进程与沙箱插件守护进程cd ~/dify_workspace/dify-plugin-daemon # 安装Go依赖 go mod download # 启动服务 go run ./cmd/server/main.go沙箱环境cd ~/dify_workspace/dify-sandbox # 首次运行 ./install.sh bash build/build_amd64.sh # 后续启动 sudo ./main5. 常见问题排查5.1 权限问题处理pgvector扩展安装失败-- 临时授予超级用户权限 ALTER USER dify WITH SUPERUSER; -- 安装扩展后撤销权限 ALTER USER dify WITH NOSUPERUSER;5.2 时间同步问题# 虚拟机与主机时间同步 sudo timedatectl set-ntp true sudo systemctl restart systemd-timesyncd5.3 端口冲突检查# 查看已占用端口 sudo netstat -tulnp | grep -E 5001|5432|63795.4 性能监控# 实时监控系统资源 sudo apt install -y htop htop # 查看PostgreSQL性能 sudo -u postgres pg_top