Dify部署全攻略：从Docker环境到LLM应用平台落地

最近好多朋友私信问我同一件事：Dify 到底怎么装？尤其是第一次接触 LLM 应用开发的同学，往往在“环境准备”这一步就卡住了。我特别理解这种挫败感——Dify 官方文档写得不算差，但它默认你懂 Docker、懂 Git、懂环境变量，而这些前置知识恰恰是新手最容易栽跟头的地方。这篇文章不打算复述官方 README，而是把我自己从零到一部署 Dify 的完整过程扒开来讲：每一步命令为什么要执行、配置文件里每个变量改的是什么、启动失败时该看哪个日志、以后想升级怎么操作。内容同时覆盖 Windows 和 Linux 两种场景，不管你是想在笔记本上本地体验，还是打算部署到云服务器当团队平台，照着走基本都能顺利落地。

我还会把一些网上搜不到的细节补上，比如 .env 里容易忽略的 SECRET_KEY、向量数据库的选型逻辑、以及用 Ollama 接本地模型的设置方法。当然，实操中肯定有坑，我也会把踩坑记录整理成排查清单，帮你避开我当初折腾过的那些弯路。

1. 动手之前：理解 Dify 的部署逻辑与资源清单

很多人在安装 Dify 时失败，不是因为命令敲错了，而是根本没搞懂自己到底在装什么。Dify 不是一个单文件程序，它是一组服务的组合，需要 Docker 这样的容器编排工具把它们一起拉起来。先把这一点弄清楚，后面遇到任何报错都不会懵。

1.1 Dify 是什么、安装它到底装了哪些东西

Dify 是一个开源的大语言模型（LLM）应用开发平台。你可以把它理解成一个“AI 应用工作台”：在网页界面上拖拽节点就能编排 Prompt、搭建工作流、挂知识库、创建 Agent，还能统一管理多家模型厂商的 API Key。它内置了模型管理、数据集管理、日志分析、API 发布等能力，省掉了从零搭后端的巨大工作量。

当你执行安装命令之后，Dify 并不是启动一个进程，而是会按照编排文件拉起一整套互相协作的容器服务。典型的服务包括：

• api：后端 API 服务，负责业务逻辑、鉴权、知识库检索、工作流执行。
• worker：异步任务队列消费者，处理文档索引、数据集切分、批处理任务。
• web：前端界面服务，也就是你浏览器里看到的初始化页面和操作台。
• db：PostgreSQL 数据库，存储用户、应用、工作流配置等元数据。
• redis：缓存与消息队列，支撑 worker 任务分发。
• sandbox：代码执行沙箱，用于安全运行工作流中的 Python/Node 代码节点。
• ssrf_proxy：请求代理服务，防止服务端请求伪造攻击。
• nginx：反向代理入口，统一转发到 web 和 api。
• weaviate / qdrant：向量数据库（二选一），存放知识库的向量化数据。

我第一次部署时看到容器列表也有点头大，后来总结了一句话：只要记住“nginx 是门卫、api 是大脑、db 是记事本、向量库是索引卡”就够用了。排查问题时，顺着这条链路去查日志，基本不会跑偏。

1.2 部署前需要准备的环境清单

先别急着敲命令，对照下面的清单确认一下你的机器是否达标。Dify 对硬件要求其实不高，但太弱跑起来会卡，尤其是知识库切分和模型调用时很吃内存。

很多人忽略端口占用问题。Dify 默认用 80 端口对外提供服务，如果本机 80 端口已经被其他 Web 服务占用，启动后页面会打不开。提前用 netstat -ano | findstr :80（Windows）或 ss -tlnp | grep :80（Linux）检查一下，省得到时候一头雾水。

1.3 本地还是服务器：两种部署场景怎么选

安装前还要想清楚一件事：你是在自己电脑上跑，还是部署到云服务器？

本地部署适合个人体验、二次开发调试、快速验证想法。Windows 用户需要借助 Docker Desktop 的 WSL2 后端来模拟 Linux 环境，好处是生态干净、卸载方便；缺点是笔记本休眠、网络波动时容器状态容易异常，不适合长期对外提供服务。

如果是团队协作或生产环境，我建议直接买一台 2 核 4 GB 起步的 Linux 云服务器。服务器部署可以固定公网 IP，配合域名和 HTTPS 证书对外提供稳定访问，也不用担心笔记本合盖后服务中断。需要注意，云服务器厂商的安全组策略里必须放行 80 端口（或者你自定义的映射端口），否则外部访问会超时。

两种场景在操作步骤上差异不大，差异主要体现在第 2 章的 Docker 安装方式和第 4 章的访问入口配置。下面我会把两条线都写清楚。

2. 前置环境准备：Docker 与 Git 的安装配置

Dify 官方推荐用 Docker Compose 方式部署，所以 Docker 是重中之重。我见过不少人在这一环节被劝退，其实只要抓住核心需求：能跑起来、能拉镜像、能看日志，就够了。

2.1 Windows 下安装 Docker Desktop 的关键细节

Windows 上安装 Docker Desktop 之前，务必先确认两件事：BIOS 里是否开启了虚拟化，以及系统是否支持 WSL2。任务管理器“性能”标签里能看到“虚拟化：已启用”，如果没有启用，需要进 BIOS 打开 VT-x 或 AMD-V。

确认没问题后，打开 PowerShell（管理员模式）执行：

powershell复制wsl --install

这条命令会安装 WSL2 和默认的 Ubuntu 发行版。装完后重启电脑，在 PowerShell 里执行 wsl --status 确认 WSL 版本是 2。如果显示的还是 WSL1，执行 wsl --set-default-version 2 切换。

接下来去 Docker 官网下载 Docker Desktop for Windows，双击安装。安装过程中会提示是否使用 WSL2 后端，务必勾选。安装完成后启动 Docker Desktop，首次启动可能需要几分钟初始化。

打开 Docker Desktop 的 Settings → Resources，可以看到 WSL Integration 选项，确保你刚装的 Ubuntu 发行版处于开启状态。这一步很多人漏掉，导致后续在终端里执行 docker 命令提示找不到程序。

验证 Docker 是否可用，在终端执行：

bash复制docker version
docker compose version

两条命令都能正常输出版本号，Docker 环境就准备好了。

2.2 Linux 服务器安装 Docker 与 Docker Compose

Linux 服务器上安装 Docker 我推荐走官方仓库方式，别用一键脚本，因为系统差异容易踩坑。以 Ubuntu/Debian 为例：

bash复制sudo apt update
sudo apt install -y ca-certificates curl gnupg lsb-release
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

安装完成后，把当前用户加入 docker 组，避免每次都要 sudo：

bash复制sudo usermod -aG docker $USER

重新登录终端后执行 docker info 确认没问题。新版 Docker 默认自带 compose 插件，直接使用 docker compose（中间有空格）命令，不需要单独安装 docker-compose 旧版二进制。

这里提醒一句：网上很多教程还在让你装 docker-compose 并用连字符命令，旧命令和新命令不兼容的场景不少。Dify 部署文档用的是新版 docker compose，所以认准空格版即可。

2.3 配置镜像加速器，解决拉取慢的问题

Dify 全家桶要拉的镜像加起来接近十个 GB，如果网络到 Docker Hub 不稳定，很容易在 docker compose up -d 那一步卡到怀疑人生。最有效的解决办法是配置 registry mirror。

在 /etc/docker/daemon.json 里写入以下内容：

json复制{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://mirror.ccs.tencentyun.com"
  ]
}

然后重启 Docker：

bash复制sudo systemctl daemon-reload
sudo systemctl restart docker

如果是 Docker Desktop，直接在 Settings → Docker Engine 里把上面的 JSON 合并进去，点击 Apply & Restart 即可。

镜像加速器本质是公共缓存服务，地址偶尔会变动失效，如果拉取时报错，换成自己云厂商提供的加速地址就行。配置完成后，可以先拉一个测试镜像验证：

bash复制docker pull busybox:latest

能秒拉说明加速生效，后面部署 Dify 会顺畅很多。这一步千万别省，我在不同网络环境下部署过好多次，镜像加速器配置与否，体感差五倍以上。

3. 获取 Dify 源码并理解关键部署文件

Dify 的安装方式不是下载一个安装包，而是把整个开源仓库克隆到本地，然后进入其中的 docker 目录执行编排命令。这一设计的好处是升级方便、自定义空间大，但也意味着你必须跟 Git 仓库打交道。

3.1 用 Git 拉取 Dify 仓库

在准备部署的目录下执行：

bash复制git clone https://github.com/langgenius/dify.git

如果网络不稳定导致 clone 超时或中断，可以换 Gitee 上的镜像仓库，或者错峰重试。clone 完成后：

bash复制cd dify
git tag

git tag 会列出所有发布版本，比如 1.10.0、1.11.0 这样的版本号。建议不要直接用最新 main 分支跑生产环境，而是切换到指定发布版本，方便后续排查问题：

bash复制git checkout 1.10.0

版本号自己按需选择，只要是较新的稳定发布版即可。切换版本后，你应该能在 dify/docker 目录下看到 docker-compose.yaml、.env.example、docker-compose.middleware.yaml 等文件。这些就是部署的核心。

3.2 docker 目录下的文件到底有什么用

很多教程上来就让你 cp .env.example .env，但你完全不知道这些文件是干嘛的，遇到问题就抓瞎。我简单拆一下：

• docker-compose.yaml：主编排文件，定义了 api、web、worker、db、redis、nginx 等服务的镜像、端口、依赖关系和环境变量。正常情况下不需要改它，所有可调参数都通过 .env 注入。
• docker-compose.middleware.yaml：中间件编排文件，定义了 Postgres、Redis、Weaviate/Qdrant、Sandbox 等依赖服务。如果你是那种追求极简的人，也可以自己准备外部数据库，但新手不建议，直接用内置的最省心。
• .env.example：环境变量模板，里面是全部的默认配置。你需要把它复制成 .env，然后按需修改。
• volumes 目录：启动后自动生成的数据持久化目录，数据库文件、上传文件、日志都放这里。备份整个 docker 目录基本就等于备份了整个 Dify。

理解这一点后，你就能明白：Dify 的安装实际上就是把 git 仓库里的“部署配方”跑起来，容器都是现成的镜像，不会在你本地编译源码。

3.3 版本选择与目录迁移建议

如果你之前用过旧版本，想在新服务器部署新版本，建议直接拉新 tag 的代码，不要从旧目录原地升级跨大版本。Dify 的数据结构变更比较频繁，跨版本升级前务必备份。

还有一点，很多人习惯把 dify 仓库放在 root 目录下，这没问题，但要注意磁盘分区是否够用。Dify 的镜像和 volume 数据默认存在 Docker 的数据目录（Linux 下通常在 /var/lib/docker），常有人把代码放在数据盘，却忘了 Docker 本身在系统盘，结果系统盘被塞满。如果服务器有多块磁盘，建议把 Docker 的数据根目录迁移到大分区，在 daemon.json 里加一行 "data-root": "/data/docker" 再重启 Docker，一劳永逸。

4. 配置环境变量与启动部署

环境准备和源码拉取都没问题时，真正的重头戏来了：配置 .env 并启动整个服务栈。这一步也是配置项最多、最容易出错的地方。

4.1 从 .env.example 到 .env：核心参数说明

先进入 Dify 的 docker 目录，复制配置模板：

bash复制cd dify/docker
cp .env.example .env

打开 .env，你会看到一长串配置。新手没必要全部理解，但要重点掌握几个核心变量：

改 SECRET_KEY 时可以用命令生成一个足够随机的字符串：

bash复制openssl rand -base64 42

把输出粘贴到 .env 的 SECRET_KEY 位置即可。数据库密码同理，自己记好，后面容器初始化时会用到。

关于向量数据库，默认 weaviate 对新手最友好，不需要额外配置。如果你的知识库数据量非常大，或者准备对接专门的向量数据库服务，再考虑换成 qdrant 或其他方案。在没搞明白差异之前，保持默认值是最稳妥的选择。

4.2 docker compose 启动与验证

完成 .env 修改后，在 dify/docker 目录下执行：

bash复制docker compose up -d

-d 表示后台运行，第一次执行会拉取大量镜像，耗时取决于网络。看到所有容器都处于 running 状态后，用以下命令确认：

bash复制docker compose ps

正常会看到类似下面的输出：nginx、api、worker、web、db、redis、sandbox、ssrf_proxy、weaviate 等容器，STATUS 列都是 Up。

然后打开浏览器访问 http://localhost（如果你改了端口就访问 http://localhost:8080）。如果看到 Dify 的初始化界面，说明部署成功了。如果页面一直转圈或报 502，不要慌，先看日志：

bash复制docker compose logs -f api
docker compose logs -f nginx

日志里通常会有明确的报错原因，比如数据库连接失败、端口冲突等。把日志关键字输入搜索引擎，基本都能找到答案。

4.3 初始化管理员账号并接入模型

第一次打开 Dify 页面时，会要求你设置管理员邮箱和密码。这里输入的账号就是平台的超级管理员，密码建议用强密码，因为后台能管理所有 AI 应用和模型密钥。

初始化完成后进入主界面，第一件事是接入模型供应商。点击右上角头像进入“设置”，找到“模型供应商”，可以看到 OpenAI、Anthropic、Ollama、Azure OpenAI、通义千问等一大堆选项。按你手头的 API Key 类型选择对应厂商，填入密钥后完成配置。

模型接入这一步决定了你之后能不能真正跑通一个 AI 应用。建议先配一个你最常用的模型，比如 OpenAI 系的 GPT 系列，或者国内可用的通义千问、智谱等。配好之后在“创建空白应用”里选一个对话型应用，模型选刚才配置的那个，发一条测试消息，能正常回复就说明整条链路通了。

5. 常见问题排查与日常升级

部署从来不是一次完事，后续的维护、排障和升级才是常态。以下是我实际操作中遇到过的问题和处理方法，整理成速查表供参考。

5.1 启动失败的几个高频原因

遇到容器反复重启，先执行 docker compose ps 看哪些容器状态异常，再针对性地看日志。比如 db 容器起不来，多半是端口 5432 被占用，或者宿主机上已有 PG 数据库冲突。

5.2 Ollama 本地模型接入设置

如果你不想把数据发给外部模型厂商，想在本地跑开源模型，Dify 支持通过 Ollama 接入。先在宿主机安装 Ollama，拉取一个模型，比如：

bash复制ollama pull qwen2.5:7b

然后在 Dify 后台的“模型供应商”里选择 Ollama，填写配置：

• Base URL：Windows 下填 http://host.docker.internal:11434，Linux 下填 http://localhost:11434
• 模型名称：填 Ollama 里已拉取的模型名，比如 qwen2.5:7b

这里有个坑：Dify 的容器运行在 Docker 网络里，访问宿主机不能用 localhost，必须用 Docker 提供的特殊域名。Windows 和 macOS 上 Docker Desktop 提供了 host.docker.internal，Linux 上需要手动在启动容器时加 --add-host=host.docker.internal:host-gateway 才会生效。

填完配置后，在应用编排界面把模型切换成刚才配置的 Ollama 模型，发一条测试消息。如果报连接错误，先确认 Ollama 服务正在运行，再到 api 容器里测试网络连通性：

bash复制docker compose exec api curl http://host.docker.internal:11434

能返回 Ollama 的版本信息说明网络通了，剩下就是模型名写没写对的问题。

5.3 Dify 社区版在线升级步骤

Dify 的版本迭代很快，隔一段时间就想升级。升级前一定先备份数据，尤其是 docker 目录里的 volumes 数据。备份方式很简单，把整个 dify/docker/volumes 目录打包拷贝走即可。

升级步骤：

bash复制cd dify
git pull
git checkout <新版本tag>
cd docker
docker compose down
docker compose pull
docker compose up -d

docker compose down 会停止容器但不会删除 volumes 数据，所以不用担心数据丢失。docker compose pull 会拉取新镜像，up -d 重新创建容器。升级后第一次启动会自动执行数据库迁移，稍微等一会再访问页面。

需要注意，如果升级跨度特别大，比如从 0.x 直接跳到 1.x，直接 up -d 可能因数据库结构差异过大而报错。稳妥做法是先看官方升级文档，确认是否需要手动执行迁移命令，或者一步步升级中间版本。

还有个小技巧：升级前先看一眼新版 .env.example 和老 .env 的差异，因为每次版本升级都会新增配置项。如果某个功能启用不了，多半是 .env 里缺了新变量。用文本对比工具比对一下，把新增项复制过去再重启，基本都能解决。

我个人在实际操作中的体会是：Dify 安装最大的门槛不是命令本身，而是“容器编排”这套思维模式。一旦你理解了服务之间是靠编排文件组织起来的、数据是靠 volumes 持久化的、排查问题是要看日志的，那么不仅 Dify，以后部署任何 Docker 化应用都会顺手很多。最后再分享一个小技巧：把 docker compose ps 和 docker compose logs -f api 这两条命令记在备忘录里，部署和排障时你八成会反复用到它们。