需启用并调优WSL2：以管理员身份执行dism启用子系统与虚拟机平台、wsl --update、wsl --set-default-version 2；配置.wslconfig限定内存6GB等参数并wsl --shutdown生效；Docker Desktop须启用WSL2引擎、配置国内镜像源；.env中修改POSTGRES_PASSWORD为强密码、UNSTRUCTURED_API_URL为localhost；docker compose up -d后检查ps状态，db_healthy、web_up、init_permissions_exited(0)全满足且浏览器可访问localhost:3000即成功。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
在Windows WSL2环境下部署Dify，需绕过Windows原生服务兼容性限制，利用Linux内核级容器运行时保障多组件协同稳定性——这一步不走WSL2而直接用Hyper-V或Docker Desktop默认Windows backend，PostgreSQL连接超时、Weaviate向量写入失败、unstructured文档解析挂起等故障概率提升3倍以上。
启用并调优WSL2子系统
以管理员身份打开PowerShell，一次性执行三组命令：
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart → dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart → wsl --update --web-download
重启后执行 【wsl --set-default-version 2】，否则后续Docker Desktop将强制降级至WSL1，导致Redis持久化异常和Weaviate mmap内存映射失败。
创建C:\Users\用户名\.wslconfig文件，填入以下内容（注意：路径必须是Windows用户目录下，不能放在WSL内部）：
[wsl2]
memory=6GB
processors=4
swap=2GB
localhostForwarding=true
保存后必须执行 【wsl --shutdown】，否则配置不生效；不要依赖图形界面重启Docker Desktop来间接触发，那不会重载.wslconfig。
配置Docker Desktop与镜像加速
安装Docker Desktop时务必勾选「Use the WSL 2 based engine」，取消勾选「Start Docker Desktop when you log in」——避免开机自启抢占WSL2资源引发init_permissions容器反复退出。
打开Docker Desktop → Settings → Docker Engine，在JSON中插入registry-mirrors字段：
{ "registry-mirrors": ["https://docker.1ms.run", "https://docker.nju.edu.cn"], "experimental": false }
点击Apply & Restart。若镜像拉取仍卡在langgenius/dify-api:1.7.0层，说明镜像源未生效，此时需手动删掉%USERPROFILE%\AppData\Local\Docker目录下的settings.json并重装Docker Desktop。
拉取Dify源码并初始化配置
方法一：使用浅克隆规避网络中断
在PowerShell中执行：git clone --depth 1 --single-branch https://github.com/langgenius/dify.git
方法二：若公司防火墙拦截GitHub，改用Gitee镜像站（需提前注册并fork）
进入Dify项目根目录后，切换到docker子目录：cd dify\docker
复制环境模板：copy .env.example .env
关键修改项仅两处：把POSTGRES_PASSWORD值从postgres改为至少8位含大小写字母+数字的强密码；把UNSTRUCTURED_API_URL从http://unstructured:8000改为http://localhost:8000——否则Windows宿主机无法访问WSL2中unstructured容器的8000端口。
启动与验证Dify服务
第一步：确保Docker Desktop已启动且状态栏图标为绿色
第二步：在dify\docker目录下执行：docker compose up -d
第三步：等待5–12分钟，期间不要关闭终端窗口或手动kill进程。首次启动会拉取约1.2GB镜像，包括postgres:15、redis:7-alpine、weaviate/weaviate:1.24.3、unstructured-io/unstructured-api:0.10.19四个核心镜像。
第四步：检查服务健康状态：docker compose ps
输出中必须同时满足三项才表示就绪：db_postgres列显示Healthy、web列显示Up、init_permissions列显示Exited (0)。若worker持续显示Restarting，立即执行docker logs docker-worker-1 --tail 50，大概率是.env里CELERY_BROKER_URL协议写成了amqp://而非redis://。
第五步：浏览器访问http://localhost:3000，看到Dify登录页即成功。管理员账号密码为admin@difylab.ai / admin，首次登录后系统强制跳转至密码重置页。
