1. 项目背景与核心需求

在企业级开发环境中，Dify作为一款新兴的AI应用开发平台，其插件生态正在快速扩展。但在金融、政务等安全敏感领域，开发机器往往处于纯内网隔离环境，无法直接访问外网资源。这就导致了一个典型矛盾：一方面需要利用Dify插件扩展功能，另一方面又受制于网络隔离政策无法在线安装。

我最近在某银行项目中就遇到了这个棘手问题。他们的开发服务器完全断网，但业务部门急需使用Markdown导出插件生成合规文档。经过两周的实践探索，最终形成了一套可靠的离线安装方案，这里把完整实施过程和技术要点分享给大家。

2. 离线安装方案设计

2.1 技术路线选择

离线安装的核心在于解决依赖传递问题。与常规Python包不同，Dify插件存在三个特殊依赖层级：

1. 运行时依赖：插件声明的requirements.txt
2. 构建依赖：setup.py中定义的build_requires
3. 系统依赖：编译所需的lib库（如libncurses）

经过对比测试，我们采用"预下载+本地构建"的混合方案：

• 对纯Python包直接下载whl文件
• 对含C扩展的包下载源码并在内网构建
• 对系统依赖通过容器化解决

2.2 工具链准备

需要在内网预置以下工具：

# 基础工具 sudo apt install -y unzip build-essential python3-dev # Python环境 python -m pip install --upgrade pip wheel setuptools # 容器运行时（可选） curl -fsSL https://get.docker.com | sh

注意：建议使用相同架构的跳板机准备资源，避免x86/ARM混用导致兼容性问题

3. 详细实施步骤

3.1 插件包获取与解压

从有网环境下载插件包（以markdown-exporter为例）：

wget https://marketplace.dify.ai/api/v1/plugins/bowenliang123/md_exporter/3.2.0/download -O md_exporter.difypkg

解压后目录结构应为：

md_exporter/ ├── MANIFEST.in ├── README.md ├── requirements.txt └── src/

3.2 依赖收集与处理

关键步骤在于正确处理三类依赖：

3.2.1 基础依赖下载

pip download \ -r requirements.txt \ -d ./wheels \ --platform manylinux2014_x86_64 \ --only-binary=:all: \ --python-version 38

3.2.2 源码包构建

对于无法直接下载whl的包：

find ./wheels -name '*.tar.gz' | while read sdist; do pip wheel --no-deps -w ./wheels "$sdist" rm "$sdist" done

3.2.3 依赖声明修改

在requirements.txt首行添加：

--no-index --find-links=./wheels

3.3 离线包重构

使用Dify官方打包工具重新封装：

dify-plugin-linux-amd64 plugin package ./md_exporter \ -o ./md_exporter-offline.difypkg \ --max-size 5120

4. 常见问题解决方案

4.1 依赖解析失败

典型报错：

× Failed to build `odfpy==1.4.1` ├─▶ No solution found when resolving: `setuptools>=40.8.0`

解决方案：

1. 提前下载setuptools的whl文件
2. 在脚本中添加强制下载逻辑：

pip download setuptools>=40.8.0 -d ./wheels

4.2 系统库缺失

错误示例：

libncurses.so.5: cannot open shared object file

解决方法：

# 统信UOS等国产系统需额外安装 sudo apt install libncurses5 libtinfo5

4.3 平台兼容性问题

对于ARM架构服务器，需要指定对应平台：

pip download --platform manylinux2014_aarch64 ...

5. 进阶技巧与优化

5.1 依赖缓存池建设

建议在内网搭建PyPI镜像：

# 使用devpi搭建私有仓库 pip install devpi-server devpi-init --serverdir /data/devpi devpi-server --start --serverdir /data/devpi

5.2 容器化部署方案

编写Dockerfile实现环境隔离：

FROM python:3.8-slim COPY wheels /wheels RUN pip install --no-index --find-links=/wheels -r requirements.txt ENTRYPOINT ["dify-plugin"]

5.3 自动化脚本优化

改进后的打包脚本应包含以下功能：

1. 自动检测系统架构
2. 依赖树完整性校验
3. 构建缓存机制

示例代码片段：

def check_dependency_complete(requirements): downloaded = {pkg.name for pkg in Path('wheels').glob('*.whl')} required = {parse_requirement(req).name for req in requirements} return downloaded.issuperset(required)

6. 安全注意事项

1. 完整性校验：所有下载的whl文件需验证hash值

   sha256sum *.whl > checksums.txt

2. 权限控制：插件安装目录应限制为：

   chown -R dify:dify /opt/dify/plugins chmod 750 /opt/dify/plugins

3. 审计日志：记录所有安装操作

   auditctl -w /opt/dify/plugins -p wa -k dify_plugins

经过多个金融项目的实践验证，这套方案能稳定支持90%以上的Dify插件离线部署。最关键的是要建立完整的依赖管理流程，建议企业可以在此基础上开发内部插件市场，实现更规范的资产管理。