先说结论Dify这玩意儿一旦要在隔离网环境里部署最折腾的其实不是主程序本身而是它那套依赖镜像和插件市场机制。我前前后后帮客户搞过好几台离线服务器从最早的社区版到后来的插件化版本踩过的坑攒了一堆。这篇就把完整的离线安装Dify主程序、以及离线安装插件的流程记录下来按我自己的实操顺序写照着做基本能通。我自己常用的场景是一台只有内网IP的Linux服务器无法访问外网需要在上面跑Dify做知识库和Agent应用开发。Dify社区版1.10之后插件体系改动挺大离线安装插件的方式跟早期也不太一样所以我会把主程序和插件两部分分开讲顺便把Dify 1.17.1涉及的新变化也提一下。1. 离线部署Dify的整体思路与方案选型1.1 离线环境下的核心难点在哪里Dify的部署方式官方推荐是Docker Compose一套跑起来至少需要十几个镜像包括api、web、db、redis、weaviate或者qdrant这些。在线环境一条docker compose up -d就搞定但离线环境里每个镜像都得手动搬运这是第一层麻烦。第二层麻烦是Dify的插件机制。老版本插件直接打包成.difypkg文件上传就行新版本1.10以后对插件进行了marketplace化很多插件还会依赖额外的Python包甚至要拉取独立的插件镜像。离线环境下如果没有提前准备插件装上也会因为缺依赖跑不起来。第三层是版本更新问题。Dify迭代速度很快从1.10到1.17.1界面、插件管理方式都有变化。离线环境一旦部署完后续想升级就得重跑一遍镜像导出导入的流程所以最开始就要想好怎么把这套流程固化成脚本别每次手动敲命令。1.2 整体方案选型Docker离线包私有镜像仓库我最终确定的方案分三层第一层用Docker Compose部署Dify主程序所有依赖镜像通过docker save打包成tar文件拷到内网后docker load导入。第二层插件镜像同样用save/load方式搬运插件本身的.difypkg文件手动上传到Dify管理后台。第三层对于Dify Marketplace插件依赖的Python包我直接在一台有外网的机器上构建好插件镜像打包搬运避免在离线服务器上装Python依赖。这个方案的好处是思路简单对运维要求不高只要会用Docker就能操作。如果只是临时部署、机器也不多没必要搭一个完整的Harbor私有仓库tar包拷来拷去反而更直接。提示如果你所在的项目后续要频繁更新Dify或者在多台内网机器上同时部署那我强烈建议在内网搭一个Harbor或Registry镜像仓库把Dify的镜像push到仓库里后续所有机器直接从内网仓库拉取。这篇文章基于单机tar包方案但仓库方案的操作路径其实是一样的只是少了save/load这两步。2. 离线安装Dify主程序的完整流程2.1 准备离线安装所需材料在能上网的机器上先去GitHub下载Dify的源码包。这里建议下载release页面里的dify-1.x.x.tar.gz这种完整包或者直接用git clone拉取指定tag的代码。我个人偏好用release包因为git clone会带上.git目录体积大而且有时候网络中断会导致仓库损坏。还需要准备的工具有Docker Engine的离线安装包我用的是Ubuntu服务器直接下载.deb文件如果是CentOS就下载.rpmDocker Compose的二进制文件注意别只下载docker-compose-linux-x86_64高版本Docker Compose的命名有变化Dify依赖镜像的tar包后续要用的插件镜像tar包这里面最容易被忽略的是Docker和Compose的版本匹配。我遇到过一台机器上的Docker版本是20.10但Dify新版要求Compose V2两者配合起来会出现网络模式不兼容的情况。建议Docker Engine版本不低于20.10Compose版本不低于2.20。2.2 如何正确导出Dify的所有依赖镜像这一步是核心很多人栽在这里。原因在于Dify的docker/docker-compose.yaml文件里有很多服务每个服务对应一个镜像有些镜像在不同的配置组合下才会被拉取比如向量数据库你选weaviate就用不上qdrant。如果只是docker compose up让它自动拉会缺漏一部分镜像。我的做法是在有外网的机器上把Dify源码包解压进入docker目录先执行一次docker compose config看看当前解析出来的镜像列表然后手动一个一个拉取再统一save。以Dify 1.17.1为例默认的镜像列表大概包括服务镜像用途apilanggenius/dify-api:1.17.1后端API服务workerlanggenius/dify-api:1.17.1异步任务Worker同一个镜像weblanggenius/dify-web:1.17.1前端页面dbpostgres:15-alpine元数据库redisredis:7-alpine缓存/队列weaviatesemitechnologies/weaviate:1.19.0向量数据库nginxnginx:latest反向代理ssrf_proxyubuntu/squid:latest防SSRF代理实际操作时我用docker compose config --images这条命令来获取所有依赖镜像列表然后循环执行docker pull和docker save。命令大致像这样cd dify/docker docker compose config --images images.txt while read image; do docker pull $image done images.txt docker save $(cat images.txt | tr \n ) -o dify-images-1.17.1.tar需要注意docker save一次传太多镜像名容易出现命令行长度超限的问题我遇到过几十个镜像时直接报Argument list too long。稳妥的办法是分两批save或者写成脚本循环save每个镜像单独压缩最后汇总。批量tar的好处是导入快坏处是如果中途损坏整个都用不了分文件更安全。2.3 内网导入镜像并启动Dify到了离线服务器上先把Docker和Compose装好然后导入镜像包docker load -i dify-images-1.17.1.tar导入完成后把之前下载的Dify源码包传上去解压进入docker目录复制环境变量文件并修改cp .env.example .env vi .env.env里需要重点改几个地方SECRET_KEY必须改成随机的长字符串不然后续会有安全风险POSTGRES_PASSWORD、REDIS_PASSWORD数据库和缓存的密码生产环境必须改VECTOR_STORE按你实际情况选weaviate、qdrant或milvusEXPOSE_NGINX_PORT默认80如果端口被占用要改成别的改完之后启动docker compose up -d启动后先看容器状态docker compose ps正常情况下api、worker、web、db、redis、weaviate、nginx这几个容器都应该是Up状态。我遇到过的问题往往出现在weaviate上因为向量数据库初始化慢api容器会一直在等待重试这时候不要慌等个一两分钟再看只要weaviate起来api一般会自动恢复。2.4 验证部署是否成功浏览器访问http://服务器IP能打开设置管理员账号的页面就说明主程序部署成功。设置完管理员账号进到Dify首页创建一个应用测试一下模型连接。如果模型走的是自建的大模型网关比如本地部署的Ollama、vLLM或者内网的OpenAI兼容接口直接配置对应的API地址就行。如果模型走外部API那离线环境就得确保防火墙放行对应的域名和端口这个属于网络策略问题不在安装流程里但经常被客户忽略。3. 离线安装Dify插件的实操过程3.1 插件机制的变化从.difypkg到MarketplacePluginDify从1.10开始插件体系和早期版本有比较大的变化。早期想在Dify里加个自定义工具或者模型接入可以直接上传.difypkg文件而且在GitHub上能找到很多安装教程。到了1.17.1Dify把插件市场Marketplace权重提得更高官方和社区插件主要通过Marketplace分发插件的安装也变成在管理后台的“插件”页面操作。但离线环境没有外网连不上Marketplace所以核心思路就两个字手搬。离线安装插件本质上是解决两个问题一是插件包本身.difypkg怎么弄到内网二是插件运行所需要的依赖Python包、Node运行时、甚至独立容器镜像怎么补齐。前者好解决后者才是真正费劲的地方。3.2 方法一手动上传.difypkg插件包如果是自研插件、或者从GitHub上直接下载了.difypkg文件的插件这种最简单。操作路径是管理后台 - 插件页面 - 右上角选“通过本地文件安装”或“从Package安装”选择.difypkg文件上传。这里有个坑.difypkg本质上是一个zip包里面除了插件的代码和元信息还会声明这个插件的运行环境要求比如用哪个Python版本、需要哪些pip依赖。Dify装插件的时候会尝试创建独立的运行时环境如果离线服务器上没有对应版本的Python或者pip源访问不到外网就会报错。解决办法是提前在一台有外网的机器上把插件需要的依赖下载好做成离线wheel目录传到内网后在插件安装前手动装一遍。不过Dify的插件运行时是隔离的直接装到系统环境里不生效所以更稳的办法是方法二。3.3 方法二通过离线Marketplace安装插件Dify的Marketplace机制其实就是一个远程的插件仓库索引Dify定期拉取索引数据在插件页面展示可安装的插件列表。离线环境下你可以把整个Marketplace的插件索引和插件文件打包配置成内网的HTTP服务Dify通过配置指向内网地址来实现“伪在线”安装。具体做法是在有外网的机器上从GitHub拉取Dify官方插件仓库langgenius/dify-plugins和Marketplace索引仓库langgenius/dify-plugin-daemon相关的marketplace配置用dify命令行工具或直接通过API把需要的插件比如langgenius-ai/openai、langgenius-ai/agent这些下载成.difypkg文件把所有.difypkg放到内网一台Web服务器的目录下同时把插件索引文件也放上去在Dify的.env里配置MARKETPLACE_API_URL指向内网地址重启api和worker容器这里要注意版本匹配问题不同版本的Dify对插件市场的API格式有要求我试过用新版本Marketplace的索引文件配到老版本Dify上直接不识别。如果只是临时用手动上传.difypkg反而更快。3.4 插件依赖的容器镜像如何处理经常被忽略的是现在很多插件不只是Python代码还会以独立容器的方式运行。比如某些爬虫插件、文档解析插件Dify会动态拉取一个镜像来执行任务。离线环境下这类插件的安装步骤里会特别标注需要镜像一执行就报错image pull failed。处理方式是在有外网的机器上提前拉取对应镜像并save拷贝到内网load。怎么知道插件需要哪些镜像方法一把.difypkg文件解压看里面的plugin.yaml或者manifest.yaml一般会列出运行时依赖的镜像地址。方法二在在线环境装一遍插件执行一次插件的某个操作然后看Dify拉取了哪些镜像再用docker save打包。第二种方法比较靠谱因为插件文档写得不全的情况很常见。我处理过的典型插件镜像有插件类型依赖镜像说明网页抓取类python:3.12-slim执行抓取脚本的Python环境文档解析类langgenius/dify-doc-parser官方文档解析器代码执行类node:18-alpine运行JavaScript代码块注意插件镜像的版本不要乱升级。Dify的插件在声明依赖镜像时如果不带tag默认拉latest而同名镜像latest更新后可能导致插件兼容性问题。save的时候务必确认tag并在内网通过docker tag把版本固定下来。4. 常见问题与排查技巧实录4.1 镜像拉取失败的典型原因与对策离线环境镜像相关的问题我归纳下来基本就是这几类现象原因解决方案docker compose up时提示pull access denied离线服务器上没有该镜像且没有配置镜像源回到有外网机器用docker compose config --images查全镜像列表逐一save/load镜像load成功但compose启动报找不到镜像tag不匹配比如load的是weaviate:1.19.0compose里写的是weaviate:latest用docker tag semitechnologies/weaviate:1.19.0 semitechnologies/weaviate:latest手动打tagapi容器一直Restarting数据库或向量库还没初始化好或者.env里的密码与postgres容器初始化密码不一致看api容器日志确认是哪种如果是连接超时多等几分钟是密码错误就删除volumes重置plugin执行时报镜像拉取失败插件运行时依赖的镜像没有提前导入在在线环境试用插件找出它拉取的镜像save/load导入特别提醒一下tag问题。很多人在线环境正常是因为docker compose会隐式补tag为latest但save出来的镜像名如果带了具体版本load之后不会自动生成latest的tag。所以离线导入后最好用docker images核查一下确保compose文件里写的镜像名和导入的镜像名完全对应。4.2 插件安装失败的排查思路插件离线安装失败的情况大多不是插件包本身的问题而是运行环境不匹配。我的排查顺序是第一步看Dify的插件管理页面有没有报错信息。如果提示缺少依赖包去在线环境检查该插件的依赖声明把对应的wheel包下载下来。第二步如果插件卡在installing状态很久多半是插件运行时在尝试访问外网比如下载Python依赖而内网环境超时了。这时候要用docker logs看插件的运行时容器日志确认具体卡在哪一步。第三步如果插件装上了但执行时报错比如module not found那就要手动在插件容器的运行环境里补装依赖。这个操作比较麻烦因为Dify插件运行时是动态创建的容器手动改不持久。我的办法是直接改插件依赖重新打包.difypkg把缺失的依赖写进安装脚本里。提示给.difypkg补依赖时不要直接把整个Python环境打进去这样包会非常大而且容易跟插件原本的运行时冲突。正确做法是在插件的安装脚本里增加pip install --no-index --find-links/path/to/wheels xxx把wheel文件放在内网某个固定路径下。4.3 Node和前端资源问题的排查虽然Dify的web服务是打包在镜像里的但有些Dify版本升级后web容器启动时会对静态资源做一次编译如果编译过程中有依赖需要从外网下载就会导致web容器反复重启。这个问题我遇到过一次场景是内网部署后登录页面能打开但页面样式错乱控制台报一堆JS资源404。排查下来是web容器在启动时从外部拉取了部分字体和图标资源内网环境下失败导致资源丢失。解决办法是提前把Dify的web资源静态化或者用内网的DNS把相关域名指向一个能响应的内网代理。更省事的方案是直接换一个包含全部资源的镜像tag比如某些镜像仓库会提供dify-web:1.17.1-full这种全量版本。如果没有就手动把缺失资源放到nginx容器挂载的静态目录里用docker cp拷贝进去。4.4 低版本Docker导致的兼容性问题如果离线服务器上装的是老的Docker版本比如19.03跑Dify会遇到一个典型问题compose文件里用了deploy.resources.limits的语法老版本Compose不支持resource limits直接报错。我见过不止一个人卡在这里以为是镜像问题实际上是Compose版本问题。判断方法很简单执行docker compose version看版本号如果低于2.0建议直接下载新版Compose二进制替换。另外老版本Docker对ipvlan、macvlan这些网络模式支持不完整而Dify默认创建的nginx容器有时会用到自定义网络。如果网络起不来检查一下是不是Docker版本太老docker network create时报了什么错。5. 部署完成后的维护建议与个人体会5.1 日常更新Dify的离线操作建议Dify版本更新频率高离线环境下追版本是个体力活。我现在的标准流程是在有外网的机器上用脚本拉取新版本的dify源码和依赖镜像列表对比新旧版本镜像差异只save新增或者变化了的镜像能少打包就少打包传到内网后load然后备份原有.env和数据库卷再启动新版本这里最怕数据库结构变更。Dify升级时会自动跑数据库迁移如果元数据库版本差太多迁移可能失败。我习惯在升级前先docker compose exec db pg_dump -U postgres dify backup.sql备份一下出问题能快速回滚。5.2 内网模型接入的踩坑经验离线部署Dify通常不是为了用开源模型而是要对接内网已有的模型服务。Dify里配置模型的时候需要注意模型类型LLM、Text Embedding、Rerank等是否被插件支持以及API地址是否填了内网地址。我踩过的一个坑是内网部署了一个OpenAI兼容协议的服务比如用vLLM起的Dify里配置OpenAI插件时填了base_url指向内网但Dify的api容器和模型服务不在同一个Docker网络里导致连接超时。后来我把模型服务的端口映射到了宿主机然后用http://宿主机IP:端口来填才通。所以离线部署Dify时如果同时跑模型服务最好把模型服务也做成Docker容器和Dify放在同一个docker network里直接用容器名访问能少很多网络问题。5.3 这套流程的扩展方向如果以后内网要部署多套Dify比如每个部门一套或者要支持多人开发插件建议把离线部署从“手动搬tar包”升级成“内网镜像仓库插件仓库”。我已经把常用的镜像push到了内网Harbor新装机器只需要改下/etc/docker/daemon.json的registry-mirrors然后docker compose up就能自动从内网仓库拉镜像省掉save/load这一步。插件仓库那边我也做了个简单的索引服务把常用插件的.difypkg按版本归档配合Dify的MARKETPLACE_API_URL配置实现内网市场效果。这套虽然初始化工作量多一点但后续维护效率高很多尤其是手底下管着好几台服务器的时候省下来的时间相当可观。最后再分享一个细节离线部署时建议把.env文件、镜像清单、插件清单、操作手册放在同一个目录里每次升级或排障都做记录。Dify这种平台部署一次容易长期维护才是真正考验文档和脚本的积累比一次性的安装成功重要得多。