Dify 本地化部署流程：以 Windows 演示，从环境准备到首次访问

本文面向希望在个人电脑、实验室工作站或本地算力服务器上搭建 Dify 的用户，演示如何在 Windows 环境下借助 WSL2、Docker Desktop 和 Docker Compose 完成 Dify 本地化部署。教程以“能跑起来、能访问、能排错”为目标，适合作为初学者部署 Dify 的入门博客。

一、为什么要本地化部署 Dify？

Dify 是一个面向大模型应用开发的开源平台，能够用于构建聊天助手、知识库问答、Agent 工作流、API 调用型应用等。对于学习、实验和私有化场景来说，本地化部署有几个明显优势：

• 数据更可控：知识库文件、应用配置和运行数据保存在本地环境中，便于内部测试和私有化管理。
• 便于二次开发：可以直接修改配置、查看日志、调试容器服务，适合开发者学习 Dify 的整体架构。
• 适合接入本地模型或私有 API：后续可以对接 Ollama、本地推理服务、私有大模型 API 或企业内部模型服务。
• 部署成本低：在个人电脑或实验室服务器上即可完成基础运行，无需一开始就购买云服务。

本文采用官方推荐的 Docker Compose 方式部署。整体流程可以概括为：

Windows 电脑
   ↓
启用 WSL2
   ↓
安装 Docker Desktop
   ↓
拉取 Dify 源码
   ↓
复制 .env 配置文件
   ↓
使用 docker compose up -d 启动服务
   ↓
浏览器访问 http://localhost/install

二、部署前准备

2.1 硬件与系统要求

建议准备一台 Windows 10/11 电脑，推荐配置如下：

项目	建议配置
操作系统	Windows 10 / Windows 11，64 位系统
CPU	2 核及以上
内存	最低 4GB，建议 8GB 及以上
磁盘空间	建议预留 20GB 以上，用于镜像、容器和数据卷
网络	首次部署需要能够访问 GitHub 和 Docker 镜像源

注意：如果电脑内存较小，Dify 可以启动，但镜像拉取、向量数据库、插件服务等组件运行时可能会比较慢。学习测试建议至少 8GB 内存。

2.2 需要安装的软件

部署前需要准备以下软件：

软件	作用
WSL2	为 Windows 提供 Linux 子系统环境
Ubuntu	推荐作为 WSL2 中的 Linux 发行版
Docker Desktop	在 Windows 上运行 Docker 容器
Docker Compose	编排 Dify 所需的多个容器服务
Git	拉取 Dify 官方源码
PowerShell / Windows Terminal	执行命令

Dify 官方文档要求 Windows 场景启用 WSL2，并使用 Docker Desktop 和 Docker Compose 2.24.0 及以上版本。为了减少路径和权限问题，建议把 Dify 源码放在 WSL2 的 Linux 文件系统中，例如：

~/projects/dify

不要优先放在下面这种 Windows 挂载路径中：

/mnt/c/Users/你的用户名/Desktop/dify

Windows 挂载路径虽然也能使用，但在大量容器文件读写时可能出现速度慢、权限异常或路径兼容问题。

三、安装与检查 WSL2

3.1 启用 WSL2

以管理员身份打开 PowerShell，执行：

wsl --install

如果已经安装过 WSL，可以检查当前状态：

wsl --status

设置 WSL 默认版本为 2：

wsl --set-default-version 2

查看已安装的 Linux 发行版：

wsl -l -v

如果看到类似下面的结果，说明 Ubuntu 已经运行在 WSL2 模式下：

  NAME            STATE           VERSION
* Ubuntu-22.04    Running         2

3.2 进入 Ubuntu 子系统

在开始菜单中打开 Ubuntu，或在 Windows Terminal 中选择 Ubuntu。进入后建议先更新软件包：

sudo apt update
sudo apt upgrade -y

安装常用工具：

sudo apt install -y git curl jq vim net-tools

其中：

• git 用于拉取 Dify 源码；
• curl 和 jq 可用于获取 Dify 最新版本号；
• vim 用于编辑配置文件；
• net-tools 便于后续检查端口占用。

四、安装 Docker Desktop 并开启 WSL2 后端

4.1 安装 Docker Desktop

在 Windows 中安装 Docker Desktop。安装完成后打开 Docker Desktop，进入设置页面，重点检查：

1. General 中启用 Use the WSL 2 based engine；
2. Resources → WSL Integration 中开启 Ubuntu 集成；
3. Docker Desktop 处于 Running 状态。

4.2 检查 Docker 是否可用

回到 Ubuntu 终端，执行：

docker --version

继续检查 Docker Compose：

docker compose version

如果可以看到版本号，说明 Docker 和 Docker Compose 已经可以在 WSL2 中使用。例如：

Docker version 26.x.x
Docker Compose version v2.x.x

如果提示 command not found，通常说明 Docker Desktop 没有开启 WSL Integration，或者当前 Ubuntu 终端需要重新打开。

五、拉取 Dify 源码

在 Ubuntu 终端中创建项目目录：

mkdir -p ~/projects
cd ~/projects

推荐使用官方最新 Release 版本进行部署：

git clone --branch "$(curl -s https://api.github.com/repos/langgenius/dify/releases/latest | jq -r .tag_name)" https://github.com/langgenius/dify.git

如果上面的命令因为网络或 jq 问题执行失败，也可以先直接拉取仓库：

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

进入 Docker 部署目录：

cd dify/docker

查看目录文件：

ls

正常情况下可以看到类似文件：

docker-compose.yaml
.env.example
envs/
volumes/

六、复制并修改环境配置文件

Dify 的 Docker 部署需要使用 .env 文件保存关键环境变量。先复制官方示例配置：

cp .env.example .env

查看配置文件：

vim .env

对于本地测试，通常可以先保持默认配置。后续如果要对接外部服务、修改访问域名、调整文件上传大小、配置向量数据库或接入对象存储，再根据需求修改。

常见需要关注的配置包括：

配置方向	说明
访问地址	如果部署到服务器，需要调整外部访问 URL
端口映射	如果 80、443 或 5003 端口冲突，需要修改映射
数据库配置	默认使用容器内 PostgreSQL，一般无需改动
Redis 配置	默认使用容器内 Redis，一般无需改动
向量数据库	默认使用 Weaviate，后续可按需求切换
文件上传限制	如果知识库文件较大，可后续调整上传大小限制

初学者建议第一遍先不要大幅修改 .env，先确保系统能成功启动和访问，再逐步调整配置。

七、启动 Dify 服务

在 dify/docker 目录下执行：

docker compose up -d

首次启动会自动拉取多个镜像，耗时取决于网络环境。等待完成后，检查容器状态：

docker compose ps

如果服务正常启动，会看到多个容器处于 Up、running 或 healthy 状态。Dify 通常会启动 Web、API、Worker、插件服务，以及 PostgreSQL、Redis、Weaviate、Nginx、Sandbox 等依赖组件。

也可以查看日志：

docker compose logs -f

如果只想查看 API 服务日志：

docker compose logs -f api

如果只想查看 Web 服务日志：

docker compose logs -f web

八、浏览器访问 Dify

8.1 首次初始化

打开 Windows 浏览器，访问：

http://localhost/install

首次访问会进入管理员账号初始化页面，需要设置：

• 管理员邮箱；
• 管理员用户名；
• 登录密码。

初始化完成后，再访问：

http://localhost

即可进入 Dify 控制台。

8.2 创建第一个应用

进入 Dify 后，可以按以下步骤简单验证系统是否可用：

1. 点击「创建应用」；
2. 选择「聊天助手」或「Chatflow」；
3. 配置模型供应商，例如 OpenAI、Azure OpenAI、通义千问、DeepSeek、Ollama 等；
4. 保存模型 API Key；
5. 在调试窗口输入问题，测试是否能够正常回复。

如果还没有外部大模型 API，也可以先完成 Dify 平台初始化，后续再配置模型供应商。

九、常用管理命令

9.1 查看容器状态

cd ~/projects/dify/docker
docker compose ps

9.2 查看全部日志

docker compose logs -f

9.3 重启 Dify

docker compose restart

9.4 停止 Dify

docker compose down

9.5 重新启动 Dify

docker compose up -d

9.6 修改配置后重启

如果修改了 .env，建议执行：

docker compose down
docker compose up -d

9.7 更新镜像

docker compose pull
docker compose down
docker compose up -d

更新前建议备份 .env 和 volumes/ 目录，避免配置或数据丢失。

十、常见问题与解决方法

10.1 浏览器打不开 http://localhost

先检查容器是否启动：

docker compose ps

如果容器未启动，重新执行：

docker compose up -d

如果容器已经启动，但页面打不开，检查 Nginx 容器日志：

docker compose logs -f nginx

也可以检查端口是否被占用。

在 Windows PowerShell 中执行：

netstat -ano | findstr :80

如果 80 端口被 IIS、Nginx、Apache 或其他服务占用，可以关闭占用服务，或者修改 Docker Compose 的端口映射。

10.2 docker compose 命令不存在

检查 Docker Desktop 是否正在运行，并确认 Docker Compose 版本：

docker compose version

注意现在推荐使用：

docker compose up -d

而不是老版本写法：

docker-compose up -d

如果仍然无法使用，打开 Docker Desktop 设置，确认已经启用 WSL2 后端和 Ubuntu 集成。

10.3 镜像拉取很慢或失败

常见原因是网络访问 Docker 镜像源较慢。可以尝试：

• 更换网络环境；
• 配置 Docker 镜像加速；
• 使用稳定代理网络；
• 多执行几次 docker compose pull。

命令如下：

docker compose pull

拉取完成后再启动：

docker compose up -d

10.4 端口冲突

Dify 默认会通过 Nginx 暴露 Web 访问端口，通常使用 80 或 443。如果本机已有其他 Web 服务，就可能发生端口冲突。

检查端口：

netstat -ano | findstr :80
netstat -ano | findstr :443

如果确认冲突，可以在 docker-compose.yaml 或相关配置中修改端口映射。例如把本机访问端口改成 8080：

ports:
  - "8080:80"

修改后重启：

docker compose down
docker compose up -d

然后访问：

http://localhost:8080

10.5 WSL2 没有启用

如果 Docker Desktop 提示 WSL2 异常，可以重新检查：

wsl --status
wsl -l -v

如果 Ubuntu 不是 Version 2，可以执行：

wsl --set-version Ubuntu-22.04 2

实际发行版名称以 wsl -l -v 输出为准。

10.6 修改 .env 后没有生效

修改 .env 后，需要重新创建容器：

docker compose down
docker compose up -d

只执行 restart 有时不会让所有环境变量重新加载，因此配置类修改更建议使用 down 后再 up -d。

10.7 磁盘占用越来越大

Docker 镜像、容器和数据卷会占用较多磁盘空间。可以查看占用：

docker system df

清理无用镜像和缓存：

docker system prune

注意：不要随意删除 Dify 正在使用的数据卷，否则可能导致知识库、应用配置、数据库数据丢失。

十一、后续扩展方向

完成本地部署后，可以继续尝试以下扩展：

11.1 接入本地大模型

可以通过 Ollama、vLLM、LM Studio 或自建推理服务接入本地模型。例如在本地启动 Ollama 后，将其作为 OpenAI-Compatible 接口配置到 Dify 中。

适合场景：

• 内网知识库问答；
• 无外网 API 环境；
• 本地模型测试；
• 实验室模型部署验证。

11.2 构建知识库问答

可以上传 PDF、Word、Markdown、TXT 等文件，构建知识库，再创建知识库问答应用。

建议流程：

准备文档 → 上传知识库 → 文档分段 → 向量化 → 创建应用 → 绑定知识库 → 测试问答效果

11.3 构建工作流应用

Dify 的工作流可以把 LLM 节点、条件判断、HTTP 请求、知识库检索、变量处理等串联起来，适合构建更复杂的业务系统。

例如：

• 图片识别结果 + 大模型分析；
• 茶叶病害检测 API + 品质评估报告生成；
• 文档解析 + 知识库问答；
• 表单输入 + 自动生成方案。

11.4 部署到局域网或服务器

如果希望局域网其他电脑访问，可以查看 Windows 本机 IP：

ipconfig

假设本机 IP 为：

192.168.1.100

同一局域网内其他电脑可以尝试访问：

http://192.168.1.100

如果无法访问，需要检查：

• Windows 防火墙；
• Docker Desktop 网络设置；
• 路由器网络隔离；
• Dify 端口映射是否正确。

十二、总结

本文以 Windows 为演示环境，完整介绍了 Dify 本地化部署流程。核心步骤并不复杂：先准备 WSL2、Docker Desktop 和 Git，然后在 WSL2 的 Linux 文件系统中拉取 Dify 源码，复制 .env 配置文件，最后通过 docker compose up -d 启动服务。首次启动完成后，访问 http://localhost/install 初始化管理员账号，即可进入 Dify 控制台。

对于初学者来说，建议先完成最小化部署，不要一开始就修改太多配置。等系统可以正常访问后，再逐步扩展模型供应商、知识库、工作流、本地模型和内网服务。这样既能降低部署失败概率，也更便于定位问题。

附录：最小部署命令汇总

# 1. 进入 WSL2 Ubuntu
mkdir -p ~/projects
cd ~/projects

# 2. 安装基础工具
sudo apt update
sudo apt install -y git curl jq

# 3. 拉取 Dify 最新 Release 源码
git clone --branch "$(curl -s https://api.github.com/repos/langgenius/dify/releases/latest | jq -r .tag_name)" https://github.com/langgenius/dify.git

# 4. 进入 Docker 部署目录
cd dify/docker

# 5. 复制环境变量文件
cp .env.example .env

# 6. 启动服务
docker compose up -d

# 7. 查看容器状态
docker compose ps

浏览器访问：

http://localhost/install

初始化完成后访问：

http://localhost

参考资料

• Dify 官方文档：Deploy Dify with Docker Compose
• Docker 官方文档：Install Docker Desktop on Windows
• Microsoft 官方文档：Install WSL