简介：面向Windows开发者的Dify Hackathon安装部署教程文档，适合熟悉Git、Docker和Python、希望快速搭建Dify本地环境并参与Hackathon的技术人群。资源为1个docx文件，压缩包仅15KB，以文字步骤和命令说明为主。教程覆盖Windows 10/11下的完整部署流程：前置环境准备（Git、Docker Desktop、Python 3.10+安装及PATH配置）、克隆dify仓库、复制环境变量文件并修改数据库与API Key、通过docker-compose up -d启动服务、初始化数据库、访问localhost:3000验证登录。同时针对Docker启动失败、端口占用、服务无法访问三类常见问题给出排查思路，如检查Hyper-V/WSL 2、修改端口映射、查看容器日志等。文末还补充了Hackathon后续操作，包括应用创建、模型集成、插件开发以及服务停止和更新版本命令。目前已有122人学习，适合需要系统性部署指南和排错参考的开发者。 Dify这名字，最近在Hackathon圈子里出现的频率越来越高。我自己也数不清参加过多少场AI主题的创客马拉松了，几乎每一次，都能看到有人卡在环境搭建这一步：代码拉不下来、Docker跑不起来、模型接不上，比赛刚开始，人就先焦虑了。所以这次我想把Windows下安装部署Dify的完整流程好好写一篇，从一台普通的Windows电脑出发，一步步把平台跑起来，同时把Hackathon现场最实用的备份、提速手法也一并放进来。不管你是第一次装Dify，还是之前在Linux上部署过、现在想在本地Windows环境搭一套开发机，这篇都能直接照着操作。
1. 赛前准备：Windows上跑Dify的方案选型
1.1 为什么我坚持用Docker Desktop + WSL2
Dify官方提供的部署方式以docker compose编排为主，默认跑的就是Linux容器，Windows没办法直接裸跑。市面上的方案有好几种：用传统的Hyper-V或VirtualBox开一台Linux虚拟机再装Docker，或者用WSL2做后端让Docker Desktop直接调度Linux容器，还有一种是在Windows本地硬把API和Web端源码跑起来，但这种方案依赖项多、版本冲突频繁，Hackathon现场非常不推荐。
我个人的经验是：用WSL2 + Docker Desktop这条路最省心。它启动快、资源占用低，命令行操作顺手，而且WSL2的文件系统和Windows互通，改配置、传模型文件都很方便。实测下来，从零开始到进入Dify初始化页面，在稳定的网络下大约十来分钟。反观传统虚拟机方案，光是系统初始化、换源、装Docker就意味着至少多出半个小时的等待，比赛场景下这半小时是致命的。
我整理过一个简单的方案对比表，供你选择时参考：
| 方案 | 优点 | 缺点 |
|---|---|---|
| WSL2 + Docker Desktop | 启动快、资源占用低、和Windows文件互通 | 依赖WSL2内核更新，Win10需要手动装补丁 |
| 虚拟机 + Linux + Docker | 隔离性最强，最接近生产服务器 | 启动慢、占内存、需要准备系统镜像 |
| Windows本地直接跑源码 | 不用Docker，纯Windows进程 | 依赖Python/Node版本太多，环境冲突几率极高 |
1.2 硬件要求与依赖清单
别想着用太丐的配置跑Dify。我实际跑下来，Dify容器全家桶大概占用8GB左右内存，后台再开着浏览器、IDE、微信之类的，16GB内存的机器会比较紧张，32GB才称得上舒服。CPU四核以上基本够用，磁盘至少留20GB空闲空间，因为镜像加数据卷会持续膨胀。系统方面，Windows 10或11都可以，但必须确认BIOS里已经开启了虚拟化。你在任务管理器里看一眼“性能”页签，如果“虚拟化”显示“已启用”，就说明没问题；如果显示“已禁用”，得先重进BIOS打开VT-x或AMD-V，不然WSL2根本起不来。
依赖清单很简单，只有三样：Git用于拉取源码，Docker Desktop是核心运行环境，Windows Terminal（可选）会让命令操作舒服很多。浏览器随便，Chrome、Edge都可以。
2. 环境搭建：从裸机到Docker可用的完整过程
2.1 三步启用WSL2
这一步是问题高发区，但原理不复杂。WSL2本质上是Windows下的一个轻量虚拟机，它需要一个叫“虚拟机平台”的Windows功能支撑。你先以管理员身份打开PowerShell，执行下面两条命令：
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart执行完重启系统。接着安装WSL2内核更新包，如果你是Windows 10，这一步很关键；Windows 11通常已经带了，但如果wsl --version命令报错，同样需要补装。最后执行：
wsl --set-default-version 2验证方式很简单：运行wsl -l -v，看输出里的“VERSION”列是不是2。如果是1，用wsl --set-version <发行版名> 2手动升级。这里我踩过一个坑：Windows 10上没装内核更新包就强行设默认版本2，结果Docker Desktop反复报“WSL register distribution failed”，装了补丁重启后才恢复正常。
2.2 Docker Desktop初始化与镜像加速配置
下载Docker Desktop安装包后，一路下一步即可，但安装过程中有一个关键勾选项：Use WSL 2 based engine，这个务必勾上。首次启动之后，进入Settings → Resources → WSL Integration，把你常用的WSL发行版（比如Ubuntu）打开，这样在WSL终端里也能直接用docker命令。
接下来是镜像加速配置。Dify要拉取的镜像数量不少，默认的Docker Hub地址在国内网络环境下经常卡住，Hackathon现场人多带宽挤，更容易拉取超时。在Settings → Docker Engine里，把registry-mirrors字段加到JSON配置中，填入你所在网络环境可用的加速地址。这个地址会随服务商调整，我建议赛前几天在自己电脑上先实测一次，能用哪个填哪个，不要等到了现场再临时换。
配置完成后重启Docker Desktop，跑一个docker run hello-world验证环境。能看到Hello from Docker输出，说明整条链路已经通了一半。
3. Dify部署实操：源码拉取、配置与启动
3.1 克隆源码并生成.env配置
选一个你记得住的工作目录，比如C:\dev，打开终端执行：
git clone https://github.com/langgenius/dify.git cd dify/docker为什么一定要进入dify/docker目录？因为Dify把docker-compose.yaml、.env.example这些编排相关文件都放在这里，它和应用源码是分离的。部署时只需要关心这个docker目录即可。
目录里有个.env.example文件，复制一份命名为.env：
cp .env.example .env然后编辑.env，重点改这三项：
- EXPOSE_NGINX_PORT：默认80，如果本机80端口已经被占用，改成8080或18080。
- SECRET_KEY：用openssl rand -base64 42生成一串随机值填进去，别用默认值。
- POSTGRES_PASSWORD：换成自己的强密码。
这里有个很细节的坑：.env文件不要加中文注释，也不要保存成带BOM的UTF-8格式，否则部分版本的Docker Compose解析会报错。我的习惯是用VS Code改完文件后，顺手在终端跑一次docker compose config，如果命令能正常打印出配置内容，说明文件没问题。
3.2 启动容器并完成管理员初始化
在dify/docker目录下执行：
docker compose up -d第一次启动会拉取api、web、nginx、postgres、redis、weaviate等一堆镜像，时间取决于网络。如果中途拉取失败，直接再执行docker compose pull补一次，然后重新up即可，不丢人，网络波动是常态。
启动完成后执行docker compose ps，看到所有服务状态都是Up，就可以打开浏览器访问了。默认地址是http://localhost/install，如果你改过端口就是http://localhost:8080/install。页面会要求设置管理员邮箱和密码，这个页面只在首次访问时出现，设置完会自动跳转到登录页。
登录进入主界面后，你看到的是空空如也的Dify后台，下一步必须把模型接进来，这平台才能真正开始干活。
3.3 接入模型供应商并跑通第一个应用
点击右上角头像 → 设置 → 模型供应商，选择你习惯用的模型服务商，填入API Key。这里我强烈建议：Hackathon现场务必提前准备至少一个额度充足、能正常访问的API Key，现场临时注册和充值，时间成本完全不可控。
模型配置好以后，点击“创建应用”，选聊天助手类型，把刚才配置的模型加进去，随便发一句话验证链路。能正常回复，说明Dify已真正可用。
如果你想跑一个更贴合比赛场景的Demo，可以创建一个“工作流”应用，拖几个节点组成完整链路：用户输入 → 知识库检索 → LLM生成回答。整个过程基本是可视化拖拽，不需要写一行代码，我第一次用时十分钟就搭出了一个能检索本地文档的问答Agent。Hackathon比的是想法和执行力，Dify把底层工程细节都藏起来了，正好适合快速迭代功能原型。
4. Hackathon现场最容易踩的5个坑
4.1 WSL2或Docker启动失败
现场最常见的状况是Docker Desktop一直转圈，或者提示Docker engine stopped。先别急着重启，打开终端执行wsl -l -v，看WSL状态是否正常。如果版本是1或没有发行版，用wsl --set-default-version 2强制切换，并检查是否符合第2章说的内核更新包已安装。
另一个典型的隐蔽问题：部分公司电脑预装的安全软件会把WSL相关服务拦截掉，导致Docker Desktop无法启动WSL后端。判断方法是换一个没有此类安全软件干扰的网络环境，或者临时关闭相关策略测试。不过比赛现场往往没有条件折腾，所以在正式比赛用的那台电脑上提前跑通全流程，比什么都重要。
4.2 端口被占用导致无法访问
浏览器访问http://localhost/install没反应，第一件事确认端口状态：
netstat -ano | findstr :80如果返回一个LISTENING的PID，说明80端口被别的程序占了。最简单的方法是改.env里的EXPOSE_NGINX_PORT，比如改成8080，然后docker compose up -d重建容器。注意修改.env后一定要让容器重建，配置才会生效。
我的习惯是赛前直接把端口改成8080。因为很多本地开发工具默认都爱占80端口，与其到了现场和别人排查冲突，不如从一开始就避开。
4.3 内存不足导致容器反复重启
Dify全家桶容器全跑起来内存占用大概8GB，如果你的机器只有16GB，后台再开浏览器和IDE，Windows会开始启用大量换页，容器运行就会不稳定。典型表现是页面一会儿能开一会儿报500，docker compose ps里看到某个容器反复显示RESTARTING。
解决思路有三个：第一，在Docker Desktop的Settings → Resources里把Memory调到8192MB以上；第二，通过.wslconfig文件给WSL2限制整体使用上限，避免和其他程序抢内存；第三，现场临时不需要的功能可以先停掉，比如不跑定时任务时把worker容器暂时停掉，能省下一部分内存。
4.4 模型API连接失败
模型配置好，但聊天时一直报连接错误。先按这个顺序排查：API Key是否正确，账户是否有余额，模型服务是否正常；本机能否正常访问对应的模型服务；在Dify模型供应商配置页测试时是否提示成功。
如果是自定义Endpoint接入，注意URL一定别填错，很多模型服务要求填写完整的/v1或/v1/chat/completions地址，而不是只写到域名根路径。曾经见过队友填成了根地址，结果Dify一直报404，白白折腾了二十分钟。
4.5 队友无法通过局域网访问
比赛通常是一个团队共用一个部署环境，让队友访问你电脑上的Dify时，最常遇到的是防火墙拦截。以管理员身份打开PowerShell，执行：
netsh advfirewall firewall add rule name="Dify" dir=in action=allow protocol=TCP localport=80如果你改了端口，把localport改成对应值。然后在队友电脑浏览器输入http://你的IP:端口/install。如果还是不通，用ping命令确认两台机器在同一网段，同时检查路由器是否开启了AP隔离。
另外提醒一点：多人同时修改同一个应用容易互相覆盖，我给团队的建议是各自创建独立应用，最后演示时再合并展示，避免冲突。
5. 比赛提速的3个私藏技巧
5.1 赛前预拉镜像并离线备份
Hackathon现场的网络质量谁也说不准。赛前一天，在稳定的网络下进入dify/docker目录，执行一次docker compose pull，把全部镜像拉到本地，确认无误后再跑一次docker compose up -d验证环境完整。更进一步的做法是挑一台机器打包镜像：
docker save -o dify-images.tar <镜像列表>把生成的tar文件拷到U盘，现场用docker load -i dify-images.tar导入。这个方法特别适合需要在两台电脑间迁移的情况，我在一次比赛里就是靠一个U盘把整套环境从家里电脑搬到了比赛机器，省去了现场几十倍时间。
5.2 用DSL模板一键复现应用
Dify里每个应用都能导出DSL文件，这是一个JSON格式的完整应用配置，包含工作流、节点设置、知识库关联等信息。我的习惯是赛前做一个通用模板：一个带知识库检索的问答Agent，导出保存。比赛现场如果需要，直接点“导入DSL文件”，应用就能秒级重建，完全不用从头拖工作流。
这个技巧在多个队友并行的场景特别有价值。每个人只需要导入同一份模板，再在自己的应用上做差异化修改，很快就能产出好几个可演示的雏形。
5.3 给版本上锁并做好升级计划
比赛现场最忌讳临时升级。Dify的迭代速度很快，部分版本之间compose编排、环境变量名都有调整，升级前不看变更说明贸然操作，轻则配置失效，重则数据库迁移报错。我的做法是：赛前确认一个稳定版本后，用git tag或者固定commit记录版本号，比赛期间一律不升级。如果确有必要升级，也要先备份数据库和docker目录，再按官方文档步骤操作。
数据库备份一条命令就够了：
docker exec <postgres容器名> pg_dump -U postgres dify > backup.sql比赛过程中就算应用配置被队友改乱，只要有备份就能快速回滚，这个习惯能让你在高压环境下保持从容。
最后分享一个我自己真实踩过的坑，也算整篇文章最想强调的一点：部署Dify最关键的不是命令敲得有多快，而是提前把现场不可控因素全部排掉。赛前花一晚上在目标电脑上完整跑通一遍，把镜像、DSL模板、数据库备份三样东西准备好，现场你的任务就从“安装部署”变成了“导入启动”。我见过太多队伍把宝贵时间浪费在环境搭建上，而真正优秀的产品原型，都是在稳定环境里迭代出来的。希望这篇教程能帮你把时间花在创意和功能上，而不是和Docker搏斗。
本文还有配套的精品资源，点击获取
