Dify离线部署插件全指南：从下载到导入的完整流程

做私有化部署的同行应该都有这种感觉：Dify本身装起来不难，真正闹心的是插件。上个月我帮客户做一套完全隔离内网环境下的Dify交付，平台装好、大模型也对接完了，结果到了插件这一步卡了整整两天——插件市场连不上网，页面永远转圈，直接暴露了离线部署最大的痛点。从这次之后我把离线插件的下载、打包、导入、排错整个流程都趟了一遍，今天这篇就把完整路径写清楚。

这篇文章适合三类人：一是给政企客户做私有化交付的工程师，二是自己公司内网要部署Dify但外网受限的运维同学，三是虽然能上网但插件市场经常拉胯、想提前把插件包囤下来的个人用户。核心只讲一件事：在没有外网的前提下，怎么把Dify插件从零装到一个能跑的平台里。

1. 先把需求讲清楚：为什么离线部署会成为刚需

1.1 哪些场景必须走离线路线

很多人一开始不理解，明明Dify支持在线安装插件，为什么非要折腾离线。我接触的离线需求大概分这么几类，你看看自己属于哪一种。

第一种最常见，企业内网物理隔离。很多开发环境、生产环境本身就与互联网隔开，运维人员只能通过跳板机登进服务器，服务器上没有外网权限。这种情况下不要说插件市场，就连pip、apt源都得走内部镜像。这属于等保合规和业务安全的要求，躲不开。

第二种是数据合规约束。有些客户的业务数据、文档内容不允许出境或经过第三方服务器。即使内网能上外网，IT部门也会在策略上禁用外网访问。我之前一个客户是金融行业的，他们说得很直白：“模型服务可以本地化，数据不能到别人那儿转一圈。”这种情况下所有软件安装流程都必须离线。

第三种是网络质量不稳定。这个我自己也踩过，公司办公网能访问外网，但访问海外插件市场时快时慢，安装一个插件可能下载到一半就断掉，重试几次都失败。与其反复搏斗，不如在有网的时候把插件包下载好，拿到服务器上直接导入，一次性搞定。

第四种是交付场景。给客户做Dify整体交付时，现场环境往往是验收机房，网络策略很严，客户只给你一台服务器和一个SSH终端，所有软件安装都得靠U盘或者内部的软件仓库。这时候离线部署不是可选项，是唯一选项。

1.2 离线部署的真正难点在哪里

表面上离线部署只是“下载好再装”，但实际操作中痛点非常集中，我捋了一下主要有四个。

第一，Dify插件市场天然依赖网络。Dify的插件市场是一个在线服务，你在管理后台点“安装插件”，平台会实时去市场拉取插件元数据和安装包。一旦网络不通，整个功能直接瘫痪。这是很多人第一次接触离线部署时最懵的地方：明明平台装好了，插件页面却什么都显示不出来。

第二，插件本身有依赖链。Dify插件不只是一个孤立的文件，很多插件会依赖额外的Python库、Node模块，甚至依赖独立的容器镜像。比如一些模型供应商插件、向量数据库插件，装完后还需要下载推理依赖或者数据库驱动。如果这些依赖也得不到满足，在线安装都可能失败，离线环境更是难上加难。

第三，版本兼容性。Dify更新很快，插件市场的版本也在跟着变。版本不匹配时可能出现插件装上了但功能报错，或者管理后台显示异常。离线环境下你没有在线市场帮你自动匹配版本，必须自己确认Dify版本和插件版本的兼容关系。

第四，故障排查难度高。在线环境报错可以直接看日志、重新拉取，离线环境一旦某个依赖缺失，你要么在服务器上慢慢找，要么回到有网环境重新打包再传一次。一次排错往往以小时为单位。

所以离线部署的核心逻辑不是“把在线变成离线”，而是提前把整个依赖链在另外一个有网的“中转环境”里准备好，再整体搬运过去。这个思路贯穿整篇文章。

2. 动手之前，准备工作越细越省事

2.1 版本确认：先给Dify“对齐颗粒度”

不管你是已经装好Dify才意识到插件问题，还是准备从零开始部署一套离线环境，第一步永远是确认版本。版本不确认好，后面所有的下载、打包、安装都可能白做。

查看Dify版本很简单。如果是docker compose部署的，进到Dify的部署目录，直接看docker-compose.yaml里nginx镜像的tag，或者看.env里的版本信息。也可以在服务器上执行：

docker images | grep dify

镜像名称后面跟的tag就是当前版本，比如langgenius/dify-api:1.17.1。如果版本比较新，建议去官方GitHub仓库的Releases页面确认对应版本信息，并关注Release Notes里关于插件机制的变更说明，因为插件模块的接口可能在某个小版本里调整过。

为什么一定要看插件市场版本和Dify版本？因为Dify的插件系统是独立组件在支撑，叫plugin_daemon。不同版本的Dify，对插件daemon的接口协议可能不一样。就好比你手机系统升级了，旧版App可能闪退，插件也是同样的道理。官方插件市场的每个插件页面都会标注兼容的Dify版本范围，下载之前一定要跟自己的平台版本比对一下。

顺带说一句，如果你用的是Dify 1.17.1或者1.10这样的社区版，插件的安装逻辑基本一致，但个别插件可能做了版本限定。举个例子，有些插件只支持API版本大于等于某一个小版本，装旧版Dify上会直接提示“不满足要求”。所以我会先建一个简单的表格，把目标Dify版本、插件市场访问的替代方案、需要的插件清单全部列出来，之后再动手。

2.2 离线环境清单与工具准备

确认版本后，下一步是准备环境和工具。推荐的做法是准备两台环境：一台“中转机”，一台“目标机”。中转机需要有外网访问能力，用来下载插件包、拉镜像、测试打包；目标机就是最终要运行Dify的服务器，通常不能访问外网。

建议你提前准备这么几样东西：

• 一台可以正常访问插件市场的中转机（可以是你的办公电脑、一台临时云主机）
• U盘或者内网文件传输通道，用于拷贝离线包（如果目标机能通过scp访问，也可直接用scp传）
• 目标机上已经安装好Docker和Docker Compose（如果Docker本身也要离线装，建议参考Linux离线部署Redis类似的方法，提前准备好Docker rpm包以及所有依赖）
• 确认目标机的端口开放情况，Dify插件daemon可能需要额外端口通信，默认情况下跟随Dify主服务即可，但如果你单独改了配置就要注意
• Dify部署目录，尤其是docker/.env文件，这个文件后面操作频繁

这里有一个细节容易踩坑：很多人以为Dify装好了所有组件就在一个容器里，实际上Dify的docker compose会启动nginx、api、worker、web、plugin_daemon、db、redis、sandbox等多个服务。插件相关的服务主要是plugin_daemon，这个名字你后面查日志一定会用到。

2.3 Docker镜像与离线包的前置处理

离线部署大多数坑不在插件本身，而在镜像。Dify插件在某些情况下需要额外镜像，比如插件使用了特定的运行时环境。另外Dify平台首次部署时本身就需要从镜像仓库拉取多个镜像，如果目标机完全离线，这一步就得提前处理。

中转机上执行镜像导出，命令很简单：

docker save -o dify-image-list.tar 镜像1:tag 镜像2:tag

在目标机上再执行导入：

docker load -i dify-image-list.tar

如果你的部署环境根本没有外网，目标机连镜像仓库都访问不了，那Dify基础镜像就一定得在这个阶段全部准备齐全。常见的做法是先把docker compose config导出的镜像列表整理出来，然后逐个docker pull，最后统一docker save。

镜像导出和插件包离线是两条线，别混在一起。插件离线走的是Dify的管理后台“导入插件”功能，镜像离线走的是Docker的save/load机制。两个都要做，但先后顺序很明确——先把Dify平台本身跑起来，再谈插件导入。如果平台镜像都还没就绪，插件装上去也没有运行的土壤。

还有一个容易被忽略的资源：插件依赖的Python包。插件如果在安装阶段需要安装Python依赖，目标机的pip源如果不可用，你就需要在中转机上把依赖包全部下载成whl文件，再拷贝过去。这块后面第4章我会展开讲。

3. 插件离线包从哪里来：三种获取方式对比

3.1 在线环境下提前下载插件包

第一种方式最直接：在中转机上，通过Dify管理后台或插件市场页面，把需要的插件包下载到本地。

Dify的插件打包格式是.difypkg，本质上是一个归档文件，里面包含了插件的元信息、代码和依赖声明。如果你已经在中转机上装了一个Dify实例（哪怕只是测试环境），在“插件”页面里找到目标插件，点击安装，再点击“下载”或者文件管理入口，通常就能拿到.difypkg文件。把这个文件传到目标机上，就完成了最原始的离线包准备。

但这里有个实际问题：不是每个环境都能访问插件市场。如果你在中转机上连插件市场都打不开，那就得换第二种方式。

3.2 从插件市场搭建内网源

第二种方式稍微进阶一点，适合团队规模较大、后续多人共用插件的场景。Dify插件市场本身是一个可以被代理或镜像的服务，你可以在内网搭一个轻量的插件市场镜像，把官方市场的插件元数据定期同步到内网。之后目标机上的Dify插件页面直接指向内网源地址，团队里的所有环境都能从内网源安装，不需要每台机器手动导入。

搭内网源的方式并不复杂，本质上是一个HTTP服务，将官方插件市场的响应结果缓存下来。你可以用Nginx来做反向代理，将marketplace.xxx的请求代理到官方市场，并配置缓存。这样内网Dify请求插件市场时，走的是内网Nginx，命中缓存就直接返回，不再需要出网。

这个方案的优点是可以保留“在线安装”的体验，缺点是你需要维护一条中转机到内网的同步流程，并且缓存策略要调好，否则插件更新后内网还是旧版本。如果你只是自己一次性部署，不建议上来就搭市场源，先考虑直接下载.difypkg文件，工作量和维护成本都低得多。

3.3 手动打包与源码构建

第三种方式适合官方市场里找不到、或者需要自定义修改的插件。Dify插件可以用Python编写，插件结构里有provider.yaml或类似元数据文件。如果你基于GitHub上的开源插件代码做二次开发，需要自己打包成.difypkg文件。

手动打包不建议手搓压缩包，最好使用Dify官方提供的插件开发工具链。它能在本地对插件代码进行校验、打包，校验通过后生成规范的.difypkg文件。打包前说明一个关键操作：在插件目录里执行打包命令，而不是把整个文件夹压缩。直接右键压缩成zip再改后缀，会丢失元数据格式，导入时大概率失败，这个问题很多人踩过。

如果你需要修改插件源码后才能适配离线环境，比如把某个插件的API地址改成内网地址，把内置的模型配置改成私有化地址，那么源码构建就更重要了。打包前把配置文件改好，再进入Dify后台导入，省去安装后的二次修改。

3.4 三种方式的取舍建议

我个人其实建议先做第一和第三种：日常安装用官方下载好的.difypkg，如果插件需要改内部配置，直接源码打包。内网插件市场镜像是团队规范化之后才值得投入的选项，个人交付场景没必要一上来就上这套。

4. 完整安装流程：从离线包到插件上线的实操记录

4.1 上传插件包到服务器与基础检查

拿到.difypkg文件后，第一步是把文件传到目标服务器。最简单的办法是scp：

scp /path/to/your-plugin.difypkg user@target-server:/tmp/

文件传到服务器后，不要急着导入。先做两个检查：第一，确认Dify服务运行正常，尤其是plugin_daemon容器它不能是退出状态；第二，查询插件文件大小，如果文件只有几KB，大概率是下载时错误或者包不完整。

对Dify服务状态的检查命令：

docker compose ps

正常状态应该是所有容器都是Up，其中plugin_daemon这一行状态不能是Exit。如果你发现plugin_daemon没有起来，先去查看日志再做插件导入。插件daemon没起来，导入操作基本都会失败，这是离线安装中一个非常常见的“先决条件问题”。

4.2 在Dify管理后台安装插件

打开Dify的管理后台，进入“插件”页面。如果当前环境能正常访问一个在线插件市场，你会看到市场列表；如果你用的是完整离线环境，市场可能显示为空，但页面右侧或顶部一般会有一个“导入插件”或“本地安装”的入口。

点击导入，选择刚才上传到服务器上的.difypkg文件，也可以直接在网页端选择本地文件进行上传。上传后系统会解析插件包，等待几秒到几十秒不等。期间可以观察页面的状态变化，如果长时间卡住不动，说明后台可能正在处理依赖。

导入成功后，插件会出现在“已安装插件”列表里。这个时候还不算完，很多插件需要激活和配置才能生效。比如模型类的插件需要配置API地址和密钥，工具类的插件可能需要设置权限范围。

一个值得注意的细节：如果是docker compose部署的Dify，插件导入后，web和api之间会有一定的同步延迟，页面刷新后可能才显示最新状态。这是正常的，不用反复点击导入按钮，避免重复安装。

4.3 插件配置与凭证填写

插件列表里点击对应插件，通常会看到配置页面。以模型供应商插件为例，常见配置项包括Base URL、API Key、模型名称等。离线环境下，Base URL往往指向内网的大模型服务地址，比如：

http://192.168.1.10:11434

填写完后记得点击保存，并做一次连接测试。连接测试是验证配置对错最直接的手段，如果测试返回异常，先看日志再修改配置，不要反复保存。

很多人的授权文件密钥填错了位置，导致插件一直提示鉴权失败。我建议你填写前先看清楚字段含义，第三方模型的API地址跟本地大模型服务的地址格式不一样，别照着在线文档的无脑填。

4.4 验证插件是否正常工作

配置完成后，在Dify内新建一个简单的应用或者工作流，把插件对应的节点拖进来，跑一次测试。这是最直观的验证方式。比如你装了一个文本摘要插件，就新建工作流，输入一段长文本，看插件是否正常输出了摘要。

如果在工作流中找不到刚安装的插件节点，检查两件事：一是插件是否已经激活，二是该插件在Dify里的类型是否与当前应用匹配。不同插件类型出现在不同入口，你装了一个模型供应商插件，它只出现在模型选择列表里，不会出现在工具节点列表中。

验证通过的插件，建议再重启一下plugin_daemon容器，确认重启后插件依然正常加载：

docker compose restart plugin_daemon

重启后再次打开Dify的插件页面确认插件列表非空、状态正常。这一步可以提前暴露出“插件依赖了某个容器内不存在的资源”这类环境型问题。

5. 安装完不等于结束：验证、调试与日常维护

5.1 日志怎么看

离线环境下，插件安装失败、运行异常，第一手的排查资料就是日志。插件的运行日志主要看plugin_daemon容器：

docker logs -f docker_plugin_daemon_1

如果你不确定容器名，先docker compose ps确认。看日志的时候重点关注几个关键词：error、exception、dependency、failed、timeout。如果是依赖缺失，日志里通常会直接提示缺少某个Python包；如果是网络问题，日志会提示连接某个地址超时。

日志排查时要注意时间线：先看插件导入时刻的前后日志，再看实际调用插件时的日志。很多时候，导入成功的插件运行不起来，问题并不在导入环节，而在于运行时依赖和网络策略。比如插件要访问某个外部API，而你的目标机无法访问该地址，就会出现“装好了但一调用就报错”的现象。

5.2 插件更新与回滚

在线环境里，插件更新很方便，点一下按钮就行。离线环境的插件更新则是“再次导入新版本插件包”。导入新版本时，老版本一般会被覆盖或标记为停用。如果你对当前版本不放心，更新前先记录当前版本号和配置信息，最好把配置文件导出一份。

回滚就更麻烦。插件更新后如果有问题，你可以再手动导入旧版本.difypkg文件。所以离线环境维护插件的要点是“存旧档”：每次升级前，把旧版本包和配置备份保留在一个专门目录里，命名格式建议是插件名-版本号-日期，这样回滚时才不用到处找。

镜像升级也是类似逻辑。Dify平台升级前用docker compose pull拉取新镜像，但离线环境没有外网，你只能在中转机上pull然后save，再拿到目标机load。这个流程要跟插件更新的时间窗口对齐，避免平台升级后插件不兼容。

5.3 多租户与多人团队的插件管理

如果你的Dify开启了多租户模式，插件管理会多一层复杂度。部分插件是全局共用的，部分插件可能需要每个租户单独授权或者单独配置。离线部署时，建议先在管理员账号下把公共插件配置好，再让各租户去关联使用，减少不同租户之间的配置冲突。

另外，如果团队里有多个Dify环境，可以统一用一个内网文件服务器存.difypkg包，所有环境导入同一个文件，避免每台机器各自下载、版本漂移。这个文件服务器可以跟公司内部的软件仓库共用，顺手定一个目录规范，比如/data/dify-plugins。

6. 常见问题与排查技巧实录

6.1 问题速查表

整理一份我实际踩过和帮人排查过的问题列表。

这张表你可以直接存下来，遇到问题时对号入座。

6.2 镜像拉取失败时的兜底方案

离线部署中最常听到的报错就是“拉取镜像失败”。不管是Dify本身还是插件依赖的镜像，一旦目标机没有外网，Docker默认去Docker Hub拉镜像就会失败。兜底方案只有一个：提前在能联网的中转机上拉取好，再导出上传。

具体方法我在2.3节提过，这里再补充一个细节：docker save打包时，最好把镜像的完整名称和tag写清楚，避免在目标机上load后出现<none>这种悬空镜像。保存时统一用：

docker save -o images-dify.tar langgenius/dify-api:1.17.1 langgenius/dify-web:1.17.1

到目标机上执行：

docker load -i images-dify.tar docker images

确认所有镜像的REPOSITORY和TAG都正常后再启动服务。镜像这一关过了，才能继续玩插件那一关。另外，Docker容器运行后还会需要一些依赖镜像，建议你先在中转机上完整跑一遍Dify部署，然后docker compose images导出现有镜像列表，再统一save，这样不会漏。

6.3 插件反复安装失败的深层原因

如果插件导入总失败，先别着急怀疑Dify坏了，百分之七八十是下面这几个原因。

第一个是插件包来源不正规。有些人从网上下了一个所谓“破解版”或第三方渠道的插件包，格式可能被改过，导入时校验必然失败。插件尽量从官方市场或官方开源仓库下载，别为了省事去乱找渠道，不仅装不上，还有安全风险。

第二个是依赖网络源。插件安装后需要从公网pip源下载依赖，但目标机无法访问，这时候即使导入成功，后台记录里也会出现安装失败。解决思路是在中转机上用pip下载所有依赖为whl文件，然后拷贝到目标机执行离线安装。Dify插件用到的Python依赖一般集中在requirements.txt里，可以这样准备离线whl：

pip download -r requirements.txt -d ./pip-offline-packages

之后在内网目标机上用：

pip install --no-index --find-links=./pip-offline-packages -r requirements.txt

第三个是权限问题。刚才说的whl安装，在实际执行时可能要写入系统目录，如果你用的是非root执行，加上--user参数或者把安装目录指定到一个可写权限的虚拟环境里。

第四个是版本兼容。这一条最隐蔽，用户导入了一个看起来完全正常的插件包，但因为平台版本太老或太新，插件接口对不上。解决思路是去插件的说明页面看兼容性说明，选择与当前Dify版本严格匹配的插件版本。

6.4 一个隐形坑：插件配置中的域名解析

离线环境往往内网DNS不完整，插件配置里如果直接填了外网域名，运行时会因为域名解析失败而报错。一个典型的场景是模型服务的Base URL用了云服务商域名，内网根本解析不了。

解决办法很简单，把所有外网域名改成对应的内网IP，或者在内网DNS服务器上添加解析记录。改完之后不要只保存，一定要重启插件或重启plugin_daemon，让配置真正生效。这个问题我替客户排查过一整天才定位到，因为日志里只显示“connect failed”，完全没有提示是DNS问题。

最后的实操心得

写了这么多，最后还是想分享一点个人经验。离线部署Dify插件，本质上是在跟“环境差异”做斗争：中转机准备好一切，目标机原样复刻，中间的每一环都得提前想清楚。我最初也走过弯路，总想着在目标机上临时解决问题，后来才意识到，离线部署最稳妥的策略是在一台干净的中转机上把Dify完整跑通、插件全部装好验证无误，再把镜像和插件包整体搬过去。这样做虽然前期多花一两个小时，但部署到目标机时基本是一遍过。

另外提醒一句，不要以为离线部署装完一次就一劳永逸。Dify版本更新、插件升级、模型服务地址变更，都会让你的离线环境需要重新准备一轮。建议你保留好中转机环境，建一个固定的目录存放所有离线包、镜像文件、依赖whl和配置文件，标注清楚版本和日期。下次再部署或者升级，直接照着清单走，一个小时就能搞定别人半天的工作量。

最后再补充一个日常实用的细节：把常用的Dify插件打包成一个“离线工具箱”，里面不仅有.difypkg，还有对应的镜像tar包、whl依赖包、配置说明文档。这样无论是交付新客户还是在旧环境上重建，都能快速恢复，也算是做私有化部署的一份底气。