2. 为什么这么多人卡在部署环节Dify 这个开源 LLM 应用开发平台这两年热度一直很高。它把智能体Agent、知识库、工作流、RAG 流水线、模型接入这些能力全部集成在一个可视化的界面里开发者不用再去拼装 LangChain 和 FastAPI就能快速搭出一个带知识库的对话应用或者跑通一条完整的多步 Agent 工作流。我自己从 1.6 版本开始用到现在升到 1.17不得不说迭代速度非常快但部署这块的坑也多尤其是对刚接触 Docker 的新手来说光拉镜像就能劝退一半人。这篇博文不是官方文档翻译而是基于我多次部署和升级 Dify 1.17 的实际操作记录整理出来的精简教程。我会把部署流程中那些必须理解的概念拆开讲清楚把每一步涉及的命令和配置逐条解释到位最后再把我踩过的坑、排查过的报错整理成问题清单方便你照着排查。适合第一次部署 Dify 的用户也适合已经部署过旧版本想要平滑升级的开发者。3. Dify 1.17 版本概览与部署思路拆解3.1 Dify 1.17 这一版到底变了什么先说版本变化。Dify 1.17 这个版本和 1.10 之前的版本相比最大的变化在三点第一多租户能力增强。从 1.10 开始 Dify 社区版引入了多租户架构1.17 继续沿用了这套设计不同团队或者不同项目可以用同一个平台做隔离和权限管理。对个人开发者来说这个变化感知不明显但如果你打算把 Dify 部署成团队内部共用的 AI 应用平台这个能力就很关键了。第二工作流编排能力的升级。1.17 对工作流节点类型、变量传递、并行分支的执行效率都有优化尤其是调试运行时的体验改善了不少。之前跑一条包含多个 LLM 节点的工作流每次调试都要等很久1.17 在响应速度上提升比较明显。第三插件化架构持续推进。Dify 从 1.15 左右开始主推插件体系模型接入、工具扩展、Agent 策略都逐渐模块化。1.17 里插件 Daemon 已经是部署时不可忽略的一部分这也意味着部署结构比旧版本更复杂了一些——多了一个 plugin_daemon 容器配置上也要多留意。有一点需要提醒Dify 社区版的版本号和它的模型接入能力是强绑定的。1.17 里面已经内置了对不少新模型和工具提供方的支持但具体支持哪些还是要以官方 release notes 为准。通用的规律是越新的版本对模型调用的抽象越统一迁移成本越低。3.2 部署方案选型为什么推荐 Docker ComposeDify 官方提供了多种部署方式包括 Docker Compose、Kubernetes Helm、以及面向开发者的本地源码运行。对新手和大多数中小团队来说Docker Compose 是最省心的一条路。原因很直白Dify 的组件多。后端 API、Web 前端、Worker、PostgreSQL、Redis、Sandbox、SSRF Proxy、Plugin Daemon、向量数据库这些服务全部要在同一套环境下配合运行手动一个个去装几乎不可维护。Docker Compose 可以把所有组件的启动顺序、网络连接、环境变量、数据卷一次性定义清楚。一条命令拉起全部容器一条命令查看所有日志这对问题排查来说价值极大。Dify 官方的 docker-compose.yaml 文件已经写好了组件之间的依赖关系比如 API 服务会等到数据库就绪后再启动新手不需要自己去处理服务编排这些细节。我个人不太建议新手在一开始就直接上 Kubernetes。Dify 作为多组件应用部署到 K8s 需要额外处理持久化存储、Ingress、Secret 管理、镜像拉取策略等问题对没有 K8s 基础的人来说踩坑成本太高。等用 Docker Compose 把 Dify 跑熟、业务流程走通了再考虑上 K8s 也不迟。3.3 “精简部署”到底精简了什么所谓精简部署我的理解不是去掉功能而是做三件事砍掉不必要的适配层。Dify 默认的部署文件里同时带了 nginx 容器作为反向代理入口但如果你只想在局域网内快速体验完全可以直接用 web 容器的映射端口访问不启用 nginx。不过如果要做生产环境暴露nginx 还是建议留着。控制向量数据库的启动开销。Dify 支持多种向量数据库默认配置用的是 Weaviate。Weaviate 本身不算特别重但如果你明确用不到知识库功能可以在 docker-compose.yaml 中注释掉向量数据库相关的服务只跑核心链路。等到真正需要做 RAG 的时候再单独启动向量库并接进去。按需调整副本和服务。默认 compose 文件里 API 和 Worker 是分开的两个服务这两者都是基于相同的 API 代码镜像运行的只是启动命令不同。对并发要求不高的小团队可以把 MODE 环境变量改成 everything让 API 服务同时处理异步任务减少容器数量。不过这个改动只适合低负载场景正式环境我还是建议保持 API 和 Worker 分离。精简部署的本质是让系统在你当前的资源条件下能跑得动、跑得稳而不是追求组件越少越好。在资源充足的前提下我更推荐保留默认的完整部署结构这样后续升级和扩展都方便。4. 部署前的环境准备与核心概念理解4.1 硬件与软件要求先看硬件底线。Dify 本体对 CPU 和内存的要求不是特别高但考虑到底层要跑 Docker 引擎再加上模型推理如果有本地需求资源要求就完全不一样了。仅部署 Dify 平台本身不做本地模型推理推荐配置是 4 核 CPU、8GB 内存磁盘空间预留至少 20GB。注意这个 20GB 是保守值Dify 相关的几个核心镜像加起来超过 4GB再加上 PostgreSQL 数据、上传的文件、向量数据库的索引数据量增长很快。如果只用了 2GB 内存的机器跑完整版 Dify经常会出现容器被 OOM Killer 杀掉的情况表现为服务突然 502 或者容器重启。如果你打算在本地接 Ollama 这类推理服务跑模型内存要求就要按模型规模往上加。7B 量级的量化模型至少要 8GB 内存13B 以上的模型建议 32GB稳妥起见可以参考部署场景CPU内存磁盘仅 Dify 平台不跑本地模型2 核4G20GDify 7B 量化模型本地推理4 核16G40GDify 13B 量化模型本地推理8 核32G80G操作系统方面Ubuntu 20.04/22.04、Debian 11/12、CentOS 7 以上都可以Windows 上建议用 Docker DesktopmacOS 同理。需要注意的是Dify 官方提供的部署脚本和文档更多是基于 Linux 环境编写的你在 Windows 上操作时命令行的差异会在后面详细说明。软件层面必须提前装好两样东西Docker Engine 和 Docker Compose 插件。Dify 1.17 的部署文件用到了一些 Compose 新特性旧版 docker-compose 独立程序可能存在兼容性问题建议都升级到 Docker 24 以上版本并且确认docker compose version能正常输出信息。4.2 Dify 的组件架构都包括哪些容器花时间理解 Dify 的容器结构比盲目执行部署命令更有价值。Dify 1.17 完整部署会拉起以下这些容器apiDify 后端主力服务所有 HTTP 请求都经过它处理也是和数据库、Redis、向量库打交道的核心进程。workerCelery 异步任务工作者负责处理知识库索引构建、文档切分、工作流异步执行等耗时任务。如果 worker 挂了你会在界面里看到任务一直卡住但 API 本身并不会报错。web前端界面服务运行的是 Next.js 应用默认端口映射到宿主机的 3000 端口。dbPostgreSQL 数据库存储账号、应用配置、工作流定义、会话记录等结构化数据。redis缓存和消息代理一方面存放临时会话状态另一方面作为 Celery 的 broker。sandbox代码执行沙箱用于在应用里安全运行 Python 代码节点。它是独立受限的进程不要随意把它关闭。ssrf_proxySSRF 防护代理所有对外部 URL 的请求都会经过这个代理转发防止服务端请求伪造攻击。plugin_daemon插件守护进程负责管理插件安装和生命周期。这是新版 Dify 特有的组件。weaviate / qdrant向量数据库。默认用 Weaviate也可以在 .env 中切换成 Qdrant 或别的向量库。nginx反向代理把所有外部请求统一转发到 web 和 api 服务。这些容器默认处于同一个 docker 网络中容器之间通过服务名互相访问。比如 api 连接数据库时用的主机名是db而不是localhost。这个设计对新手来说需要适应一下你在排查问题时容器之间访问不通是很常见的原因。4.3 部署文件在哪里获取docker-compose.yaml 和 .env 是什么关系Dify 的部署文件在官方 GitHub 仓库中的docker目录下。获取方式很简单去 Dify 的 GitHub 仓库下载对应版本的源码包解压后进入docker目录或者用 git clone 拉取仓库代码后在docker目录下操作。在docker目录下你会看到配置文件示例。文件名一般是docker-compose.yaml或docker-compose-mid.yaml这类。前者对应核心功能后者会额外开启一些中间件和中间层能力。环境变量文件示例。这就是.env.example你需要把它复制一份并改名为.env然后按需修改内部的配置。扩展目录。比如volumes目录用于存放数据库、上传文件等数据确保容器重建后数据不丢。.env和docker-compose.yaml的关系是这样的compose 文件里会引用形如${VARIABLE}的变量占位符.env中的每一行KEYVALUE就在 startup 时填充这些占位符。换句话说.env是配置的源头compose 文件是配置的消费者。新手最常见的错误是只改了.env里的配置但忘了重启容器让它生效或者改了.env之后没有重新执行docker compose up -d。5. 新手精简部署实操一步步来5.1 第一步下载部署文件并进入 docker 目录部署第一步确定你要用的 Dify 版本。我建议直接到 GitHub 的 Dify 仓库 Releases 页面找到 v1.17.x 的 tag下载 Source code 压缩包。这样能保证你拿到的部署文件内容与版本完全对应。# 以 v1.17.1 为例下载并解压源码 wget https://github.com/langgenius/dify/archive/refs/tags/1.17.1.tar.gz tar -zxvf 1.17.1.tar.gz cd dify-1.17.1/docker如果你更习惯用 git 操作也可以整仓克隆然后 checkout 到对应 taggit clone https://github.com/langgenius/dify.git cd dify git checkout 1.17.1 cd docker进入docker目录后就能看到部署用的全部文件。这里要特别强调后续所有操作都要在这个目录下执行否则 compose 找不到对应的配置文件和卷定义。5.2 第二步复制 .env.example 并生成密钥在这个目录下找到.env.example文件复制一份为.env。Windows 用户在文件夹地址栏输入 cmd 打开命令行后可以直接执行copy .env.example .envLinux 或 macOS 用户执行cp .env.example .env复制完成后.env文件就是你整套部署的配置中心。接下来修改几个关键变量。最重要的一个变量是SECRET_KEY。它用于加密 Dify 内部的敏感数据比如 API 密钥、加密后的模型凭证。官方要求在部署前重新生成它不要沿用示例文件里的默认值。生成方式有几种Linux 下推荐用openssl rand -base64 42把输出的随机字符串填到.env文件的SECRET_KEY后面。我之前见过有人忘记改这一步结果部署完成后 API 请求一直返回 401 或 500 错误排查了很久才发现是 SECRET_KEY 的问题。接着修改 PostgreSQL 的密码也就是POSTGRES_PASSWORD。这一步建议直接从一开始就设一个强密码避免后续上线生产再改。另外POSTGRES_USER和POSTGRES_DB默认值是postgres如果没特殊要求可以保留。还需要确认一个很关键的变量EXPOSE_PLUGIN_DAEMON_PORT。1.17 默认会把插件守护进程的管理端口暴露到宿主机上如果这个端口被占用启动时可能会报错。可以在不冲突的前提下修改或者保持默认在首次启动前确认端口空闲。5.3 第三步明确向量数据库的选择Dify 1.17 默认的向量数据库配置是 Weaviate这也是 compose 文件里默认启动的向量库容器。如果你暂时用不到知识库功能可以先把VECTOR_STOREweaviate改成其他占位值或者保持不动反正对整体启动影响不大。如果你确定要用知识库就保持默认的 Weaviate 即可。Dify 对 Weaviate 的支持最成熟文档示例也最多新手尽量不要在这里折腾替代方案。等跑通了知识库全流程再考虑切 Qdrant 或者 pgvector。有一点值得注意Dify 的向量数据库配置是全局的一旦选定了类型并开始写入数据后期更换向量数据库等于要重建所有知识库索引代价很大。所以在部署初期就要想清楚。5.4 第四步启动容器并验证服务状态配置文件准备好之后执行启动命令docker compose up -d注意-d参数是后台运行。服务启动过程中Docker 会先拉取所有镜像这个过程比较漫长取决于网络状况。镜像全部拉取完成后各个容器会按照依赖关系依次启动。你可以用下面的命令查看当前容器状态docker compose ps这个命令会列出 compose 管理的所有容器以及它们各自的状态、端口映射和启动时间。正常状态应该显示Up并且没有类似Restarting或Exit的状态出现。再强调一次不要用docker ps来替代docker compose ps。docker ps能看到所有运行的容器但不会反映 compose 项目级别的健康状态尤其是容器反复重启的情况下docker compose ps能更直观地告诉你哪些服务没有起来。初次启动后观察 web 容器的日志docker compose logs -f web当日志中出现 Next.js 已经启动监听端口的信息时就可以在浏览器里访问了。如果 web 端口默认映射的是宿主机 3000 端口访问地址就是http://服务器IP:3000。首次访问会要求你设置管理员账号。这里的管理员账号对应 .env 中配置的数据库但它不是直接操作数据库的超级用户而是 Dify 平台内的管理员。设置完账号密码之后就能进入 Dify 的主界面了。5.5 第五步注册一个临时模型提供方并跑通对话进入 Dify 界面之后建议先别急着建应用。第一件事是去“设置”里接入一个模型提供方这里推荐先用 OpenAI 兼容的 API 或者临时用平台内置的托管模型把流程跑通。即使用 Ollama 这种本地推理服务配置方式也很简单在模型提供商页面选择 Ollama填入 Ollama 服务的地址和模型名即可。如果你用的是 Docker 方式部署的 Ollama那么 Ollama 服务地址不能填 localhost而要填宿主机在 Docker 网络中的可访问地址。举个具体例子假设你的 Dify 容器在宿主机 A 上Ollama 也跑在 A 上且是 Docker 容器部署那么 Dify 的 api 容器访问 Ollama 时应该使用host.docker.internal:11434或者宿主机在 Docker 网络中的 IP。这个细节不知道坑了多少人我在问题排查部分会继续展开。模型接入成功后新建一个“聊天助手”应用选好模型发送一条测试消息如果模型正常回复说明 Dify 的核心链路已经跑通了。到这一步部署就算完成了一半——平台已经能运行剩下的就是按业务需求配置知识库、工作流和插件。6. 我遇到过的部署问题与排查经验6.1 拉取镜像失败原因与解决方案Dify 部署失败最高发的问题就是镜像拉不下来。核心原因无非是网络问题Docker Hub 在国内访问不稳定或者是镜像较大导致拉取超时。解决方案也比较成熟首选方案是配置 Docker 镜像加速器。在/etc/docker/daemon.json中加入镜像加速源不同地区可用的加速源差异比较大建议以当前可用的公共源为准然后重启 Docker 服务sudo systemctl daemon-reload sudo systemctl restart docker配置好加速器之后如果拉取还是失败可以先手动执行docker pull把大镜像拉下来再执行docker compose up -d。这样能明确镜像拉取失败具体是哪个镜像也方便反复重试docker pull langgenius/dify-api:1.17.1 docker pull langgenius/dify-web:1.17.1还有一个常见情况是磁盘空间不足导致镜像层写入失败。用df -h检查磁盘如果根分区占用超过 85%建议先清理无用的镜像和容器docker system prune -a这条命令会清理掉所有未被使用的镜像和容器代价是下次启动时要重新拉取但能快速释放空间。谨慎使用避免误删有用的本地镜像。6.2 服务一直重启或容器退出如何快速定位如果docker compose ps显示某个容器一直在Restarting状态最有效的定位方式是查看这个容器的日志docker compose logs -f 服务名常见的退出原因大概有这么几类数据库相关服务未就绪。API 容器启动时会等 PostgreSQL但如果有健康检查配置不当或数据库容器异常连接会超时。检查db容器是否正常运行日志里是否有连接拒绝的报错。Redis 连接失败。Dify 运行强依赖 Redis容器启动时如果 Redis 没起来api 会报连接错误。同样先检查redis容器状态。端口被占用。web 容器的 3000 端口如果已经被本机其他进程占用容器会启动失败。用netstat -tlnp | grep 3000或lsof -i:3000排查。SECRET_KEY 长度或格式错误。有些版本的 Dify 对 SECRET_KEY 有长度要求建议用openssl rand -base64 42生成不要手动随意编造太短的字符串。还有一个坑值得单独提出来你改了.env之后如果只是执行docker compose restart容器里的环境变量并不会重新读取。需要先执行docker compose up -d让它重新创建容器才能生效。很多新手在这里反复折腾以为改了没反应是配置写得不对其实只是没有重建容器。6.3 从旧版本升级到 1.17 的注意事项如果你已经在跑旧版本的 Dify比如 1.6 或者 1.10升级到 1.17 不能简单粗暴地执行docker compose pull然后重启建议按下面的顺序来第一步备份数据。Dify 的数据主要存在 PostgreSQL 数据卷和上传文件的 volumes 目录里。最简单的备份方式是直接打包整个docker/volumes目录或者用 pg_dump 导出数据库。pg_dump -h localhost -U postgres -p 5432 dify dify_backup.sql第二步确认版本对应的部署文件变化。Dify 的每个版本都会在仓库里更新docker-compose.yaml和.env.example。别直接拿旧版本的.env套在新版本的 compose 上有些新的环境变量必须补上否则功能异常。建议对比新旧.env.example把新增的变量同步进你的.env。第三步执行更新docker compose down docker compose pull docker compose up -d务必先 down 再 up而不是直接 up -d。这样能确保旧容器被正确停止新容器按新配置启动。升级过程中如果遇到接口请求异常优先检查.env中的 SECRET_KEY 是否在之前被重置过这会影响所有加密数据的可读性。6.4 常见问题速查表问题现象可能原因排查方向web 页面打不开web 容器未启动、端口被占用执行 docker compose ps检查 web 状态netstat 查端口占用API 请求返回 401/403SECRET_KEY 设置有问题重新生成 SECRET_KEY重启容器知识库上传文档后一直处理中worker 容器异常查看 worker 日志确认 Redis 连接对话应用能发消息但不回复模型提供方连不上或 Key 无效在模型提供商页面测试连接确认网络与 API Key使用 Ollama 本地模型时连接失败Dify 容器无法访问宿主机 Ollama 地址将 Ollama 地址改为 host.docker.internal:11434上传文件大小受限nginx 配置或 backend 配置限制查看文档调整上传大小限制参数容器反复重启资源不足或健康检查失败查看容器日志检查内存占用插件无法安装plugin_daemon 端口问题或网络问题检查插件守护进程容器日志这里面每个问题我都实际踩过尤其是 Ollama 地址问题。当时我在 Docker 里同时部署了 Dify 和 OllamaDify 的 api 容器里填 localhost:11434 一直连不上查了半天才发现 Docker 容器的 localhost 指的是容器自身不是宿主机。改成 host.docker.internal 之后问题立刻消失了。这个经验单独拿出来分享就是希望看到这篇文章的人不用再走一遍弯路。7. 部署完成后建议做的几件事部署只是一个起点我把 Dify 跑起来之后做的第一件事是先把它配置成“团队可用”的状态。几个步骤供你参考第一配置 HTTPS 和域名。如果 Dify 要暴露到公网一定要加上 HTTPS 证书否则模型 API Key 的传输过程会被拦截存在泄露风险。通常的做法是在 nginx 容器前面再加一层宿主机的 Nginx 或者 Caddy 做反向代理用 Let’s Encrypt 申请证书。第二备份策略。Dify 的数据包括 PostgreSQL 中的结构化数据、向量数据库中的索引、以及 volumes 目录下的上传文件。不要只备份数据库向量库索引和文件也都要覆盖。你可以写一个定时任务定期打包整个docker/volumes目录到远程存储。第三关闭默认的管理员账户风险。首次创建管理员之后建议在账号设置里开启二步验证并且不要用默认邮箱作为登录名。第四保持模型提供方密钥的安全。团队的模型 API Key 统一放在 Dify 的模型提供商配置里不要在应用代码里硬编码。Dify 在存储密钥时会加密但这个加密依赖 SECRET_KEY所以 SECRET_KEY 的保管一定要严格。我个人在实际操作中的体会是Dify 的部署本身并不复杂难的是理解它是一套多组件的系统而不是单个应用。只要把组件之间如何协作、日志怎么看、配置怎么改这三点想清楚了后面所有问题排查都有章可循。本文中提到的方案和命令我都按实际部署经验验证过直接照做基本可以跑通。最后再分享一个小技巧每次修改 .env 之后记得用docker compose config先检查一下配置是否正确这条命令会把 compose 文件解析后的完整配置打印出来比直接启动排错快得多。
Dify 1.17 Docker Compose 部署实战：从零到跑通全流程指南
2. 为什么这么多人卡在部署环节Dify 这个开源 LLM 应用开发平台这两年热度一直很高。它把智能体Agent、知识库、工作流、RAG 流水线、模型接入这些能力全部集成在一个可视化的界面里开发者不用再去拼装 LangChain 和 FastAPI就能快速搭出一个带知识库的对话应用或者跑通一条完整的多步 Agent 工作流。我自己从 1.6 版本开始用到现在升到 1.17不得不说迭代速度非常快但部署这块的坑也多尤其是对刚接触 Docker 的新手来说光拉镜像就能劝退一半人。这篇博文不是官方文档翻译而是基于我多次部署和升级 Dify 1.17 的实际操作记录整理出来的精简教程。我会把部署流程中那些必须理解的概念拆开讲清楚把每一步涉及的命令和配置逐条解释到位最后再把我踩过的坑、排查过的报错整理成问题清单方便你照着排查。适合第一次部署 Dify 的用户也适合已经部署过旧版本想要平滑升级的开发者。3. Dify 1.17 版本概览与部署思路拆解3.1 Dify 1.17 这一版到底变了什么先说版本变化。Dify 1.17 这个版本和 1.10 之前的版本相比最大的变化在三点第一多租户能力增强。从 1.10 开始 Dify 社区版引入了多租户架构1.17 继续沿用了这套设计不同团队或者不同项目可以用同一个平台做隔离和权限管理。对个人开发者来说这个变化感知不明显但如果你打算把 Dify 部署成团队内部共用的 AI 应用平台这个能力就很关键了。第二工作流编排能力的升级。1.17 对工作流节点类型、变量传递、并行分支的执行效率都有优化尤其是调试运行时的体验改善了不少。之前跑一条包含多个 LLM 节点的工作流每次调试都要等很久1.17 在响应速度上提升比较明显。第三插件化架构持续推进。Dify 从 1.15 左右开始主推插件体系模型接入、工具扩展、Agent 策略都逐渐模块化。1.17 里插件 Daemon 已经是部署时不可忽略的一部分这也意味着部署结构比旧版本更复杂了一些——多了一个 plugin_daemon 容器配置上也要多留意。有一点需要提醒Dify 社区版的版本号和它的模型接入能力是强绑定的。1.17 里面已经内置了对不少新模型和工具提供方的支持但具体支持哪些还是要以官方 release notes 为准。通用的规律是越新的版本对模型调用的抽象越统一迁移成本越低。3.2 部署方案选型为什么推荐 Docker ComposeDify 官方提供了多种部署方式包括 Docker Compose、Kubernetes Helm、以及面向开发者的本地源码运行。对新手和大多数中小团队来说Docker Compose 是最省心的一条路。原因很直白Dify 的组件多。后端 API、Web 前端、Worker、PostgreSQL、Redis、Sandbox、SSRF Proxy、Plugin Daemon、向量数据库这些服务全部要在同一套环境下配合运行手动一个个去装几乎不可维护。Docker Compose 可以把所有组件的启动顺序、网络连接、环境变量、数据卷一次性定义清楚。一条命令拉起全部容器一条命令查看所有日志这对问题排查来说价值极大。Dify 官方的 docker-compose.yaml 文件已经写好了组件之间的依赖关系比如 API 服务会等到数据库就绪后再启动新手不需要自己去处理服务编排这些细节。我个人不太建议新手在一开始就直接上 Kubernetes。Dify 作为多组件应用部署到 K8s 需要额外处理持久化存储、Ingress、Secret 管理、镜像拉取策略等问题对没有 K8s 基础的人来说踩坑成本太高。等用 Docker Compose 把 Dify 跑熟、业务流程走通了再考虑上 K8s 也不迟。3.3 “精简部署”到底精简了什么所谓精简部署我的理解不是去掉功能而是做三件事砍掉不必要的适配层。Dify 默认的部署文件里同时带了 nginx 容器作为反向代理入口但如果你只想在局域网内快速体验完全可以直接用 web 容器的映射端口访问不启用 nginx。不过如果要做生产环境暴露nginx 还是建议留着。控制向量数据库的启动开销。Dify 支持多种向量数据库默认配置用的是 Weaviate。Weaviate 本身不算特别重但如果你明确用不到知识库功能可以在 docker-compose.yaml 中注释掉向量数据库相关的服务只跑核心链路。等到真正需要做 RAG 的时候再单独启动向量库并接进去。按需调整副本和服务。默认 compose 文件里 API 和 Worker 是分开的两个服务这两者都是基于相同的 API 代码镜像运行的只是启动命令不同。对并发要求不高的小团队可以把 MODE 环境变量改成 everything让 API 服务同时处理异步任务减少容器数量。不过这个改动只适合低负载场景正式环境我还是建议保持 API 和 Worker 分离。精简部署的本质是让系统在你当前的资源条件下能跑得动、跑得稳而不是追求组件越少越好。在资源充足的前提下我更推荐保留默认的完整部署结构这样后续升级和扩展都方便。4. 部署前的环境准备与核心概念理解4.1 硬件与软件要求先看硬件底线。Dify 本体对 CPU 和内存的要求不是特别高但考虑到底层要跑 Docker 引擎再加上模型推理如果有本地需求资源要求就完全不一样了。仅部署 Dify 平台本身不做本地模型推理推荐配置是 4 核 CPU、8GB 内存磁盘空间预留至少 20GB。注意这个 20GB 是保守值Dify 相关的几个核心镜像加起来超过 4GB再加上 PostgreSQL 数据、上传的文件、向量数据库的索引数据量增长很快。如果只用了 2GB 内存的机器跑完整版 Dify经常会出现容器被 OOM Killer 杀掉的情况表现为服务突然 502 或者容器重启。如果你打算在本地接 Ollama 这类推理服务跑模型内存要求就要按模型规模往上加。7B 量级的量化模型至少要 8GB 内存13B 以上的模型建议 32GB稳妥起见可以参考部署场景CPU内存磁盘仅 Dify 平台不跑本地模型2 核4G20GDify 7B 量化模型本地推理4 核16G40GDify 13B 量化模型本地推理8 核32G80G操作系统方面Ubuntu 20.04/22.04、Debian 11/12、CentOS 7 以上都可以Windows 上建议用 Docker DesktopmacOS 同理。需要注意的是Dify 官方提供的部署脚本和文档更多是基于 Linux 环境编写的你在 Windows 上操作时命令行的差异会在后面详细说明。软件层面必须提前装好两样东西Docker Engine 和 Docker Compose 插件。Dify 1.17 的部署文件用到了一些 Compose 新特性旧版 docker-compose 独立程序可能存在兼容性问题建议都升级到 Docker 24 以上版本并且确认docker compose version能正常输出信息。4.2 Dify 的组件架构都包括哪些容器花时间理解 Dify 的容器结构比盲目执行部署命令更有价值。Dify 1.17 完整部署会拉起以下这些容器apiDify 后端主力服务所有 HTTP 请求都经过它处理也是和数据库、Redis、向量库打交道的核心进程。workerCelery 异步任务工作者负责处理知识库索引构建、文档切分、工作流异步执行等耗时任务。如果 worker 挂了你会在界面里看到任务一直卡住但 API 本身并不会报错。web前端界面服务运行的是 Next.js 应用默认端口映射到宿主机的 3000 端口。dbPostgreSQL 数据库存储账号、应用配置、工作流定义、会话记录等结构化数据。redis缓存和消息代理一方面存放临时会话状态另一方面作为 Celery 的 broker。sandbox代码执行沙箱用于在应用里安全运行 Python 代码节点。它是独立受限的进程不要随意把它关闭。ssrf_proxySSRF 防护代理所有对外部 URL 的请求都会经过这个代理转发防止服务端请求伪造攻击。plugin_daemon插件守护进程负责管理插件安装和生命周期。这是新版 Dify 特有的组件。weaviate / qdrant向量数据库。默认用 Weaviate也可以在 .env 中切换成 Qdrant 或别的向量库。nginx反向代理把所有外部请求统一转发到 web 和 api 服务。这些容器默认处于同一个 docker 网络中容器之间通过服务名互相访问。比如 api 连接数据库时用的主机名是db而不是localhost。这个设计对新手来说需要适应一下你在排查问题时容器之间访问不通是很常见的原因。4.3 部署文件在哪里获取docker-compose.yaml 和 .env 是什么关系Dify 的部署文件在官方 GitHub 仓库中的docker目录下。获取方式很简单去 Dify 的 GitHub 仓库下载对应版本的源码包解压后进入docker目录或者用 git clone 拉取仓库代码后在docker目录下操作。在docker目录下你会看到配置文件示例。文件名一般是docker-compose.yaml或docker-compose-mid.yaml这类。前者对应核心功能后者会额外开启一些中间件和中间层能力。环境变量文件示例。这就是.env.example你需要把它复制一份并改名为.env然后按需修改内部的配置。扩展目录。比如volumes目录用于存放数据库、上传文件等数据确保容器重建后数据不丢。.env和docker-compose.yaml的关系是这样的compose 文件里会引用形如${VARIABLE}的变量占位符.env中的每一行KEYVALUE就在 startup 时填充这些占位符。换句话说.env是配置的源头compose 文件是配置的消费者。新手最常见的错误是只改了.env里的配置但忘了重启容器让它生效或者改了.env之后没有重新执行docker compose up -d。5. 新手精简部署实操一步步来5.1 第一步下载部署文件并进入 docker 目录部署第一步确定你要用的 Dify 版本。我建议直接到 GitHub 的 Dify 仓库 Releases 页面找到 v1.17.x 的 tag下载 Source code 压缩包。这样能保证你拿到的部署文件内容与版本完全对应。# 以 v1.17.1 为例下载并解压源码 wget https://github.com/langgenius/dify/archive/refs/tags/1.17.1.tar.gz tar -zxvf 1.17.1.tar.gz cd dify-1.17.1/docker如果你更习惯用 git 操作也可以整仓克隆然后 checkout 到对应 taggit clone https://github.com/langgenius/dify.git cd dify git checkout 1.17.1 cd docker进入docker目录后就能看到部署用的全部文件。这里要特别强调后续所有操作都要在这个目录下执行否则 compose 找不到对应的配置文件和卷定义。5.2 第二步复制 .env.example 并生成密钥在这个目录下找到.env.example文件复制一份为.env。Windows 用户在文件夹地址栏输入 cmd 打开命令行后可以直接执行copy .env.example .envLinux 或 macOS 用户执行cp .env.example .env复制完成后.env文件就是你整套部署的配置中心。接下来修改几个关键变量。最重要的一个变量是SECRET_KEY。它用于加密 Dify 内部的敏感数据比如 API 密钥、加密后的模型凭证。官方要求在部署前重新生成它不要沿用示例文件里的默认值。生成方式有几种Linux 下推荐用openssl rand -base64 42把输出的随机字符串填到.env文件的SECRET_KEY后面。我之前见过有人忘记改这一步结果部署完成后 API 请求一直返回 401 或 500 错误排查了很久才发现是 SECRET_KEY 的问题。接着修改 PostgreSQL 的密码也就是POSTGRES_PASSWORD。这一步建议直接从一开始就设一个强密码避免后续上线生产再改。另外POSTGRES_USER和POSTGRES_DB默认值是postgres如果没特殊要求可以保留。还需要确认一个很关键的变量EXPOSE_PLUGIN_DAEMON_PORT。1.17 默认会把插件守护进程的管理端口暴露到宿主机上如果这个端口被占用启动时可能会报错。可以在不冲突的前提下修改或者保持默认在首次启动前确认端口空闲。5.3 第三步明确向量数据库的选择Dify 1.17 默认的向量数据库配置是 Weaviate这也是 compose 文件里默认启动的向量库容器。如果你暂时用不到知识库功能可以先把VECTOR_STOREweaviate改成其他占位值或者保持不动反正对整体启动影响不大。如果你确定要用知识库就保持默认的 Weaviate 即可。Dify 对 Weaviate 的支持最成熟文档示例也最多新手尽量不要在这里折腾替代方案。等跑通了知识库全流程再考虑切 Qdrant 或者 pgvector。有一点值得注意Dify 的向量数据库配置是全局的一旦选定了类型并开始写入数据后期更换向量数据库等于要重建所有知识库索引代价很大。所以在部署初期就要想清楚。5.4 第四步启动容器并验证服务状态配置文件准备好之后执行启动命令docker compose up -d注意-d参数是后台运行。服务启动过程中Docker 会先拉取所有镜像这个过程比较漫长取决于网络状况。镜像全部拉取完成后各个容器会按照依赖关系依次启动。你可以用下面的命令查看当前容器状态docker compose ps这个命令会列出 compose 管理的所有容器以及它们各自的状态、端口映射和启动时间。正常状态应该显示Up并且没有类似Restarting或Exit的状态出现。再强调一次不要用docker ps来替代docker compose ps。docker ps能看到所有运行的容器但不会反映 compose 项目级别的健康状态尤其是容器反复重启的情况下docker compose ps能更直观地告诉你哪些服务没有起来。初次启动后观察 web 容器的日志docker compose logs -f web当日志中出现 Next.js 已经启动监听端口的信息时就可以在浏览器里访问了。如果 web 端口默认映射的是宿主机 3000 端口访问地址就是http://服务器IP:3000。首次访问会要求你设置管理员账号。这里的管理员账号对应 .env 中配置的数据库但它不是直接操作数据库的超级用户而是 Dify 平台内的管理员。设置完账号密码之后就能进入 Dify 的主界面了。5.5 第五步注册一个临时模型提供方并跑通对话进入 Dify 界面之后建议先别急着建应用。第一件事是去“设置”里接入一个模型提供方这里推荐先用 OpenAI 兼容的 API 或者临时用平台内置的托管模型把流程跑通。即使用 Ollama 这种本地推理服务配置方式也很简单在模型提供商页面选择 Ollama填入 Ollama 服务的地址和模型名即可。如果你用的是 Docker 方式部署的 Ollama那么 Ollama 服务地址不能填 localhost而要填宿主机在 Docker 网络中的可访问地址。举个具体例子假设你的 Dify 容器在宿主机 A 上Ollama 也跑在 A 上且是 Docker 容器部署那么 Dify 的 api 容器访问 Ollama 时应该使用host.docker.internal:11434或者宿主机在 Docker 网络中的 IP。这个细节不知道坑了多少人我在问题排查部分会继续展开。模型接入成功后新建一个“聊天助手”应用选好模型发送一条测试消息如果模型正常回复说明 Dify 的核心链路已经跑通了。到这一步部署就算完成了一半——平台已经能运行剩下的就是按业务需求配置知识库、工作流和插件。6. 我遇到过的部署问题与排查经验6.1 拉取镜像失败原因与解决方案Dify 部署失败最高发的问题就是镜像拉不下来。核心原因无非是网络问题Docker Hub 在国内访问不稳定或者是镜像较大导致拉取超时。解决方案也比较成熟首选方案是配置 Docker 镜像加速器。在/etc/docker/daemon.json中加入镜像加速源不同地区可用的加速源差异比较大建议以当前可用的公共源为准然后重启 Docker 服务sudo systemctl daemon-reload sudo systemctl restart docker配置好加速器之后如果拉取还是失败可以先手动执行docker pull把大镜像拉下来再执行docker compose up -d。这样能明确镜像拉取失败具体是哪个镜像也方便反复重试docker pull langgenius/dify-api:1.17.1 docker pull langgenius/dify-web:1.17.1还有一个常见情况是磁盘空间不足导致镜像层写入失败。用df -h检查磁盘如果根分区占用超过 85%建议先清理无用的镜像和容器docker system prune -a这条命令会清理掉所有未被使用的镜像和容器代价是下次启动时要重新拉取但能快速释放空间。谨慎使用避免误删有用的本地镜像。6.2 服务一直重启或容器退出如何快速定位如果docker compose ps显示某个容器一直在Restarting状态最有效的定位方式是查看这个容器的日志docker compose logs -f 服务名常见的退出原因大概有这么几类数据库相关服务未就绪。API 容器启动时会等 PostgreSQL但如果有健康检查配置不当或数据库容器异常连接会超时。检查db容器是否正常运行日志里是否有连接拒绝的报错。Redis 连接失败。Dify 运行强依赖 Redis容器启动时如果 Redis 没起来api 会报连接错误。同样先检查redis容器状态。端口被占用。web 容器的 3000 端口如果已经被本机其他进程占用容器会启动失败。用netstat -tlnp | grep 3000或lsof -i:3000排查。SECRET_KEY 长度或格式错误。有些版本的 Dify 对 SECRET_KEY 有长度要求建议用openssl rand -base64 42生成不要手动随意编造太短的字符串。还有一个坑值得单独提出来你改了.env之后如果只是执行docker compose restart容器里的环境变量并不会重新读取。需要先执行docker compose up -d让它重新创建容器才能生效。很多新手在这里反复折腾以为改了没反应是配置写得不对其实只是没有重建容器。6.3 从旧版本升级到 1.17 的注意事项如果你已经在跑旧版本的 Dify比如 1.6 或者 1.10升级到 1.17 不能简单粗暴地执行docker compose pull然后重启建议按下面的顺序来第一步备份数据。Dify 的数据主要存在 PostgreSQL 数据卷和上传文件的 volumes 目录里。最简单的备份方式是直接打包整个docker/volumes目录或者用 pg_dump 导出数据库。pg_dump -h localhost -U postgres -p 5432 dify dify_backup.sql第二步确认版本对应的部署文件变化。Dify 的每个版本都会在仓库里更新docker-compose.yaml和.env.example。别直接拿旧版本的.env套在新版本的 compose 上有些新的环境变量必须补上否则功能异常。建议对比新旧.env.example把新增的变量同步进你的.env。第三步执行更新docker compose down docker compose pull docker compose up -d务必先 down 再 up而不是直接 up -d。这样能确保旧容器被正确停止新容器按新配置启动。升级过程中如果遇到接口请求异常优先检查.env中的 SECRET_KEY 是否在之前被重置过这会影响所有加密数据的可读性。6.4 常见问题速查表问题现象可能原因排查方向web 页面打不开web 容器未启动、端口被占用执行 docker compose ps检查 web 状态netstat 查端口占用API 请求返回 401/403SECRET_KEY 设置有问题重新生成 SECRET_KEY重启容器知识库上传文档后一直处理中worker 容器异常查看 worker 日志确认 Redis 连接对话应用能发消息但不回复模型提供方连不上或 Key 无效在模型提供商页面测试连接确认网络与 API Key使用 Ollama 本地模型时连接失败Dify 容器无法访问宿主机 Ollama 地址将 Ollama 地址改为 host.docker.internal:11434上传文件大小受限nginx 配置或 backend 配置限制查看文档调整上传大小限制参数容器反复重启资源不足或健康检查失败查看容器日志检查内存占用插件无法安装plugin_daemon 端口问题或网络问题检查插件守护进程容器日志这里面每个问题我都实际踩过尤其是 Ollama 地址问题。当时我在 Docker 里同时部署了 Dify 和 OllamaDify 的 api 容器里填 localhost:11434 一直连不上查了半天才发现 Docker 容器的 localhost 指的是容器自身不是宿主机。改成 host.docker.internal 之后问题立刻消失了。这个经验单独拿出来分享就是希望看到这篇文章的人不用再走一遍弯路。7. 部署完成后建议做的几件事部署只是一个起点我把 Dify 跑起来之后做的第一件事是先把它配置成“团队可用”的状态。几个步骤供你参考第一配置 HTTPS 和域名。如果 Dify 要暴露到公网一定要加上 HTTPS 证书否则模型 API Key 的传输过程会被拦截存在泄露风险。通常的做法是在 nginx 容器前面再加一层宿主机的 Nginx 或者 Caddy 做反向代理用 Let’s Encrypt 申请证书。第二备份策略。Dify 的数据包括 PostgreSQL 中的结构化数据、向量数据库中的索引、以及 volumes 目录下的上传文件。不要只备份数据库向量库索引和文件也都要覆盖。你可以写一个定时任务定期打包整个docker/volumes目录到远程存储。第三关闭默认的管理员账户风险。首次创建管理员之后建议在账号设置里开启二步验证并且不要用默认邮箱作为登录名。第四保持模型提供方密钥的安全。团队的模型 API Key 统一放在 Dify 的模型提供商配置里不要在应用代码里硬编码。Dify 在存储密钥时会加密但这个加密依赖 SECRET_KEY所以 SECRET_KEY 的保管一定要严格。我个人在实际操作中的体会是Dify 的部署本身并不复杂难的是理解它是一套多组件的系统而不是单个应用。只要把组件之间如何协作、日志怎么看、配置怎么改这三点想清楚了后面所有问题排查都有章可循。本文中提到的方案和命令我都按实际部署经验验证过直接照做基本可以跑通。最后再分享一个小技巧每次修改 .env 之后记得用docker compose config先检查一下配置是否正确这条命令会把 compose 文件解析后的完整配置打印出来比直接启动排错快得多。