Dify 本地部署教程：基于 Docker Compose 的私有化安装步骤

看着别人在 Dify 上轻松拖拽生成 AI 应用，自己也想试试，结果卡在“怎么把这套复杂的系统搬进自家服务器”这一步？尤其是面对一堆微服务组件，手动安装简直是一场噩梦。

其实，官方提供的 Docker Compose 方案已经帮我们屏蔽了绝大多数底层依赖。只要你的机器能跑 Docker，剩下的工作基本上就是“下载、改两个参数、启动”。别被那些复杂的架构图吓到，我们直接看怎么让它在你的电脑上转起来。

1. 检查前置环境与获取代码

在动手之前，先确认你的电脑或服务器上已经安装了 Docker 和 Docker Compose。现在的 Docker Desktop 通常自带 Compose 插件，你在终端输入 docker compose version 能看到版本号就算过关。如果还在用旧版的 docker-compose 命令，建议尽快升级，因为官方脚本主要适配新版语法。

接下来，我们需要从 GitHub 获取最新的部署脚本。打开终端，找一个空间充足的目录（Dify 运行后会产生不少镜像和数据），执行以下命令克隆仓库：

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

进入 docker 目录后，你会看到几个关键文件。这里不需要去根目录找，所有的启动配置都收敛在这个文件夹里。这种结构的好处是干净，不会污染你的其他项目文件。

Dify 部署脚本集中在 docker 目录下，结构清晰

2. 修改关键环境变量

直接运行默认配置虽然能启动，但为了后续使用顺畅，有两个地方必须看一眼。首先是 .env 文件，它是整个系统的控制中心。

复制一份示例配置：

cp .env.example .env

用编辑器打开 .env，重点检查 EXPOSE_NGINX_PORT。默认是 80，如果你本地已经跑了 Nginx 或其他 Web 服务，端口冲突会导致启动失败。把它改成 8080 或者 3000 等空闲端口更稳妥。

另外，如果你打算接入自己的大模型 API（比如 OpenAI 或 Azure），可以在这里预填 OPENAI_API_KEY，这样启动后就不用再去网页后台反复找了。不过，即使现在不填，后面在 Web 界面里也能随时补充，所以不必有压力。

修改 .env 文件中的端口和 API Key 配置

3. 启动服务与等待初始化

一切就绪后，执行启动命令：

docker compose up -d

加上 -d 参数会让容器在后台运行，终端不会一直被日志刷屏。第一次启动时，Docker 需要拉取多个镜像，包括前端、后端、Worker、Redis、PostgreSQL 和 Weaviate（向量数据库）。这取决于你的网络状况，可能需要几分钟到十几分钟不等。

你可以使用 docker compose ps 随时查看状态。只有当所有服务的 STATUS 都显示为 Up 且健康检查通过时，才算真正准备好。特别注意 api 和 worker 服务，如果它们不断重启，通常是数据库连接或环境变量配置有误。

使用 docker compose ps 查看所有服务运行状态

4. 访问界面与初始账号设置

当所有容器稳定运行后，打开浏览器，访问 http://localhost:你设置的端口。如果之前没改端口，就是 http://localhost。

首次访问会跳转到初始化页面。你需要创建一个管理员账号，设置邮箱和密码。这一步完成后，你就拥有了一个完全属于你自己的 Dify 实例。

进入控制台后，建议先去“模型供应商”页面测试一下模型连接。如果之前在 .env 里没填 Key，现在填上也来得及。试着发送一条简单的对话请求，如果能收到回复，说明从前端到后端再到模型接口的整条链路已经打通。

首次访问 Dify 时的管理员账号创建界面

5. 常见启动问题与数据持久化

如果遇到启动失败，90% 的情况是因为端口被占用或者内存不足。Dify 的全家桶比较吃资源，建议至少预留 4GB 以上的可用内存。如果是 Mac 用户，记得在 Docker Desktop 的设置里调高资源限额。

关于数据保存，默认的 docker-compose.yaml 已经配置了 Volume 挂载，这意味着你的应用数据、知识库文件和数据库记录都会保存在本地磁盘。即使删除了容器，只要不手动删掉这些卷，下次重新 up 时数据依然还在。

如果想彻底重置，可以使用 docker compose down -v，但这会清空所有数据，操作前请务必确认备份。对于日常迭代更新，只需拉取最新代码并重新执行 docker compose up -d --build 即可平滑升级。

现在，你的私有 AI 开发平台已经就绪，可以去尝试创建第一个聊天助手或工作流了。