Dify 这个项目我从 0.6 版就开始折腾一直跟到现在的 1.17中间踩过的坑够写一本书。1.17 给我的整体感觉是功能上已经把 Agent、工作流、知识库、插件这些核心能力整合得比较成熟但安装部署这条线对新手依然不算友好。网上教程一大把但很多都是抄官方文档真正把“为什么会这样”“卡住怎么办”讲清楚的没几个。这篇东西不打算做成面面俱到的官方手册就按我自己实际部署的经验来目标很明确让你用最精简的步骤把 Dify 1.17 跑起来再带你把高频故障现场挨个过一遍。适合什么人看第一次接触 Dify、没怎么玩过 Docker、想在自己机器上搭一套智能体平台来试用或者做小项目的人。老手可以直接跳到第 4 节问题排查。1. 部署前先搞懂几件事Dify 到底要装什么1.1 这套系统由哪些部分组成很多人第一次看到 Dify 的 docker-compose.yml 会懵因为服务列表长一串api、worker、web、db、redis、sandbox、ssrf_proxy、weaviate、plugin_daemon还有 nginx看起来像部署了一整个机房。其实拆开看没那么复杂。Dify 本身是一个典型的前后端分离应用。web 是前端控制台负责你看到的操作界面api 是后端服务负责处理接口请求、调用大模型、执行业务逻辑worker 是异步任务队列专门跑那些不能同步返回的任务比如文档解析、索引创建、批量生成之类的。db 用的是 PostgreSQL存业务数据redis 做缓存和消息队列weaviate 是向量数据库知识库的向量检索就靠它。sandbox 是代码执行沙箱工作流里如果需要跑 Python 代码就放到这个隔离环境里执行。plugin_daemon 是 1.x 版本之后加入的插件管理进程专门负责模型插件和工具插件的生命周期。这套组件是官方设计好的“全家桶”你不需要自己去装 PostgreSQL 和 Redis因为容器内部都封装好了。想精简也可以但不建议新手动官方默认这套组合是经过大规模测试验证的贸然砍组件反而容易把系统搞挂。我的建议是第一次部署老老实实用全家桶等服务跑顺了再琢磨优化。1.2 机器配置怎么选普通人够用就行关于硬件要求官方文档写的是 2 核 4G 内存起步但根据我实际测试这个配置非常勉强。api 和 worker 两个 Java不对Dify 后端是基于 Python 的内存占用没有 Java 那么吓人但服务数量摆在那里4G 内存光是把全家桶拉起来可用内存就剩不到 1G 了一旦折腾知识库或者跑工作流立刻卡到怀疑人生。我给个实在的建议如果你只是测试和学习8G 内存是舒适线16G 则可以跑得很宽松。CPU 方面 2 核以上就行磁盘建议至少预留 20G因为镜像加数据很容易就吃掉十几个 G。你要是还用 Ollama 在本地跑大模型那内存需求另算一个 7B 的量化模型起步就是 8G 内存这个钱省不得。操作系统方面Linux 服务器是首选Ubuntu 20.04 和 22.04 我都测试过非常稳。Windows 用户也没问题装 Docker Desktop把引擎切到 Linux 容器一样能跑。macOS 同样支持M 系列芯片的机器跑起来反而很流畅。唯一的区别就是文件路径和命令行的使用习惯后面讲到具体步骤时我会额外标注。1.3 Docker 和 Docker Compose 的安装与校验Dify 的部署完全依赖 Docker所以这一步是地基。安装 Docker 本身不复杂Linux 上直接走官方脚本Windows 和 macOS 就下载 Docker Desktop 安装包。但我发现一个新手特别容易踩的坑装完 Docker 忘了装 Docker Compose。Docker Compose 是管理多个容器的工具新版 Docker Desktop 自带这个插件Linux 上用命令行安装 Docker 时如果没特意装 docker-compose-plugin那docker compose命令就会提示找不到。我建议装好后先跑两条命令验证docker --version docker compose version两条都能正常输出版本号说明环境没问题。如果第二条报错就是 Compose 插件没装好。Ubuntu 上可以用sudo apt install docker-compose-plugin补齐或者在安装 Docker 时把 docker-compose-plugin 这个包一起装上。还有一点需要注意Docker 服务必须处于运行状态。Linux 上可以执行systemctl status docker查看没起来就sudo systemctl start docker然后设置开机自启sudo systemctl enable docker。我见过不少用户卡在后续步骤最后发现是 Docker 服务根本没起来白白折腾半小时。2. 精简部署实操从下载源码到跑起来2.1 下载 Dify 1.17 源码并解压Dify 的部署方式有点特殊它不提供独立的安装包而是要求你把整个源码仓库下载下来因为 docker-compose.yml 和配置模板都放在源码里。官方推荐的做法是直接用 git clone我建议拉取指定的版本 tag避免总是跟着主分支走防止版本漂移导致配置对不上。git clone -b 1.17.0 https://github.com/langgenius/dify.git如果 GitHub 下载慢你也可以直接访问仓库主页在 Tags 页面找到 1.17 对应的 tag下载 zip 压缩包再解压。Windows 上如果免安装 Git下载 zip 反而是个更直观的方案。执行完你会得到一个 dify 目录真正的部署核心在dify/docker这个子目录里面。这里顺便回答一个网上问得特别多的问题解压后打开 dify-main 文件夹下一步去哪就是进入 docker 文件夹后面所有操作都在这个目录下进行。Windows 用户在资源管理器里进到这个目录可以按住 Shift 键右键选择“在此处打开 PowerShell 窗口”也可以直接打开 CMD 后用 cd 命令切换。2.2 配置 .env 文件这一步别有歧义进入 docker 目录你会看到一个.env.example文件这是官方提供的环境变量模板。部署前要把它复制一份文件名改成.env系统启动时 Docker Compose 会自动读取.env文件里的配置。Linux 和 macOS 上命令是cd dify/docker cp .env.example .envWindows 在 PowerShell 里同样支持 cp 命令因为它是 Copy-Item 的别名但如果用的是 CMD官方文档里那句cp .env.example .env是跑不通的CMD 里要用copy .env.example .env。真是很多人在 Windows 部署 Dify 时卡壳的第一个地方。复制完之后用文本编辑器打开.env文件你会看到密密麻麻的环境变量。新手不需要全部看懂但有一个必须检查SECRET_KEY。这个字段是用来加密会话和数据的关键密钥如果留空或者使用默认值会有安全隐患。建议生成一个足够随机的值填进去Linux 上可以执行openssl rand -base64 42把输出结果填到SECRET_KEY后面。另外一个常见的坑是有些教程让你改EXPOSE_NGINX_PORT和EXPOSE_NGINX_SSL_PORT这两个变量控制对外访问的端口映射默认是 80 和 443。如果你的服务器 80 端口已被 Nginx 或其他程序占用可以改成别的端口比如 8080。改完之后访问地址就是http://服务器IP:8080别到时候打不开页面又说部署失败了。2.3 容器镜像拉取与加速配置好.env之后下一步是拉取镜像并启动服务命令就一条docker compose up -d-d参数表示后台运行这样终端不会一直被日志刷屏。执行这条命令时Docker 会根据 docker-compose.yml 的定义到 Docker Hub 拉取对应的镜像文件。这一步是整个部署过程中新手最容易崩溃的环节我后面第 4 节会专门讲。这里先给一个应急方案如果拉取镜像的时候长时间卡住不动或者报timeout错误多半是网络问题。常见解决办法是给 Docker 配置镜像加速器国内云厂商基本都提供了容器镜像加速服务。配置方法是编辑/etc/docker/daemon.json文件加上 registry-mirrors 配置然后重启 Docker。{ registry-mirrors: [https://你的加速器地址] }配置完重启 Docker 后再重新执行docker compose up -d镜像拉取速度通常会有明显改善。这个加速器地址去阿里云、腾讯云的容器镜像服务控制台都能找到填自己的专属地址就行。2.4 启动容器并首次验证镜像拉取完毕容器会自动创建并启动。第一次启动时 api 容器会执行数据库迁移和初始化所以需要给它一点时间我建议等 30 到 60 秒再开始验证。验证第一步看容器状态docker compose ps正常情况下列表里的服务状态应该是 Up注意 nginx 和 db 这些必须显示 healthy 或者至少是 Uphealthy如果显示 Restarting 或者 Exited说明某个环节出了问题跳到第 4 节排查。验证第二步访问前端页面。默认配置下浏览器访问http://localhost或者http://服务器IP看到的应该是 Dify 的初始化页面让你设置管理员账号。这里我多说一句Dify 没有所谓默认账号密码第一打开页面就注册你创建的第一个用户就是系统管理员刚才建的账号密码一定要记住别信网上那些“默认 admin/admin123”的鬼话。走到这一步恭喜Dify 1.17 已经跑起来了。先别急着导入模型建议用管理员账号登录进去逛一圈界面然后把用户指南里的快速上手流程走一遍。3. 启动之后先摸清家底核心容器、端口与资源占用3.1 默认容器都有谁各管什么服务跑起来之后执行docker compose ps会看到一长串容器名。我把每个容器的职责整理了一下方便你以后排查问题时知道应该看哪个日志。容器名职责常见日志位置docker-web-1Nginx 统一入口反向代理到前端和后端docker compose logs webdocker-api-1后端 API 服务处理业务逻辑docker compose logs apidocker-worker-1异步任务队列跑文档解析、索引生成docker compose logs workerdocker-db-1PostgreSQL存业务数据docker compose logs dbdocker-redis-1缓存与消息队列docker compose logs redisdocker-weaviate-1向量数据库知识库检索docker compose logs weaviatedocker-sandbox-1代码执行沙箱跑内置代码节点docker compose logs sandboxdocker-plugin_daemon-1插件管理进程docker compose logs plugin_daemondocker-ssrf_proxy-1请求代理防止服务端请求伪造一般不用细看理清这个对应关系很重要。比如你上传文档后一直不进入索引状态优先看 worker 日志页面能打开但登录报错重点看 api 日志知识库检索结果是空的就要看 weaviate 是否正常。3.2 端口访问与外部链路整个系统只有一个对外入口就是 nginx 容器默认占用宿主机 80 端口。如果你把EXPOSE_NGINX_PORT改成了 8080那入口就是 8080。nginx 内部负责把请求转发给 web 容器和 api 容器对外你不需要也不应该直接访问 3000、5001 这些旧教程里提到的端口。这里有个历史遗留问题网上很多早期教程会说 Dify 的 web 在 3000 端口、API 在 5001 端口这是 Dify 早期版本或者源码跑法的情况。1.17 的官方 docker-compose 已经把外层封装好了你只需要记住一个入口端口就行。如果看了旧教程去访问 3000 打不开不是装错是教程过时了。安全检查方面如果你的机器有公网 IP我强烈建议在防火墙层面把 80 端口的访问控制好只允许你自己的 IP 或者内网网段访问不要裸奔到公网。Dify 默认没有复杂的安全认证体系管理员账号一旦被爆破整个系统就暴露了。本地测试无所谓线上使用一定要重视。3.3 性能和容量参考我用一台 4 核 8G 的云服务器做过测试全家桶启动后 idle 状态下内存占用大概在 3 到 4G 左右其中 weaviate 和 postgresql 是吃内存大户各占五六百兆api 和 worker 加起来也有 1G 多剩下的都被 redis、sandbox、plugin_daemon 这些瓜分。磁盘方面镜像本身大约占用 6 到 8G运行一段时间后日志、数据库、上传文件都会增长知识库索引尤其吃磁盘。我给客户的建议是至少保留 30G 磁盘空间否则别拎着扫雷的配置就上生产。如果你发现系统很卡第一步先看内存是不是被打满了执行free -h。内存不够的常规操作是给机器加内存而不是盲目去调 JVM 参数因为 Dify 的 Python 进程内存调优空间有限。3.4 数据备份别等到丢数据再学部署成功之后很多人高高兴兴玩两天突然某天 docker compose down 再 up发现知识库没了、应用配置丢了才想起来备份。我给你列两个最核心的备份点。第一步备份数据库。Dify 的业务数据都在 PostgreSQL 里用 pg_dump 导出docker compose exec db pg_dump -U postgres -d dify dify_backup_$(date %F).sql第二步备份持久化文件。Dify 的上传文件、知识库原始文档、索引数据都存在dify/docker/volumes目录里直接用 tar 打包tar -czf volumes_backup_$(date %F).tar.gz volumes恢复的时候反过来操作先恢复 SQL 文件再把 volumes 目录解压回去最后重启容器。这个流程我建议你部署完就演练一遍真到灾难现场再查命令心态会崩的。4. 问题排查实录按经验排优先级4.1 镜像拉取失败是最常见的第一道坎部署 Dify 最容易翻车的地方就是执行docker compose up -d时镜像拉不下来。我见过的报错五花八门但本质都是同一个问题Docker 拉镜像的网络链路不稳定镜像层文件下载到一半就断了。典型报错症状卡在某个镜像的Pulling状态半小时没动静最后报timeout或者connect: connection refused报manifest unknown但其实是你写错了镜像标签镜像层下载到某个百分比一直不动最后超时排查思路按这个顺序来。第一个确认网络本身是通的试试直接拉一个最基础的镜像docker pull hello-world如果这个也拉不动那基本确认是 Docker Hub 访问问题。第二个检查 Docker 配置看/etc/docker/daemon.json里有没有配置镜像加速器没配置就按第 2.3 节的方法加上。第三个配置好加速器后重启 Docker再重新执行docker compose pull先手动拉一遍镜像确认全部拉完再执行启动命令。这里特别提醒一点不要反复执行docker compose up -d每次都因为镜像拉取失败而中断容易产生一堆悬空镜像浪费磁盘。正确的姿势是先在 docker 目录下执行docker compose pull这一步只负责把镜像全部拉下来把所有镜像拉成功后再执行docker compose up -d。如果你的网络环境实在拉不动也可以换个思路找一台网络状况较好的机器把镜像 pull 下来后 export 成 tar 文件再拷到目标机器上 load。这个操作有点绕但确实是应急方案。4.2 服务起不来先看 docker compose ps 和日志镜像拉完了容器也创建了但没跑起来或者跑起来又自动重启这是第二个高频故障点。遇到这种情况不要慌更不要直接删了容器重新建。第一步看状态docker compose ps状态列显示Exited说明容器退出显示Restarting说明陷入重启循环。第二步看日志docker compose logs api查看日志是定位问题的核心手段。我把几种常见日志问题对上了号api 容器日志报Psych::BadAlias或者Redis connection error多半是 Redis 还没就绪就启动了等一会再看或者重启 api 容器日志报database dify does not exist说明数据库初始化没完成可能是因为存储卷权限问题检查 volumes 目录的所有者日志报Listen on 0.0.0.0:5001 failed大概率是端口被宿主机上其他进程占了端口冲突这个问题值得展开说一下。Dify 全家桶内部端口很多比如 api 用 5001、web 用 3000但如果这些端口没有映射到宿主机一般不会冲突。真正容易冲突的是 nginx 映射的 80 端口。如果你的服务器本来跑了 NginxDify 的 nginx 容器就起不来。解决办法有两个要么改 Dify 的EXPOSE_NGINX_PORT为 8080要么停掉宿主机上的 Nginx二选一看你需求。另一个隐藏很深的问题Docker 容器时间和宿主机时间不一致可能导致某些认证或者证书校验失败。可以对比一下date和docker compose exec api date的输出如果差太多建议给容器挂载宿主机的/etc/localtime或者在 Compose 文件里设置TZAsia/Shanghai环境变量。4.3 页面能开但模型连不上页面正常打开管理员账号也注册好了但在“设置-模型供应商”里选好模型添加供应商时却报各种连接错误。这是 Dify 部署完成后最打击热情的问题而且类型非常多样每个供应商的报错都长得不一样。先说外置 API 类型的供应商比如用 DeepSeek 的官方 API 或者 OpenAI 的 API。这种一般在设置-模型供应商里填两个关键信息即可API Key 和 Base URL。很多人在 Base URL 上犯错误提供了一个完整到/v1结尾的 URL然后又习惯性加上/v1导致最终的请求地址变成/v1/v1/chat/completions。填的时候仔细看页面上有没有 URL 后缀说明Dify 1.17 已经对这种重复做了容错但有些供应商插件还是会踩坑。再说调试方法。页面报错只会提示抽象的“BadRequestError”之类真正有用的信息要看 api 日志docker compose logs api | grep -i error日志里会记录模型请求的完整路径和响应信息。如果看到401或者403基本是 API Key 填错或者没有对应模型的权限看到404多半是 Base URL 的路径不对看到timeout或者max retries exceeded就是 api 容器访问外网不通或者供应商接口确实慢。还有一个冷门但真实存在的坑如果你是通过 nginx 反向代理来访问 Dify 的而且 Dify 部署在内网外网 API 需要直连那就要确认容器能不能正常出网。执行下面命令测试docker compose exec api curl -I https://api.deepseek.com要是这个请求超时模型永远连不上问题不在 Dify而在网络出口层。4.4 本地模型 Ollama 接入的几个“隐藏坑”热词里频频出现 Ollama 本地部署我多说几句。用 Ollama 在本地跑模型再接 Dify属于纯内网方案数据不出本机测试环境用起来很舒服。先说部署姿势。Ollama 可以装在宿主机上Dify 跑在 Docker 里两者是独立的进程。Dify 这边的模型供应商设置里选择 OpenAI-API-compatible把 Base URL 填成http://host.docker.internal:11434/v1host.docker.internal是 Docker Desktop 提供的特殊域名Windows 和 macOS 上可以直接用让你在容器里访问宿主机。但如果你用的是 Linux 服务器这个域名默认不通你要么用宿主机的局域网 IP要么在 compose 文件里给容器加extra_hostsextra_hosts: - host.docker.internal:host-gateway加了这条Linux 下就能正常访问宿主机上的 Ollama 了。Ollama 这边也要做配置。默认情况下 Ollama 只监听 127.0.0.1也就是只允许本机访问Docker 容器访问的时候会被拒绝。需要设置环境变量让 Ollama 监听所有网卡OLLAMA_HOST0.0.0.0:11434 ollama serve这里我额外叮嘱一句如果服务器有公网 IP而你又把 Ollama 暴露成了 0.0.0.0就相当于把模型服务裸奔在公网上建议改回只监听内网 IP比如OLLAMA_HOST192.168.1.10:11434。最后还有一个新手容易忽略的点Dify 接入 Ollama 之后要确认你想要的模型已经在本地拉取完毕。比如要用 llama3 或者 qwen 系列先直接在宿主机上执行ollama pull llama3 ollama listDify 那边填模型名的时候要跟 Ollama 里 pull 下来的名字完全一致比如llama3:latest不要凭感觉写一个没拉过的模型名否则会报model not found。4.5 升级到 1.17 的注意点如果你是从老版本升级到 1.17而不是全新部署那有几个地方需要特别小心。第一升级前先备份先照第 3.4 节的方式备份数据库和 volumes 目录这是老生常谈但总有人偷懒。第二升级前对比一下新旧.env.example文件Dify 每次大版本都会新增环境变量直接拿旧.env硬跑有时候会出兼容性问题。我的升级建议流程是cd dify git pull cd docker docker compose down docker compose pull docker compose up -d这里docker compose down不会删除 volumes 数据只停止并移除容器所以你的数据还在。升级完成后第一次启动 api 容器会自动执行数据库迁移迁移期间服务可能表现为“正在初始化”这时候不要去手动重启容器等它自己跑完就好。另外1.17 版本对插件体系做了不少调整。如果你在旧版本里装过第三方插件升级之后最好到插件管理页面看一遍插件的兼容状态不兼容的及时卸载重装。我身边就有朋友升级后知识库一直报错最后发现是旧版插件不兼容导致卸载之后立刻恢复了。5. 新手避坑指南带过的人踩过的共性教训5.1 别把 .env 文件改得面目全非配置文件的坑往往比代码的坑更难排查。我见过有个朋友为了优化性能把.env里能看到的参数都改了结果系统起不来最后逐行对比原始文件的 diff 才找到问题。新手要克制“改配置”的冲动默认配置对绝大多数场景都是够用的。如果你确实需要调参数一次只改一个改完记录在案别一口气改十个然后系统挂了你根本不知道哪一个是元凶。还有一个小细节.env文件里值的空格是会被解析进去的比如SECRET_KEY abc和SECRET_KEYabc是两回事。复制粘贴配置内容时值前后别留空格别加引号除非官方模板里明确写了带引号。5.2 数据和备份目录别乱动volumes目录是 Dify 的地基里面存了上传文件、数据库物理文件、向量索引。如果你看着磁盘空间不够想手动删这个目录里看起来像垃圾的东西相当于跑着跑着把房子的承重墙拆了。磁盘不够的正确处理方式先看哪些真正占了大头比如docker system df查看镜像和悬空容器再针对处理。业务数据只能用 Dify 自带的管理功能或者数据库命令来清理。我再说一个经历过的事件有个用户把volumes/weaviate整个目录删了想“重置向量库”结果知识库的确空了但是 Docker 容器还是挂着旧的挂载关系服务直接崩溃最后只能从备份里恢复。如果你真想清空知识库正确姿势是在 Dify 界面里删除相关数据集或者用 docker compose down 停掉服务后再处理 volumes而不是趁服务运行的时候直接删文件。5.3 团队使用话记得先理清账号体系1.17 版本支持一个实例下创建多个成员账号通过“团队”功能做简单隔离。但这里要提醒社区版的多租户能力是有限度的做内部开发测试可以真要给外部客户做隔离环境还是得考虑其他方案。我在实际项目里遇到过一个需求两个部门希望共用一套 Dify数据完全隔离。社区版做起来非常费劲因为权限粒度没那么细。如果你有这种需求趁早在部署层面就把环境拆开比如一台机器起两套 compose中间用不同端口隔离别指望一套实例能解决所有权限问题。最后再分享一个习惯每次改动.env或者 compose 文件之前把当前能正常运行的版本打一个 tag比如把整个 docker 目录压缩一份存起来。这个习惯我吃了亏之后才养成现在任何升级和调试都有回退方案心里踏实得多。Dify 部署本身不复杂真正崩心态的都是细节问题这篇写到这里的核心结论就一句话一步一步来先跑通再折腾。