Windows部署Dify参赛指南：Docker Desktop与WSL2避坑全流程

简介：面向具备一定编程基础、熟悉 Git / Docker / Python 的开发者，这份 Windows 下 Dify Hackathon 安装部署教程，解决在本地快速搭建 Dify 大语言模型应用开发环境的问题。教程以 docx 文档形式呈现，共 1 个文件、压缩包约 15KB，内容按前置环境准备、代码克隆、环境变量配置、服务启动、数据库初始化、安装验证的顺序编排，并附有 Docker 启动失败、端口占用、服务无法访问等常见问题的排查方法。文中还给出了应用创建、自定义模型集成、插件扩展及参与 Hackathon 开发等后续操作建议。相比零散的网络资料，这份教程将完整部署流程与排错思路集中在一份文档中，读者可对照步骤逐步执行，降低 Windows 环境下安装 Dify 的试错成本。目前已有 125 人学习下载，适合正在准备或参与 Dify Hackathon 的技术爱好者使用。

1. Windows 下部署 Dify 参加 Hackathon：先装对 Docker Desktop，再谈其他

如果你正在准备 Dify Hackathon，搜到这个标题，大概率已经在 Windows 笔记本上被安装部署折腾过几轮了。我的建议很直接：别急着 clone 源码、在本机装 Python 和 Node 去裸跑前后端，那是一条最容易让人在比赛前一天弃赛的路。在 Windows 上做 Dify Hackathon 的环境准备，最怕卡在安装部署这一步，而最短路径其实是 Docker Desktop 的 WSL2 后端配合官方 docker 目录里的 docker-compose.yaml。下面按「准备环境 → 启动服务 → 参赛前必调 → 现场排错 → 验证备份」的顺序一步步走，正常网络条件下，15 到 20 分钟能从空环境跑到浏览器里创建第一个应用。这篇内容适合第一次装 Dify 的参赛者，也适合想在本地把 Dify 摸熟再做 demo 的开发者。

2. Dify 安装部署的 Windows 前置：Docker Desktop 与 WSL2 的参数选型

Dify 没有原生 Windows 安装包，官方提供的是 docker compose 部署方式。它的编排里包含 api、worker、web、db（PostgreSQL 15）、redis、weaviate、sandbox、ssrf_proxy 和 nginx 等十几个容器。这些容器通过内部网络互相通信，全部依赖 Docker 引擎。Windows 上 Docker 引擎靠不靠谱，基本由两件事决定：后端选 WSL2 还是 Hyper-V，以及 Docker Desktop 的资源分配。很多人把后面的报错全部归咎于 Dify，其实 80% 的问题出在这一层。

2.1 为什么选 Docker Desktop 4.x + WSL2 后端，而不是 Hyper-V

Docker Desktop 在 Windows 上支持两种后端。WSL2 后端把 Docker 跑在轻量级虚拟机里，内存动态分配、启动快，还能直接读写 Windows 文件系统；Hyper-V 后端则是一整台独立的虚拟化平台，启动慢、资源占用高，和很多学校或赛场的旧电脑不兼容。Dify 这个编排有十几个容器，内存动态分配意味着 8GB 内存的机器也能跑起来。

先确认系统条件：Windows 10 2004（20H1）及以上，或 Windows 11。接着在 PowerShell 里检查虚拟化是否开启：

systeminfo | findstr /i "Hyper-V"

输出里有“已检测到虚拟机监控程序”或“虚拟化已启用”这类字样，说明硬件虚拟化没问题。如果公司电脑被组策略锁死了 Hyper-V，或者是在虚拟机里套虚拟机，Docker Desktop 基本装不上，建议先解决环境问题再谈 Hackathon。

确认没问题后安装 WSL2。Windows 11 和较新的 Windows 10 直接一条命令：

wsl --install -d Ubuntu-22.04

这条命令会启用 Windows 子系统、启用虚拟机平台、安装 WSL2 内核并装上 Ubuntu 22.04。装完重启电脑，Ubuntu 首次启动会让你建用户名密码。Dify 部署过程中并不需要你会用 Ubuntu，它只需要 WSL2 的后端存在即可，Ubuntu 只是这个后端里的最小系统。

2.2 安装后必改的三个设置：镜像源、镜像盘位置、内存上限

Docker Desktop 装好后，第一件事不是急着拉 Dify。先打开 Settings，做三处修改。

先改镜像加速。Docker Hub 在国内访问经常超时，拉 Dify 那 2GB 镜像会卡到怀疑人生。打开 daemon.json，加入 registry-mirrors：

{ "registry-mirrors": [ "https://docker.m.daocloud.io" ] }

这个地址不是永久有效的，填完在 Docker Desktop 里点 Apply & Restart。如果后续 docker compose up 时仍卡在 pull 阶段，就换一个当前可用的公共加速源。注意 daemon.json 改动后不会立刻生效，右下角 Docker 图标会重新启动一次。

第二个设置是镜像盘位置。Docker 默认把虚拟磁盘放在C:\Users\<用户名>\AppData\Local\Docker，一套 Dify 镜像加容器和数据大概 8 到 12GB，C 盘紧张的话很容易把系统盘塞满。在 Disk image location 里把它挪到 D 盘或移动硬盘。这个动作会复制现有镜像，第一次切换耗时较长，建议趁还没拉 Dify 镜像时就去改。

第三个是内存上限。Resources > Advanced 里的 Memory 默认可能只有 2GB，Dify 的 weaviate 向量库和 api 容器同时跑时，2GB 完全不够。我一般直接拉到 6GB 到 8GB，CPU 至少 4 核。比赛笔记本如果只有 8GB 内存，就关掉浏览器多余标签页，把所有余量让给 Docker。这个资源分配直接决定后面知识库索引会不会中途挂掉。

2.3 验证环境的三条命令与常见误判

环境配没配好，不要靠感觉，用三条命令验证。在普通 PowerShell 或 CMD 窗口里依次执行：

docker version docker compose version wsl --status

docker version 看 Server 段，如果 Server 下面没有内容，说明 Docker Desktop 引擎没起来；docker compose version 确认 compose 插件版本，Docker Desktop 4.x 自带；wsl --status 里出现“默认版本: 2”才算 WSL2 生效。一个常见误判是只看到 Client 段就以为 Docker 可用，实际容器根本起不来。

另一个常见误判是：在 WSL 发行版里自己又装了一套 docker。平时在 Ubuntu 终端里执行 docker 命令能用，但回到 Windows 终端就找不到命令。这是两套完全不同的环境。正确做法是只用 Windows 侧安装的 Docker Desktop，WSL 发行版里的 docker 不要装，否则两边抢 daemon，Hackathon 现场很容易手忙脚乱。

3. 用 docker compose 拉起 Dify：clone、改 .env、看日志

3.1 获取安装文件：clone 整个仓库还是只拉 docker 目录

部署 Dify 需要的是官方仓库里的 docker 目录，不是整个前端和后端源码。完整 clone：

git clone --depth 1 https://github.com/langgenius/dify.git cd dify/docker

depth 1 只拉最新一次提交，省时间也省磁盘。如果你还没装 Git for Windows，去装一个，Hackathon 现场要改代码、拉更新，Git 迟早要用。如果只想部署不想拿源码，也可以只下载 docker 目录的 zip，但我不太建议这么做，因为后文讲二次开发时你还是要回到这个仓库。

接下来复制环境变量模板。Linux 和 macOS 用：

cp .env.example .env

Windows 的 CMD 用 copy，PowerShell 用 Copy-Item。这里有个小坑：.env 是隐藏文件，资源管理器里默认看不到，别以为复制失败了。复制完用 notepad .env 打开，进入下一步。

3.2 必改的四个 .env 参数与密钥生成

.env 里面有很多配置项，Hackathon 阶段只需要改四个。

生成 SECRET_KEY 的稳妥方式，在 Git Bash 里执行：

openssl rand -hex 32

没有 openssl 的话，PowerShell 也能凑：

-join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Max 256) })

把输出的一长串字符原样填进 SECRET_KEY。两个数据库密码直接设成一个顺手的长密码。改完保存。为什么这套要提前做？因为 Dify 第一次启动时容器会按 .env 初始化数据库，之后再改密码会和新容器对不上，反而增加排查成本。

这里提醒一句：改完 .env 后，要用 docker compose up -d 重新创建容器才能让新环境变量生效。只执行 docker compose restart 不会重新读取 .env，这是新手最容易踩的坑。

3.3 启动、检查健康、关闭再启动的命令

在 docker 目录下执行：

docker compose up -d

第一次执行会把所有镜像拉下来，总量大概 2GB 左右。网络好时几分钟，网络不好就盯着终端看它卡在哪一个镜像。拉完后容器创建，进入等待就绪阶段。

docker compose ps

这个命令看每个容器的状态。理想情况是 api、worker、web 都是 Up，db 显示 healthy。如果 api 一直在 restarting，别急着删掉重来，先看日志：

docker compose logs -f api

日志里出现 PostgreSQL connection refused，多半是 db 容器还在初始化，等一下再看；出现 password authentication failed，回 3.2 检查密码。全部就绪后，访问http://localhost:8080（或你填的 EXPOSE_NGINX_PORT），第一次打开会进入管理员账号创建页，邮箱密码填完就进工作台了。能点开“创建应用”，部署就成功了。

关闭和再次启动也有固定套路。docker compose stop 只是停容器，数据还在；docker compose start 再启动；docker compose down 会删容器但保留卷里的数据。Hackathon 比赛期间，别动不动 down -v，那个会把库和数据一起清掉。

4. 参赛前一天必调的四处配置：端口、Ollama、知识库与二次开发

4.1 把默认 80 端口让出来：Hackathon 现场的网络冲突

比赛场地通常是同一个 Wi-Fi 下几十台电脑。80 端口是 HTTP 默认端口，很多公司内网或现场网络会对它做拦截或冲突，后台演示时也会因为其他设备占用给自己找麻烦。把端口改成不常用的高位端口最省心。回到 .env 修改 EXPOSE_NGINX_PORT=8088，然后重新应用：

docker compose up -d

不要用 docker compose restart，必须 up 才会重建 nginx 容器。如果提示端口被占用，先找到占用进程：

netstat -ano | findstr :8088

最后一列是 PID，再用 taskkill /PID /F 结束。注意只改宿主机映射端口，别动容器内部的 80。另外，Windows 防火墙弹窗询问是否允许 Docker 通信时，要选“允许”，否则浏览器能打开但 API 一直连不上。

4.2 零成本接入本地大模型：Ollama 的 host.docker.internal 与 credentials validation 排查

Hackathon 现场没有 OpenAI Key 或不想被 API 费用卡住，本地大模型是最实用的备选方案。先在本机装 Ollama，拉一个够用的模型：

ollama pull qwen2.5:7b ollama serve

Ollama 默认只监听 127.0.0.1，这在桌面端用没问题，但 Dify 是容器，访问不到宿主机回环地址。所以要把监听地址放开：

setx OLLAMA_HOST "0.0.0.0"

重启 Ollama 后，在 Dify 左侧“设置 > 模型供应商”里找到 Ollama。关键参数如下：Model Type 选 LLM，Model Name 填 qwen2.5:7b，Base URL 填http://host.docker.internal:11434。host.docker.internal 是 Windows 下 Docker Desktop 内置的宿主机域名，容器内用它访问 Windows 本机服务。如果用 Linux 就要换成 host-gateway，Windows 用户直接无脑用 host.docker.internal。

填完点保存，如果报 “An error occurred during credentials validation”，按这三条顺序查：第一，Base URL 里是不是写了 localhost，改成 host.docker.internal；第二，Ollama 有没有监听 0.0.0.0，用 netstat -ano | findstr :11434 确认；第三，Windows 防火墙是否拦了 11434 端口，去“允许应用通过防火墙”里把 Ollama 放行。绝大多数本地模型验证失败都出在这三条，Dify 侧的配置反而是最不容易出错的。

4.3 知识库流水线参数与“工作流上下文超长”的解法

Dify 的知识库处理链路可以理解成一条流水线：上传文档 → 分段与清洗 → Embedding → 写入向量库。比赛 demo 里最常见的翻车是把整本 PDF 直接丢进知识库，然后工作流里把检索结果全部拼给大模型，报“上下文超长”。问题不在 Dify，在分段和召回参数。

创建知识库时，“分段设置”里有三项值得改：分段长度，默认 500 Token，代码和表格多的文档改成 250 到 300，避免切到语义半截；分段重叠，默认 50，如果答案经常丢上下文就调大到 80；检索模式，比赛问答场景选“混合检索”最稳，纯向量检索对同义改写不友好。

工作流里的“知识检索”节点也要调。召回条数默认 3，如果你的文档分段特别多，调成 2 就能显著减少塞给大模型的 Token 量。LLM 节点的高级设置里，把“上下文”窗口和“历史消息”轮数显式设小。很多人没改过这里，模型默认窗口和真实值对不上，上下文超长就是这么来的。Hackathon 演示时，人为控制喂给模型的文本量，比指望模型自己截断靠谱得多。

4.4 二次开发的两种启动方式：挂载源码与本地进程

Dify Hackathon 经常要改后端逻辑。第一种常见做法是源码挂载进容器。编辑 docker 目录下的 docker-compose.yaml，在 api 服务里加一段卷映射：

services: api: volumes: - ../api:/app/api

改完执行 docker compose up -d api，宿主机上的 api 源码就覆盖了容器内代码。这里严格要求宿主机代码分支和镜像版本一致，省事的话直接 clone 同一 commit。之后每次改完源码，重启 api 容器生效。这个方案改动最小，适合不想折腾本机环境的人。

第二种是本地起 API 进程。先进入仓库 api 目录，建虚拟环境、装依赖：

python -m venv venv source venv/Scripts/activate pip install -r requirements.txt

然后配置连接参数，让它复用 compose 里的 PostgreSQL 和 Redis：

$env:DATABASE_URL="postgresql://postgres:你的密码@localhost:5432/dify" $env:REDIS_URL="redis://localhost:6379/0"

最后启动调试进程：

flask run --host 0.0.0.0 --port 5001

本地起进程适合要大改 LLM 节点逻辑的团队，调试速度比改容器内代码快。但要注意本地依赖和镜像版本如果对不上，会出现数据库模型迁移报错。这两种方式我都跑过，前者适合赶时间，后者适合深度二次开发，别把两套方式混着用。

5. 避坑清单：Windows 装 Dify 最容易翻车的 5 个现场问题

5.1 api 容器不断 restarting，日志里是数据库连接失败

现象：docker compose ps 里 api 和 worker 一直在 restarting，logs 里反复出现 connection refused 或 password authentication failed。

原因：第一类是首次启动时 PostgreSQL 初始化还没完成，api 启动前十几秒连不上很正常；第二类是 .env 里 POSTGRES_PASSWORD 和 DB_PASSWORD 没填一致，或者数据库密码带了 #、& 这类特殊字符，被 .env 解析截断，容器里实际读到的密码和初始化用的对不上。

解决：先看 db 状态，确认 healthy 后强制重建 api：

docker compose up -d --force-recreate api worker

再不行，确认数据不重要时用 down -v 清掉 volume 重来一次。注意 down -v 会把账号和知识库全部删掉，只适合还没正式使用的时候。

5.2 页面白屏或 502：先查 api，再清浏览器缓存

现象：浏览器能打开 Dify 地址，但页面白屏，或登录后一直转圈，网络面板里 API 请求 502。

原因：web 是静态文件容器加 nginx，它代理到 api 容器。api 没起来，前端还能加载但拿不到数据。这不是前端问题，是后端容器的问题。

解决：先按 5.1 把 api 弄健康，再强制刷新浏览器 Ctrl+F5。如果改了 EXPOSE_NGINX_PORT，还要确认访问地址用的是新端口，旧端口 80 在新环境里可能指向别人的机器。

5.3 “dify ssl错误”与 credentials validation：证书链与地址协议

现象：配置模型供应商时，Base URL 填了内网或自建网关的 https 地址，报 “An error occurred during credentials validation”，控制台提示 SSL 相关错误。

原因：自建网关用的是自签证书，证书链不完整，Dify 容器内的信任库不认；另一个常见原因，是把 https 地址填给了一个只支持 http 的服务。

解决：先用 http 测试，把地址改 http 后如果能通过，就确认 HTTPS 证书链。补证书链需要证书签发方提供完整 CA 包，现场往往拿不到。实战里最省事的做法是直接用本地 Ollama，前面 4.2 的 host.docker.internal 方案能绕开所有证书问题。

5.4 出现 non-elevated terminal 的 docker daemon 启动报错

现象：在某个终端执行 docker 命令，报 “error: start the windows daemon from a non-elevated terminal; shared clients” 一类的启动错误，Docker Desktop 图标却是正常的。

原因：Docker Desktop 本身不需要管理员权限运行，但如果你在管理员终端里执行 docker 命令，Windows 会把 CLI 拉起一个新的 daemon 上下文，和已有的 desktop-linux 上下文冲突。这个情况常见于 VS Code 集成终端继承了管理员权限。

解决：打开普通 PowerShell（非管理员）执行：

docker context ls docker context use desktop-linux

然后完全退出 Docker Desktop 再启动，终端也要新开。以后养成习惯，日常操作 docker 一律用普通终端，管理员终端只在排查特殊情况时用。

5.5 知识库索引一直卡住：weaviate 被 OOM 杀掉

现象：创建知识库后，文档一直显示“待处理”或“索引中”，docker compose ps 里 weaviate 反复重启。

原因：weaviate 是向量数据库，内存占用不低。Docker Desktop 只分给 2GB 内存时，系统会 OOM kill。大文档分段后一次性写入，内存直接打满。

解决：用 docker stats 看各容器内存占用；在 Docker Desktop 的 Resources > Advanced 里把内存拉到 6GB 以上；然后单独重启 weaviate：

docker compose up -d weaviate

如果机器内存实在有限，就把文档分段长度调小，减少单批写入体积。Hackathon 现场出现这个坑，多数是赛前只顾着装 Dify，没给 Docker 分够内存。

6. 赛前验证与数据备份：20 分钟确认环境能撑到答辩

6.1 一条健康自查命令

答辩前的晚上，我用一条命令确认环境还是好的。在普通 PowerShell 里执行：

echo "---- 容器状态 ----"; docker compose ps; echo "---- API 健康 ----"; curl.exe -s -o NUL -w "%{http_code}`n" http://localhost:8080/health

curl.exe 返回 200 说明 API 活着。这里有个 Windows 细节：PowerShell 里 curl 默认是 Invoke-WebRequest 的别名，要用 curl.exe 才是真正的 curl。如果在 Git Bash 里跑，把 NUL 换回 /dev/null。接着在页面上把报名要演示的应用完整跑一遍，用户提问、返回回答、知识库引用一条不落。20 分钟能全部走通，比赛当天就不会在台上被环境问题拖垮。

6.2 用数据卷打包做后悔药

Dify 的数据主要落在两个数据卷里：PostgreSQL 卷存用户、应用配置和工作流，weaviate 卷存向量索引。备份前先查实际卷名：

docker volume ls | findstr postgres

查到的卷名可能带项目名前缀，以实际输出为准。然后打包 PostgreSQL 卷：

docker run --rm -v dify_postgres:/data -v "${PWD}:/backup" alpine tar czf /backup/dify_postgres_backup.tar.gz -C /data .

恢复时反向解包：

docker run --rm -v dify_postgres:/data -v "${PWD}:/backup" alpine tar xzf /backup/dify_postgres_backup.tar.gz -C /data

恢复完 docker compose up -d 重启容器。这个 tar 包拿到新电脑上解包，就是官方没有单独给的“迁移”方案。日常升级 Dify 前也先打这个包，再 docker compose pull && docker compose up -d，新版出问题还能回滚。社区版后续版本加的多租户体系，比赛单人场景完全用不到，别在上面花时间。我吃过一次没备份就重建的亏，从那以后每次动环境前先打一个卷备份。希望帮到你。

本文还有配套的精品资源，点击获取