1. 环境准备与前置条件在Windows 10系统上部署Dify需要先配置好两个核心组件Docker Desktop和WSL2。这两个工具构成了容器化运行的基础环境。我推荐使用Windows 10 20H2或更高版本这个版本对WSL2的支持最为稳定。1.1 启用WSL2功能首先需要启用Windows子系统Linux功能。以管理员身份打开PowerShellWinX选择Windows终端(管理员)依次执行以下命令# 启用WSL功能 dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart # 启用虚拟机平台功能 dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart执行完成后需要重启计算机。重启后继续在PowerShell中设置WSL2为默认版本wsl --set-default-version 2注意如果遇到WSL2需要更新内核组件的提示需要下载并安装最新的WSL2内核更新包可从微软官网获取。1.2 安装Linux发行版建议选择Ubuntu作为WSL2的Linux发行版。打开Microsoft Store搜索Ubuntu选择最新的LTS版本如Ubuntu 22.04 LTS进行安装。安装完成后首次启动会要求设置用户名和密码。验证WSL版本是否正确wsl -l -v输出中应显示VERSION为2。如果显示为1可通过以下命令转换wsl --set-version Ubuntu 21.3 安装Docker Desktop从Docker官网下载最新的Docker Desktop for Windows安装包。安装过程中有几个关键选项需要注意勾选Use WSL 2 instead of Hyper-V这是性能更好的选择安装完成后不要立即启动先进入设置在Docker Desktop设置中需要配置常规设置中启用Use the WSL 2 based engine资源 WSL集成中启用Enable integration with my default WSL distro根据需要可以调整CPU和内存分配建议至少4GB内存配置完成后启动Docker Desktop等待系统托盘出现鲸鱼图标表示服务已正常运行。2. Dify容器部署流程2.1 获取Dify镜像打开Ubuntu WSL终端可通过开始菜单直接启动首先更新软件包列表sudo apt update sudo apt upgrade -y然后安装Docker Compose如果尚未安装sudo apt install docker-compose-plugin -y验证Docker和Docker Compose是否正常工作docker --version docker compose version接下来创建Dify的工作目录并进入mkdir -p ~/dify cd ~/dify2.2 配置Docker Compose文件创建docker-compose.yml文件内容如下version: 3 services: redis: image: redis:6.2 restart: always volumes: - redis_data:/data ports: - 6379:6379 db: image: postgres:13 restart: always environment: POSTGRES_DB: dify POSTGRES_USER: dify POSTGRES_PASSWORD: dify123 volumes: - postgres_data:/var/lib/postgresql/data ports: - 5432:5432 api: image: langgenius/dify-api:latest restart: always depends_on: - db - redis environment: - DB_HOSTdb - DB_PORT5432 - DB_NAMEdify - DB_USERdify - DB_PASSWORDdify123 - REDIS_HOSTredis - REDIS_PORT6379 ports: - 5001:5001 worker: image: langgenius/dify-worker:latest restart: always depends_on: - db - redis environment: - DB_HOSTdb - DB_PORT5432 - DB_NAMEdify - DB_USERdify - DB_PASSWORDdify123 - REDIS_HOSTredis - REDIS_PORT6379 web: image: langgenius/dify-web:latest restart: always depends_on: - api ports: - 3000:3000 volumes: redis_data: postgres_data:这个配置包含了Dify所需的全部组件PostgreSQL数据库、Redis缓存、API服务、后台工作进程和前端界面。2.3 启动Dify服务在docker-compose.yml所在目录执行docker compose up -d首次运行会下载所有需要的镜像这个过程可能需要一些时间取决于网络速度。下载完成后会自动启动所有服务。可以通过以下命令查看服务状态docker compose ps正常情况下应该看到所有容器的状态都是running。3. 系统配置与访问3.1 初始化管理员账户服务启动后需要初始化管理员账户。访问以下URLhttp://localhost:3000/setup按照页面提示填写管理员邮箱和密码。这个账户将拥有系统最高权限。3.2 配置邮箱服务可选为了使用密码重置等功能建议配置SMTP邮件服务。进入管理员后台登录后右上角头像 系统设置找到邮件服务器配置项填写你的SMTP信息。常用配置示例以QQ邮箱为例SMTP服务器smtp.qq.com端口465安全连接SSL/TLS用户名你的QQ邮箱密码需要申请SMTP授权码3.3 防火墙设置如果无法访问3000或5001端口可能需要配置Windows防火墙打开Windows Defender 防火墙选择允许应用或功能通过Windows Defender防火墙点击更改设置然后允许其他应用添加Docker Desktop和Ubuntu WSL的可执行文件4. 常见问题排查4.1 WSL2网络问题如果遇到容器间通信问题可能是WSL2的网络配置问题。尝试以下解决方案# 在Ubuntu WSL中执行 sudo apt install resolvconf sudo nano /etc/resolvconf/resolv.conf.d/head添加以下内容nameserver 8.8.8.8 nameserver 8.8.4.4然后重启服务sudo service resolvconf restart4.2 端口冲突如果遇到端口冲突特别是5432或6379可以修改docker-compose.yml中的端口映射如将5432:5432改为5433:5432或者关闭占用端口的本地服务查看端口占用情况netstat -ano | findstr 54324.3 磁盘空间不足WSL2默认会分配有限的磁盘空间。如果遇到空间不足问题查看WSL磁盘使用情况wsl --system info扩展虚拟硬盘大小# 首先关闭WSL wsl --shutdown # 找到vhdx文件位置通常在%USERPROFILE%\AppData\Local\Packages # 然后使用diskpart扩展 diskpart select vdisk filepath_to_vhdx expand vdisk maximum51200 # 扩展到50GB4.4 性能优化建议将Dify的工作目录放在WSL文件系统中如/home/username/dify而不是Windows文件系统如/mnt/c/...在Docker Desktop设置中增加分配给WSL2的内存建议至少4GB定期清理无用的Docker镜像和容器docker system prune -f5. 日常维护与管理5.1 服务启停停止所有服务docker compose down重新启动docker compose up -d5.2 数据备份重要数据都存储在Docker卷中备份方法# 备份PostgreSQL数据 docker run --rm -v postgres_data:/volume -v $(pwd):/backup alpine tar cvf /backup/postgres_backup.tar /volume # 备份Redis数据 docker run --rm -v redis_data:/volume -v $(pwd):/backup alpine tar cvf /backup/redis_backup.tar /volume5.3 版本升级升级到最新版本docker compose pull docker compose down docker compose up -d升级前建议先备份数据。如果遇到数据库迁移问题可以查看API容器的日志docker compose logs api
