Dify 这个项目第一次听说的时候我还是持观望态度的。后来在社区里看到有人用它的工作流搭了一个知识库问答机器人从提问到检索文档再到生成回答全程没写多少代码才意识到这东西的定位有多讨喜。它全名叫 Dify.AI开源的大模型应用开发平台适合我这种想把大模型落地到具体应用、又不想从头撸 Prompt 工程和 RAG 管道的普通人。1.17 版本虽然不算最新但胜在稳定工作流编辑、模型管理、知识库这些核心模块都到了一个比较完备的状态做新手的起点非常合适。这篇东西就是一篇实战记录目标很明确帮你用最小的成本把 Dify 1.17 跑起来并把你大概率会踩的坑提前拆开。文章会覆盖环境准备、精简部署、模型接入本地 Ollama 和云端 API 两种主流方案、知识库与工作流的基础配置以及一套可以直接照着操作的排查方法。不管你是第一次碰 Docker还是已经折腾过几天按这个顺序走下来至少在部署这个环节不会再对着满屏错误日志发呆。1. 部署前的准备功夫1.1 先搞清楚 Dify 解决什么问题Dify 能做什么用一句话概括把大模型从“能聊天”变成“能干活”。它把模型调用、Prompt 编排、知识库检索、Agent 工具调用、日志与运营分析这些组件全部收拢到一个可视化的管理界面里。你在界面上创建的应用可以直接通过 API 暴露给外部系统也可以嵌入网页当成一个小产品来用。对新手来说Dify 最大的价值是省掉了大量的工程化工作。如果你自己从零搭一个 RAG 服务你得处理向量库选型、文档分段、Embedding 模型调用、检索排序、上下文组装、流式输出……这一套下来少说一两个星期。而 Dify 把这些全部封装成了开箱即用的功能你只需要关注业务问题本身。版本选择这块我坚持推荐 1.17 而不是盲目追新原因有三第一1.17 的工作流编辑器已经支持节点复制、单节点调试、分支逻辑功能上完全够用第二这个版本的模型供应商适配非常全主流的 OpenAI、DeepSeek、Ollama、MiniMax 都内置了第三社区里关于 1.17 的踩坑记录已经很多遇到问题大概率搜得到答案。选一个被大家验证过的稳定版本开始比追随最新版要理性得多。1.2 硬件和软件环境给个能直接抄的答案先说我实测的配置。我自己用的是一台 4 核 8G 内存的云服务器Ubuntu 22.04跑 Dify 1.17 加上一个 7B 的量化模型日常知识库问答体验尚可但内存已经比较吃紧。如果你打算在本地用 Ollama 跑模型建议内存至少 16G如果只是接云端 API8G 内存跑 Dify 本体是够的。磁盘方面Dify 本身的镜像加起来大约占用 8G 到 10G再加上文档数据、日志和向量索引预留 20G 比较稳妥。软件环境只需要两个核心组件Docker Engine 和 Docker Compose 插件。Dify 1.17 的 compose 文件依赖 Docker Compose v2 语法如果你服务器上还是老版的docker-compose建议统一升级。另外提一句Windows 用户部署 Dify 也不是不行用 Docker Desktop 就能跑我后面会用到一个关键配置差异容器访问宿主机的地址到时候再细说。1.3 安装 Docker 环境一条命令起步如果你面对的是一台干净的 Ubuntu 服务器安装 Docker 最省事的方式是curl -fsSL https://get.docker.com | bash -s docker这条命令会把 Docker Engine、CLI 和 Compose 插件一次装好。装完验证一下docker --version docker compose version两个命令都有输出环境就绪。Windows 用户安装 Docker Desktop 后记得在设置里确认使用的是 WSL2 后端macOS 用户直接装 Docker Desktop 就行。这里有一个新手经常忽略的细节docker compose up和docker-compose up是两套不同版本的命令前者是 Compose v2推荐后者是独立的 Python 工具。Dify 1.17 的部署文档默认使用前者。如果你在输入命令时报“compose 命令不存在”大概率是没装插件而不是 Dify 的问题。2. 精简部署全流程实操2.1 下载 Dify 1.17拿到 docker 目录就够了下载 Dify 1.17 的源码包你不需要关心整个仓库的源码只需要关注解压后的docker目录。这个目录里躺着三个关键东西docker-compose.yaml所有服务怎么编排、.env.example配置模板、nginx子目录反向代理和 HTTPS 配置。如果你用 Git 拉取可以指定版本分支git clone --branch 1.17.0 https://github.com/langgenius/dify.git cd dify/docker在 Windows 上下载源码包之后解压到某个目录进入dify-main/docker在文件夹空白处按住 Shift 键点右键选择“在终端中打开”就能得到命令窗口。这里要注意路径不要带有中文或空格否则后面部分工具处理起来容易出些莫名其妙的幺蛾子。2.2 复制 .env 模板修改关键参数进入 docker 目录后无论如何先执行这一条cp .env.example .env复制模板到.env之后你可以用文本编辑器打开它看一下都配置了些什么。核心参数有下面几个EXPOSE_NGINX_PORT80Dify 的 Web 入口端口。服务器上 80 端口被占的话改成8080或别的可用端口。EXPOSE_NGINX_SSL_PORT443HTTPS 入口端口本地部署一般用不到但端口冲突时也要留意。SECRET_KEY默认是一个固定的开发用值。部署到服务器后用openssl rand -base64 42生成一个新的替换它。DB_USERNAME/DB_PASSWORDPostgreSQL 的连接账号密码。默认值其实也可以跑但生产环境建议改掉。VECTOR_STOREweaviate向量数据库默认用 Weaviate新手不用动。我想特别强调一点新手最容易犯的错误是打开.env看到一堆配置项就忍不住到处改。其实 Dify 官方默认配置是针对标准部署调好的你只需要改那些明显和你的环境冲突的参数比如端口其他的一律别动。改得越多排查问题的时候变量越多自找麻烦。2.3 启动服务完成首次登录配置好.env后回到docker目录执行docker compose up -d首次执行会拉取全部镜像。这个过程我建议耐心等中间不要 CtrlC也不要急着开另一个容器操作。拉完之后运行docker compose ps你会看到一堆Up状态的容器包括nginx、api、worker、web、db、redis、sandbox、ssrf_proxy、weaviate等。刚启动的前几十秒api容器可能还在做数据库迁移页面先打不开是正常的。等个十几秒浏览器访问http://服务器IP:EXPOSE_NGINX_PORT看到管理员创建页面就成功了。第一次登录后记得把邮箱、密码这些信息记好重置密码的流程虽然存在但没必要走一遍。如果想看启动日志用docker compose logs -f api跟踪 API 服务的输出会出现Database migration之类的字样等它跑完再刷新页面即可。3. 把模型和知识库都接进来从能跑到能用3.1 本地模型接入Ollama 的 Base URL 千万别写 localhost部署完成只是第一步接不上模型就等于白跑。对个人用户来说最灵活的方式是接本地模型Ollama 是这里面最省心的选择。先在宿主机安装 Ollama拉一个你想要的模型ollama pull qwen2.5:7b然后进入 Dify 后台路径是“设置”→“模型供应商”→“Ollama”。这里需要填写两个关键信息Model Name例如qwen2.5:7b要和ollama list输出完全一致。Base URL这里 90% 的新手都踩过坑。如果你在 Dify 的 Docker 容器里填http://localhost:11434它访问的是容器自己的 11434 端口而 Ollama 跑在宿主机上必然连不上。正确写法是Docker Desktop 用户填http://host.docker.internal:11434Linux 服务器用户填http://172.17.0.1:11434或宿主机的局域网 IP。提示在 Dify 容器里访问宿主机服务时localhost指向的是容器自身不是宿主机。这是模型连接失败最常见的根源。填完点击“测试”如果模型列表正常加载说明连通了。还有一个前置条件Ollama 默认只监听本机请求跨容器或跨机器访问时需要设置环境变量OLLAMA_HOST0.0.0.0然后重启 Ollama否则即使 Base URL 填对了也会被拒绝。3.2 云端 API 接入以 DeepSeek 为例的通用做法接入云端模型的思路更简单。以 DeepSeek 为例先在对应平台注册并申请 API Key然后在 Dify 的“模型供应商”页面找到 DeepSeek填入 Key完成。Dify 对 OpenAI 兼容接口的适配做得已经很成熟所以很多国产模型的接入本质是在做“填 Key、填 Base URL”两件事。如果你的模型供应商在 Dify 列表里没有直接出现可以试试用“OpenAI-API-compatible”这类通用入口手动填 Base URL一样能接起来。这里分享一个适配细节不同模型的上下文长度差异很大。Dify 在模型设置里允许你配置上下文长度和最大 Token 数如果你用的是长上下文模型却保留了默认的短上下文参数Dify 会在上下文组装时主动截断导致回答丢失前面的关键信息。接完模型后花一分钟检查这两个参数能帮你省掉后面一大半“模型回答不完整”的困惑。3.3 创建第一个应用、工作流和知识库模型接通后快速验证链路的方式是创建一个“聊天助手”类型的应用选好模型发一条消息试试。如果回复正常恭喜Dify 的核心链路已经通了。接下来值得体验的是工作流。创建应用时选择“Chatflow”类型会进入一个可视化画布。最简单的工作流就是三个节点开始 → LLM → 结束。把 LLM 节点的模型选成刚才接好的模型输入变量从开始节点传递过去点击“运行”测试观察节点输出。这里我特别想强调的是Dify 的每个节点都支持单独调试你在某个节点右上角就能看到输入输出的完整记录这个能力对排查问题太重要了——不用猜直接看数据。知识库的接入同样门槛很低。创建一个数据集上传文档Dify 会自动完成分段和向量化。分段参数是后面影响检索效果的关键段落太长召回时会把不相关内容一起带回来段落太短上下文碎片化模型像在看一段段无头无尾的文字。我处理中文技术文档时习惯把分段大小设在 500 到 800 个字符重叠区域 50 到 100 字符实际按文档类型微调。4. 问题排查与避坑实录4.1 容器反复重启先看日志再动配置新手部署 Dify遇到最多的就是“某个容器一直在重启”。遇到这种情况我建议按下面的顺序排查docker compose ps docker compose logs api docker compose logs db先看哪个容器是Restarting状态再去看它的日志。api容器日志里如果出现数据库连接错误多半是db容器还没就绪或者数据库密码不匹配解决方法是把全部容器停掉再重新起来让依赖关系正常走一遍docker compose down docker compose up -d如果db容器自己也是Restarting就要看它的日志。比较常见的是数据卷权限问题和宿主机目录权限设置有关如果排除了权限可以备份数据后删除对应的卷重新初始化。注意删除卷意味着清空已有数据操作前想清楚是否接受这个代价。4.2 端口冲突与页面访问异常页面访问不了的另一个典型原因是端口冲突。Dify 的 Nginx 容器默认监听 80 和 443如果你在服务器上已经跑着 Nginx 或其他 Web 服务新容器怎么都起不来。用下面的命令查一下端口占用情况sudo lsof -i:80确认被占用后去.env把EXPOSE_NGINX_PORT改成 8080执行docker compose up -dCompose 检测到配置变化会重建容器。这里有个经验改端口后如果页面还是访问不了检查一下防火墙和云服务商的安全组规则很多云服务器的 8080 端口默认是不放行的需要在控制台里把端口加进白名单。4.3 镜像拉取超时与升级时的坑第一次拉镜像超时基本是所有国内用户都会遇到的问题。常规解法是给 Docker 配置镜像加速器。修改/etc/docker/daemon.json加入 registry-mirrors 配置项然后重启 Docker 服务。如果某个镜像反复失败可以单独拉取这个镜像再重新启动 compose。关于升级我补充几个细节。Dify 升级的核心命令是docker compose down # 更新源码git pull 或重新解压 cp .env.example .env docker compose pull docker compose up -d但这里有一个很容易踩的坑直接覆盖.env会丢掉你之前改过的所有参数。正确操作是先备份旧.env然后用新版模板和旧文件做对比把新增的参数补进去保留你已经自定义过的旧参数。升级数据库结构也需要时间启动后建议观察api容器的日志等迁移完成再访问页面。4.4 常见错误速查表现象可能原因解决方案容器反复重启端口冲突、依赖服务未就绪查看日志改端口或清理数据卷页面无法访问Nginx 未启动、端口映射错误确认EXPOSE_NGINX_PORT和防火墙规则API 日志提示数据库连接错误PostgreSQL 未就绪或密码不正确检查 db 容器状态核对.env配置Ollama 模型连接失败Base URL 写错、Ollama 未监听外部请求容器内使用宿主机地址设置OLLAMA_HOST0.0.0.0模型调用超时模型加载慢、上下文过长调整上下文长度提升硬件配置知识库检索为空分段参数不当、向量化失败调整分段大小重新执行索引登录后部分页面白屏Web 容器和 API 容器版本不一致确保所有镜像版本一致重建容器5. 部署后的调优、备份与下一步5.1 给容器加资源限制防止一台机器被拖垮Dify 默认的 compose 文件没有给容器设置资源上限这在低配机器上是个隐患。几个容器同时跑起来内存很容易被吃满然后整个系统进入卡顿甚至 OOM 状态。建议在/etc/docker/daemon.json中设置 Docker 的总资源限制或者在 compose 文件的对应服务下面加deploy.resources.limits配置。一个可以照抄的片段services: api: deploy: resources: limits: memory: 2G cpus: 1.5给 API、Worker、Web 这三个服务都加上合理限制其余服务按类似思路配置。这样即使某个容器出现内存泄漏也不会把整台机器拖死。5.2 数据备份与后续可以玩的方向部署完成之后千万别忘了备份的重要性。Dify 的数据主要存在 PostgreSQL、Redis、Weaviate向量索引这几个容器里最简单粗暴的备份方式是定时docker compose down后打包整个 docker 目录。如果不想停机可以用docker run挂载卷的方式直接复制数据目录。无论采用哪种方式备份频率取决于你写入数据的频度至少一周一次起步。后续可玩的方向非常多但是别想着一步到位。我现在用 Dify 的习惯是先把一个很小的应用场景跑通比如让工作流里加一个知识库检索节点再逐步加工具、加分支。踩过几次坑之后你会发现部署只是第一步把数据和业务逻辑梳理清楚才是工作中最花时间的部分。先把这版 1.17 跑稳后面再考虑升级或者扩展不迟。
Dify 1.17 部署实战：从环境准备到模型接入与避坑指南
Dify 这个项目第一次听说的时候我还是持观望态度的。后来在社区里看到有人用它的工作流搭了一个知识库问答机器人从提问到检索文档再到生成回答全程没写多少代码才意识到这东西的定位有多讨喜。它全名叫 Dify.AI开源的大模型应用开发平台适合我这种想把大模型落地到具体应用、又不想从头撸 Prompt 工程和 RAG 管道的普通人。1.17 版本虽然不算最新但胜在稳定工作流编辑、模型管理、知识库这些核心模块都到了一个比较完备的状态做新手的起点非常合适。这篇东西就是一篇实战记录目标很明确帮你用最小的成本把 Dify 1.17 跑起来并把你大概率会踩的坑提前拆开。文章会覆盖环境准备、精简部署、模型接入本地 Ollama 和云端 API 两种主流方案、知识库与工作流的基础配置以及一套可以直接照着操作的排查方法。不管你是第一次碰 Docker还是已经折腾过几天按这个顺序走下来至少在部署这个环节不会再对着满屏错误日志发呆。1. 部署前的准备功夫1.1 先搞清楚 Dify 解决什么问题Dify 能做什么用一句话概括把大模型从“能聊天”变成“能干活”。它把模型调用、Prompt 编排、知识库检索、Agent 工具调用、日志与运营分析这些组件全部收拢到一个可视化的管理界面里。你在界面上创建的应用可以直接通过 API 暴露给外部系统也可以嵌入网页当成一个小产品来用。对新手来说Dify 最大的价值是省掉了大量的工程化工作。如果你自己从零搭一个 RAG 服务你得处理向量库选型、文档分段、Embedding 模型调用、检索排序、上下文组装、流式输出……这一套下来少说一两个星期。而 Dify 把这些全部封装成了开箱即用的功能你只需要关注业务问题本身。版本选择这块我坚持推荐 1.17 而不是盲目追新原因有三第一1.17 的工作流编辑器已经支持节点复制、单节点调试、分支逻辑功能上完全够用第二这个版本的模型供应商适配非常全主流的 OpenAI、DeepSeek、Ollama、MiniMax 都内置了第三社区里关于 1.17 的踩坑记录已经很多遇到问题大概率搜得到答案。选一个被大家验证过的稳定版本开始比追随最新版要理性得多。1.2 硬件和软件环境给个能直接抄的答案先说我实测的配置。我自己用的是一台 4 核 8G 内存的云服务器Ubuntu 22.04跑 Dify 1.17 加上一个 7B 的量化模型日常知识库问答体验尚可但内存已经比较吃紧。如果你打算在本地用 Ollama 跑模型建议内存至少 16G如果只是接云端 API8G 内存跑 Dify 本体是够的。磁盘方面Dify 本身的镜像加起来大约占用 8G 到 10G再加上文档数据、日志和向量索引预留 20G 比较稳妥。软件环境只需要两个核心组件Docker Engine 和 Docker Compose 插件。Dify 1.17 的 compose 文件依赖 Docker Compose v2 语法如果你服务器上还是老版的docker-compose建议统一升级。另外提一句Windows 用户部署 Dify 也不是不行用 Docker Desktop 就能跑我后面会用到一个关键配置差异容器访问宿主机的地址到时候再细说。1.3 安装 Docker 环境一条命令起步如果你面对的是一台干净的 Ubuntu 服务器安装 Docker 最省事的方式是curl -fsSL https://get.docker.com | bash -s docker这条命令会把 Docker Engine、CLI 和 Compose 插件一次装好。装完验证一下docker --version docker compose version两个命令都有输出环境就绪。Windows 用户安装 Docker Desktop 后记得在设置里确认使用的是 WSL2 后端macOS 用户直接装 Docker Desktop 就行。这里有一个新手经常忽略的细节docker compose up和docker-compose up是两套不同版本的命令前者是 Compose v2推荐后者是独立的 Python 工具。Dify 1.17 的部署文档默认使用前者。如果你在输入命令时报“compose 命令不存在”大概率是没装插件而不是 Dify 的问题。2. 精简部署全流程实操2.1 下载 Dify 1.17拿到 docker 目录就够了下载 Dify 1.17 的源码包你不需要关心整个仓库的源码只需要关注解压后的docker目录。这个目录里躺着三个关键东西docker-compose.yaml所有服务怎么编排、.env.example配置模板、nginx子目录反向代理和 HTTPS 配置。如果你用 Git 拉取可以指定版本分支git clone --branch 1.17.0 https://github.com/langgenius/dify.git cd dify/docker在 Windows 上下载源码包之后解压到某个目录进入dify-main/docker在文件夹空白处按住 Shift 键点右键选择“在终端中打开”就能得到命令窗口。这里要注意路径不要带有中文或空格否则后面部分工具处理起来容易出些莫名其妙的幺蛾子。2.2 复制 .env 模板修改关键参数进入 docker 目录后无论如何先执行这一条cp .env.example .env复制模板到.env之后你可以用文本编辑器打开它看一下都配置了些什么。核心参数有下面几个EXPOSE_NGINX_PORT80Dify 的 Web 入口端口。服务器上 80 端口被占的话改成8080或别的可用端口。EXPOSE_NGINX_SSL_PORT443HTTPS 入口端口本地部署一般用不到但端口冲突时也要留意。SECRET_KEY默认是一个固定的开发用值。部署到服务器后用openssl rand -base64 42生成一个新的替换它。DB_USERNAME/DB_PASSWORDPostgreSQL 的连接账号密码。默认值其实也可以跑但生产环境建议改掉。VECTOR_STOREweaviate向量数据库默认用 Weaviate新手不用动。我想特别强调一点新手最容易犯的错误是打开.env看到一堆配置项就忍不住到处改。其实 Dify 官方默认配置是针对标准部署调好的你只需要改那些明显和你的环境冲突的参数比如端口其他的一律别动。改得越多排查问题的时候变量越多自找麻烦。2.3 启动服务完成首次登录配置好.env后回到docker目录执行docker compose up -d首次执行会拉取全部镜像。这个过程我建议耐心等中间不要 CtrlC也不要急着开另一个容器操作。拉完之后运行docker compose ps你会看到一堆Up状态的容器包括nginx、api、worker、web、db、redis、sandbox、ssrf_proxy、weaviate等。刚启动的前几十秒api容器可能还在做数据库迁移页面先打不开是正常的。等个十几秒浏览器访问http://服务器IP:EXPOSE_NGINX_PORT看到管理员创建页面就成功了。第一次登录后记得把邮箱、密码这些信息记好重置密码的流程虽然存在但没必要走一遍。如果想看启动日志用docker compose logs -f api跟踪 API 服务的输出会出现Database migration之类的字样等它跑完再刷新页面即可。3. 把模型和知识库都接进来从能跑到能用3.1 本地模型接入Ollama 的 Base URL 千万别写 localhost部署完成只是第一步接不上模型就等于白跑。对个人用户来说最灵活的方式是接本地模型Ollama 是这里面最省心的选择。先在宿主机安装 Ollama拉一个你想要的模型ollama pull qwen2.5:7b然后进入 Dify 后台路径是“设置”→“模型供应商”→“Ollama”。这里需要填写两个关键信息Model Name例如qwen2.5:7b要和ollama list输出完全一致。Base URL这里 90% 的新手都踩过坑。如果你在 Dify 的 Docker 容器里填http://localhost:11434它访问的是容器自己的 11434 端口而 Ollama 跑在宿主机上必然连不上。正确写法是Docker Desktop 用户填http://host.docker.internal:11434Linux 服务器用户填http://172.17.0.1:11434或宿主机的局域网 IP。提示在 Dify 容器里访问宿主机服务时localhost指向的是容器自身不是宿主机。这是模型连接失败最常见的根源。填完点击“测试”如果模型列表正常加载说明连通了。还有一个前置条件Ollama 默认只监听本机请求跨容器或跨机器访问时需要设置环境变量OLLAMA_HOST0.0.0.0然后重启 Ollama否则即使 Base URL 填对了也会被拒绝。3.2 云端 API 接入以 DeepSeek 为例的通用做法接入云端模型的思路更简单。以 DeepSeek 为例先在对应平台注册并申请 API Key然后在 Dify 的“模型供应商”页面找到 DeepSeek填入 Key完成。Dify 对 OpenAI 兼容接口的适配做得已经很成熟所以很多国产模型的接入本质是在做“填 Key、填 Base URL”两件事。如果你的模型供应商在 Dify 列表里没有直接出现可以试试用“OpenAI-API-compatible”这类通用入口手动填 Base URL一样能接起来。这里分享一个适配细节不同模型的上下文长度差异很大。Dify 在模型设置里允许你配置上下文长度和最大 Token 数如果你用的是长上下文模型却保留了默认的短上下文参数Dify 会在上下文组装时主动截断导致回答丢失前面的关键信息。接完模型后花一分钟检查这两个参数能帮你省掉后面一大半“模型回答不完整”的困惑。3.3 创建第一个应用、工作流和知识库模型接通后快速验证链路的方式是创建一个“聊天助手”类型的应用选好模型发一条消息试试。如果回复正常恭喜Dify 的核心链路已经通了。接下来值得体验的是工作流。创建应用时选择“Chatflow”类型会进入一个可视化画布。最简单的工作流就是三个节点开始 → LLM → 结束。把 LLM 节点的模型选成刚才接好的模型输入变量从开始节点传递过去点击“运行”测试观察节点输出。这里我特别想强调的是Dify 的每个节点都支持单独调试你在某个节点右上角就能看到输入输出的完整记录这个能力对排查问题太重要了——不用猜直接看数据。知识库的接入同样门槛很低。创建一个数据集上传文档Dify 会自动完成分段和向量化。分段参数是后面影响检索效果的关键段落太长召回时会把不相关内容一起带回来段落太短上下文碎片化模型像在看一段段无头无尾的文字。我处理中文技术文档时习惯把分段大小设在 500 到 800 个字符重叠区域 50 到 100 字符实际按文档类型微调。4. 问题排查与避坑实录4.1 容器反复重启先看日志再动配置新手部署 Dify遇到最多的就是“某个容器一直在重启”。遇到这种情况我建议按下面的顺序排查docker compose ps docker compose logs api docker compose logs db先看哪个容器是Restarting状态再去看它的日志。api容器日志里如果出现数据库连接错误多半是db容器还没就绪或者数据库密码不匹配解决方法是把全部容器停掉再重新起来让依赖关系正常走一遍docker compose down docker compose up -d如果db容器自己也是Restarting就要看它的日志。比较常见的是数据卷权限问题和宿主机目录权限设置有关如果排除了权限可以备份数据后删除对应的卷重新初始化。注意删除卷意味着清空已有数据操作前想清楚是否接受这个代价。4.2 端口冲突与页面访问异常页面访问不了的另一个典型原因是端口冲突。Dify 的 Nginx 容器默认监听 80 和 443如果你在服务器上已经跑着 Nginx 或其他 Web 服务新容器怎么都起不来。用下面的命令查一下端口占用情况sudo lsof -i:80确认被占用后去.env把EXPOSE_NGINX_PORT改成 8080执行docker compose up -dCompose 检测到配置变化会重建容器。这里有个经验改端口后如果页面还是访问不了检查一下防火墙和云服务商的安全组规则很多云服务器的 8080 端口默认是不放行的需要在控制台里把端口加进白名单。4.3 镜像拉取超时与升级时的坑第一次拉镜像超时基本是所有国内用户都会遇到的问题。常规解法是给 Docker 配置镜像加速器。修改/etc/docker/daemon.json加入 registry-mirrors 配置项然后重启 Docker 服务。如果某个镜像反复失败可以单独拉取这个镜像再重新启动 compose。关于升级我补充几个细节。Dify 升级的核心命令是docker compose down # 更新源码git pull 或重新解压 cp .env.example .env docker compose pull docker compose up -d但这里有一个很容易踩的坑直接覆盖.env会丢掉你之前改过的所有参数。正确操作是先备份旧.env然后用新版模板和旧文件做对比把新增的参数补进去保留你已经自定义过的旧参数。升级数据库结构也需要时间启动后建议观察api容器的日志等迁移完成再访问页面。4.4 常见错误速查表现象可能原因解决方案容器反复重启端口冲突、依赖服务未就绪查看日志改端口或清理数据卷页面无法访问Nginx 未启动、端口映射错误确认EXPOSE_NGINX_PORT和防火墙规则API 日志提示数据库连接错误PostgreSQL 未就绪或密码不正确检查 db 容器状态核对.env配置Ollama 模型连接失败Base URL 写错、Ollama 未监听外部请求容器内使用宿主机地址设置OLLAMA_HOST0.0.0.0模型调用超时模型加载慢、上下文过长调整上下文长度提升硬件配置知识库检索为空分段参数不当、向量化失败调整分段大小重新执行索引登录后部分页面白屏Web 容器和 API 容器版本不一致确保所有镜像版本一致重建容器5. 部署后的调优、备份与下一步5.1 给容器加资源限制防止一台机器被拖垮Dify 默认的 compose 文件没有给容器设置资源上限这在低配机器上是个隐患。几个容器同时跑起来内存很容易被吃满然后整个系统进入卡顿甚至 OOM 状态。建议在/etc/docker/daemon.json中设置 Docker 的总资源限制或者在 compose 文件的对应服务下面加deploy.resources.limits配置。一个可以照抄的片段services: api: deploy: resources: limits: memory: 2G cpus: 1.5给 API、Worker、Web 这三个服务都加上合理限制其余服务按类似思路配置。这样即使某个容器出现内存泄漏也不会把整台机器拖死。5.2 数据备份与后续可以玩的方向部署完成之后千万别忘了备份的重要性。Dify 的数据主要存在 PostgreSQL、Redis、Weaviate向量索引这几个容器里最简单粗暴的备份方式是定时docker compose down后打包整个 docker 目录。如果不想停机可以用docker run挂载卷的方式直接复制数据目录。无论采用哪种方式备份频率取决于你写入数据的频度至少一周一次起步。后续可玩的方向非常多但是别想着一步到位。我现在用 Dify 的习惯是先把一个很小的应用场景跑通比如让工作流里加一个知识库检索节点再逐步加工具、加分支。踩过几次坑之后你会发现部署只是第一步把数据和业务逻辑梳理清楚才是工作中最花时间的部分。先把这版 1.17 跑稳后面再考虑升级或者扩展不迟。
