Dify 自托管指南：Docker Compose 部署 AI Workflow、Agent 与 RAG

Dify 是用于构建大语言模型应用的平台，支持 Workflow、Agent 和知识库等能力。本文介绍以 Docker Compose 自托管的基本流程、模型 Provider 配置、应用验证，以及升级、备份和公网访问前需要考虑的事项。

资料核对日期：2026-10-22。 Dify 的版本、硬件建议和部署命令会变化；开始前请核对官方文档与 Releases，不要将示例版本号当作长期固定值。

部署前准备

截至资料核对日，官方快速开始列出的最低要求为 Linux 2 CPU / 4 GiB 内存；macOS 的 Docker 虚拟机建议至少 2 CPU / 8 GiB，并要求 Docker Compose v2.24.0 或更新版本。部署前请复核官方页面，因为版本要求可能变化；这些最低值也不代表所有模型、并发量和插件都能流畅运行。数据目录、数据库、向量存储和模型服务都需要规划持久化与备份。

先检查官方 Self-hosting Quick Start 和 Dify Releases，选择当前稳定版本；生产环境优先固定到明确的 release/tag，而不是未经评估地跟随开发分支。确保已安装 Docker Engine/Desktop 与 Compose 插件，并确认目标主机有足够磁盘空间。

Docker Compose 快速启动

先从官方 Releases 选择稳定 tag 并固定版本，再按 Quick Start 获取代码。将环境变量替换为已核实的 tag：

git clone https://github.com/langgenius/dify.git
cd dify
export DIFY_RELEASE_TAG="替换为已核实的 release tag"
git checkout "$DIFY_RELEASE_TAG"
cd docker
cp .env.example .env
docker compose up -d

首次启动会下载镜像并初始化多个服务。运行 docker compose ps 查看状态，必要时用 docker compose logs -f 排查。某些初始化服务会完成任务后退出，应结合官方说明、退出码和依赖服务健康状态判断，而不是要求所有容器一直处于 running。然后按 Quick Start 打开本地入口完成管理员初始化。

启动前阅读 .env，替换示例密钥，并按域名、邮件和存储需求检查生产配置。不要把 .env、数据库口令、SECRET_KEY 或 Provider API Key 提交到代码仓库。记录实际 release tag 和 Compose 版本，作为之后升级及排错的基线。

配置模型 Provider

管理员可在 Dify 设置中配置模型供应商，并按供应商说明填写凭证和可用模型。不同 Provider 的字段、计费、可用区域、速率限制和数据处理条款各不相同；只添加当前确实准备使用的模型，并在小规模请求中验证对话、嵌入或重排序等所需能力。

API Key 应只保存在受控的服务端配置中，设置最小权限并定期检查使用量。不要把真实密钥放进 Workflow 提示词、前端代码、教程截图或日志。模型调用会将相应输入发送给 Provider；涉及个人、客户或敏感数据时，先完成数据分类和供应商审查。

Workflow、Agent 与 RAG 入门

类型	主要用途	上线前重点
Workflow	将输入、模型和条件节点组织为可重复流程	检查节点映射、异常分支和输出约束
Agent	在设定范围内选择工具或执行步骤	最小化工具权限并测试边界输入
Knowledge / RAG	从导入资料检索相关片段供生成使用	检查授权、召回质量、引用与人工复核
API	由外部应用调用已发布应用	Key 仅保存在服务端并设置访问限制

Workflow：把输入、模型调用、条件分支和输出组织成可观测的步骤。先做窄范围流程，逐个检查输入输出与失败路径。
Agent：允许应用根据目标选择工具或采取步骤。明确工具权限、可访问的数据和调用限制；不要给 Agent 超出任务所需的写权限。
Knowledge / RAG：导入经过授权的数据，配置分段和索引，再用代表性问题检查召回与引用。索引结果并不保证事实正确，应设计人工核验流程。
API：发布应用后使用 Dify 提供的服务端 API。API 密钥不能交给浏览器端或公开代码；由自己的后端安全保存和调用。

上线前用错误输入、空数据、Provider 超时和权限边界做测试。记录模型版本、提示词变更和评估样例，避免只凭一两次演示判断效果。

验证一个 Workflow 与知识库

先从最小的输入—模型—输出 Workflow 开始：定义输入字段，确保模型节点收到预期变量，给输出节点设置稳定字段，再用无敏感信息的样例试运行。检查节点日志与异常分支，依次测试空输入、超长输入、Provider 超时和格式不符的回答。确认基本路径稳定后，再增加条件、工具调用和 Agent 行为，明确每个工具可以读写哪些资源。

Knowledge / RAG 流程应从获授权、经过脱敏的小批量资料开始。检查切分后的文本是否保留标题和上下文，再以代表性问题测试召回片段；记录哪些答案没有依据。检索到内容并不保证模型忠实引用，也不能代替专家审核。对高风险结论设置人工确认，且不要把生产敏感数据直接用于初期调试。

备份、升级与运维

Dify 自托管不仅是容器镜像，还包括 .env、数据库、上传文件、向量数据及其他持久化目录。备份范围取决于实际启用的组件和存储后端，至少盘点配置文件、数据库、上传对象、向量存储以及自定义插件或其他持久化卷；不要将此清单视为对所有部署都完整。按一致性要求安排备份窗口，并定期在隔离环境恢复演练。

升级前阅读对应 release notes 和官方升级指南，检查版本兼容性、迁移要求与已知问题，并以对应版本的官方升级文档为准；先备份，再在测试环境升级，验证应用、知识库和 API，最后安排生产变更窗口。不要在不清楚数据迁移与回滚边界时直接执行 docker compose pull && docker compose up -d。

上线前检查清单

将管理入口限定给需要的身份；公开 hostname 之前先验证 Access 或其他身份策略。
仅开放必需端口，检查反向代理、跨站点和外部 URL 设置。
为模型 Provider 配置独立凭证和必要额度；评估输入数据是否允许发送给该供应商。
识别当前 Compose 启用的数据库、向量存储、上传文件、插件和其他卷，形成可恢复备份并定期演练。
记录 Dify release、Compose 版本和变更；升级先在测试环境验证，再按官方指南执行迁移。

安全发布到公网

自托管面板和 API 不应因为“服务能访问”就直接公开。启用强管理员身份验证，妥善保管密钥，限制管理路径，配置 HTTPS、备份、更新和监控。若使用反向代理或 Cloudflare Tunnel，还要确认访问策略确实生效；Tunnel 本身不是登录系统。生产环境也应检查默认端口、跨站点设置、邮件和对象存储等环境变量是否符合部署要求。

常见问题

Docker Compose 启动后有容器退出，是部署失败吗？

不一定。有些初始化服务会完成任务后退出。对照官方容器说明、退出码以及主服务健康状态一起判断。

本机能运行 Dify，为什么换服务器后失败？

检查 Compose 版本、环境变量、持久化卷权限、端口占用、磁盘空间和容器间 DNS。模型 Provider 的凭证与网络访问也需要单独确认。

知识库检索能保证回答准确吗？

不能。RAG 会根据索引召回内容，但分段、召回和模型生成都可能产生遗漏或错误。用真实问题集评估，并让高风险场景保留人工复核。

官方资料

将本地安装视为平台运维工作：先固定可复现版本、保护密钥与持久化数据，再逐步配置模型和工作流。任何生产升级都应以备份和可验证的恢复方案为前提。