1. 环境准备与前置条件

在Windows 10系统上部署Dify需要先配置好两个核心组件：Docker Desktop和WSL2。这两个工具构成了容器化运行的基础环境。我推荐使用Windows 10 20H2或更高版本，这个版本对WSL2的支持最为稳定。

1.1 启用WSL2功能

首先需要启用Windows子系统Linux功能。以管理员身份打开PowerShell（Win+X选择"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 2

1.3 安装Docker Desktop

从Docker官网下载最新的Docker Desktop for Windows安装包。安装过程中有几个关键选项需要注意：

1. 勾选"Use WSL 2 instead of Hyper-V"（这是性能更好的选择）
2. 安装完成后不要立即启动，先进入设置

在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 ~/dify

2.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_HOST=db - DB_PORT=5432 - DB_NAME=dify - DB_USER=dify - DB_PASSWORD=dify123 - REDIS_HOST=redis - REDIS_PORT=6379 ports: - "5001:5001" worker: image: langgenius/dify-worker:latest restart: always depends_on: - db - redis environment: - DB_HOST=db - DB_PORT=5432 - DB_NAME=dify - DB_USER=dify - DB_PASSWORD=dify123 - REDIS_HOST=redis - REDIS_PORT=6379 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 初始化管理员账户

服务启动后，需要初始化管理员账户。访问以下URL：

http://localhost:3000/setup

按照页面提示填写管理员邮箱和密码。这个账户将拥有系统最高权限。

3.2 配置邮箱服务（可选）

为了使用密码重置等功能，建议配置SMTP邮件服务。进入管理员后台（登录后右上角头像 > 系统设置），找到邮件服务器配置项，填写你的SMTP信息。

常用配置示例（以QQ邮箱为例）：

• SMTP服务器：smtp.qq.com
• 端口：465
• 安全连接：SSL/TLS
• 用户名：你的QQ邮箱
• 密码：需要申请SMTP授权码

3.3 防火墙设置

如果无法访问3000或5001端口，可能需要配置Windows防火墙：

1. 打开"Windows Defender 防火墙"
2. 选择"允许应用或功能通过Windows Defender防火墙"
3. 点击"更改设置"，然后"允许其他应用"
4. 添加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 restart

4.2 端口冲突

如果遇到端口冲突（特别是5432或6379），可以：

1. 修改docker-compose.yml中的端口映射（如将"5432:5432"改为"5433:5432"）
2. 或者关闭占用端口的本地服务

查看端口占用情况：

netstat -ano | findstr "5432"

4.3 磁盘空间不足

WSL2默认会分配有限的磁盘空间。如果遇到空间不足问题：

1. 查看WSL磁盘使用情况：

wsl --system info

2. 扩展虚拟硬盘大小：

# 首先关闭WSL wsl --shutdown # 找到vhdx文件位置（通常在%USERPROFILE%\AppData\Local\Packages） # 然后使用diskpart扩展 diskpart > select vdisk file="path_to_vhdx" > expand vdisk maximum=51200 # 扩展到50GB

4.4 性能优化建议

1. 将Dify的工作目录放在WSL文件系统中（如/home/username/dify），而不是Windows文件系统（如/mnt/c/...）
2. 在Docker Desktop设置中增加分配给WSL2的内存（建议至少4GB）
3. 定期清理无用的Docker镜像和容器：

docker system prune -f

5. 日常维护与管理

5.1 服务启停

停止所有服务：

docker compose down

重新启动：

docker compose up -d

5.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 /volume

5.3 版本升级

升级到最新版本：

docker compose pull docker compose down docker compose up -d

升级前建议先备份数据。如果遇到数据库迁移问题，可以查看API容器的日志：

docker compose logs api