Dify 本地环境搭建教程：macOS / Windows

部署方式：Docker Compose｜适用版本：Dify 1.17.1｜用途：本地学习、开发和功能验证

本文依据 2026 年 10 月 16 日核对的官方资料整理，未在你的 Mac 和 Windows 设备上实际执行。以下适用于全新安装，已有环境升级请遵循目标版本的升级说明。

一、准备工作

项目	macOS	Windows
容器环境	Docker Desktop	Docker Desktop + WSL 2
执行安装命令	系统"终端"	Ubuntu 终端
项目位置	用户目录下	Ubuntu 的 Linux 文件目录下
建议电脑内存	16 GB 或以上	16 GB 或以上
建议预留磁盘	30 GB 或以上	30 GB 或以上

以上内存和磁盘为本教程的使用建议。Dify 要求 Docker Compose 2.24.0 或以上 ；Mac 的 Docker 虚拟机至少分配 2 核 CPU、8 GiB 内存。安装时应同时满足当前 Docker Desktop 的操作系统要求。

网络需能访问 GitHub、Docker 镜像仓库，以及后续使用的插件市场和模型服务。

参考：Dify 部署要求、Dify 1.17.1 发布说明。

二、macOS 环境准备

2.1 安装 Docker Desktop

打开 Docker Desktop for Mac 官方下载页，按芯片选择安装包：

M 系列芯片：Apple silicon。
Intel 芯片：Intel chip。

安装后启动 Docker Desktop，等待 Docker 引擎就绪。

进入 Settings → Resources，为 Docker 分配至少 8 GiB 内存，应用设置。具体设置位置以当前版本界面为准。

2.2 检查工具

打开系统"终端"，分别执行：

bash 复制代码

git --version
docker --version
docker compose version
docker info

验收标准：Git、Docker、Compose 能显示版本；Compose 不低于 2.24.0；docker info 能正常返回服务端信息。

如果 Git 提示需要安装开发者工具，按系统提示完成安装。

三、Windows 环境准备

3.1 安装 WSL 2 和 Ubuntu

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

powershell 复制代码

wsl --install -d Ubuntu

按提示重启电脑。随后打开 Ubuntu，完成 Linux 用户名、密码设置。输入 Linux 密码时，终端不会显示字符，属于正常现象。

回到 PowerShell，执行：

powershell 复制代码

wsl --update
wsl --version
wsl -l -v

确认 Ubuntu 的 VERSION 为 2。如果为 1，执行：

powershell 复制代码

wsl --set-version Ubuntu 2

如果发行版名称不是 Ubuntu，使用 wsl -l -v 显示的实际名称。已有 WSL 2 和 Ubuntu 时，可直接检查版本，无需重复安装。

参考：微软 WSL 安装说明。

3.2 安装并配置 Docker Desktop

从 Docker Desktop for Windows 官方页面下载符合电脑架构的安装包，并核对 Windows 版本、WSL 版本及硬件虚拟化要求。

安装后启动 Docker Desktop，确认：

Settings → General ：启用 Use the WSL 2 based engine。
Settings → Resources → WSL Integration：启用 Ubuntu 集成。
应用设置，等待 Docker 就绪。

参考：Docker WSL 集成说明。

3.3 在 Ubuntu 中检查环境

从这一步开始，Windows 用户的部署命令全部在 Ubuntu 终端执行。

安装 Git：

bash 复制代码

sudo apt update
sudo apt install -y git

检查环境：

bash 复制代码

git --version
docker --version
docker compose version
docker info

如果找不到 docker，检查 Docker Desktop 是否启动，以及 Ubuntu 的 WSL Integration 是否开启。采用这条部署路线时，Ubuntu 无需另装一套 Docker Engine。

四、下载并启动 Dify

以下命令适用于 Mac 系统终端、Windows Ubuntu 终端。

4.1 下载固定版本

bash 复制代码

mkdir -p ~/projects
cd ~/projects
git clone --depth 1 --branch 1.17.1 https://github.com/langgenius/dify.git
cd dify/docker

Windows 用户请保留这个 Linux 路径，避免改到 /mnt/c/ 下，减少跨文件系统访问带来的问题。

如果已有 dify 目录，先确认是否包含已有环境或数据；必要时使用其他目录，避免混用。

4.2 创建配置文件

bash 复制代码

cp .env.example .env

首次本地体验可使用默认配置。该版本的基础配置位于 .env，可选配置模板位于 envs/。复制操作适用于全新安装；已有环境不要直接覆盖 .env。

参考：1.17.1 配置模板。

4.3 检查配置并启动

逐条执行：

bash 复制代码

docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps -a

第一条命令成功时通常没有输出。首次拉取镜像耗时取决于网络和镜像大小。

持续运行的服务应显示 Up 或 healthy。init_permissions 是一次性权限初始化任务，正常完成后退出属于预期行为；若退出码非零，则需要查看日志。

参考：官方启动步骤。

五、初始化账号并接入模型

5.1 创建管理员

在电脑浏览器访问管理员初始化页面，按页面提示创建账号。

完成后访问本地 Dify。

5.2 配置模型供应商

进入工作区 设置 → 模型供应商：

选择需要使用的供应商。
如有提示，安装对应模型插件。
填写供应商提供的 API Key 及其他必要参数。
验证并保存。

Dify 部署完成后，还需要配置模型访问凭据，才能正常调用对应模型。使用云端模型时，计费和额度由模型供应商决定。

参考：模型配置说明、官方插件市场。

5.3 验证完整链路

创建一个简单聊天应用，选择已配置的模型，输入：

请用一句话介绍你自己。

正常返回回答，即可确认"浏览器 → Dify → 模型服务"的基本链路可用。

若需使用知识库，还应配置 Embedding 模型，并通过上传文件、完成索引、成功检索来单独验收。

六、日常启动与停止

以下命令都在项目的 dify/docker 目录执行：

bash 复制代码

cd ~/projects/dify/docker

启动服务：

bash 复制代码

docker compose up -d

查看状态：

bash 复制代码

docker compose ps -a

查看最近日志：

bash 复制代码

docker compose logs --tail=100

停止服务：

bash 复制代码

docker compose stop

停止后再次启动：

bash 复制代码

docker compose start

保留项目配置和持久化数据目录，便于继续使用。备份或升级前，应按目标版本官方说明处理数据库及其他持久化数据。

七、常见问题处理

现象	优先检查
无法连接 Docker daemon	Docker Desktop 是否启动，`docker info` 是否正常
Ubuntu 中找不到 Docker	是否开启 Ubuntu 的 WSL Integration
镜像拉取超时	查看 pull 报错，检查网络、代理及镜像仓库访问
`port is already allocated`	按报错定位占用端口的程序，释放端口后重试
页面打不开或出现 502	检查服务状态，以及 nginx、web、api 日志
容器反复重启	检查对应服务日志、Docker 内存和磁盘空间
模型调用失败	检查插件、API Key、额度、接口地址及容器网络
插件安装失败	检查 plugin_daemon 日志，以及插件市场和下载网络

针对页面或后端问题：

bash 复制代码

docker compose logs --tail=100 nginx web api

针对插件问题：

bash 复制代码

docker compose logs --tail=100 plugin_daemon

若服务名称不存在，先通过 docker compose ps -a 确认实际名称。

八、验收清单

Docker Desktop 正常运行。
持续运行的服务没有反复退出。
能打开本地登录页面，并创建管理员账号。
至少一个模型供应商配置成功。
聊天应用能收到模型回复。
停止并重新启动后，仍能登录并看到已创建的应用。

九、官方参考资料

封面为 AI 生成插图，用于本教程展示，不代表官方背书。分享本文时，请将 Markdown 和封面图片保存在同一文件夹。