简介面向具备一定编程基础、熟悉Git、Docker及Python的开发者这是一份Windows系统下Dify Hackathon安装部署教程系统讲解如何在Windows 10/11环境中从零搭建Dify开源大语言模型应用开发平台。作为一个开源平台Dify适合快速构建人工智能应用在Hackathon黑客松场景中可用于原型开发与调试。内容涵盖前置环境准备、克隆代码仓库、配置环境变量、使用docker-compose启动服务、初始化数据库及浏览器访问验证并给出Docker启动失败、端口占用、服务无法访问等高频问题的排查思路。后续还补充了创建AI应用、集成自定义模型、参与Hackathon开发等建议。资源为单个Worddocx文档压缩包大小仅15KB便于保存和快速查阅全文以步骤命令、关键配置说明及验证方式为主适合本地实践时对照操作。现已累计125人学习下载适合需要快速搭建Dify开发环境并参加Hackathon的技术爱好者。1. Windows下Dify Hackathon安装部署先搞定环境再谈做应用参加Windows环境下的Dify Hackathon第一天最容易浪费在环境搭建上。Dify本身是开源LLM应用开发平台后端核心是Flask服务前端是Next.js整体由Docker Compose编排起来如果只把它当普通Python项目直接跑忽略容器网络、环境变量和端口映射后面会翻车翻得莫名其妙。这篇笔记按我在Windows上把Dify本地部署跑通的过程来写覆盖Docker Desktop配置、源码拉取、环境变量改动、首次启动观测点到Add模型和Hackathon现场排错命令和参数都偏“可直接抄作业”的粒度。适合两类人Hackathon现场临时装机的选手以及想先在本机把Dify社区版跑熟再往服务器迁移的开发者。2. 安装前的硬前置Docker Desktop、Git和Python各自要满足什么条件很多人以为装Dify等于装个Python包实际上Dify依赖Postgres、Redis、Weaviate、Sandbox等一整套服务单跑Flask进程根本起不来。Windows下的正确做法是依靠Docker Desktop来跑官方编排Git负责把仓库按正确行尾拉到本地Python则更多用于Hackathon阶段的扩展脚本和密钥生成。三者缺一不可但坑也正好都藏在三者交界处。2.1 Docker Desktop的WSL2后端默认值可以但建议改内存Windows上装Docker Desktop有两种后端Hyper-V和WSL2。Dify容器一拉就是十来个推荐直接选WSL2因为WSL2启动快、内存回收比Hyper-V好Dify社区版默认docker-compose文件也偏向Linux容器。Docker Desktop安装完在Settings - General里把“Use the WSL 2 based engine”勾上再确认一下默认发行版是当前正在用的Ubuntu或Debian。如果你机器内存只有16GB劝你不要用默认值硬扛。Dify首次启动时api、worker、web、plugin_daemon、weaviate几个容器会同时吃内存尤其weaviate做向量检索时会把缓存顶得很高。可以通过%USERPROFILE%.wslconfig来限制WSL2的内存上限文件不存在就新建# 放在 %USERPROFILE%\.wslconfig [wsl2] memory6GB processors4 swap2GB localhostForwardingtruememory给6GB是因为Dify整套容器稳定运行时大概吃3GB多留出一点余量给编译和日志。processors给4核是一个保守值Hackathon现场如果旁边还有人开着VS Code和浏览器限制CPU可以避免整个系统卡死。swap设为2GB避免容器内存瞬间冲高时直接把WSL2虚拟机杀掉。改完这个文件需要让WSL2重新加载配置。在PowerShell里执行wsl --shutdown再重新打开Docker Desktop等系统托盘里的鲸鱼图标不再转圈。之后用wsl -l -v看一眼状态如果VERSION列显示2就说明你当前用的是WSL2。这个步骤看起来玄学但很多“docker compose up到一半被kill”其实就是WSL2内存上限没设好。2.2 Git安装把core.autocrlf设置为false再cloneWindows上Git默认有个“好心”行为checkout时把仓库里的LF转成CRLF。这个行为对普通文档无所谓对Dify容器镜像却是毒药。Dify的docker目录里有entrypoint.shapi镜像里也有shell脚本这些文件在Linux容器里要按LF执行。一旦被Windows转成CRLF容器启动时会报/bin/sh^M: bad interpreter网上一查全是玄学其实是行尾符问题。我一般会先配置Git全局参数再拉仓库命令顺序放前面比较稳git config --global core.autocrlf false git config --global core.eol lf git config --global --get core.autocrlf把core.autocrlf设为false表示checkout时不自动转换行尾core.eol lf进一步要求工作区文件保持LF。最后git config --get是验证一下如果输出为false说明配置生效。注意如果你已经用默认Git配置clone过Dify就算现在改这个参数坏文件也已经躺在工作区里了最省事的后悔药是删掉整个目录重新clone一次。还有个容易被忽略的点Hackathon现场如果机器上装了多个Git版本老版本对core.eol协议支持不完整。装Git的时候最好在“Checkout as-is, commit as-is”那一项上选第三项。这不是必须项但它能保证后续git pull不会在更新Dify源码时又偷偷把关键文件转成CRLF。2.3 端口占用确认80/443的两种情况Dify默认通过Nginx容器对外暴露80和443端口浏览器访问http://localhost就能进。Windows上这两个端口最常见的意外是IIS或“系统进程”占用。你Docker容器明明显示Up访问却跳到IIS欢迎页这种情况通常不是Dify的问题而是宿主机80端口根本没转发到Nginx容器。在PowerShell里可以先查端口占用Get-NetTCPConnection -LocalPort 80,443 -ErrorAction SilentlyContinue | Select-Object LocalAddress, LocalPort, State, OwningProcess这条命令会列出80和443上的监听进程OwningProcess对应的PID再用Get-Process -Id PID查看是谁。如果看到的是System进程ID为4那多半是HTTP.sys占住端口改Dify端口比跟系统服务较劲省事得多。端口调整在.env文件里做后面第3章会详细讲。这里先记一个对应关系对外入口默认端口.env中的变量影响范围HTTP控制台80EXPOSE_NGINX_PORT换后访问地址会变HTTPS控制台443EXPOSE_NGINX_SSL_PORT证书相关配置API容器内部端口5001容器间通信用一般不对外暴露如果是在局域网里给队友访问改成8080后还需要放行Windows防火墙管理员PowerShell执行netsh advfirewall firewall add rule nameDify Web dirin actionallow protocolTCP localport8080这条命令的localport8080要和.env里的EXPOSE_NGINX_PORT保持一致否则Docker转发到了8080防火墙却只放行80队友照样连不上。Hackathon现场如果大家都用同一台机器做演示这一步直接决定别人能否访问你的应用。3. 拉取Dify代码与配置环境变量clone、.env、compose.yaml三件事前置环境确定后下一步是把Dify仓库拿到本地、复制环境变量模板、确认compose文件位置。很多教程把这三步混在一句话里实际上每一步都可能带出不同故障特征clone阶段出换行符问题.env阶段出密钥和端口问题compose阶段出命令不存在问题。分开处理会好排查很多。3.1 clone到本地为什么换行符会破坏容器启动在Windows Terminal里进入你要放工程的盘符比如D盘根目录然后执行clonegit clone Dify官方仓库地址 D:\dify如果你不想记具体地址也可以到Dify官网或GitHub页面复制仓库地址。这里故意不写死一串URL因为不同参赛场地方提供的镜像仓库地址不一定相同Hackathon现场有时会要求内部镜像加速直接用你拿到的地址替换即可。如果网络状况不好可以加浅克隆参数git clone --depth 1 --branch 版本标签 Dify官方仓库地址 D:\dify--depth 1表示只拉最近一次提交能大幅减少传输量但代价是你之后想切换其他版本标签时会比较麻烦。--branch后面填具体标签比如1.10.x这类社区版标签按你实际拿到的通知来填。没有明确版本要求时可以不写branch直接拉默认分支。clone完成后进到目录里看一眼有没有docker这个子目录Set-Location D:\dify Get-ChildItemDify的docker编排文件是放在docker子目录里的根目录下的.env.example未必是最新版。如果你在根目录找不到.env.example多半是版本目录结构变了这时候认准docker目录。我见过不少人在根目录反复执行docker compose然后提示找不到compose文件其实是走错了目录。3.2 .env关键参数EXPOSE_NGINX_PORT、SECRET_KEY与VERSIONDify的配置入口是docker/.env.example进入docker目录后把它复制成.envSet-Location D:\dify\docker Copy-Item .env.example .env.env是Dify所有容器读取环境变量的源头Nginx、api、web、worker都会从这里取值。复制完不要直接启动先改三个最关键的参数。第一个是SECRET_KEY它用于Flask签名Cookie和CSRF保护。.env.example里通常给了一个示例值如果保持默认所有按同样教程搭建的人都会得到相同密钥别人构造的Cookie可以直接冒充你的管理员身份。生成一个新密钥很简单Windows下用Pythonpython -c import secrets; print(secrets.token_hex(32))如果你的机器上python命令被Windows Store的占位符拦截就用py -3 -c import secrets; print(secrets.token_hex(32))。把输出的一长串hex复制到.env的SECRET_KEY后面值里不要加引号、不要加空格因为compose解析时会把空格也当成值的一部分。第二个要改的是对外端口。如果80端口被系统服务占用直接把EXPOSE_NGINX_PORT改成8080EXPOSE_NGINX_SSL_PORT改成8443。注意只改这两个变量还不算完NGINX_PORT和NGINX_SSL_PORT是容器内部的监听端口一般保持默认不动对外端口变量名带EXPOSE前缀才是宿主机上真正监听的端口。第三个值是数据库和Redis密码。.env.example里默认密码是可预测的参赛现场如果整个网络环境里有人扫描默认密码很容易被测出来。把POSTGRES_PASSWORD、DB_PASSWORD、REDIS_PASSWORD统一改成一串新的强密码并且三个地方的密码要互相匹配。这里给出我常用的参数表变量名默认值建议改法影响SECRET_KEY固定示例串用secrets生成hex登录态安全EXPOSE_NGINX_PORT80改成8080或随机高位端口浏览器访问入口EXPOSE_NGINX_SSL_PORT443改成8443HTTPS入口POSTGRES_PASSWORD默认值改成32位随机串数据库连接DB_PASSWORD默认值与POSTGRES_PASSWORD保持一致api连库REDIS_PASSWORD默认值改成随机串redis连接3.3 compose 文件位置Windows 新旧命令差别的处理Dify仓库里的编排文件是docker/docker-compose.yaml不是放在根目录。确认路径后先做一次配置校验再真正启动docker compose --env-file .env -p dify config --quiet这条命令里的--env-file .env指定环境变量文件-p dify把项目名固定为difyconfig --quiet只校验配置不创建容器。如果配置里有变量没被替换这里会直接报错错误信息会比启动时更直观。Windows上还残留着两个相似命令docker compose和docker-compose。前者是Docker官方v2插件随Docker Desktop默认安装后者是旧版独立二进制很多老教程还在用。2024年以后的新环境里Docker Desktop官方安装包已经不带docker-compose独立命令了所以你执行docker-compose大概率提示“无法识别”。如果你以前装过独立的docker-compose版本又是1.x它在解析新版compose文件时可能不认depends_on的某些写法。判断当前命令是否可用docker compose version如果输出类似Docker Compose version v2.x.x说明路径正确。后面所有启动命令都用docker compose不要混用。为了减少现场输入错误我习惯把项目名固定下来$env:COMPOSE_PROJECT_NAMEdify docker compose --env-file .env up -dPowerShell里用$env:给当前会话设置COMPOSE_PROJECT_NAME之后不带-p dify也能维持同一套容器前缀。如果不开新终端这个变量只在当前会话有效不会污染全局。容器前缀统一后后续查日志和找volume都会方便很多。4. 执行docker compose up -d容器启动顺序与第一次初始化的观测点配置没问题接下来就是拉镜像和启动。这一步最大的风险不是命令写错而是“不知道当前进度到哪了”。Dify首次启动需要拉多个镜像还要做数据库迁移界面看起来像卡死实际容器内部正在忙。掌握启动命令、日志观测和初始化完成后三个状态基本就能判断系统健不健康。4.1 启动命令与docker compose ps状态进入D:\dify\docker目录执行正式启动Set-Location D:\dify\docker docker compose --env-file .env -p dify up -d-d表示后台运行pull镜像和创建容器的过程不会一直刷屏。第一次执行时终端会长时间停在“Pulling”状态这是正常的Dify全家桶包含api、worker、web、nginx、postgres、redis、weaviate、sandbox、ssrf_proxy、plugin_daemon等十来个服务镜像总量比较大。如果中途网络断开重新执行同样命令即可Docker会续传已下载的层。启动完成后查看容器状态docker compose --env-file .env -p dify ps -a正常状态下大部分容器Status列应该显示Up尤其是api、worker、web、nginx这四类关键服务。如果你看到某个容器状态是Restarting说明它启动后崩溃了需要单独看日志。-a参数会把已停止的容器也列出来方便看到哪些服务根本没起来。另外docker compose ps输出的PORTS列只显示宿主机暴露的端口。如果.env里把对外端口改成了8080这里会显示0.0.0.0:8080-80/tcp看到这个映射关系就说明Nginx端口转发正常。4.2 看日志等待api与plugin_daemon完成的几次“长时间无输出”容器全部起来不等于服务全部就绪。Dify里最容易给人“卡死”错觉的是api容器和worker容器。首次启动时api要等数据库就绪还要执行数据库迁移日志前几十行常常只有等待提示docker compose -p dify logs -f api如果日志滚动到Waiting for database connection就停下来不要急着CtrlCGive它一两分钟。Postgres首次初始化需要建库建表api容器这时候是在轮询数据库。看到Database connection established后日志会累出新内容说明数据库链路打通。然后是plugin_daemon。这个服务负责模型供应商插件加载第一次启动时会同步插件元数据输出密集程度远低于api。很多Hackathon选手在这一步误判为死机直接重启Docker Desktop结果插件没加载完后面接入模型时反复报错。另一个观测点是worker容器。它负责异步任务比如知识库索引和文档解析。如果worker没起来你在网页里上传文档到知识库任务会一直堆积在“处理中”。查看worker日志docker compose -p dify logs --tail50 worker--tail50只显示最后50行适合快速判断是“正在运行”还是“启动失败”。看到Connected to redis之类的日志说明worker和redis之间通讯正常如果报Redis连接被拒绝优先检查.env里的REDIS_PASSWORD是否和compose里Postgres等服务的密码设置一致。4.3 浏览器初始化管理员账号与默认HTTP端口容器日志稳定后打开浏览器访问http://localhost。如果你改过EXPOSE_NGINX_PORT就访问http://localhost:8080。第一次访问会进入初始化向导需要创建一个管理员账号填写邮箱、姓名、密码。这里容易有个误解邮箱不是用来收验证邮件的只要格式合法就能过。管理员账号创建完页面会跳到Dify控制台主界面。到这一步“安装部署”已经成功了。接下来先别急着写工作流先干两件事一是确认右上角能看到你的头像说明登录态写入成功二是进入“设置 - 模型供应商”随便添加一个模型试试因为Hackathon的核心是把模型跑通不是只看页面。如果你希望验证API入口是否正常可以在浏览器打开http://localhost:8080/health会返回一个正常状态文本。这个接口走Nginx转发到api容器能明确告诉你整条网络链路是不是通着的。返回异常时再分别查nginx和api两个容器日志前后端的问题就能分隔开。5. Windows下安装避坑五个让Dify“翻车”的常见问题以下是实际在Windows上装Dify最容易遇到的五个坑。它们很多看起来像“Docker坏了”“镜像有问题”最后定位下来全是Windows环境细节。整理成“现象 - 原因 - 解决”的结构方便你现场照着排查。5.1 现象WSL2内存占满docker compose up到一半被kill现象是执行docker compose up -d后终端突然跳出类似Killed的报错Docker Desktop整个变灰再打开容器大量消失。原因不是Dify镜像占内存夸张而是WSL2虚拟机的默认内存上限会跟宿主机抢资源拉镜像和容器间通信同时发生时内存触顶。解决方法是写.wslconfig限制内存然后执行wsl --shutdown重新打开Docker Desktop。等Docker引擎启动完再重新docker compose up -d。这一步的关键是改完.wslconfig必须关闭全部WSL会话包括Docker Desktop否则配置不生效。5.2 现象entrypoint.sh报/bin/sh^M: bad interpreter这种现象在Windows下clone Dify后特别明显api容器或worker容器启动即崩溃日志里的错误指向shell脚本解释失败。原因是之前说的Git行尾转换仓库里的LF被Windows Git转成CRLF。解决方式是先执行git config --global core.autocrlf false然后把已经clone到本地的Dify目录整个删掉重新clone。不要试图手动改文件行尾因为Dify内部脚本不止一两个漏改后续还是会报错。这是血泪经验配置Git参数必须在clone之前之后再做都是给现场添麻烦。5.3 现象Docker容器提示找不到挂载盘或目录为空现象是容器能起来但打开Dify页面后上传的文件丢失或者容器日志里出现类似share has been granted but path not found。原因是Dify目录被放在了OneDrive、Dropbox这类云同步目录里云盘会锁文件Docker Desktop的共享机制解析不了这种路径。解决方法是把整个Dify工程挪到本地磁盘比如C:\dify或D:\dify不要在用户目录下的同步文件夹里安装。另外如果目录放在D盘而Docker Desktop没有授权共享D盘也会出现同样问题需要到Docker Desktop的Settings - Resources - File Sharing里把对应盘符勾上。5.4 现象Windows重启后Dify所有页面打不开Windows重启后Docker Desktop不会自己恢复所有容器特别是WSL2模式下很多容器的状态会变成Exited。现象是浏览器访问http://localhost直接拒绝连接但Docker Desktop右下角图标看着正常。原因是Docker Desktop开机后只启动引擎不会主动拉起你手动创建的compose项目。解决方法是重新执行启动命令Set-Location D:\dify\docker docker compose --env-file .env -p dify up -d如果你想偷懒可以在Windows任务计划程序里加一个开机脚本但Hackathon现场不建议这么做因为比赛环境可能随时重启网络手动拉起反而更容易控制启动顺序。5.5 现象添加模型供应商时报“an error occurred during credentials validation”这是接入外部模型时最容易遇到的拦路虎。现象是在Dify控制台填写模型API Key后点击保存界面弹出An error occurred during credentials validation。原因有两个方向一是Dify的plugin_daemon服务要发外部请求验证KeyWindows容器网络里对这类外部请求有限制经常是SSL证书检查失败二是host.docker.internal在Windows和Linux容器之间的解析不够稳定导致自建模型的验证请求到达不了宿主机。解决时分两步走。先查看plugin_daemon的日志docker compose -p dify logs --tail100 plugin_daemon如果日志里有SSL或证书相关报错说明验证链路被网络策略挡住优先换用本机可直连的模型比如用Ollama搭本地模型在供应商设置里把API基础地址填成http://host.docker.internal:11434。这个地址专门用于Windows容器访问宿主机服务不要填localhost因为容器内的localhost指向容器自己。如果是外部模型确认Key本身有效且服务没欠费不要把密钥填错。这类问题不是Docker玄学本质上是验证请求没到达该到的地方。6. Hackathon里的落地技巧用环境变量迁移与固定容器版本6.1 固定Dify镜像版本别让默认标签坑了后续Hackathon现场最怕“昨天还能用今天容器重启后版本变了”。Dify的docker-compose里部分镜像可能没有锁死具体版本默认拉取标签会随时间漂移。比赛前我会先查看本地镜像标签docker compose --env-file .env -p dify config | Select-String image:确认当前实际使用的镜像标签后直接编辑docker/docker-compose.yaml或对应的.env变量把image:字段改成固定标签。这样能保证另一台电脑复现时拉到的镜像和你是同一套避免api和web版本不匹配导致页面登录后白屏。Hackathon结束时把这份改过的compose文件和.env模板一起提交比口头交代步骤可靠得多。6.2 用docker compose config做交付前验证我每次准备提交前都会强制走一遍同样的检查命令docker compose --env-file .env -p dify config --quiet docker compose --env-file .env -p dify ps --format json第一条命令验证环境变量有没有缺漏第二条把容器运行状态输出为结构化JSON方便快速数出到底哪些服务没起来。然后浏览器访问页面随机走一遍“创建应用 - 添加模型 - 对话”的流程。只有这几步全通我才会把部署过程写进参赛文档。从那以后我在Windows上部署Dify都强制先改.env、再跑config校验、最后才启动容器这套顺序帮我省掉了很多次现场救火。希望帮到你。本文还有配套的精品资源点击获取