本文基于 Windows 11 + WSL2 + Docker Desktop 环境，从零部署 Dify v1.15.0 完整版，记录所有踩坑点与解决方案。

---

一、Dify 是什么

Dify 是一款开源的 LLM 应用开发平台，支持可视化搭建 Agent、工作流、RAG 知识库，可私有化部署。

• 官方 GitHub：https://github.com/langgenius/dify
• 官方文档：https://docs.dify.ai/
• 官方 Demo：https://udify.app/

---

二、环境准备（前置依赖）

2.1 系统要求

• Windows 10 2004 版本以上 / Windows 11
• 至少 4GB 内存（推荐 8GB+）
• 开启虚拟化（BIOS 中开启）

2.2 安装 WSL2（必须！）

Docker Desktop 在 Windows 上依赖 WSL2 后端，这一步是最容易踩坑的地方。

⚠️ 关键避坑：必须用管理员终端

很多人安装 WSL 失败，根本原因是用了普通终端执行命令，权限不足。

终端类型	权限	能否安装 WSL
普通 CMD / PowerShell	标准用户权限	❌ 经常失败、中断
管理员 CMD / PowerShell	系统最高权限	✅ 正常安装

窗口颜色 ≠ 管理员权限。蓝色 PowerShell 也可以普通身份启动，黑色 CMD 也可以管理员运行。

正确安装步骤

1. 右键开始菜单 → 选择「Windows PowerShell (管理员)」或「终端(管理员)」
2. 执行安装命令：

wsl --install

1. 等待安装完成，按提示重启电脑
2. 重启后，设置 Ubuntu 用户名和密码

验证 WSL 安装成功

wsl --status
wsl -l -v

看到 VERSION: 2 即为正常。

---

2.3 安装 Docker Desktop

下载地址

• 官方下载：https://www.docker.com/products/docker-desktop/
• 国内镜像（速度更快）：各大软件管家搜索 Docker Desktop

安装前优化（节省 C 盘空间，必做！）

Docker 默认安装在 C 盘，镜像、容器体积很容易膨胀到几十 GB，强烈建议安装前就改到非系统盘。

优化 1：安装位置改到 D 盘

安装 Docker Desktop 时，自定义安装路径，选择 D 盘或其他非系统盘。

优化 2：修改镜像存储位置（WSL 虚拟磁盘迁移）

Docker 的镜像、容器数据存在 WSL 虚拟磁盘中，默认在 C 盘用户目录下，体积增长很快。

迁移步骤（管理员 PowerShell）：

# 1. 关闭 Docker Desktop
# 2. 导出 WSL 数据到 D 盘
wsl --export docker-desktop-data D:\Docker\docker-desktop-data.tar

# 3. 注销原 WSL 数据
wsl --unregister docker-desktop-data

# 4. 重新导入到 D 盘新位置
wsl --import docker-desktop-data D:\Docker\data D:\Docker\docker-desktop-data.tar --version 2

# 5. 删除导出的 tar 包（导入完成后就没用了）
del D:\Docker\docker-desktop-data.tar

迁移完成后启动 Docker Desktop，所有镜像数据都存在 D 盘了。

优化 3：配置镜像加速器（国内拉取速度翻倍）

Docker Desktop → Settings → Docker Engine，把下面配置直接粘贴进去，替换原有内容：

{
  "builder": {
    "gc": {
      "defaultKeepStorage": "20GB"
    }
  },
  "experimental": false,
  "registry-mirrors": [
    "https://hub.rat.dev",
    "https://docker.himirror.com",
    "https://docker.nju.edu.cn"
  ]
}

点击「Apply & restart」重启 Docker 生效。

镜像源说明：

• hub.rat.dev：Rat 镜像站，速度稳定
• docker.himirror.com：HiMirror 镜像站
• docker.nju.edu.cn：南京大学开源镜像站

安装注意事项

1. 安装时勾选「Use WSL 2 instead of Hyper-V」
2. 安装完成后启动 Docker Desktop
3. 进入 Settings → Resources → WSL Integration，确保 Ubuntu 集成已开启
4. Settings → Resources → Advanced 可以调整 Docker 可用内存、CPU 上限

验证 Docker 安装

打开 PowerShell 执行：

docker --version
docker-compose --version

输出版本号即为成功。

---

三、下载 Dify

方式一：Git 克隆（推荐）

git clone https://github.com/langgenius/dify.git

方式二：直接下载 ZIP 包

• GitHub Releases：https://github.com/langgenius/dify/releases
• 下载最新版本的 Source code (zip)

目录结构说明

解压/克隆后，进入 docker 目录，核心文件：

dify/
└── docker/
    ├── docker-compose.yaml          # 主配置文件（完整版，12个容器）
    ├── .env.example                 # 环境变量模板
    └── nginx/                       # 反向代理配置

---

四、部署步骤

4.1 进入 docker 目录

cd dify/docker

4.2 复制环境变量配置文件

copy .env.example .env

.env 文件包含所有配置项（端口、密钥、数据库密码等），可按需修改。

4.3 启动 Dify

docker compose up -d

第一次启动会自动拉取所有镜像，需要几分钟，取决于网络速度。

4.4 查看启动状态

docker compose ps

所有容器状态为 Up 即为启动成功。

---

五、部署成功后：12 个容器完整说明

完整版 Dify 默认启动 12 个常驻容器，功能齐全。网上说的 5、6 个容器是精简阉割版。

容器清单

容器名称	作用	分类
docker-web-1	前端网页界面，你浏览器看到的页面	🌐 访问层
docker-nginx-1	反向代理网关，统一分发请求，http 入口	🌐 访问层
docker-api-1	核心后端主服务，所有业务逻辑	🧠 核心业务
docker-api_websocket-1	长连接实时通讯，实现流式打字输出	🧠 核心业务
docker-db_postgres-1	PostgreSQL 业务数据库，存配置、对话记录	💾 数据存储
docker-redis-1	缓存 & 消息队列，加速访问、分发异步任务	💾 数据存储
docker-weaviate-1	向量数据库，RAG 知识库检索核心	💾 数据存储
docker-worker-1	异步任务消费者，处理大文件导入等耗时任务	⚙️ 后台任务
docker-worker_beat-1	定时任务调度器，周期性任务	⚙️ 后台任务
docker-sandbox-1	代码沙箱，代码节点 Python 运行环境	🧩 扩展功能
docker-plugin_daemon-1	插件后台服务，支撑插件市场	🧩 扩展功能
docker-ssrf-proxy-1	安全代理，防止模型访问内网恶意地址	🛡️ 安全组件

实际运行截图

上图为本地部署成功后的容器状态，12 个容器全部正常运行（Up）。

---

六、访问 Dify

浏览器打开：

http://localhost

首次访问需要注册管理员账号，设置邮箱和密码。

---

七、常见问题 & 解决方案

问题 1：WSL 安装失败 / 报错

现象：执行 wsl --install 报错、卡住、下载失败。

原因：90% 是因为没有用管理员终端执行。

解决方案：

1. 右键 PowerShell → 以管理员身份运行
2. 重新执行 wsl --install
3. 仍失败可手动安装 WSL 内核更新包

问题 2：Docker 启动报错，WSL 未运行

现象：Docker Desktop 提示 WSL 2 installation is incomplete。

解决方案：

1. 管理员终端执行 wsl --update
2. 重启 Docker Desktop

问题 3：docker compose up 拉取镜像慢

解决方案：

1. 配置 Docker 镜像加速器（阿里云、网易等）
2. Docker Desktop → Settings → Docker Engine → 添加 registry-mirrors

问题 4：启动后部分容器一直重启

排查步骤：

1. 查看容器日志：docker compose logs api
2. 常见原因：数据库未就绪就启动了 api 服务
3. 解决：等待数据库初始化完成，或重启 api 容器

问题 5：端口被占用，无法访问

解决方案：

1. 修改 .env 文件中的 EXPOSE_NGINX_PORT
2. 重新执行 docker compose up -d

问题 6：CMD 和 PowerShell 命令不通用

说明：

• CMD 是老版命令解释器，语法老旧
• PowerShell 是新一代终端，WSL/Docker 推荐使用
• 两者权限规则一致，都有普通/管理员模式

建议：所有 WSL、Docker 操作统一用 PowerShell。

---

八、常用命令速查

# 启动 Dify
docker compose up -d

# 停止 Dify
docker compose down

# 重启所有容器
docker compose restart

# 查看运行状态
docker compose ps

# 查看某个容器日志
docker compose logs api

# 更新 Dify（拉取最新镜像）
docker compose pull
docker compose up -d

# 完全卸载（删除数据，谨慎！）
docker compose down -v

---

九、精简方案（减少容器数量）

如果不需要某些功能，可以注释掉对应服务，容器数量可以从 12 个降到 8 个甚至更少。

可关闭的服务

服务	关闭后影响
weaviate	无法使用内置知识库向量库
sandbox	代码节点无法运行
plugin_daemon	插件功能失效
ssrf_proxy	失去网络安全防护（不建议关）

关闭方法

编辑 docker-compose.yaml，注释掉对应服务的配置，然后重新 docker compose up -d。

⚠️ 新手不建议随意删减，关掉后对应功能直接失效。

---

十、总结

1. 环境准备是最大坑点：WSL 必须管理员终端安装，Docker Desktop 依赖 WSL2
2. 完整版 12 个容器：功能最全，包含知识库、代码沙箱、插件等全套能力
3. 访问入口：http://localhost，首次注册管理员账号
4. 日常维护：docker compose up/down 启停，docker compose logs 排查问题

---

部署环境：Windows 11 + WSL2 + Docker Desktop + Dify v1.15.0