简介：这份资源是面向Windows平台开发者的Dify Hackathon环境部署文档，适合具备Git、Docker与Python基础、准备参与Dify Hackathon或搭建本地大模型应用开发环境的技术爱好者。内容围绕前置环境准备、代码克隆、环境变量配置、docker-compose服务启动、数据库初始化与安装验证等环节展开，并针对Docker启动失败、端口占用、服务无法访问等常见问题给出排查思路，同时延伸至应用创建、模型集成与Hackathon开发等后续操作。资源包为1个docx文档，约15KB，以图文步骤形式组织，便于按流程对照执行。目前已有125人学习，适合希望快速在Windows下跑通Dify本地环境、减少部署踩坑的开发者参考。
1. Windows 上跑 Dify：为什么我劝你先别急着双击安装包
如果你在 Windows 上搜 Dify 安装，大概率会看到两种答案：一种是让你装 Docker Desktop 然后一条命令拉起，另一种是让你老老实实配 Python 环境、拉源码、跑 Flask。这两条路我都走过，结论是——在 Windows 上部署 Dify，Docker 是主线，Python 源码是备胎，Git 是你全程都要用的工具。Dify 本身是一个开源的 LLM 应用开发平台，能拖拽编排工作流、挂知识库、接各种模型 API，社区版功能已经够一个小团队内部用。但它的官方部署文档默认你是 Linux 环境，Windows 下有一堆路径、权限、端口、WSL 的坑等着你。这篇不是官方文档翻译，是我自己在一台 Windows 11 机器上从零把 Dify 跑起来、又踩了几轮坑之后的记录，适合想本地部署 Dify 做工作流验证、又不想折腾 Linux 双系统的后端或全栈。下面从环境准备讲到插件安装和升级，每一步都给你能直接抄的命令。
2. 环境准备：Docker Desktop、WSL2 与 Git 的版本选择
2.1 为什么 Dify 在 Windows 上必须走 Docker
Dify 的社区版部署包里包含 API 服务、Worker、Web 前端、PostgreSQL、Redis、Weaviate 或 Qdrant 向量库、Nginx 这一整套。你如果手动一个个装，光是 PostgreSQL 和 Redis 在 Windows 上的原生支持就够你喝一壶。官方提供的docker-compose.yaml把这些组件的镜像、网络、卷、环境变量全编排好了，你只需要保证 Docker 能跑。
Windows 上跑 Docker 有两条路：一是 Docker Desktop 配合 WSL2 后端，二是直接在 WSL2 的 Linux 发行版里装 Docker Engine。我推荐前者，因为 Docker Desktop 的图形界面在排查容器状态时省事，而且端口映射到 Windows 宿主机是自动的，你在浏览器里直接访问localhost就行。后者虽然更“干净”，但每次都要进 WSL 终端操作，对不熟悉 Linux 的人反而增加心智负担。
版本上，Docker Desktop 建议 4.30 以上，它内置的 Docker Compose V2 对docker compose子命令支持更完整。WSL2 内核更新到最新，否则 Docker Desktop 启动时可能卡在 “Starting the Docker Engine”。Git 用 2.40 以上，因为 Dify 的部署脚本里有些git clone和子模块操作，老版本 Git 在 Windows 路径处理上偶尔会抽风。
2.2 安装 Docker Desktop 与开启 WSL2 的具体步骤
先确认你的 Windows 版本。Win+R 输入winver，版本号要 21H2 及以上，家庭版也能用 WSL2。然后以管理员身份打开 PowerShell，执行下面两条命令开启所需功能：
# 启用 WSL 和虚拟机平台功能，这两条是 Docker Desktop 的硬前提 dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart执行完重启电脑。重启后下载 WSL2 内核更新包并安装，然后在 PowerShell 里把默认版本设为 2：
# 将 WSL 默认版本设为 2，Docker Desktop 必须用 WSL2 后端 wsl --set-default-version 2 # 查看当前 WSL 状态，确认没有报错 wsl --status接下来去 Docker 官网下载 Docker Desktop for Windows 的安装包，双击安装。安装时勾选 “Use WSL 2 instead of Hyper-V”，不要勾选 “Add shortcut to desktop” 以外的多余选项。装完启动 Docker Desktop，右下角托盘图标变成绿色鲸鱼且不再闪烁，说明引擎就绪。
这里有个参数值得注意：Docker Desktop 默认给 WSL2 分配的内存是宿主机的一半。如果你机器只有 8GB 内存，Dify 全套容器跑起来会非常吃力，PostgreSQL 和向量库都可能因为 OOM 被 kill。解决办法是在用户目录下建一个.wslconfig文件：
# 放在 C:\Users\你的用户名\.wslconfig [wsl2] memory=6GB processors=4 swap=2GB改完在 PowerShell 执行wsl --shutdown再重启 Docker Desktop 生效。这个文件是 WSL2 的全局配置，不是 Docker 专属，但直接影响容器能用的资源上限。
2.3 Git 拉取 Dify 源码与目录规划
Dify 的部署方式有两种：一种是直接下载 release 里的 docker-compose 包，另一种是git clone主仓库然后进docker目录。我建议用 Git 克隆，因为后续升级、看配置变更、切分支都方便。
选一个路径不要太深的目录，比如D:\projects。Windows 的路径长度限制虽然在新版已经放宽，但 Docker 挂载卷时如果路径里有中文或空格，偶尔会出现挂载失败。执行：
# 克隆 Dify 主仓库，--depth 1 只拉最新一次提交，省时间 git clone --depth 1 https://github.com/langgenius/dify.git D:\projects\dify # 进入 docker 部署目录，所有编排文件都在这里 cd D:\projects\dify\docker克隆完成后你会看到.env.example、docker-compose.yaml、nginx目录等。.env.example是环境变量模板，下一步要复制成.env再改。这里注意：不要直接在.env.example上改，升级时这个文件会被覆盖，你的配置就丢了。复制命令：
# 复制环境变量模板，后续所有密钥和端口配置都改这个文件 copy .env.example .env到这一步，环境准备就算完成。Docker 引擎在跑，源码在本地，环境变量文件已就位。下一章进入真正的启动和配置环节。
3. 启动 Dify：.env 关键参数与容器编排实操
3.1 .env 里必须改的五个参数
.env文件里参数上百个，但初次部署真正影响能不能跑起来、能不能从外部访问的，就下面这几个。用记事本或 VS Code 打开.env，逐项确认。
第一个是EXPOSE_NGINX_PORT，默认 80。如果你 Windows 上已经装了 IIS 或者别的占用了 80，容器启动时 Nginx 会报端口冲突。改成 8080 或别的空闲端口。第二个是SECRET_KEY，这是 Dify 用来签名会话的，默认值是个占位符，必须换成一串随机字符。用 Python 生成一个：
# 生成一个 42 位的随机密钥，复制到 .env 的 SECRET_KEY import secrets print(secrets.token_urlsafe(42))第三个是数据库密码POSTGRES_PASSWORD，默认difyai123456。本地玩无所谓，但只要这台机器在局域网里能被别人访问，就一定要改。第四个是CONSOLE_API_URL和CONSOLE_WEB_URL，如果你只在本机用localhost访问，保持默认空值即可；如果你想让同局域网的其他机器访问，要填宿主机的 IP，比如http://192.168.1.100:8080，否则前端会请求不到 API。第五个是向量库选择，Dify 默认用 Weaviate，.env里VECTOR_STORE变量控制。如果你机器内存紧张，可以改成qdrant，Qdrant 的资源占用比 Weaviate 低一些，但需要把docker-compose.yaml里对应的服务启起来。
改完.env后，有一个容易忽略的点：docker-compose.yaml里很多服务通过env_file读取.env，但 Compose 在解析时对变量替换的时机有要求。如果你在.env里写了带空格的值，比如CONSOLE_API_URL=http://192.168.1.100:8080，不要加引号，加了引号在某些 Compose 版本里会把引号也当成值的一部分。
3.2 docker compose up 的正确姿势与首次启动观察
在D:\projects\dify\docker目录下打开 PowerShell，执行：
# -d 后台运行，首次启动会拉取所有镜像，视网速需要 5-15 分钟 docker compose up -d首次执行会从 Docker Hub 拉取 postgres、redis、weaviate、nginx、dify-api、dify-web 等镜像。如果卡在某一层不动，大概率是网络问题，可以配置 Docker Desktop 的镜像加速器，在 Settings → Docker Engine 里加 registry-mirrors。拉取完成后容器会依次启动，但注意：容器启动顺序不代表服务就绪顺序。PostgreSQL 初始化需要时间，API 服务如果比数据库先起来，会反复重试连接，日志里刷connection refused，这是正常的，等一两分钟就好。
用下面命令观察状态：
# 查看所有容器状态，STATUS 列显示 Up 且没有 Restarting 才算稳 docker compose ps # 跟踪 api 服务日志，看到 "Application startup complete" 才算真正就绪 docker compose logs -f api当api日志出现Application startup complete，并且docker compose ps里所有服务都是Up状态，就可以打开浏览器访问http://localhost:8080（如果你改了端口就换成对应端口）。第一次访问会让你设置管理员账号，填邮箱和密码，这个账号是存在 PostgreSQL 里的，后续升级不会丢。
3.3 验证部署是否成功的三个检查点
第一个检查点：前端页面能正常加载，登录后能看到「探索」「工作室」「知识库」这些菜单。如果页面白屏，按 F12 看 Console，大概率是CONSOLE_API_URL配错了，前端请求 API 跨域被拦。
第二个检查点：在「设置 → 模型供应商」里能添加一个模型。Dify 本身不带模型，你需要填 OpenAI 兼容的 API Key 和 Base URL。如果保存时报错，看api容器日志，常见的是网络不通或者 Key 格式不对。
第三个检查点：创建一个空白应用，选「工作流」类型，随便拖一个开始节点和一个结束节点，点运行。如果能在几秒内返回结果，说明 API、Worker、数据库、Redis 这条链路全通了。这一步是端到端验证，比看容器状态更可靠。
提示：如果
docker compose ps里某个容器一直Restarting，先看它的日志docker compose logs 服务名，八成是环境变量缺失或端口冲突，不要急着重装。
4. 避坑与排查：Windows 下 Dify 部署的五个血泪经验
4.1 端口冲突导致 Nginx 反复重启
现象：docker compose ps里 nginx 容器状态是Restarting，日志报bind() to 0.0.0.0:80 failed (98: Address already in use)。
原因：Windows 宿主机上 80 端口被 IIS、Skype 或者某些后台服务占了。Docker Desktop 的端口映射是把容器端口绑到宿主机端口，宿主机端口被占就直接失败。
解决：先用netstat -ano | findstr :80找到占用进程的 PID，再tasklist | findstr PID看是什么程序。如果是 IIS，去服务里停掉；如果不想动别的服务，就改.env里的EXPOSE_NGINX_PORT=8080，然后docker compose down再up -d。改完记得浏览器访问也要带新端口。
4.2 WSL2 内存不足导致容器被 OOM Kill
现象：用着用着 Dify 突然打不开，docker compose ps里 postgres 或 weaviate 不见了，docker compose logs显示Killed。
原因：WSL2 默认最多用宿主机一半内存，Dify 全套跑起来峰值能到 4-5GB。8GB 机器上如果同时开浏览器和 IDE，很容易触发 OOM。
解决：按 2.2 节说的建.wslconfig限制内存并加 swap，或者关掉不用的容器。如果你不用 Weaviate，可以在docker-compose.yaml里把 weaviate 服务注释掉，.env里VECTOR_STORE改成qdrant，能省几百 MB。
4.3 路径含中文或空格导致卷挂载失败
现象：docker compose up时报invalid mount path或容器启动后数据目录为空。
原因：Docker Desktop 在 Windows 上做路径转换时，对中文和空格的处理不稳定。你把项目放在D:\我的项目\dify这种路径下就容易翻车。
解决：项目路径只用英文和数字，比如D:\projects\dify。已经放错位置的，docker compose down之后把整个目录移到纯英文路径，再重新up -d。数据卷在 Docker 的虚拟磁盘里，移动源码目录不影响已有数据，但.env要跟着走。
4.4 升级后数据库迁移失败
现象：git pull拉了新代码，docker compose up -d之后 api 容器启动报alembic.util.exc.CommandError或数据库列不存在。
原因：Dify 版本升级时数据库 schema 会变，需要跑迁移脚本。官方镜像在启动时会自动执行迁移，但如果你的数据库卷是旧版本留下的，且迁移脚本有冲突，就会失败。
解决：升级前先备份数据库。执行docker compose exec db pg_dump -U postgres dify > backup.sql，把备份文件放到源码目录外。然后docker compose down，git pull，再up -d。如果迁移还是失败，看 api 日志里具体是哪条迁移报错，有时候需要手动进数据库删掉冲突的记录。这个操作有风险，新手建议直接备份后重建数据库卷，代价是丢失已有应用数据。
4.5 插件安装时 SSL 错误
现象：在 Dify 后台安装插件，进度条卡住然后报SSLError或certificate verify failed。
原因：插件市场走 HTTPS，容器内如果缺少 CA 证书或者系统时间不对，就会校验失败。Windows 宿主机时间一般没问题，但容器内时区可能是 UTC，和证书有效期判断偶尔出偏差。
解决：先确认宿主机时间准确。然后在docker-compose.yaml的 api 服务里加环境变量TZ=Asia/Shanghai，重启容器。如果还不行，检查公司网络是否有证书拦截，这种情况需要把自定义 CA 证书挂载进容器，具体路径看你的网络环境。
5. 进阶技巧：用 Flask 写一个 Dify 工作流的外部调用壳
5.1 为什么要自己包一层 Flask
Dify 的工作流可以通过 API 对外暴露，但它的 API 需要传Authorization: Bearer app-xxx这种应用级 Key，而且请求体格式是固定的。如果你想让内部其他系统调用，又不想把 Key 散落在各处，常见做法是用 Flask 写一个薄薄的代理层：对外暴露你自己的接口，内部转发到 Dify，顺便做鉴权、参数校验和日志。
这个壳子还能解决一个实际问题：Dify 工作流的输入变量如果很多，调用方很容易传错。Flask 层可以做默认值填充和类型转换，把 Dify 的报错挡在外面。
5.2 Flask 代理的最小实现
先装依赖：
pip install flask requests然后写一个app.py：
from flask import Flask, request, jsonify import requests import os app = Flask(__name__) # Dify 工作流的 API 地址和 Key，从环境变量读，不要硬编码 DIFY_API_BASE = os.environ.get("DIFY_API_BASE", "http://localhost:8080/v1") DIFY_API_KEY = os.environ.get("DIFY_API_KEY", "app-xxxxxxxx") @app.route("/run-workflow", methods=["POST"]) def run_workflow(): # 接收调用方传来的 inputs，做一层非空校验 data = request.get_json() inputs = data.get("inputs", {}) if not inputs: return jsonify({"error": "inputs is required"}), 400 # 转发到 Dify 的 workflow run 接口 resp = requests.post( f"{DIFY_API_BASE}/workflows/run", headers={ "Authorization": f"Bearer {DIFY_API_KEY}", "Content-Type": "application/json" }, json={ "inputs": inputs, "response_mode": "blocking", # blocking 表示同步等待结果 "user": data.get("user", "flask-proxy") }, timeout=60 ) # 把 Dify 的响应原样返回，调用方按需解析 return jsonify(resp.json()), resp.status_code if __name__ == "__main__": app.run(host="0.0.0.0", port=5000)这段代码的逻辑很直白：Flask 收到请求后，把inputs和user拿出来，拼成 Dify 工作流 API 要求的格式，带上 Key 转发过去。response_mode设成blocking表示同步等结果，适合短流程；如果工作流跑得久，改成streaming然后做 SSE 转发，但那样 Flask 这边要处理流式响应，复杂度高一些。
参数说明：DIFY_API_BASE是你 Dify 的访问地址加/v1，本地就是http://localhost:8080/v1。DIFY_API_KEY在 Dify 后台的应用「访问 API」页面生成，每个应用一个。timeout=60是防止 Dify 那边卡住导致 Flask 线程被占满，按你工作流的最长耗时调整。
5.3 验证与一个我常犯的错
启动 Flask 后，用 curl 测一下：
curl -X POST http://localhost:5000/run-workflow \ -H "Content-Type: application/json" \ -d '{"inputs": {"query": "你好"}, "user": "test"}'如果返回 Dify 工作流的执行结果，说明代理通了。如果返回 401，检查 Key 有没有复制错；如果返回 404，检查DIFY_API_BASE后面有没有多写或少写/v1。
我自己的血泪经验是：每次改完 Dify 的工作流输入变量，忘了同步改 Flask 这边的默认值，结果调用方传了旧字段名，Dify 报变量不存在，Flask 原样返回 400，排查半天才发现是两边没对齐。从那以后我每次动工作流变量，都强制走一遍「改 Dify → 改 Flask 默认值 → curl 测一遍」这个流程，不再靠记忆。希望帮到你。
本文还有配套的精品资源，点击获取
