在自己的电脑上使用 Dify，需要先准备容器环境、配置文件，并确认服务和模型连通性。本文以Dify 社区版 1.17.1为固定版本，分别说明 macOS 与 Windows 的准备步骤，再通过 Docker Compose 完成部署、账号初始化和一次聊天验证。

完成后，应能在本机浏览器登录 Dify，并创建一个能收到模型回复的聊天应用。本文面向全新安装和本地学习，已有实例升级请先阅读目标版本的升级说明。

**适用范围：**macOS / Windows；Docker Compose 部署；Dify 1.17.1。

1. 准备工作

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

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

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

2. macOS 环境准备

2.1 安装 Docker Desktop

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

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

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

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

2.2 检查工具

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

git--versiondocker--versiondockercompose versiondockerinfo

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

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

3. Windows 环境准备

3.1 安装 WSL 2 和 Ubuntu

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

wsl--install-d Ubuntu

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

回到 PowerShell，执行：

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

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

wsl--set-versionUbuntu 2

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

参考：微软 WSL 安装说明。

3.2 安装并配置 Docker Desktop

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

安装后启动 Docker Desktop，确认：

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

参考：Docker WSL 集成说明。

3.3 在 Ubuntu 中检查环境

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

安装 Git：

sudoaptupdatesudoaptinstall-ygit

检查环境：

git--versiondocker--versiondockercompose versiondockerinfo

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

4. 下载并启动 Dify

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

4.1 下载固定版本

mkdir-p~/projectscd~/projectsgitclone--depth1--branch1.17.1 https://github.com/langgenius/dify.gitcddify/docker

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

如果已有dify目录，先确认是否包含已有环境或数据；必要时使用其他空目录，避免混用。命令固定检出1.17.1，后续配置与运行也应使用这一版本的文件。Dify 1.17.1 发布页

4.2 创建配置文件

cp.env.example .env

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

参考：1.17.1 配置模板。

4.3 检查配置并启动

逐条执行：

dockercompose config--quietdockercompose pulldockercompose up-ddockercomposeps-a

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

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

参考：官方启动步骤。

5. 初始化账号并接入模型

5.1 创建管理员

在电脑浏览器访问http://localhost/install，按页面提示创建管理员账号。

完成后访问http://localhost登录。以上地址使用默认 HTTP 端口；如果修改过端口映射，应使用实际配置的端口。

5.2 配置模型供应商

进入工作区的模型供应商 / Model Provider页面。入口可能显示为集成 → 模型供应商，部分界面位于头像菜单的设置中：

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

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

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

5.3 验证完整链路

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

请用一句话介绍你自己。

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

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

6. 日常启动与停止

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

cd~/projects/dify/docker

启动服务：

dockercompose up-d

查看状态：

dockercomposeps-a

查看最近日志：

dockercompose logs--tail=100

停止服务：

dockercompose stop

停止后再次启动：

dockercompose start

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

7. 常见问题处理

针对页面或后端问题：

dockercompose logs--tail=100nginx web api

针对插件问题：

dockercompose logs--tail=100plugin_daemon

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

8. 验收清单

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

9. 官方参考资料

• Dify Docker Compose 部署
• Dify 1.17.1 发布说明与升级要求
• Docker Desktop：macOS 安装
• Docker Desktop：Windows 安装
• Docker Desktop：WSL 2 集成
• 微软 WSL 安装说明