Dify 离线升级操作手册（适用于无外网企业内网环境）

一、准备工作

1. 准备一台能访问互联网的外网机器

   • 用于拉取最新的 Dify 镜像和代码
   • 建议使用 Linux 或 Windows + Docker 环境

2. 准备传输介质

   • U盘、移动硬盘，或企业内部网络共享路径

3. 确认当前内网 Dify 版本和配置

   • 确认版本号，备份配置文件和数据库

二、外网机器操作步骤

1. 拉取最新镜像

docker pull langgenius/dify-api:1.4.0
docker pull langgenius/dify-web:1.4.0
docker pull langgenius/dify-plugin-daemon:0.0.10-local
# 视实际情况拉取其他相关镜像

2. 导出镜像为文件

docker save langgenius/dify-api:1.4.0 -o dify-api_1.4.0.tar
docker save langgenius/dify-web:1.4.0 -o dify-web_1.4.0.tar
docker save langgenius/dify-plugin-daemon:0.0.10-local -o dify-plugin-daemon_0.0.10.tar
# 其他镜像同理

3. 下载对应版本的 Dify 代码包

• 从官方 GitHub release 页面下载对应版本的代码压缩包（zip/tar.gz）

4. 将镜像文件和代码包拷贝到传输介质

三、内网机器操作步骤

1. 备份当前环境（强烈建议）

• 备份数据库（PostgreSQL、Redis 等）
• 备份挂载的持久化数据目录
• 备份现有代码和配置文件

2. 导入镜像

docker load -i /path/to/dify-api_1.4.0.tar
docker load -i /path/to/dify-web_1.4.0.tar
docker load -i /path/to/dify-plugin-daemon_0.0.10.tar
# 其他镜像同理

3. 替换代码文件

• 解压代码包到指定目录，覆盖旧代码
• 注意保留 .env 或配置文件中的自定义配置

4. 重启 Docker 容器

• 停止当前 Dify 服务容器

docker-compose down

• 启动新版本容器

docker-compose up -d

• 或使用 docker stack deploy 等方式，依据实际部署方式

四、升级后验证

1. 检查容器状态

docker ps
docker logs <container_name>

2. 访问前端页面，确认版本号和功能正常

3. 检查数据库是否正常连接，日志无异常

五、常见问题及排查建议

六、附录

• 镜像导出与导入示例脚本

# 外网机器导出所有镜像
for image in langgenius/dify-api:1.4.0 langgenius/dify-web:1.4.0 langgenius/dify-plugin-daemon:0.0.10-local; do
  docker save $image -o ${image//[:\/]/_}.tar
done

# 内网机器导入所有镜像
for file in dify-api_1.4.0.tar dify-web_1.4.0.tar dify-plugin-daemon_0.0.10-local.tar; do
  docker load -i $file
done

• 代码覆盖示例

unzip dify-code-v1.4.0.zip -d /opt/dify/
# 保留/opt/dify/.env 文件

七、离线升级PowerShell 脚本示例

下面是一个Dify 离线升级专用的批处理脚本（Windows PowerShell 版），适合内网环境使用，自动完成镜像导入、代码解压覆盖、服务重启等核心步骤。

# Dify离线升级脚本（PowerShell版）

param(
  [string]$ImageDir = ".\images",            # 镜像文件存放目录
  [string]$CodeZipPath = ".\dify-code.zip",  # 代码压缩包路径
  [string]$DifyRootDir = "D:\AI\dify-main",  # Dify代码根目录（需替换为你的路径）
  [string]$DockerComposeFile = "docker-compose.yaml" # docker-compose 文件名（相对DifyRootDir）
)

Write-Host "=== Dify 离线升级开始 ===" -ForegroundColor Cyan

# 1. 导入镜像
Write-Host "Step 1: 导入 Docker 镜像..."
$tarFiles = Get-ChildItem -Path $ImageDir -Filter *.tar -ErrorAction Stop
foreach ($tar in $tarFiles) {
  Write-Host "导入镜像文件: $($tar.FullName)"
  docker load -i $tar.FullName
  if ($LASTEXITCODE -ne 0) {
    Write-Error "镜像导入失败: $($tar.Name)，请检查文件完整性！"
    exit 1
  }
}
Write-Host "镜像导入完成！" -ForegroundColor Green

# 2. 备份旧代码（可选）
$backupDir = Join-Path $DifyRootDir "backup_$(Get-Date -Format 'yyyyMMdd_HHmmss')"
Write-Host "Step 2: 备份旧代码到 $backupDir ..."
if (-Not (Test-Path $backupDir)) {
  New-Item -ItemType Directory -Path $backupDir | Out-Null
}
Copy-Item -Path "$DifyRootDir\*" -Destination $backupDir -Recurse -Force
Write-Host "备份完成！" -ForegroundColor Green

# 3. 解压新代码覆盖
Write-Host "Step 3: 解压新代码包并覆盖..."
if (-Not (Test-Path $CodeZipPath)) {
  Write-Error "代码压缩包不存在: $CodeZipPath"
  exit 1
}
Add-Type -AssemblyName System.IO.Compression.FileSystem
[System.IO.Compression.ZipFile]::ExtractToDirectory($CodeZipPath, $DifyRootDir, $true)
Write-Host "代码解压完成！" -ForegroundColor Green

# 4. 重启服务
Write-Host "Step 4: 重启 Dify 服务..."
Set-Location $DifyRootDir

# 停止旧容器
Write-Host "停止旧容器..."
docker-compose -f $DockerComposeFile down
if ($LASTEXITCODE -ne 0) {
  Write-Warning "docker-compose down 失败，检查 Docker 状态。"
}

# 启动新容器
Write-Host "启动新容器..."
docker-compose -f $DockerComposeFile up -d
if ($LASTEXITCODE -ne 0) {
  Write-Error "docker-compose up 启动失败！"
  exit 1
}

Write-Host "Dify 离线升级完成！" -ForegroundColor Cyan

使用说明

1. 准备好离线升级包

   • 镜像文件 .tar 放到同一个文件夹，比如 images
   • 代码包压缩文件，例如 dify-code.zip

2. 修改脚本参数

   • $ImageDir 指向镜像目录
   • $CodeZipPath 指向代码包压缩文件
   • $DifyRootDir 指向你的 Dify 项目根目录（docker-compose 文件所在目录）
   • $DockerComposeFile 一般是 docker-compose.yaml 或 docker-compose.yml

3. 运行脚本

   • 以管理员身份打开 PowerShell
   • 执行 .\dify-offline-update.ps1 （假设你保存为该文件名）

备注

• 该脚本会自动备份当前代码目录，避免误覆盖
• 适配了 Windows PowerShell 环境，如需 Linux shell 版本可以参照以上脚本修改对应命令。
• 确保 Docker 服务正常运行且已登录，无需外网访问