尧图网站建设 
简介面向具备一定编程基础、熟悉 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、dbPostgreSQL 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-VDocker Desktop 在 Windows 上支持两种后端。WSL2 后端把 Docker 跑在轻量级虚拟机里内存动态分配、启动快还能直接读写 Windows 文件系统Hyper-V 后端则是一整台独立的虚拟化平台启动慢、资源占用高和很多学校或赛场的旧电脑不兼容。Dify 这个编排有十几个容器内存动态分配意味着 8GB 内存的机器也能跑起来。先确认系统条件Windows 10 200420H1及以上或 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做三处修改。设置项位置推荐值作用镜像加速Settings Docker Engine或手工改C:\Users\用户名\.docker\daemon.jsonregistry-mirrors 填一个当前可用的国内加速地址避免拉 Dify 镜像时反复超时镜像盘位置Settings Resources Advanced Disk image location挪到 D 盘或空间充足的盘避免 C 盘被容器镜像塞满内存和 CPU 上限Settings Resources Advanced内存 6GB 以上CPU 4 核以上决定知识库索引和容器并发会不会卡死先改镜像加速。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 到 12GBC 盘紧张的话很容易把系统盘塞满。在 Disk image location 里把它挪到 D 盘或移动硬盘。这个动作会复制现有镜像第一次切换耗时较长建议趁还没拉 Dify 镜像时就去改。第三个是内存上限。Resources Advanced 里的 Memory 默认可能只有 2GBDify 的 weaviate 向量库和 api 容器同时跑时2GB 完全不够。我一般直接拉到 6GB 到 8GBCPU 至少 4 核。比赛笔记本如果只有 8GB 内存就关掉浏览器多余标签页把所有余量让给 Docker。这个资源分配直接决定后面知识库索引会不会中途挂掉。2.3 验证环境的三条命令与常见误判环境配没配好不要靠感觉用三条命令验证。在普通 PowerShell 或 CMD 窗口里依次执行docker version docker compose version wsl --statusdocker 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 DesktopWSL 发行版里的 docker 不要装否则两边抢 daemonHackathon 现场很容易手忙脚乱。3. 用 docker compose 拉起 Difyclone、改 .env、看日志3.1 获取安装文件clone 整个仓库还是只拉 docker 目录部署 Dify 需要的是官方仓库里的 docker 目录不是整个前端和后端源码。完整 clonegit clone --depth 1 https://github.com/langgenius/dify.git cd dify/dockerdepth 1 只拉最新一次提交省时间也省磁盘。如果你还没装 Git for Windows去装一个Hackathon 现场要改代码、拉更新Git 迟早要用。如果只想部署不想拿源码也可以只下载 docker 目录的 zip但我不太建议这么做因为后文讲二次开发时你还是要回到这个仓库。接下来复制环境变量模板。Linux 和 macOS 用cp .env.example .envWindows 的 CMD 用 copyPowerShell 用 Copy-Item。这里有个小坑.env 是隐藏文件资源管理器里默认看不到别以为复制失败了。复制完用 notepad .env 打开进入下一步。3.2 必改的四个 .env 参数与密钥生成.env 里面有很多配置项Hackathon 阶段只需要改四个。参数默认值建议值作用EXPOSE_NGINX_PORT808080 或 8088Dify 对外访问的 HTTP 端口比赛现场容易和同网段冲突SECRET_KEY空openssl 随机生成会话签名和敏感数据加密POSTGRES_PASSWORD空自定义长密码数据库 superuser 密码DB_PASSWORD空与 POSTGRES_PASSWORD 一致业务库连接密码生成 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 都是 Updb 显示 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_PORT8088然后重新应用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 serveOllama 默认只监听 127.0.0.1这在桌面端用没问题但 Dify 是容器访问不到宿主机回环地址。所以要把监听地址放开setx OLLAMA_HOST 0.0.0.0重启 Ollama 后在 Dify 左侧“设置 模型供应商”里找到 Ollama。关键参数如下Model Type 选 LLMModel Name 填 qwen2.5:7bBase URL 填http://host.docker.internal:11434。host.docker.internal 是 Windows 下 Docker Desktop 内置的宿主机域名容器内用它访问 Windows 本机服务。如果用 Linux 就要换成 host-gatewayWindows 用户直接无脑用 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_URLpostgresql://postgres:你的密码localhost:5432/dify $env:REDIS_URLredis://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 一直在 restartinglogs 里反复出现 connection refused 或 password authentication failed。原因第一类是首次启动时 PostgreSQL 初始化还没完成api 启动前十几秒连不上很正常第二类是 .env 里 POSTGRES_PASSWORD 和 DB_PASSWORD 没填一致或者数据库密码带了 #、 这类特殊字符被 .env 解析截断容器里实际读到的密码和初始化用的对不上。解决先看 db 状态确认 healthy 后强制重建 apidocker 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 弄健康再强制刷新浏览器 CtrlF5。如果改了 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 以上然后单独重启 weaviatedocker 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/healthcurl.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新版出问题还能回滚。社区版后续版本加的多租户体系比赛单人场景完全用不到别在上面花时间。我吃过一次没备份就重建的亏从那以后每次动环境前先打一个卷备份。希望帮到你。本文还有配套的精品资源点击获取 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、dbPostgreSQL 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-VDocker Desktop 在 Windows 上支持两种后端。WSL2 后端把 Docker 跑在轻量级虚拟机里内存动态分配、启动快还能直接读写 Windows 文件系统Hyper-V 后端则是一整台独立的虚拟化平台启动慢、资源占用高和很多学校或赛场的旧电脑不兼容。Dify 这个编排有十几个容器内存动态分配意味着 8GB 内存的机器也能跑起来。先确认系统条件Windows 10 200420H1及以上或 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做三处修改。设置项位置推荐值作用镜像加速Settings Docker Engine或手工改C:\Users\用户名\.docker\daemon.jsonregistry-mirrors 填一个当前可用的国内加速地址避免拉 Dify 镜像时反复超时镜像盘位置Settings Resources Advanced Disk image location挪到 D 盘或空间充足的盘避免 C 盘被容器镜像塞满内存和 CPU 上限Settings Resources Advanced内存 6GB 以上CPU 4 核以上决定知识库索引和容器并发会不会卡死先改镜像加速。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 到 12GBC 盘紧张的话很容易把系统盘塞满。在 Disk image location 里把它挪到 D 盘或移动硬盘。这个动作会复制现有镜像第一次切换耗时较长建议趁还没拉 Dify 镜像时就去改。第三个是内存上限。Resources Advanced 里的 Memory 默认可能只有 2GBDify 的 weaviate 向量库和 api 容器同时跑时2GB 完全不够。我一般直接拉到 6GB 到 8GBCPU 至少 4 核。比赛笔记本如果只有 8GB 内存就关掉浏览器多余标签页把所有余量让给 Docker。这个资源分配直接决定后面知识库索引会不会中途挂掉。2.3 验证环境的三条命令与常见误判环境配没配好不要靠感觉用三条命令验证。在普通 PowerShell 或 CMD 窗口里依次执行docker version docker compose version wsl --statusdocker 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 DesktopWSL 发行版里的 docker 不要装否则两边抢 daemonHackathon 现场很容易手忙脚乱。3. 用 docker compose 拉起 Difyclone、改 .env、看日志3.1 获取安装文件clone 整个仓库还是只拉 docker 目录部署 Dify 需要的是官方仓库里的 docker 目录不是整个前端和后端源码。完整 clonegit clone --depth 1 https://github.com/langgenius/dify.git cd dify/dockerdepth 1 只拉最新一次提交省时间也省磁盘。如果你还没装 Git for Windows去装一个Hackathon 现场要改代码、拉更新Git 迟早要用。如果只想部署不想拿源码也可以只下载 docker 目录的 zip但我不太建议这么做因为后文讲二次开发时你还是要回到这个仓库。接下来复制环境变量模板。Linux 和 macOS 用cp .env.example .envWindows 的 CMD 用 copyPowerShell 用 Copy-Item。这里有个小坑.env 是隐藏文件资源管理器里默认看不到别以为复制失败了。复制完用 notepad .env 打开进入下一步。3.2 必改的四个 .env 参数与密钥生成.env 里面有很多配置项Hackathon 阶段只需要改四个。参数默认值建议值作用EXPOSE_NGINX_PORT808080 或 8088Dify 对外访问的 HTTP 端口比赛现场容易和同网段冲突SECRET_KEY空openssl 随机生成会话签名和敏感数据加密POSTGRES_PASSWORD空自定义长密码数据库 superuser 密码DB_PASSWORD空与 POSTGRES_PASSWORD 一致业务库连接密码生成 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 都是 Updb 显示 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_PORT8088然后重新应用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 serveOllama 默认只监听 127.0.0.1这在桌面端用没问题但 Dify 是容器访问不到宿主机回环地址。所以要把监听地址放开setx OLLAMA_HOST 0.0.0.0重启 Ollama 后在 Dify 左侧“设置 模型供应商”里找到 Ollama。关键参数如下Model Type 选 LLMModel Name 填 qwen2.5:7bBase URL 填http://host.docker.internal:11434。host.docker.internal 是 Windows 下 Docker Desktop 内置的宿主机域名容器内用它访问 Windows 本机服务。如果用 Linux 就要换成 host-gatewayWindows 用户直接无脑用 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_URLpostgresql://postgres:你的密码localhost:5432/dify $env:REDIS_URLredis://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 一直在 restartinglogs 里反复出现 connection refused 或 password authentication failed。原因第一类是首次启动时 PostgreSQL 初始化还没完成api 启动前十几秒连不上很正常第二类是 .env 里 POSTGRES_PASSWORD 和 DB_PASSWORD 没填一致或者数据库密码带了 #、 这类特殊字符被 .env 解析截断容器里实际读到的密码和初始化用的对不上。解决先看 db 状态确认 healthy 后强制重建 apidocker 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 弄健康再强制刷新浏览器 CtrlF5。如果改了 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 以上然后单独重启 weaviatedocker 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/healthcurl.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新版出问题还能回滚。社区版后续版本加的多租户体系比赛单人场景完全用不到别在上面花时间。我吃过一次没备份就重建的亏从那以后每次动环境前先打一个卷备份。希望帮到你。本文还有配套的精品资源点击获取