当前位置：首页 > article >正文

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

article 2025/8/26 10:18:42

一、准备工作

准备一台能访问互联网的外网机器
- 用于拉取最新的 Dify 镜像和代码
- 建议使用 Linux 或 Windows + Docker 环境
准备传输介质
- U盘、移动硬盘，或企业内部网络共享路径
确认当前内网 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 等方式，依据实际部署方式

四、升级后验证

检查容器状态

docker ps
docker logs <container_name>

访问前端页面，确认版本号和功能正常
检查数据库是否正常连接，日志无异常

五、常见问题及排查建议

问题描述	可能原因	解决方案
容器无法启动	镜像未正确加载，或代码版本不匹配	确认镜像导入成功，确认代码版本一致
配置文件丢失或异常	代码覆盖时误删自定义配置	恢复 `.env` 等配置文件
数据库连接失败	数据库未启动或配置错误	检查数据库服务和网络配置
镜像导入报错	镜像文件损坏或不完整	重新导出和传输镜像文件
升级后功能异常	版本间不兼容，需参考升级文档或迁移步骤	检查升级文档，执行数据迁移脚本（如果有）

六、附录

镜像导出与导入示例脚本

# 外网机器导出所有镜像
for image in langgenius/dify-api:1.4.0 langgenius/dify-web:1.4.0 langgenius/dify-plugin-daemon:0.0.10-local; dodocker 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; dodocker 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.FullNameif ($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

使用说明

准备好离线升级包
- 镜像文件 .tar 放到同一个文件夹，比如 images
- 代码包压缩文件，例如 dify-code.zip
修改脚本参数
- $ImageDir 指向镜像目录
- $CodeZipPath 指向代码包压缩文件
- $DifyRootDir 指向你的 Dify 项目根目录（docker-compose 文件所在目录）
- $DockerComposeFile 一般是 docker-compose.yaml 或 docker-compose.yml
运行脚本
- 以管理员身份打开 PowerShell
- 执行 .\dify-offline-update.ps1 （假设你保存为该文件名）