Dify私有化部署全攻略：Docker Compose组件拆解与Ollama本地模型接入

1. 部署前先弄清楚的事：Dify跑起来到底需要哪些组件

很多人在第一次接触 Dify 时，都被它那句“开箱即用的 LLM 应用开发平台”给带偏了，以为部署就是一个容器的事。实际用下来你才会发现，Dify 不是一个单进程应用，而是一整套服务的编排组合。它解决的核心问题，是让开发者不用从零去写 Prompt 管理、上下文拼接、知识库检索、工作流编排、Agent 调度这些重复轮子，直接把精力放在业务逻辑上。社区版免费、开源、可私有化部署，适合个人学习、企业内部工具、AI 应用原型的快速验证，以及一切对数据隐私有要求的场景。

如果你只是想在本地电脑上跑个 Demo，或者在一台云服务器上给团队搭一个 AI 应用平台，这篇部署记录能帮你少踩不少坑。我会把从环境准备、Compose 启动、配置项调整，到本地模型接入、升级报错排查的完整过程都过一遍，包括大量我在实际操作中才意识到的问题——这些在官方文档里往往只是一句带过，但恰恰是决定部署成败的细节。

1.1 拆解 Docker Compose 里的组件清单

先看一眼 dify/docker 目录下的 docker-compose.yaml，你会发现服务列表比想象中长：nginx 负责反向代理和静态资源，web 是前端页面，api 是后端逻辑，worker 是异步任务消费队列，db 是 PostgreSQL，redis 承担缓存和队列中间件，weaviate 或 qdrant 负责向量检索，还有 ssrf_proxy 用于代理外部 HTTP 请求、sandbox 用于隔离代码执行、plugin_daemon 是较新版本里的插件守护进程。不同版本的服务列表会有差异，以你下载的 docker-compose.yaml 实际内容为准。

这一整套组件各司其职：你上传一份文档，api 会把文档交给 worker 去切分，切分后用 embedding 模型生成向量，写入向量库；有人提问时，api 先从向量库召回相关片段，再把片段拼进 Prompt，最后调用大模型生成回答。任何一个环节出问题，表现出来就是“知识库报错”或“对话异常”。所以部署 Dify 之前，心里要有这张组件拓扑图，排查问题时才知道该去看哪个容器的日志。

1.2 硬件与操作系统的底线

Dify 官方推荐 2C4G 起步，但我的实测体会是：2C4G 能跑，启动过程明显偏慢，知识库文档一多，worker 的处理速度会让人等到怀疑人生。个人学习可以接受，生产或团队使用建议至少 4C8G，磁盘预留 20GB 以上（镜像加数据很容易超过 10GB），因为模型调用和向量数据会持续增长。

操作系统方面，Debian 11/12、Ubuntu 22.04/24.04 最省心，CentOS 7 因为 Docker 版本太老，装新版 Docker 会比较折腾。Windows 用户建议用 Docker Desktop，并且让 WSL2 作为后端，同时把部署目录放在 WSL2 的文件系统内而不是 /mnt/c 下，否则文件读写性能和路径映射会带来非常诡异的权限问题。macOS 上用 Docker Desktop 基本没什么坑，唯一要注意的是 Apple Silicon 机器上某些镜像如果没有 arm64 版本，Docker 会走模拟层，性能打折扣。

2. Docker 环境准备与 Compose 目录初始化

很多部署失败其实不是 Dify 的问题，而是 Docker 环境本身就处于“看似能用、实际残缺”的状态。我在帮同事排查时发现，最常见的两种情况：一是 docker 命令存在，但 docker compose（注意，是带空格的插件，不是老式的 docker-compose）没装；二是 Docker 服务没有设置开机自启，服务器重启后所有容器全部停摆。

2.1 先用这两条命令确认底座

不管你是哪种系统，先执行下面两条命令，确定 Docker 和 Compose 插件都可用：

bash复制docker --version
docker compose version

如果你的 Linux 服务器还没有 Docker，可以按官方源安装：

bash复制sudo apt update
sudo apt install -y docker.io docker-compose-v2
sudo systemctl enable --now docker

这里我踩过一个坑：某些云主机预装的 Docker 版本很老，不支持 Compose v2 语法，直接跑 docker compose 会提示找不到命令。解决办法就是把 Docker 升级到较新版本，别在旧版上浪费时间。

2.2 Clone 源码并锁定版本号

Dify 的部署目录不在根目录，而是在仓库里的 docker/ 子目录，这一点很关键。操作流程：

bash复制git clone https://github.com/langgenius/dify.git
cd dify/docker
cp .env.example .env

这里强烈建议不要直接用 main 分支。main 分支是开发分支，镜像标签和配置项随时可能变化，今天能启动，明天 pull 一个新镜像可能就起不来了。正确做法是先用 git tag 看看最新的稳定版本号，然后 checkout 到具体版本：

bash复制git fetch --tags
git tag -l | s