Dify 安装流程及常见问题和解决办法

环境：Windows 11 (x64) | Docker Desktop：29.5.2 | Dify：1.14.2
更新时间：2026-05-30

---

目录

1. 什么是 Dify？
2. 前置要求
3. 完整安装流程
4. 常见问题及解决办法（踩坑实录）
5. Dify 常用管理命令
6. 总结

---

1. 什么是 Dify？

Dify 是一个开源的 LLM 应用开发平台，支持以下核心功能：

• 可视化编排：通过拖拽方式构建 AI 应用工作流
• RAG 引擎：内置文档检索与知识库能力
• Agent 智能体：支持 ReAct、Function Calling 等多种 Agent 模式
• 多模型接入：兼容 OpenAI、通义千问、文心一言、Claude 等主流 LLM
• 开箱即用：提供聊天助手、文本生成、SQL 生成等多种模板

Dify 采用 Docker Compose 部署，是目前最流行的开源 AI 应用搭建方案之一。

---

2. 前置要求

在安装 Dify 之前，你的 Windows 电脑需要满足以下条件：

组件	最低版本	推荐版本	用途
操作系统	Windows 10 21H2+	Windows 11	运行基础环境
WSL	WSL 2	WSL 2.6+	Docker Desktop 后端
Docker Desktop	4.x	29.x+	容器运行时
Git	2.x	2.53+	克隆 Dify 仓库
内存	≥ 8 GB	≥ 16 GB	运行多个容器
磁盘空间	≥ 20 GB	≥ 50 GB	存储镜像和数据

快速检测命令

打开 PowerShell，依次运行：

# 检查 WSL
wsl --version

# 检查 Docker
docker --version
docker compose version

# 检查 Git
git --version

如果以上命令都能正常输出版本号，可以跳过第 3 节，直接进入 克隆并启动 Dify。

---

3. 完整安装流程

3.1 安装 WSL 2（Windows Subsystem for Linux）

Docker Desktop on Windows 依赖 WSL2 作为后端运行环境。

步骤 1：以管理员身份启用 WSL

1. 右键点击开始菜单
2. 选择 「Windows PowerShell（管理员）」 或 「终端（管理员）」
3. 执行以下命令：

wsl --install

该命令会自动：

• 启用 WSL 可选功能
• 下载最新 Linux 内核
• 安装 Ubuntu 发行版（约 500 MB）
• 将 WSL 默认版本设置为 2

⏳ 预计耗时：5 ~ 15 分钟（取决于网速）

步骤 2：重启电脑

Restart-Computer

重启是必须的！WSL 安装完成后需要重启才能生效。

步骤 3：首次启动 Ubuntu 并初始化

1. 按 Win 键 → 搜索 “Ubuntu” → 打开

2. 首次启动会要求设置用户名和密码：

   Enter new UNIX username: yourname
   New password: ********
   Retype new password: ********
   

   ⚠️ 输入密码时屏幕不会显示任何字符，这是 Linux 的正常安全机制。

3. 初始化完成后关闭 Ubuntu 即可。

步骤 4：验证 WSL

wsl --version

✅ 预期输出（示例）：

WSL 版本: 2.6.1.0
内核版本: 6.6.87.2-1
默认版本: 2

---

3.2 安装 Docker Desktop

方法一：使用 winget 安装（推荐尝试）

winget install Docker.DockerDesktop --accept-package-agreements --accept-source-agreements

⚠️ 注意：根据实际经验，winget 可能显示「已成功安装」但 Docker 实际并未正确部署。如果安装后找不到 Docker，请使用方法二。

方法二：手动下载安装（最可靠）

1. 访问 Docker 官网：https://www.docker.com/products/docker-desktop/
2. 点击 “Download for Windows” 下载安装程序（约 630 MB）
3. 双击运行 Docker Desktop Installer.exe
4. 安装向导中保持默认选项，确保勾选：
   • ✅ Install required Windows components for WSL 2
5. 点击 “Ok” 开始安装
6. 安装完成后重启电脑

验证安装

重启后打开新的 PowerShell 窗口：

docker --version
docker compose version

✅ 预期输出：

Docker version 29.5.2, build xxxxx
Docker Compose version v5.1.3

💡 如果提示 docker 不是可识别的命令，请确认：

1. Docker Desktop 已启动（系统托盘有鲸鱼图标）
2. 已重启电脑（PATH 需要刷新）
3. 打开的是新的 PowerShell 窗口

---

3.3 安装 Git

方法一：使用 winget 安装

winget install Git.Git -e --accept-package-agreements --accept-source-agreements

方法二：手动下载安装

1. 访问 https://git-scm.com/download/win
2. 下载 64-bit Git for Windows Setup（约 50 MB）
3. 运行安装程序，关键配置项：

配置步骤	推荐选项	说明
Select Components	保持默认	确保勾选 Git Bash Here
Default Editor	VS Code 或 Notepad	按需选择
PATH environment	Git from the command line and also from 3rd-party software	⚠️ 最重要！否则 PowerShell 中无法使用 git
HTTPS backend	Use OpenSSL library	默认即可
Line endings	Checkout Windows-style, commit Unix-style	默认即可
Terminal emulator	Use MinTTY	默认即可
git pull default	Default (fast-forward or merge)	默认即可
Credential helper	Git Credential Manager	默认即可

4. 安装完成后重新打开 PowerShell

验证安装

git --version

✅ 预期输出：git version 2.53.0.windows.2

---

3.4 克隆 Dify 仓库

标准克隆方式

cd ~
New-Item -ItemType Directory -Force -Path workspace
cd workspace
git clone https://github.com/langgenius/dify.git

⏳ 预计耗时：1 ~ 10 分钟（取决于网络速度，仓库约 300 MB）

浅克隆方式（推荐国内用户使用）

如果标准克隆太慢或卡住，使用浅克隆只下载最新版本：

git clone --depth 1 https://github.com/langgenius/dify.git

✅ 优点：下载量从 300 MB 降至约 50 MB，速度快 3-5 倍。

ZIP 下载方式（最稳定）

如果 git clone 反复失败，直接下载 ZIP 包：

cd ~\workspace
Invoke-WebRequest -Uri "https://github.com/langgenius/dify/archive/refs/heads/main.zip" -OutFile "dify.zip"
Expand-Archive -Path dify.zip -DestinationPath .
Rename-Item -Path "dify-main" -NewName "dify"
Remove-Item dify.zip

---

3.5 配置 Docker 镜像加速器（国内必做！）

由于 Docker Hub (docker.io) 在国内访问经常超时或极慢，必须配置镜像加速器。

配置步骤

1. 右键系统托盘的 Docker 鲸鱼图标 → 选择 “Settings”
2. 点击左侧菜单 “Docker Engine”
3. 修改 JSON 配置，添加 registry-mirrors 字段：

{
  "builder": {
    "gc": {
      "defaultKeepStorage": "20GB",
      "enabled": true
    }
  },
  "experimental": false,
  "registry-mirrors": [
    "https://docker.m.daocloud.io"
  ]
}

4. 点击 “Apply & restart” 按钮
5. 等待 Docker 重启完成（鲸鱼图标停止旋转）

📌 镜像源推荐（按稳定性排序）：

镜像源地址	说明
https://docker.m.daocloud.io	DaoCloud 公共加速器（推荐）
https://registry.docker-cn.com	Docker 中国官方镜像
https://hub-mirror.c.163.com	网易镜像

⚠️ 已知不可用的镜像源：mirror.ccs.tencentyun.com（腾讯云镜像 DNS 解析失败）

---

3.6 启动 Dify

步骤 1：进入 docker 目录并配置环境变量

cd ~\workspace\dify\docker
Copy-Item .env.example .env

.env 文件包含 Dify 的所有配置项（数据库密码、端口、API 密钥等），首次部署使用默认值即可。

步骤 2：拉取镜像并启动容器

docker compose up -d

⏳ 首次启动预计需要 5-15 分钟，因为需要下载约 2-5 GB 的 Docker 镜像，包括：

镜像	大小	用途
langgenius/dify-api	~700 MB	Dify 后端 API 服务
langgenius/dify-web	~100 MB	Dify 前端界面
langgenius/dify-sandbox	~200 MB	代码沙箱执行环境
postgres:15-alpine	~600 MB	PostgreSQL 数据库
redis:6-alpine	~90 MB	Redis 缓存
ubuntu/squid	~70 MB	HTTP 代理缓存
nginx:latest	~150 MB	反向代理
semitechnologies/weaviate	~200 MB	向量数据库

步骤 3：验证服务状态

docker compose ps

✅ 所有核心服务应显示 running (healthy) 或 Up：

NAME                        SERVICE           STATUS
docker-db-1                 db                running (healthy)
docker-redis-1              redis             running (healthy)
docker-web-1                web               running (healthy)
docker-api-1                api               running (healthy)
docker-sandbox-1            sandbox           running (healthy)
docker-weaviate-1           weaviate          running (healthy)
docker-nginx-1              nginx             running

💡 注意：ssrf_proxy 和 init_permissions 显示 Exited 是正常的——它们是一次性初始化容器，执行完毕后会自动退出。

步骤 4：访问 Dify

打开浏览器，访问：

http://localhost

首次访问会引导你创建管理员账号（邮箱 + 密码）。设置完成后即可开始使用 Dify！

🎉 恭喜！Dify 安装成功！

---

4. 常见问题及解决办法（踩坑实录）

以下是笔者在 Windows 11 上安装 Dify 时遇到的所有问题及对应的解决方案。每个问题都经过实测验证。

---

问题 1：winget 安装 Docker Desktop 显示成功但实际未安装

现象：执行 winget install Docker.DockerDesktop 后显示「已成功安装」，但重启后 docker --version 报错「无法识别命令」，开始菜单中也找不到 Docker Desktop。

原因：winget 在安装 GUI 应用时可能存在静默安装失败的情况，退出码显示成功但文件未正确部署。

解决方法：使用方法二：手动下载安装，从 Docker 官网下载安装程序手动安装。

经验教训：winget 安装 GUI 类应用后，务必验证程序是否真的可用（检查 PATH、开始菜单、可执行文件是否存在）。

---

问题 2：Git 安装后在当前 PowerShell 中找不到命令

现象：Git 安装成功（git --version 在新窗口中正常），但在已打开的 PowerShell 窗口中始终报错「无法将 ‘git’ 项识别为 cmdlet」。

原因：Windows 的 PATH 环境变量只在新进程中生效。已打开的终端会话不会自动加载新安装程序的路径。

解决方法：

• 关闭所有 PowerShell 窗口
• 重新打开一个新的 PowerShell 窗口
• 再次执行 git --version 验证

经验教训：安装任何命令行工具后，都需要在新的终端中验证，而不是继续使用旧窗口。

---

问题 3：git clone 卡住不动（GitHub 连接超时）

现象：执行 git clone https://github.com/langgenius/dify.git 时进度卡在 52% 不再移动，持续超过 5 分钟无变化。

原因：GitHub 在国内的连接不稳定，大仓库克隆容易因网络波动导致超时断开。

解决方案（按推荐顺序）：

方案 A — 浅克隆（推荐）：

git clone --depth 1 https://github.com/langgenius/dify.git

只下载最新一次提交，不拉取历史记录，体积缩小 80% 以上。

方案 B — 下载 ZIP 包：

Invoke-WebRequest -Uri "https://github.com/langgenius/dify/archive/refs/heads/main.zip" -OutFile "dify.zip"
Expand-Archive -Path dify.zip -DestinationPath .
Rename-Item -Path "dify-main" -NewName "dify"

不依赖 git，单次 HTTP 请求更稳定。

方案 C — 使用 Gitee 镜像：

git clone https://gitee.com/mirrors/dify.git

使用国内 Gitee 平台的 GitHub 镜像仓库（如果可用的话）。

---

问题 4：Docker 拉取镜像超时（docker.io 连接失败）

现象：执行 docker compose up -d 时报错：

Error response from daemon: failed to resolve reference "docker.io/langgenius/dify-api:1.14.2":
failed to do request: Head "https://registry-1.docker.io/v2/...":
dial tcp registry-1.docker.io:443: connectex: A connection attempt failed...

原因：Docker 默认从 Docker Hub（docker.io）拉取镜像，但该服务在国内访问极其不稳定，经常出现连接超时。

解决方法：配置 Docker 镜像加速器（详见 3.5 节）。

---

问题 5：腾讯云镜像源 DNS 解析失败

现象：配置了腾讯云镜像源 mirror.ccs.tencentyun.com 后报错：

dialing mirror.ccs.tencentyun.com:443: dial tcp:
lookup mirror.ccs.tencentyun.com: no such host

原因：腾讯云 Docker 镜像源已于 2024 年停止对外提供服务，DNS 记录已被移除，但很多教程仍在推荐它。

解决方法：更换为 DaoCloud 公共加速器：

{
  "registry-mirrors": ["https://docker.m.daocloud.io"]
}

经验教训：网上很多 Docker 教程中的镜像源地址已经过时，推荐使用 DaoCloud 或网易镜像。

---

问题 6：DaoCloud 镜像源限流（请求过于频繁）

现象：使用 DaoCloud 镜像源拉取大部分镜像成功后，最后几个镜像报错：

error from registry: 请求过于频繁，请稍后再试

原因：免费公共镜像源通常有速率限制（Rate Limiting），短时间内大量请求会被临时限流。

解决方法：等待 30 秒 ~ 1 分钟后重试：

docker compose up -d

Docker 会自动跳过已下载成功的镜像，只重新拉取失败的几个。重试一次即可成功。

备选方案：如果反复限流，可以手动单独拉取失败的镜像：

docker pull nginx:latest
docker pull ubuntu/squid:latest

然后再次执行 docker compose up -d。

---

问题 7：WSL 未安装导致 Docker 启动失败

现象：Docker Desktop 安装后启动报错：「WSL 2 installation is incomplete」或「WSL kernel update required」。

原因：Docker Desktop 依赖 WSL2 作为后端，但系统尚未安装或启用 WSL。

解决方法：以管理员身份运行：

wsl --install

然后重启电脑，再启动 Docker Desktop。

---

问题汇总表

#	问题	原因	解决难度	解决方法
1	winget 安装 Docker 失败	GUI 静默安装缺陷	⭐⭐	手动从官网下载安装
2	新安装的工具找不到	PATH 未刷新	⭐	打开新终端窗口
3	git clone 卡住	GitHub 国内连接不稳定	⭐⭐	使用 --depth 1 浅克隆或下载 ZIP
4	Docker 拉取镜像超时	docker.io 国内不可达	⭐⭐	配置国内镜像加速器
5	腾讯云镜像 DNS 失败	镜像源已停服	⭐⭐	改用 DaoCloud 加速器
6	镜像源限流	免费源速率限制	⭐	等待 1 分钟后重试
7	WSL 未安装	Docker 依赖 WSL2	⭐	wsl --install + 重启

---

5. Dify 常用管理命令

安装完成后，以下命令会在日常使用中频繁用到：

# 进入 Dify 目录
cd ~\workspace\dify\docker

# 启动 Dify
docker compose up -d

# 停止 Dify
docker compose down

# 重启 Dify
docker compose restart

# 查看所有服务状态
docker compose ps

# 查看某个服务的日志（实时跟踪）
docker compose logs -f api        # API 服务日志
docker compose logs -f web        # Web 前端日志
docker compose logs -f db         # 数据库日志

# 更新 Dify 到最新版本
cd ~\workspace\dify
git pull origin main
cd docker
docker compose up -d --build

# 清理所有数据（⚠️ 会删除所有数据，谨慎操作）
docker compose down -v

---

6. 总结

在 Windows 上安装 Dify 的完整流程可以概括为以下 6 个关键步骤：

1. 安装 WSL 2          → Docker 的运行基础
2. 安装 Docker Desktop → 容器引擎
3. 安装 Git            → 克隆代码仓库
4. 克隆 Dify 仓库       → 获取部署文件
5. 配置镜像加速器      → 解决国内网络问题（关键！）
6. docker compose up -d → 一键启动

其中最容易出问题的环节是网络相关的问题（GitHub 克隆超时、Docker Hub 拉取镜像失败），这也是国内开发者安装 Dify 时最常见的障碍。只要提前配置好镜像加速器并选择合适的克隆方式，整个安装过程可以在 20-30 分钟内顺利完成。

---

参考链接：

• Dify 官方文档：https://docs.dify.ai/
• Dify GitHub 仓库：https://github.com/langgenius/dify
• Docker Desktop 下载：https://www.docker.com/products/docker-desktop/
• Git for Windows：https://git-scm.com/download/win