Dify 本地 Docker 部署完整指南（Windows 环境）

本文基于 Windows 11 WSL2 Docker Desktop 环境从零部署 Dify v1.15.0 完整版记录所有踩坑点与解决方案。一、Dify 是什么Dify 是一款开源的 LLM 应用开发平台支持可视化搭建 Agent、工作流、RAG 知识库可私有化部署。官方 GitHubhttps://github.com/langgenius/dify官方文档https://docs.dify.ai/官方 Demohttps://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 也可以管理员运行。正确安装步骤右键开始菜单 → 选择「Windows PowerShell (管理员)」或「终端(管理员)」执行安装命令wsl--install等待安装完成按提示重启电脑重启后设置 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-dataD:\Docker\docker-desktop-data.tar# 3. 注销原 WSL 数据wsl--unregister docker-desktop-data# 4. 重新导入到 D 盘新位置wsl--import docker-desktop-dataD:\Docker\dataD:\Docker\docker-desktop-data.tar--version 2# 5. 删除导出的 tar 包导入完成后就没用了delD:\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.devRat 镜像站速度稳定docker.himirror.comHiMirror 镜像站docker.nju.edu.cn南京大学开源镜像站安装注意事项安装时勾选「Use WSL 2 instead of Hyper-V」安装完成后启动 Docker Desktop进入 Settings → Resources → WSL Integration确保 Ubuntu 集成已开启Settings → Resources → Advanced 可以调整 Docker 可用内存、CPU 上限验证 Docker 安装打开 PowerShell 执行docker--version docker-compose--version输出版本号即为成功。三、下载 Dify方式一Git 克隆推荐git clone https://github.com/langgenius/dify.git方式二直接下载 ZIP 包GitHub Releaseshttps://github.com/langgenius/dify/releases下载最新版本的 Source code (zip)目录结构说明解压/克隆后进入docker目录核心文件dify/ └── docker/ ├── docker-compose.yaml # 主配置文件完整版12个容器 ├── .env.example # 环境变量模板 └── nginx/ # 反向代理配置四、部署步骤4.1 进入 docker 目录cd dify/docker4.2 复制环境变量配置文件copy.env.example.env.env文件包含所有配置项端口、密钥、数据库密码等可按需修改。4.3 启动 Difydocker compose up-d第一次启动会自动拉取所有镜像需要几分钟取决于网络速度。4.4 查看启动状态docker composeps所有容器状态为Up即为启动成功。五、部署成功后12 个容器完整说明完整版 Dify 默认启动12 个常驻容器功能齐全。网上说的 5、6 个容器是精简阉割版。容器清单容器名称作用分类docker-web-1前端网页界面你浏览器看到的页面 访问层docker-nginx-1反向代理网关统一分发请求http 入口 访问层docker-api-1核心后端主服务所有业务逻辑 核心业务docker-api_websocket-1长连接实时通讯实现流式打字输出 核心业务docker-db_postgres-1PostgreSQL 业务数据库存配置、对话记录 数据存储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首次访问需要注册管理员账号设置邮箱和密码。七、常见问题 解决方案问题 1WSL 安装失败 / 报错现象执行wsl --install报错、卡住、下载失败。原因90% 是因为没有用管理员终端执行。解决方案右键 PowerShell → 以管理员身份运行重新执行wsl --install仍失败可手动安装 WSL 内核更新包问题 2Docker 启动报错WSL 未运行现象Docker Desktop 提示 WSL 2 installation is incomplete。解决方案管理员终端执行wsl --update重启 Docker Desktop问题 3docker compose up 拉取镜像慢解决方案配置 Docker 镜像加速器阿里云、网易等Docker Desktop → Settings → Docker Engine → 添加 registry-mirrors问题 4启动后部分容器一直重启排查步骤查看容器日志docker compose logs api常见原因数据库未就绪就启动了 api 服务解决等待数据库初始化完成或重启 api 容器问题 5端口被占用无法访问解决方案修改.env文件中的EXPOSE_NGINX_PORT重新执行docker compose up -d问题 6CMD 和 PowerShell 命令不通用说明CMD 是老版命令解释器语法老旧PowerShell 是新一代终端WSL/Docker 推荐使用两者权限规则一致都有普通/管理员模式建议所有 WSL、Docker 操作统一用 PowerShell。八、常用命令速查# 启动 Difydocker compose up-d# 停止 Difydocker compose down# 重启所有容器docker compose restart# 查看运行状态docker composeps# 查看某个容器日志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。⚠️ 新手不建议随意删减关掉后对应功能直接失效。十、总结环境准备是最大坑点WSL 必须管理员终端安装Docker Desktop 依赖 WSL2完整版 12 个容器功能最全包含知识库、代码沙箱、插件等全套能力访问入口http://localhost首次注册管理员账号日常维护docker compose up/down启停docker compose logs排查问题部署环境Windows 11 WSL2 Docker Desktop Dify v1.15.0