Dify本地部署完全指南：从Docker Compose到Ollama接入与知识库实战

如果你所在团队的诉求是“把大模型能力真正用起来但数据不想出内网”那Dify的本地部署大概率是绕不开的那个名字。它是一个开源的大语言模型应用开发平台把智能体、知识库、工作流、模型管理都收进一个可视化控制台而且可以完全跑在自己的服务器上。这篇文章记录我多次部署和迁移Dify的实际过程从硬件准备到Docker Compose起服务从接Ollama跑本地DeepSeek到知识库工作流的玩法最后聊聊升级、迁移和几个高频报错的完整排查链路希望能帮你少走几趟弯路。部署这件事最怕的不是步骤多而是不知道每一步在干什么就开始复制粘贴。所以我尽量把“为什么这么做”也讲清楚。1. 先算算资源账本地部署前需要准备的硬件与软件很多人一上来就急着拉代码结果跑到一半发现内存不够、端口被占、Docker版本太老又折回去折腾环境。本地部署Dify第一步应该是算账把硬件、软件和版本这三件事定下来。1.1 最低配置与推荐配置怎么定Dify本身对硬件并不算贪婪它本质上是几个容器组成的Web服务。官方建议是2核4G起步但请注意这个“起步”只够让平台本身转起来——如果你只是对接云端API做一些简单测试那确实够用。可一旦你要跑文档解析、知识库分段、异步任务这些活CPU和内存很快就会被打满。我的实际建议是纯平台体验只接云端大模型API4核8G内存磁盘40G以上。日常使用比较舒服。平台加本地小模型7B量化级16G内存起步磁盘100G以上。7B的量化模型在纯CPU环境下推理速度只能说“能用”想要流畅就得上GPU。平台加中大型本地模型14B以上32G内存是底线显存越大越好。如果没有独显纯CPU跑14B会非常煎熬建议慎重。磁盘方面也别卡太死。Dify的镜像全家桶大概会占10G左右Ollama拉一个7B模型又要4到5G知识库的向量数据、日志、备份都会慢慢涨。我给自己的服务器留了200G目前看是够用的。1.2 版本怎么选别用main分支认准Release TagDify的社区版迭代很快GitHub上的main分支基本上是“随时都在变”的状态。我第一次部署图新鲜直接clone了main分支结果过几天发现API行为变了配置项也换了排查起来很痛苦。所以我的习惯是只用打了Tag的Release版本。做法是先clone代码然后切到对应的版本Tag再操作。git clone https://github.com/langgenius/dify.git cd dify git tag # 查看可用的版本列表 git checkout 1.1x.x # 按需切到某个稳定版本选择版本还有一个原则不要追求最新要选“社区验证过一段时间的稳定版”。因为Dify的插件机制、模型供应商配置在版本之间有过调整如果你要接入Ollama、做知识库建议先查一下目标版本的发布说明确认没有大的不兼容变更再动手。软件环境方面Docker和Docker Compose是必须的。Dify的部署默认走Compose所以你的Docker版本最好在20.10以上Compose用V2版本。操作系统我推荐Ubuntu 20.04以上或Debian 12省心Windows虽然能用Docker Desktop跑但资源占用更高生产环境不建议。2. Docker Compose从零起一套Dify实操记录与组件拆解环境确认后部署本身并不复杂核心就是三步拿代码、配环境变量、拉起来。但每一部里都有值得说道的细节。2.1 获取代码与初始化环境变量在Dify的docker子目录下你会发现所有部署相关的东西都放在这里cd dify/docker cp .env.example .env这个复制动作千万别跳过。.env里存着Dify的全部运行参数包括数据库密码、密钥、各类端口、模型供应商API Key等。直接改它而不是自己手写一个可以避免漏项。.env里最需要关心的是这几个配置项作用我的建议SECRET_KEY加密会话和敏感数据用openssl rand -base64 42生成POSTGRES_PASSWORD数据库密码改成强随机密码DB_PASSWORD数据存储密码和上面保持同步即可EXPOSE_NGINX_PORT对外访问端口默认80如果被占用改成8080之类SECRET_KEY是重中之重。很多人部署完能跑就不管了结果等要迁移的时候才发现这个值没记录导致所有加密数据解不开。我建议你把它单独记到一个密码管理工具里这个习惯后面会救命。2.2 启动容器与初始化管理员环境变量配好之后一条命令拉起整个集群docker compose up -d第一次执行会拉取大量镜像时间取决于你的网络状况。拉完之后查看状态docker compose ps看到所有服务都处于running状态就基本成功了。然后在浏览器访问http://你的服务器IP/install这一步是Dify的初始化向导设置管理员邮箱和密码。这里有个容易忽略的点初始化管理员这一步不要跳过也不要随便填一个以后不用的邮箱。这个账号是后续邀请成员、创建多工作空间、管理模型供应商的入口。如果初始化中途失败检查一下是不是端口没访问对——Dify是通过nginx统一入口对外暴露的默认80端口如果被系统里其他服务占了请回到.env改EXPOSE_NGINX_PORT然后重新执行docker compose up -d。2.3 每个容器是干什么的遇到故障时知道去哪看Dify一启动就是一堆容器很多人看到docker compose ps里密密麻麻的列表就发怵。其实这些组件分工很明确我梳理了一张表容器名职责apiFastAPI后端处理业务请求和编排逻辑worker异步任务执行者比如知识库文档分段和索引web前端界面也就是你浏览器里看到的控制台dbPostgreSQL数据库存业务数据redis缓存和消息队列sandbox代码节点运行沙箱隔离用户脚本ssrf_proxy外发请求的安全代理防止服务端被诱导访问内网资源plugin_daemon插件管理服务Dify 1.x开始引入weaviate/qdrant向量数据库存知识库的向量化数据知道每个容器的职责排错思路就清晰了。比如知识库文档一直显示“处理中”大概率是worker出了问题直接看它的日志比瞎猜快得多docker compose logs worker --tail 100记住一个原则出问题先看日志别急着重启所有容器。日志会告诉你真正的原因。3. 本地模型接入Ollama用DeepSeek跑通Dify的完整链路对很多团队来说本地部署Dify的真正目的不是省那点API费用而是要用本地大模型完成闭环。Dify本身不自带模型它是个“模型网关编排器”所以接入Ollama就成了本地化部署里最热门的一步。3.1 Ollama侧的准备安装、拉模型、放开网络监听Ollama是目前跑本地模型最省事的工具之一。安装完成后第一件事是拉一个合适的模型。我常用的是DeepSeek系列比如ollama pull deepseek-r1:7b ollama pull qwen2.5:7b-instruct用ollama list可以查看本地已有的模型。注意模型名字一定要记准后面在Dify配置里填的就是这个名字大小写和tag都不能错。Ollama默认只监听127.0.0.1:11434也就是说只有本机能访问。而Dify的API容器是独立的它要访问宿主机上的Ollama就必须让Ollama监听所有网卡。Linux上推荐用systemd配置systemctl edit ollama在打开的配置里写入[Service] EnvironmentOLLAMA_HOST0.0.0.0保存后重启Ollamasystemctl restart ollama这一步不做后面在Dify里测试模型供应商一定会报连接失败这是本地部署场景最典型的“坑”之一。3.2 Dify侧配置模型供应商的注意点登录Dify控制台进入“设置-模型供应商”添加Ollama供应商。这时需要填一个API Base URL和模型名称。API Base URL怎么填取决于你的系统环境Windows或macOS的Docker Desktop填http://host.docker.internal:11434Docker Desktop自带宿主机域名映射。Linux服务器填http://宿主机局域网IP:11434比如http://192.168.1.10:11434。模型名称就填你在Ollama里拉取的名字比如deepseek-r1:7b。填完之后点击“测试”如果通过说明链路打通了。如果测试失败别急着怀疑Dify先在宿主机上确认Ollama本身是好的curl http://127.0.0.1:11434/api/tags能返回JSON就说明Ollama正常。再进Dify的api容器里试一次看容器能不能访问到宿主机docker exec -it dify-api bash curl http://宿主机IP:11434/api/tags不通过的话要么是OLLAMA_HOST没生效要么是防火墙拦了11434端口。这个排查链路基本能覆盖90%的连接问题。3.3 宿主机与容器网络打通的两条路关于host.docker.internal这个地址我多说一句。它在Docker Desktop里开箱即用但在纯Linux环境下Docker并不会默认提供这个域名。你要么用宿主机IP要么在docker-compose.yaml里给api和worker服务都加上这样一段extra_hosts: - host.docker.internal:host-gateway这样容器里就能直接通过host.docker.internal访问宿主机了。两种方法我都试过生产环境我更推荐直接用宿主机IP少一层依赖逻辑也更直观。另外如果你还要做知识库的本地化EmbeddingOllama同样可以承担。拉一个支持embedding的模型比如bge-m3ollama pull bge-m3然后在Dify里添加同名的Ollama Embedding模型。注意bge-m3的向量维度是1024配置时要手动确认填对否则知识库召回结果会变得很奇怪。4. 知识库、工作流与对外API部署完之后真正要做的事平台跑起来、模型接进来这只是“部署完成”离“用起来”还有一段路。Dify最能提现价值的两个功能就是知识库和工作流如果你只是把它当成一个聊天页面那本地部署的意义就少了一半。4.1 本地Embedding模型的选择与知识库搭建知识库的本质是“把文档切成小段转成向量检索时按语义找最相关的片段”。Dify里创建知识库的流程很成熟上传文档、选分段策略、保存并索引。这里有几个实操细节分段长度我一般设在500字符左右重叠100字符。分段太短会丢失上下文太长又会让检索结果不精准。Dify支持自定义分段标识符如果文档结构规整用标题作为分段边界效果更好。Embedding模型选型上本地场景我首推bge-m3它在中文理解上比很多同体量模型好而且Ollama直接支持。建好知识库之后一定要在Dify的“召回测试”里手动试几个问题看看召回的片段语义对不对。这个验证动作很多人会省掉结果应用上线后发现回答牛头不对马嘴再回头排查就慢了。4.2 工作流编排的最小可用示例知识库建好后可以去“工作室”里创建一个应用类型选“工作流”。Dify的工作流是可视化的我建议第一个流程保持最小闭环开始节点 → 知识库检索 → LLM → 结束。把用户问题传进知识库检索节点作为查询变量检索结果再塞给LLM节点作为上下文提示词。这样模型回答时会引用知识库内容而不是凭空发挥。跑通之后再逐步加条件分支、变量赋值、代码节点这些高级玩法。变量赋值节点是我用得比较多的一环。它能把中间结果临时存起来比如从用户输入里抽取一个参数传给后续的HTTP请求或代码节点做二次处理。Dify里称为“变量赋值”搜这个关键词能找到对应节点。工作流的好处是可以把每个节点单独调试出问题能定位到具体环节而不是面对一个黑盒。4.3 把应用发布成API与MCP供Cursor等外部工具调用Dify做好的应用不只能在这个平台里用还可以发布成服务API。在应用页面点击“发布”打开API访问开关就会生成一个API密钥和调用地址。这样你内部的知识库问答能力就可以被其他系统直接调用。新版Dify还支持把应用发布成MCP服务和OpenAPI兼容接口。这意味着像Cursor这类AI编程工具可以直接通过MCP协议连上你的Dify知识库在不离开编辑器的情况下查内部文档。热搜里那批“cursor连接dify知识库”的折腾记录基本就是在走这条线路。配置方式也不复杂在Dify的API管理页面找到MCP端点地址把它作为MCP Server配置到Cursor里即可。这个玩法特别适合有大量内部技术文档、又想用AI辅助写代码的团队。5. 升级、迁移和报错自救三个高频坑的完整排查过程部署完成只是开始Dify社区版更新快日常运维里遇到最多的就是升级、迁移和几个经典报错。这一章我把自己的处理过程完整记录下来。5.1 温和升级流程与必备备份Dify升级本身不复杂真正复杂的是“防止升级后数据出问题”。我的升级流程永远是备份先行docker compose stop # 备份数据库 docker exec -it dify-db pg_dump -U postgres -d dify dify_backup_$(date %Y%m%d).sql # 备份环境变量和编排文件 cp .env .env.bak cp docker-compose.yaml docker-compose.yaml.bak确认备份成功后从GitHub仓库拉取新版代码并切Tag然后cd dify/docker docker compose pull docker compose up -d升级之后如果一切正常再把备份留到一周后再清理。别急着删万一新版本有隐藏问题你还留了后悔药。5.2 迁移到新服务器SECRET_KEY是命门换服务器这件事我踩过一次大坑。当时直接把数据卷拷过去数据库也恢复了结果所有模型API Key解密失败、登录态全部失效。最后发现症结就是SECRET_KEY。Dify用SECRET_KEY加密存储敏感信息比如模型供应商的API Key。新服务器如果用了新的随机SECRET_KEY旧数据里的密文就解不开。迁移的正确流程是旧服务器上备份数据库和向量数据库数据。新服务器上装好Docker和相关环境拉下相同版本的Dify代码。把旧服务器的.env原样复制过去尤其是SECRET_KEY。恢复数据库备份再启动容器。向量数据库的数据卷也要一起备份和恢复否则知识库的索引会丢失需要重新分段和向量化。这块数据量大的时候重跑很耗时迁移前一定要连向量库一起处理。5.3 三个高频报错从表象到根因第一个是“An error occurred during credentials validation”。这个报错几乎每个接本地模型的人都会遇到。它发生在你测试模型供应商的时候含义是Dify无法通过你填的API地址和Key完成验证。排查链路我上面已经写过了先确认Ollama在宿主机正常再确认容器能访问宿主机最后确认模型名完全一致。大多数情况下都不是Dify的问题而是网络和配置的问题。第二个是SSL错误。如果你在本地环境用HTTP访问但Dify某些接口或Ollama地址写成了HTTPS就会报SSL相关错误。比如Ollama的Base URL误填成https://192.168.1.10:11434而Ollama实际只提供HTTP服务。反过来如果你用Nginx或Caddy给Dify做了HTTPS反代回源配置错了也会报SSL。排查思路是确认访问协议和实际服务协议是否一致curl一测便知。第三个是“too many incorrect password attempts”。这是连续登录失败触发的锁定提示。Dify的API容器里提供了重置密码的命令docker exec -it dify-api bash flask reset-password按提示输入管理员邮箱和新的密码完成后重新登录即可。这条命令比去改数据库安全得多。最后再分享一个我的习惯无论升级还是排查问题都先看一眼对应的容器日志再动手改配置。Dify的容器划分很干净api、worker、web各管一摊日志里基本都能找到线索别一上来就docker compose restart一把梭那样只会把问题掩盖掉。本地部署这件事只要环境理清楚、备份做到位Dify完全可以成为一个很稳的内部AI基础设施。