Logo

菜单

于飞
发布于 2026-05-20 / 13 阅读
0
0

Dify 1.9.2 离线部署完整操作手册

#Docker#Dify#离线部署#插件开发#DevOps

本手册涵盖从有网环境准备文件、打包插件，到离线环境安装部署的全流程操作。

一、前置准备说明

适用版本：Dify 1.9.2（Linux x86_64）

核心难点：

  1. 离线机器需二进制方式安装 Docker
  2. Dify 容器镜像需提前导出
  3. 插件需离线重打包（含所有 Python 依赖）

操作分两阶段：

  • 阶段A（有网机器）：拉取 Dify 源码、导出镜像、打包插件
  • 阶段B（离线机器）：通过 U 盘拷贝文件后执行安装

二、阶段A：有网机器上准备文件

2.1 下载 Docker 二进制包

离线机器需通过二进制方式安装 Docker，因此需提前下载静态包。

访问 Docker 官方下载地址：

https://download.docker.com/linux/static/stable/x86_64/

选择最新版本下载即可，例如：

docker-26.1.4.tgz

注意：务必选择 x86_64 目录下的包，对应 64 位 PC 架构。

2.2 拉取 Dify 源码并获取镜像

# 克隆 Dify 仓库
git clone https://github.com/langgenius/dify.git
cd dify

# 切换到 1.9.2 标签
git checkout 1.9.2

cd docker

# 复制环境变量模板（必须先执行此步骤，否则部分容器可能无法启动）
cp .env.example .env

# （可选但推荐）清空本地所有 Docker 镜像，确保导出列表干净
docker rmi -f $(docker images -q) 2>/dev/null || true

# 启动 Dify，自动拉取所有镜像
docker compose up -d

# 等待所有容器运行正常后，查看完整镜像列表
docker compose images

2.3 导出所有 Dify 镜像

推荐使用脚本自动导出，避免手动输入遗漏：

# 方式一：自动获取并导出所有 Dify 相关镜像（推荐）
docker save -o dify-images-1.9.2.tar $(docker compose images -q)

# 方式二：手动列出镜像导出（作为参考）
docker save -o dify-images-1.9.2.tar \
  langgenius/dify-api:1.9.2 \
  langgenius/dify-web:1.9.2 \
  langgenius/dify-plugin-daemon:1.9.2 \
  postgres:15-alpine \
  redis:7-alpine \
  nginx:alpine \
  langgenius/dify-sandbox:latest

提示：docker compose images -q 会输出所有服务使用的镜像 ID，确保不会遗漏任何依赖镜像。

2.4 下载插件

根据目标离线环境是否有内网 PIP 源，选择不同的方式：

场景一：目标机器有内网 PIP 源（推荐）

直接从 Dify 插件市场手动下载原始插件包，无需重新打包：

  1. 访问 Dify 插件市场：https://marketplace.dify.ai/plugins
  2. 搜索所需插件（如 OpenAI API Compatible、HuggingFace TEI、Chatflow Invoker 等）
  3. 进入插件详情页后，点击 历史版本，选择指定版本下载（如 0.0.25、0.1.1、0.0.6）
  4. 将下载的 .difypkg 文件保存到 plugins/ 目录

场景二：完全离线环境（无任何网络）

若目标机器完全无网络（包括内网 PIP 源），需将插件的 Python 依赖一并打包：

# 获取重打包工具
git clone https://github.com/langgenius/dify-plugin-repackaging.git
cd dify-plugin-repackaging

# 确保 Python 版本为 3.12（与插件守护进程一致）
python3 --version  # 应输出 3.12.x

# 下载并重打包插件
./plugin_repackaging.sh market langgenius openai_api_compatible 0.0.25
./plugin_repackaging.sh market langgenius huggingface_tei 0.1.1
./plugin_repackaging.sh market yzddmr6 chatflow_invoker 0.0.6

脚本执行逻辑：

  1. 解压 .difypkg 文件（实际为 zip 格式）
  2. 执行 pip download 将所有 requirements.txt 中的依赖下载到 ./wheels/
  3. 在 requirements.txt 头部插入 --no-index --find-links=./wheels/
  4. 重新打包为 *-offline.difypkg

2.5 整理文件清单

在打包源码前，需先清理启动时生成的临时数据：

# 停止并移除容器
cd dify/docker
docker compose down -v

# 返回源码根目录
cd ..

# 删除 volumes 目录（包含容器运行时生成的数据）
rm -rf docker/volumes

# 还原代码到干净状态
git reset --hard

在 U 盘上创建以下目录结构：

U盘:/dify-offline/
├── docker-26.1.4.tgz              # Docker 二进制包
├── dify-images-1.9.2.tar           # 所有 Docker 镜像
├── dify/                           # Dify 1.9.2 源码目录（含 docker compose 配置）
│   ├── docker/
│   │   ├── docker-compose.yaml
│   │   ├── .env.example
│   │   └── ...
│   └── ...
└── plugins/                        # 插件离线包
    ├── langgenius-openai_api_compatible_0.0.25.difypkg
    ├── langgenius-huggingface_tei_0.1.1.difypkg
    └── yzddmr6-chatflow_invoker_0.0.6.difypkg

三、阶段B：离线 Linux 机器上部署

3.1 拷贝文件到目标机器

将 U 盘中的 dify-offline/ 目录拷贝到离线机器的工作目录，例如 /data/dify-offline/。

3.2 安装 Docker（离线）

cd /data/dify-offline

# 解压 Docker 二进制包
tar -xzvf docker-26.1.4.tgz

# 将 Docker 可执行文件复制到系统路径
sudo cp docker/* /usr/bin/

# 创建 Docker 服务文件
sudo tee /etc/systemd/system/docker.service <<EOF
[Unit]
Description=Docker Daemon
After=network.target

[Service]
ExecStart=/usr/bin/dockerd
Restart=always
ExecReload=/bin/kill -HUP \$MAINPID

[Install]
WantedBy=multi-user.target
EOF

# 重载 systemd 并启动 Docker
sudo systemctl daemon-reload
sudo systemctl enable docker
sudo systemctl start docker

# 验证安装
docker --version

提示：如目标机器无 systemd，可直接用 dockerd & 后台启动。

3.3 导入 Dify 镜像

docker load -i dify-images-1.9.2.tar

验证镜像是否导入成功：

docker images

3.4 配置 Dify

# 进入 Dify docker 目录
cd /data/dify-offline/dify/docker

# 复制环境变量模板
cp .env.example .env

编辑 .env 文件，配置关键参数：

# 插件签名验证（离线环境必须关闭）
FORCE_VERIFYING_SIGNATURE=false

# 插件包大小限制（部分离线包较大，建议调大）
PLUGIN_MAX_PACKAGE_SIZE=524288000

# Nginx 上传大小限制
NGINX_CLIENT_MAX_BODY_SIZE=500M

3.5 配置 PIP 源与信任主机

如果离线机器有本地 PIP 源（如企业内部 PyPI 镜像），需在 .env 中配置：

# 在 .env 中添加
PIP_MIRROR_URL=http://your-pypi-server.local/simple/

同时修改 docker-compose.yaml，在 plugin_daemon 容器下添加环境变量：

services:
  plugin_daemon:
    image: langgenius/dify-plugin-daemon:1.9.2
    environment:
      # ... 原有环境变量 ...
      PIP_EXTRA_ARGS: "--trusted-host your-pypi-server.local"

说明：PIP_MIRROR_URL 配置 PIP 源地址，PIP_EXTRA_ARGS 配置信任主机。如果打包的离线插件已完全包含所有依赖（即 -offline.difypkg），则此配置非必需。

3.6 启动 Dify

docker compose up -d

检查所有容器状态：

docker compose ps

确保所有容器处于 Up 状态。

3.7 安装插件

  1. 浏览器访问 Dify 控制台（如 http://<服务器IP>）
  2. 进入 插件管理 页面
  3. 点击 上传插件
  4. 依次选择 U 盘中的插件文件：
    • langgenius-openai_api_compatible_0.0.25.difypkg
    • langgenius-huggingface_tei_0.1.1.difypkg
    • yzddmr6-chatflow_invoker_0.0.6.difypkg
  5. 等待安装完成

若目标机器配置了内网 PIP 源，插件守护进程会通过内网下载 Python 依赖；若使用重打包的离线插件（*-offline.difypkg），则直接从包内 wheels/ 目录安装依赖。

四、验证与排错

4.1 验证 Docker 运行状态

docker ps
docker logs docker-plugin_daemon-1

4.2 验证插件安装

在 Dify 控制台的工作流中，尝试添加 OpenAI API Compatible 模型提供商，测试能否正常连接。

4.3 常见问题

问题 原因 解决
插件安装报 Signature verification failed 离线环境无法验证签名 .env 中设置 FORCE_VERIFYING_SIGNATURE=false
插件安装报 Package too large 离线包体积超过默认限制 调大 PLUGIN_MAX_PACKAGE_SIZE 和 NGINX_CLIENT_MAX_BODY_SIZE
插件守护进程报依赖安装失败 pip 无法联网下载依赖或 SSL 报错 确认使用的是 -offline.difypkg 版本；或配置 .env 中的 PIP_MIRROR_URL 指向本地 pip 源；SSL 报错需在 docker-compose.yaml 中配置 PIP_EXTRA_ARGS: "--trusted-host your-pypi-server.local"
解决 Zsh 中 docker c...

评论