如果你已经准备自己装一套 Dify 社区版大概率会经历这样一个过程先被功能很强大打动然后被部署细节折磨。我上个月刚帮一位朋友从 1.10 升到 1.17.1中间遇到镜像拉不下来、容器启动顺序混乱、登录后白屏等一系列问题。趁着记忆还热乎把整套精简部署流程和排查思路整理出来尤其是 1.17 这个版本的新手友好度相比早期版本已经好了很多只要按规矩来基本能一次跑通。这篇文章不打算讲太深层的源码逻辑主要面向第一次接触 Dify 的人覆盖版本选择、前置准备、部署操作、常见报错处理、以及后续跑通一个应用所需的模型接入和知识库配置。我尽量按实际会踩到的顺序来写而不是按官方文档的目录结构来写因为后者对新手来说太抽象了。1. 部署前就得看清的三件事版本选择、硬件底线和镜像来源1.1 为什么新手上路直接选 1.17而不是守着旧版本Dify 社区版从 1.x 开始迭代速度非常快几乎每隔几周就有一个小版本。很多人有个习惯觉得老版本稳定新版可能有坑但在 Dify 这里我的建议恰恰相反新手直接上 1.17.1不要从 1.10 或 1.12 开始。原因有两个。第一Dify 的数据库结构和插件机制在这几个版本之间变过不少次你如果先用旧版本把数据建起来后面升级基本都要做迁移迁移过程中最容易出现的字段不存在外键冲突对新手来说非常劝退。第二1.17 在部署层面做了明显的工程化改进最直观的感受是 api、worker、plugin_daemon 这几个服务之间的启动依赖关系比旧版本合理很多。旧版本经常出现 web 容器已经 started 但 api 还没就绪导致页面一直 50x1.17 里加了更严格的健康检查容器之间会互相等待整体起来的成功率要高得多。另外一个容易被忽略的点是镜像 tag 的对应关系。docker-compose.yaml 里的镜像版本必须和源码版本一致。你如果 clone 了最新 main 分支源码却因为网络原因手动拉了一个旧的 dify-api 镜像启动时大概率会报字段不匹配或者接口 404。所以最稳妥的方式用 git tag 固定到一个版本比如 1.17.1然后源码、镜像、compose 文件全部以这个 tag 为准。1.2 硬件配置官方文档的最低配置对新手并不够用官方写的硬件要求是 2 核 4G 内存可以跑这句话在纯空载状态下成立但一旦你开始上传知识库、跑工作流、接本地模型4G 内存会让整台机器处于崩溃边缘。我自己实际测试过几个配置档位给你一个参考配置档位CPU内存磁盘适合场景体验档2 核4 GB40 GB简单对话不挂知识库不跑本地模型入门档4 核8 GB100 GB SSD日常开发知识库 工作流建议档8 核16 GB200 GB SSD团队协作在线服务重度向量检索新手最容易低估的是内存。Dify 全家桶一次性会拉起十几个容器包括 api、worker、web、nginx、postgres、redis、weaviate、sandbox、ssrf_proxy、plugin_daemon。光这些容器常驻内存加起来在空载状态也要占用 2.5G 到 3G 左右。如果你的机器只有 4G 内存再叠加系统本身占用docker stats 里就会看到内存几乎跑满紧接着出现 OOM症状就是某个容器突然退出页面报服务异常。磁盘同样别按最低要求来。Dify 自己的业务数据不算大但 Weaviate 作为向量数据库存储量会随着你上传到知识库的文档数线性增长。假设你往知识库里塞了几百个 PDF每个文件分段后生成向量数据几十 G 磁盘很快就会被吃掉。所以无论如何给 Docker 的数据目录预留 100G 以上磁盘满了以后 postgres 和 weaviate 都会出各种奇怪问题。1.3 镜像拉取失败先配置加速器再考虑离线导入镜像拉取失败几乎是每个新手的第一个坎。Dify 部署一次要拉十几个镜像总量大概 3 到 5 个 G中间任何一层镜像下载失败docker compose 都会停在那里不报错也不继续。常见的失败形式有几种拉取时报dial tcp i/o timeout进度条走到一半就不动了提示某个 tag 不存在docker compose 启动时直接说 image not found前两种在特定网络环境下非常常见处理思路按优先级排序第一步给 Docker 配置镜像加速器。Linux 下编辑/etc/docker/daemon.json加入 registry-mirrors 配置然后重启 Docker 服务。Windows 的 Docker Desktop 用户直接在设置里的 Docker Engine 选项卡中编辑同一个 JSON 即可。示例配置{ registry-mirrors: [ https://docker.m.daocloud.io ] }改完以后重启 Docker再单独拉一个核心镜像测试docker pull langgenius/dify-api:1.17.1能正常拉下来说明加速器生效再执行完整的 docker compose up。第二步如果加速器在你的网络环境下还是不稳定可以换一台网络环境好一些的机器先执行 docker pull 把镜像拉下来然后用 save 和 load 的方式打包传输到目标机器docker save langgenius/dify-api:1.17.1 -o dify-api.tar scp dify-api.tar user目标机器IP:/tmp/ ssh user目标机器IP docker load -i /tmp/dify-api.tar把所有需要的镜像都传过去之后再执行 docker compose up -d这样能绕开大部分镜像源不稳定的问题代价是需要手动操作一遍。至于第三种tag 不存在基本是你手动指定了不存在的镜像版本或者源码和镜像版本没对齐。回到代码目录确认 taggit tag -l然后根据实际 release 版本去拉对应镜像。提示如果你手动 pull 过镜像注意 compose 文件里 image 字段与你本地镜像的版本必须完全一致。不要随手改 tag除非你明确知道 compose 里引用的是哪一个名称。2. 精简部署操作流从拿到源码到浏览器看到登录页2.1 源码获取与目录选择Dify 的部署入口在源码根目录下的 docker 文件夹里。你可以用 git 从 GitHub 克隆也可以从官方 release 下载源码 zip 包。克隆方式git clone https://github.com/langgenius/dify.git cd dify git checkout 1.17.1 cd docker这里有一个新手常犯的错只从 release 页面下载 docker 文件夹觉得 compose 文件都在里面就够了。实际上不是的Dify 的 compose 配置里引用了 .env.example 和一些相对路径完整的部署最好基于整个源码包。下载完源码解压后Windows 上会看到 dify-main 这样的目录你需要进入dify-main/docker目录。在资源管理器地址栏输入 cmd 回车就能直接在当前路径打开命令提示符。接下来复制环境变量文件Linux 和 mac 用cp .env.example .envWindows cmd 里不太认 cp用 copy 或者直接在 PowerShell 里用 Copy-ItemCopy-Item .env.example .env在正式执行 docker compose 之前先确认本机 Docker 环境是完好的。检查命令docker --version docker compose version有些 Linux 发行版用了 docker-ce 但不带 compose 插件会提示找不到 docker compose。Ubuntu 下可以用sudo apt-get update sudo apt-get install docker-compose-plugin检查完 Docker 环境再往后走避免后面报的错到底是 Docker 没装好还是 Dify 配置问题混在一起难排查。2.2 .env 文件里需要改和不需要改的项.env 是 Dify 部署的配置中心。默认值对于纯体验来说基本够用但有几个关键项值得你留意SECRET_KEYDify 用它做会话加密和敏感数据签名。.env.example 里的默认值虽然能跑但部署到公网环境或者多人协作时建议生成一个自己的随机串。生成命令openssl rand -base64 42然后把输出替换到 .env 的SECRET_KEY后面。EXPOSE_NGINX_PORT默认值是 80。如果服务器 80 端口已经被其他 Web 服务占用改成 8080 或者你喜欢的其他端口。改完后访问地址变为http://服务器IP:8080。这是新手部署出现端口被占用时最直接的解决办法。POSTGRES_PASSWORD、REDIS_PASSWORD本地体验不修改问题不大生产环境必须改。这两个密码一旦启动过 postgres 容器再改会比较麻烦因为数据库数据已经以旧密码初始化了。所以想改的话要在第一次启动前改好。外部模型 API 的 key 不用提前在这里配部署完成后在 Dify 页面后台里添加反而更直观也方便管理多个供应商。2.3 docker compose up 启动与首次初始化等待一切准备就绪在 docker 目录下执行docker compose up -d第一次执行会拉取全部镜像时间取决于网络和机器性能。完成后再执行docker compose ps看到所有服务状态为 running 或 healthy 就成功了。其中 db、redis、api、worker、nginx、web 这几个核心服务必须健康。如果某些服务显示 unhealthy不用太着急因为 api 和 worker 第一次启动时要做数据库初始化期间健康检查会短暂失败等一两分钟再观察。首次启动成功后浏览器打开http://localhost假设端口没改看到初始化管理员的页面就说明部署成功了。第一次进入需要设置管理员邮箱和密码这个账号就是超级管理员后面可以建团队、开工作空间。整个等待过程建议你不要频繁刷新页面给容器一点时间把事情干完反而更快。3. 启动失败的排查链路以日志为准不靠瞎猜3.1 第一步永远都是 docker compose ps 和 logs页面提示服务异常时新手的本能反应是不停刷新但 Dify 这类多容器应用的正确姿势是先看容器状态。执行docker compose ps观察每个容器的状态列这里有几类典型异常状态含义优先排查对象Exited (code)容器已退出code 是退出码查看对应容器日志Restarting容器反复重启多半是资源不足或依赖未就绪unhealthy健康检查失败确认依赖服务是否正常running 但页面 502服务在跑但依赖挂了nginx 的上游服务确定可疑容器后查看具体日志docker compose logs api加--tail参数能只看最近的行数比如docker compose logs api --tail 200日志是排查的第一手资料containers 的错误基本都会写在这里。比如 api 容器反复出现Connection refused那基本可以确定是数据库或 Redis 连不上接下来就去查对应容器状态。3.2 端口占用与 nginx 起不来Dify 默认用 nginx 容器对外提供 80 端口。如果宿主机已经有别的 Web 服务占用 80你会看到 nginx 容器反复退出日志里出现bind 0.0.0.0:80 failed: port is already allocated解决方案有两个修改 .env 里的EXPOSE_NGINX_PORT8080然后重新执行docker compose up -d。停掉占用 80 端口的旧服务。检查端口占用的命令sudo netstat -tlnp | grep :80拿到占用进程的 PID 之后再看是什么服务占用谨慎决定要不要停。3.3 api 连不上数据库和 Redis容器内视角与宿主机视角api 容器如果反复重启日志里有password authentication failed那大概率是 postgres 的密码不匹配。有两种可能一是 .env 里改了 POSTGRES_PASSWORD但数据库卷是之前用旧密码初始化的二是 compose 文件里环境变量覆盖了 .env 值导致 api 连库密码不一致。先查 db 容器状态docker compose logs db --tail 50如果 db 能起来只是认证失败再确认 api 容器里的实际环境变量docker compose exec api env | grep DB把这个输出和 .env 里的值比对就知道是不是配置被覆盖了。还有一种更隐蔽的问题postgres 数据目录权限不对。在某些 Linux 环境下容器内的 postgres 用户和宿主机挂载目录的属主不一致导致初始化数据库时报Permission denied。处理方式是调整卷目录属主sudo chown -R 999:999 ./volumes/db/data这里 999 是官方 postgres 容器内 postgres 用户的 uid。改完把容器删掉重新创建docker compose up -d --force-recreate db3.4 内存不足导致容器被 Kill容器退出码如果是 137 或 139别去查配置了大概率是内存溢出。137 对应 SIGKILL通常是系统 OOM Killer 干的。确认方式dmesg | grep -i kill看到 oom-kill 相关日志说明物理内存不够了。解决方式两条路加内存或者砍掉非必要服务。在 docker-compose.yaml 里暂时注释掉 sandbox、ssrf_proxy、weaviate 等容器只保留核心服务可以降低内存占用但代价是工作流里的部分能力会受影响。如果你后面的确要用工作流和工具还是老老实实加内存。以我实际经验4G 内存的机器跑 Dify 全家桶是极限想在旁边再跑一个 Ollama 服务做本地模型基本必 OOM。本地模型方案建议 8G 起步16G 比较舒服。3.5 页面白屏、登录异常但容器都健康容器状态全 healthy页面却白屏或者一直转圈这种情况在升级场景里比较多见全新部署偶尔也会遇到。首先排除浏览器缓存。Dify 的前端是打包的静态资源升级前后资源哈希会变旧缓存容易导致白屏。开一个无痕窗口试一次如果无痕模式正常清理浏览器缓存即可。无痕也不行的继续查 nginx 日志docker compose logs nginx --tail 100关注有没有upstream timed out或者connection refused之类的关键词。nginx 正常的话再看 web 容器日志。web 容器是纯前端静态服务一般不会有问题除非你自己动过 compose 文件里的端口映射或者环境变量。默认情况下 web 监听 3000nginx 反代配置写死在里面没有十足把握不要在 compose 文件里乱改这些值。4. 部署完成后先把模型接进来再谈知识库和工作流4.1 用云端 API 还是本地模型就差一个 URL 的事容器都正常运行了接下来要做的是把大模型接进 Dify。没有模型后面的对话、知识库、工作流全都跑不起来。入口在页面右上角头像 → 设置 → 模型供应商。如果你是云端模型比如 DeepSeek、OpenAI、通义千问配置很简单API Key 填进去模型名称填对测试通过即可用。以 DeepSeek 为例模型名填deepseek-chatKey 填你在平台申请到的 sk- 开头字符串。如果你用 Ollama 跑本地模型配置里面有一个特别容易踩的坑。Dify 的容器和你宿主机上的 Ollama 不在同一个网络命名空间容器内部的localhost:11434指的是容器自己不是宿主机。所以 Ollama 的 Base URL 不能填 localhost要填宿主机 IP。如果 Dify 容器用的是默认 bridge 网络宿主机在容器内部的地址通常是172.17.0.1。更稳妥的方式是直接填宿主机局域网 IP。http://172.17.0.1:11434填完后点测试能连通就说明模型配置成功。4.2 知识库流水线的三个关键配置分段、索引、召回模型接进来后大部分人第二件事是上传文档建知识库。创建知识库的时候有三处配置直接决定效果新手往往没太在意到后面发现问题再回头改成本就高了。第一是分段设置。文档上传后会被切成文本块再向量化。这个切块动作很关键分太短单块文本缺乏上下文检索出来可能答非所问分太长噪声太多检索精度下降。官方默认的分段方式在多数场景下表现中庸新手可以先默认跑通流程后续觉得效果不好再改成按标题分或者自定义分隔符。第二是索引方式。高质量模式会走向量化索引语义检索效果好但每次处理文档要消耗模型 token。经济模式是关键词索引不消耗模型 token但检索效果上限低。想体验完整能力就用高质量模式想省钱测试就先小范围试。第三是召回设置。在应用里关联知识库之后召回策略可以选择向量检索、全文检索、混合检索。混合检索在大多数业务场景下效果明显好于单一模式代价是多了一点点检索耗时。如果你当前用的向量化模型不太行混合检索能兜底。4.3 用官方模板工作流验证全链路部署完、模型接上、知识库建好最后一步是完整跑通一个应用否则你无法确认整个部署链路真的没问题。在工作室里点击创建空白应用或者从模板市场导入一个模板工作流。导入了模板之后做的第一件事是把工作流里的模型节点切换到你自己配置好的模型。很多测试失败都是因为模板里写了某个模型名称在你的环境里并不存在。测试过程中如果节点报错不用慌。Dify 的工作流节点支持查看每一步的输入输出双击节点或点击节点详情能看到实际传入的数据和返回的结果。跟着日志里的错误信息走绝大多数问题就三类模型未配置、prompt 里变量名拼错、知识库没有正确关联到节点。跑通一个模板工作流说明从 Docker 容器到模型调用、到知识库检索的整条链路都是通的到此才算真正完成了部署。5. 长期维护与版本升级的实战经验5.1 备份永远比升级更优先数据安全这块要放在最前面。Dify 的业务数据主要存在 postgres 里向量数据在 weaviate 里缓存和会话在 redis 里。备份时不需要把整个容器打包备份 volumes 目录即可。官方 compose 默认把数据放在当前目录的 volumes 下最简单的方式是直接备份这个目录。想对 postgres 单独做逻辑备份也可以这样docker compose exec db pg_dump -U postgres dify dify_backup.sql恢复docker compose exec -T db psql -U postgres -d dify dify_backup.sql备份前最好先停掉业务容器避免数据写入不一致。我习惯的操作顺序是docker compose stop api worker web nginx docker compose exec db pg_dump -U postgres dify dify_$(date %Y%m%d).sql docker compose start5.2 从旧版本升级到 1.17.1保留 .env、替换代码、观察迁移升级的核心是保留 .env 配置和 volumes 数据替换代码和镜像。cd dify git pull git checkout 1.17.1 cd docker docker compose down如果你的部署是从 release zip 来的没有 git 仓库下载新版本的 zip 解压后把旧版本的 .env 和 volumes 目录拷贝到新版对应位置。官方每次发布都会在 .env.example 里增加新配置项。升级时不要直接cp .env.example .env覆盖那样会丢掉 SECRET_KEY 和数据库密码导致老数据连不上。正确做法是把 .env.example 里的新增项合并进旧 .env旧 .env 里已有的配置一项都不要动。Linux 下可以用 diff 命令对比两个文件手动确认新增内容。合并完配置后docker compose pull docker compose up -d升级后 api 容器会自动执行数据库迁移。这一步要看日志确认有没有成功docker compose logs api --tail 200迁移过程中页面可能暂时无法正常访问这是正常的。等日志里不再出现 migration 相关的输出再刷新页面测试主流程。我升级过程中遇到过迁移后 redis 里缓存了旧数据导致页面异常的情况清理一下 redis 缓存就好了docker compose exec redis redis-cli FLUSHALL这个命令会把所有会话踢下线执行前和团队同步好时间点。5.3 容器日志无限增长和资源占用失控Dify 跑一段时间后最容易被忽略的问题是容器日志无限增长。默认情况下 docker 的 json-file 驱动不会自动轮转日志遇到某个服务频繁打印错误几天就能吃掉几个 G 磁盘。在 docker-compose.yaml 里给服务加上日志限制是很好的习惯logging: driver: json-file options: max-size: 50m max-file: 5这样单个服务日志最多保留 250M 左右磁盘不会被日志打满。quiet 期间你可能不会注意到日志直到磁盘满了 postgres 突然写不进去数据那时候才是真麻烦。再看资源占用。运行时间长了如果发现 Dify 响应变慢先跑一下docker stats --no-stream观察哪个容器在长时间吃 CPU 或内存。我遇到比较多的是 weaviate在知识库大量写入的时候内存会持续攀升。如果长时间不释放可以给它设置资源上限services: weaviate: mem_limit: 2g同理 redis 和 postgres 也建议加上资源限制避免单个服务吃掉宿主机所有资源。要注意修改 docker-compose.yaml 后执行docker compose up -d重新创建容器才能生效只 restart 是没用的。我在几次部署和升级中的经验是Dify 这类多容器应用部署过程本身并不难难的是出了问题以后还在靠页面刷新和猜来排查。先看容器状态再看日志最后才动配置这套顺序适用于绝大多数问题。真心希望这篇精简部署和排查指南能让你少走几个弯路一次把 Dify 跑起来。
