前言

Dify 是一款开源的 LLM 应用开发平台，它可以帮助开发者快速构建和运营基于大语言模型的 AI 应用、工作流和知识库。对于开发者而言，在本地环境中部署一套 Dify，可以更方便地进行功能测试、方案验证和二次开发，无需依赖云服务，同时也能更好地保护数据隐私。

本文旨在记录在 Windows 11 系统上，利用 Docker Desktop 的 WSL 2 后端，通过 Docker Compose 方式完整部署 Dify Community Edition 的过程。文章不仅会说明每一步的操作和命令，还会解释关键配置的原理，并详细记录在部署过程中遇到的网络问题及其排查与解决方法。

本文适合对 Docker 和 WSL 有基本了解、希望在本地搭建 AI 应用开发环境的开发者。在完整跟随本文的步骤后，您将能够在本地成功运行 Dify，并通过浏览器访问其管理界面，完成管理员账号的初始化。

本文涉及的主要软件及版本如下：

• 操作系统：Windows 11
• WSL：2.7.11.0
• Docker Desktop：4.85.0
• Docker Compose：v5.3.1
• Dify：1.16.1

环境与工具

项目	版本/配置	用途
操作系统	Windows 11	提供 Docker Desktop 的运行环境
WSL	2.7.11.0	为 Docker 提供 Linux 内核支持
Docker Desktop	4.85.0	管理 Docker 镜像和容器
Docker Compose	v5.3.1	编排和启动 Dify 所需的多容器服务
Dify	1.16.1	开源 LLM 应用开发平台
代理软件	SOCKS5/HTTP: 127.0.0.1:10808	用于解决镜像拉取时的网络问题

---

---

实现效果

部署完成后，通过浏览器访问 http://localhost 即可打开 Dify 的页面。完成管理员账号初始化后，可以成功进入 Dify 的中文首页。

通过 docker compose ps 命令检查，可以看到 PostgreSQL、Redis、Weaviate、Dify API、Web、Worker 等核心服务均处于 Up 或 Healthy 状态，表明应用已成功运行。后续可基于此环境进行知识库、工作流和 AI Agent 应用的构建与测试。

准备工作

在开始安装之前，需要确保系统满足以下条件并完成一些基础准备工作。

1. 开启 Windows 虚拟化功能：确保系统已启用 “Windows 虚拟机监控程序平台” 和 “适用于 Linux 的 Windows 子系统”。这是安装和运行 WSL 2 的前提。
2. 充足的磁盘空间：Docker 镜像、容器数据以及 Dify 源码和持久化数据会占用较多空间。建议在空间充足的磁盘（例如 D 盘）上规划好存放目录。
3. 稳定的网络连接：首次部署需要从 Docker Hub 拉取多个大型镜像，需要网络状况良好。
4. 安装 Git：用于从 GitHub 克隆 Dify 项目源码。

为了方便管理和备份，本次部署在 D 盘根目录下规划了以下文件夹：

目录	用途
D:\DockerInstall	存放 Docker 安装包
D:\DockerProgram	Docker Desktop 程序安装目录
D:\DockerData\wsl	Docker 的 WSL 虚拟磁盘和 Linux 容器数据
D:\DockerData\windows	Docker 的 Windows 容器数据（本次未使用）
D:\Dify	Dify 源码、配置和持久化数据

在管理员 PowerShell 中执行以下命令创建这些目录：

New-Item -ItemType Directory -Force -Path "D:\DockerInstall"
New-Item -ItemType Directory -Force -Path "D:\DockerProgram"
New-Item -ItemType Directory -Force -Path "D:\DockerData\wsl"
New-Item -ItemType Directory -Force -Path "D:\DockerData\windows"
New-Item -ItemType Directory -Force -Path "D:\Dify"

创建完成后，为了确保 Docker Desktop 和 WSL 有足够的权限操作这些目录，为 D:\DockerData 和 D:\DockerProgram 授予 Users 组的完全控制权限：

icacls "D:\DockerData" /grant "*S-1-5-32-545:(OI)(CI)F" /T
icacls "D:\DockerProgram" /grant "*S-1-5-32-545:(OI)(CI)F" /T

完整操作步骤

安装 WSL 2

WSL（Windows Subsystem for Linux，Windows 子系统 for Linux）是 Docker Desktop 在 Windows 上运行 Linux 容器所必需的底层环境。它提供了一个轻量级的虚拟化 Linux 内核，让 Docker 引擎可以高效运行。

注意：Docker Desktop Installer.exe 是 Docker 的安装程序，而 WSL 是微软提供的独立子系统功能，二者是不同的，需要分别安装。

（插入图1）

在管理员 PowerShell 中执行以下命令来安装 WSL，并使用 --no-distribution 参数避免额外安装一个 Linux 发行版（如 Ubuntu），从而节省 C 盘空间。

wsl --install --no-distribution --web-download

如果遇到下载速度慢或连接被重置的情况，这是网络波动导致的。保持网络稳定，重新执行上述命令即可继续或完成安装，无需卸载或重置。

安装完成后，重启电脑，然后在 PowerShell 中执行以下命令验证 WSL 是否安装成功。

wsl --version
wsl --status

确认 WSL 版本为 2.7.11.0，默认版本为 2。如果提示"当前计算机配置不支持 WSL1"，可以忽略，因为 Docker Desktop 实际使用的是 WSL 2。

安装 Docker Desktop 到 D 盘

1. 从 Docker 官方网站下载 Docker Desktop Installer.exe，并将其保存到 D:\DockerInstall 目录下。
2. 在管理员 PowerShell 中，执行以下命令进行安装。这里通过参数明确指定了程序目录、WSL 数据目录和 Windows 容器数据目录，确保所有相关内容都集中存放在 D 盘。

Start-Process -FilePath "D:\DockerInstall\Docker Desktop Installer.exe" -Wait -ArgumentList @("install","--accept-license","--installation-dir=D:\DockerProgram","--wsl-default-data-root=D:\DockerData\wsl","--windows-containers-default-data-root=D:\DockerData\windows","--backend=wsl-2")

各参数含义如下：

参数	作用
--installation-dir	指定 Docker Desktop 应用程序文件的安装目录。
--wsl-default-data-root	指定 WSL 2 后端使用的虚拟磁盘和 Linux 容器数据的存储目录。
--windows-containers-default-data-root	指定 Windows 容器数据的存储目录（此配置项为预留）。
--backend=wsl-2	强制 Docker Desktop 使用 WSL 2 作为后端。

安装完成后，从 Windows 开始菜单启动 Docker Desktop。首次启动时，可能会提示登录 Docker Hub，选择右上角的 Skip 跳过即可。

WSL 欢迎页面可以直接关闭，不需要安装额外发行版。

验证 Docker Desktop

Docker Desktop 启动后，需要等待左下角状态变为 Engine running，这表示 Docker 引擎已成功启动并准备好接收命令。在 PowerShell 中执行经典的 hello-world 镜像测试：

docker run hello-world

如果出现 failed to connect to the docker API at npipe:////./pipe/dockerDesktopLinuxEngine 错误，是因为 Docker 引擎尚未完全启动。请等待 Docker Desktop 状态就绪后重试。

成功执行后，会看到 Hello from Docker! 的输出，表示 Docker 能够正常拉取镜像、创建并运行容器，整个环境验证通过。

您也可以通过以下命令确认 Docker Desktop 的版本：

(Get-Item "D:\DockerProgram\frontend\Docker Desktop.exe").VersionInfo.ProductVersion

本次安装的版本为 4.85.0.235549。

部署 Dify 1.16.1

1. 下载固定版本的 Dify 源码

为了确保稳定性，避免 main 分支的持续更新带来的不确定性，本次部署固定到 Dify 的稳定版本标签 1.16.1。在 PowerShell 中执行：

git clone --branch 1.16.1 --depth 1 https://github.com/langgenius/dify.git "D:\Dify"

此命令会将 1.16.1 版本的源码下载到 D:\Dify 目录。--depth 1 参数只克隆最近的提交历史，以加快下载速度。Git 显示 detached HEAD 是固定到版本标签后的正常提示，不是报错。

2. 进入部署目录并创建环境配置文件

Set-Location "D:\Dify\docker"
Copy-Item ".env.example" ".env"

.env 文件包含了 Dify 运行所需的所有环境变量。其中 DIFY_AGENT_API_TOKEN 是 Dify 内部服务（如 Agent）之间通信使用的安全令牌，必须是一个随机且复杂的字符串。执行以下命令生成并替换该令牌：

$token=([guid]::NewGuid().ToString("N")+[guid]::NewGuid().ToString("N")); (Get-Content ".env" -Raw) -replace "(?m)^DIFY_AGENT_API_TOKEN=.*$","DIFY_AGENT_API_TOKEN=$token" | Set-Content ".env" -Encoding UTF8

此文件包含重要密钥，请务必妥善保管，切勿分享。

执行以下命令以验证 Compose 配置文件的正确性：

docker compose config --quiet

命令没有输出，则代表配置通过。

3. 拉取 Docker 镜像

执行以下命令拉取所有必需的镜像：

docker compose pull

在首次拉取时，可能会遇到 failed to resolve reference "docker.io/library/nginx:latest": EOF 或 failed to fetch anonymous token: TLS handshake timeout 等错误。

这些错误不是由 Dify 配置引起的，而是 Docker 守护进程在访问 Docker Hub 的认证服务器或镜像仓库时发生了网络中断或超时。

如果 nginx:latest 能够成功下载，说明代理配置生效。

完成 Dify 镜像下载和启动

重新拉取全部镜像：

docker compose pull

镜像较多且较大，dify-plugin-daemon 单个镜像约 608 MB。下载到接近完成时短暂停留属于最后解压和校验的正常过程。

所有镜像显示 Pulled 后，启动服务：

docker compose up -d

此命令会以后台模式（-d）启动容器。执行成功后，会看到 PostgreSQL、Redis、Weaviate、API、Web、Worker、插件服务、沙箱、代理和 Nginx 等多个容器正在创建和启动。

4. 验证容器状态

使用以下命令检查所有容器的运行状态：

docker compose ps

init_permissions 容器显示 Exited 是正常的，因为它是一个一次性任务，负责初始化文件权限，完成后即退出。PostgreSQL、Redis、Sandbox 等核心服务的健康检查状态应显示为 Healthy。

至此，Dify 的部署步骤已全部完成。打开浏览器访问初始化地址：

http://localhost/install

创建管理员账号后即可进入 Dify 首页。

日常使用命令

启动 Dify

先启动 Docker Desktop，等待 Engine running，然后：

Set-Location "D:\Dify\docker"
docker compose start

浏览器访问：

http://localhost

停止 Dify

Set-Location "D:\Dify\docker"
docker compose stop

查看容器状态

Set-Location "D:\Dify\docker"
docker compose ps

查看日志

Set-Location "D:\Dify\docker"
docker compose logs --tail 100

重新启动

Set-Location "D:\Dify\docker"
docker compose restart

完全停止并移除容器网络

Set-Location "D:\Dify\docker"
docker compose down

docker compose down 默认不会删除 volumes 目录中的持久化数据，但不要添加 -v 参数，避免误删 Docker 卷。

备份重点

至少备份以下两个位置：

D:\Dify\docker\.env
D:\Dify\docker\volumes

建议关闭 Dify 后再复制备份：

Set-Location "D:\Dify\docker"
docker compose stop

备份完成后恢复运行：

docker compose start

不要随意删除：

• D:\DockerData
• D:\Dify\docker\.env
• D:\Dify\docker\volumes

这些目录分别保存 Docker 镜像/容器、Dify 配置密钥和 Dify 业务数据。

问题排查

问题一：WSL 下载速度慢或连接被重置

问题现象

执行 wsl --install --no-distribution --web-download 时，下载进度缓慢，或提示服务器连接被重置。

原因分析

微软的 WSL 下载服务器位于海外，国内网络环境下可能出现连接不稳定或速度较慢的情况。

解决方法

保持网络稳定，重新执行上述命令即可继续或完成安装，不需要卸载任何已有组件。可以使用 --web-download 参数确保从网络获取最新版本。

验证结果

重新执行命令后，下载进度继续推进，最终 WSL 安装完成。

问题二：docker run 提示无法连接 Docker API

问题现象

执行 docker run hello-world 时出现：

failed to connect to the docker API at npipe:////./pipe/dockerDesktopLinuxEngine

原因分析

Docker Desktop 虽然已经安装，但 Docker 引擎尚未完全启动。

解决方法

打开 Docker Desktop，等待左下角状态变为 Engine running，再重新执行测试命令。

验证结果

docker run hello-world 正常输出欢迎信息。

问题三：拉取镜像时出现 EOF 或 TLS handshake timeout

问题现象

执行 docker compose pull 时出现以下错误：

failed to resolve reference "docker.io/library/nginx:latest": EOF
failed to fetch anonymous token: TLS handshake timeout

原因分析

Docker 守护进程访问 Docker Hub 的认证服务器或镜像仓库时，网络连接被中断或超时。这是国内访问海外镜像仓库时的常见网络问题。

解决方法

在 Docker Desktop 的 Settings → Resources → Proxies 中配置本机代理，地址为 http://127.0.0.1:10808，然后重新执行镜像拉取命令。

验证结果

docker pull nginx:latest 成功，docker compose pull 所有镜像成功拉取。

问题四：镜像下载到接近完成时长时间不动

问题现象

拉取 dify-plugin-daemon 等大镜像时，进度停留在 605 MB / 607.9 MB 等接近完成的状态较长时间。

原因分析

镜像下载完成后，Docker 还需要进行解压和校验，对于数 GB 的大镜像，这个过程可能需要一些时间，属于正常现象。

解决方法

继续等待，不要取消操作。

验证结果

镜像最终显示 Pulled，解压和校验完成。

问题五：init_permissions 容器状态为 Exited

问题现象

执行 docker compose ps 时，init_permissions 容器显示 Exited (0)。

原因分析

init_permissions 是一个一次性初始化容器，负责设置 Dify 数据目录的文件权限。任务完成后即正常退出，这是预期行为。

验证结果

无需处理。确认 PostgreSQL、Redis、Sandbox 等核心服务显示 Healthy 即可。

常见问题

1. 为什么安装 Docker 前需要 WSL？

Docker Desktop 在 Windows 上运行 Linux 容器时，需要借助 WSL 2 提供的轻量级 Linux 内核环境。没有 WSL，Docker 无法正常运行 Linux 容器。

2. Docker Desktop 是否会自动使用 WSL？

安装时通过 --backend=wsl-2 参数强制指定后端，Docker Desktop 默认也会优先使用 WSL 2 后端。

3. 创建目录时是否必须使用管理员权限？

创建目录本身不需要管理员权限，但为目录授予权限以及安装 Docker 和 WSL 需要管理员权限。建议全程在管理员 PowerShell 中操作。

4. Docker 程序和镜像数据能否放到不同磁盘？

可以。本次部署通过安装参数将程序安装在 D:\DockerProgram，数据存放在 D:\DockerData，实现了程序与数据的分离。

5. Docker Desktop 没有启动时为什么无法执行 docker run？

docker 命令需要与 Docker 守护进程通信，而守护进程随 Docker Desktop 启动。Docker Desktop 未启动时，任何 docker 命令都无法执行。

6. 拉取镜像失败后是否需要重新安装？

不需要。拉取镜像失败通常是网络问题，重新执行 docker compose pull 或先拉取单个镜像测试即可。

7. docker compose pull 中断后能否继续？

可以。docker compose pull 是幂等的，已经下载完成的镜像层不会重新下载，重新执行会从中断处继续。

8. 如何检查 Dify 的容器是否全部启动？

使用 docker compose ps 命令查看容器状态，核心服务应显示 Up 或 Healthy。

9. 为什么 init_permissions 容器显示 Exited？

这是正常的。该容器是一次性任务，完成初始化后即退出。只要其他核心服务正常运行即可。

10. 修改环境变量后为什么需要重新创建容器？

环境变量在容器创建时注入。修改 .env 文件后，需要执行 docker compose up -d 重新创建容器才能使新配置生效。

11. 如何正常停止和重新启动 Dify？

停止使用 docker compose stop，重新启动使用 docker compose start。如需完全重建，可使用 docker compose down && docker compose up -d。

12. 如何备份 Dify 的配置和数据？

备份 D:\Dify\docker\.env 和 D:\Dify\docker\volumes 目录即可。建议先停止 Dify 服务再备份，避免数据不一致。

总结

本文完整记录了在 Windows 11 系统上，利用 Docker Desktop 的 WSL 2 后端，通过 Docker Compose 方式部署 Dify 1.16.1 的整个过程。核心技术路线包括：安装 WSL 2、将 Docker Desktop 程序与数据分离安装、通过 Git 克隆固定版本源码、配置环境变量、拉取镜像并启动容器。

最终验证了 Docker 基础环境运行正常、所有 Dify 必需镜像成功拉取、核心容器健康检查通过，并且能够通过浏览器访问并完成 Dify 管理员初始化。整个部署过程中最容易出错的环节是 Docker Hub 镜像拉取时的网络问题，通过配置代理得以解决。

后续可以在此基础上进一步完成以下工作：接入第三方 LLM API 密钥、创建知识库、设计工作流以及构建 AI Agent 应用。Docker 在这里扮演的是 AI 应用的运行平台，而真正的目标是能够利用 Dify 快速构建自己的 AI 应用。

参考资料

1. Microsoft WSL 官方文档：https://learn.microsoft.com/zh-cn/windows/wsl/
2. Docker Desktop 官方文档：https://docs.docker.com/desktop/
3. Dify 官方文档：https://docs.dify.ai/
4. Dify GitHub 仓库：https://github.com/langgenius/dify

版权说明

本文根据个人实际安装、部署和排错过程整理。不同系统版本、软件版本和网络环境下的操作结果可能存在差异，请以实际环境和官方文档为准。