容器化部署服务升级实战：从旧版本平稳迁移到新架构

在AI应用平台的日常运维中，版本升级是绕不开的环节。尤其是当平台从较早的版本跃迁至全新大版本时，底层架构、数据存储方式、插件体系往往发生根本性变化，升级不再是简单的“替换镜像”可以搞定。本文将以一套典型的容器编排部署环境为例，详细拆解从旧版本升级至新版本的完整流程，并重点攻克数据迁移这一核心难题。无论你是在本地开发环境还是测试环境中操作，这套方法论都具有普适参考价值。

一、升级前的认知准备

在动手之前，我们需要明确几个前提：

• 部署方式：采用容器编排工具进行多容器管理，各服务以独立容器形式运行。
• 版本跨度：从较早期版本升级至架构有较大调整的新版本，插件系统、数据卷挂载方式可能发生变化。
• 核心风险：数据丢失、工作流消失、插件环境不兼容。

理解这些背景后，我们按照“先备份、再替换、后迁移”的思路逐步推进。

二、第一步：全面备份——最朴素也最有效

任何升级操作的第一要务都是备份。对于容器编排部署而言，最直接的备份方式就是将整个安装目录完整复制一份。

假设你的项目根目录为 ~/dify-deploy（此处仅为示例路径），直接执行：

cp -r ~/dify-deploy ~/dify-deploy-backup-0.15.3

这种“简单粗暴”的方式看似笨拙，实则最为可靠。它保留了旧版本的所有配置文件、数据卷、环境变量、日志等，一旦升级过程中出现不可逆错误，可以在几分钟内回滚到升级前的状态。

建议：备份完成后，确认备份目录中的 docker/volumes 子目录存在且数据完整，这是后续数据恢复的关键。

三、第二步：获取新版本源码并替换

从官方渠道获取新版本的源码包后，将其中的所有文件直接拷贝并覆盖到旧版本的安装目录中。

# 假设新版本源码解压至 ~/dify-new
cp -rf ~/dify-new/* ~/dify-deploy/

这里需要注意：

• 覆盖操作会替换掉旧的编排文件、环境变量模板等，但不会自动删除旧的数据卷目录（volumes）。
• 如果新旧版本的目录结构有差异，建议先对比两版的 docker-compose.yaml，了解服务定义的变化。

四、第三步：拉取新版本镜像

在拉取镜像前，建议先停止当前运行的容器编排服务，避免新旧镜像混用导致异常：

cd ~/dify-deploy/docker
docker compose down

随后拉取新版本所需的三个核心镜像（以下为通用示意，具体镜像名称以实际项目为准）：

docker pull <web镜像>:1.0.0
docker pull <api镜像>:1.0.0
docker pull <插件守护进程镜像>:0.0.3-local

其中，插件守护进程镜像尤其重要——新版本通常将插件体系独立为单独的服务容器，负责管理模型供应商和工具插件的生命周期。

五、第四步：启动新版本服务

镜像拉取完成后，进入编排目录启动所有服务：

cd ~/dify-deploy/docker
docker compose -f docker-compose.yaml up -d

通过 docker ps 确认各容器状态均为 Up，然后打开浏览器访问本地服务地址（如 http://localhost/apps），验证基本登录功能是否正常。

六、第五步：数据迁移——真正的重头戏

如果此时你能成功登录，但发现之前的工作流、应用配置全部消失，不必惊慌——这是因为新版本使用了全新的数据卷或数据库初始化逻辑。接下来才是升级的核心环节。

6.1 恢复历史数据卷

将备份的旧版本中 docker/volumes 目录下的全部内容，拷贝到新版本的对应目录中：

cp -r ~/dify-deploy-backup-0.15.3/docker/volumes/* ~/dify-deploy/docker/volumes/

随后重启容器编排服务：

docker compose -f docker-compose.yaml restart

再次访问应用页面，之前的工作流和应用应当已经恢复。

6.2 插件数据迁移——模型与工具的自动提取与安装

新版本引入了独立的插件体系，旧版本中内置的模型供应商和工具需要被“提取”并“重新安装”到新的插件环境中。这一过程分为两个阶段：

阶段一：提取旧环境中的插件信息

1. 找到API容器ID：

   docker ps

   在输出中找到负责API服务的容器ID（通常为 docker-api-1 或类似名称）。

2. 进入容器终端：

   docker exec -it <容器ID> bash

3. 执行插件提取命令：

   poetry run flask extract-plugins --workers=20

   • --workers=20 表示使用20个并行进程加速提取，可根据机器性能调整。
   • 该命令会扫描当前环境中所有工作区使用的模型和工具，生成 plugins.jsonl 文件，其中包含插件的完整信息。

   注意：此步骤需要容器能够访问公网，特别是插件市场的域名，否则提取过程可能因无法校验插件信息而失败。

阶段二：在新环境中安装插件

在同一个API容器内，继续执行：

poetry run flask install-plugins --workers=2

• --workers=2 表示使用2个并行进程进行安装，避免对容器资源造成过大压力。
• 该命令会读取 plugins.jsonl 中的插件列表，逐一从插件市场下载并安装到新版本的插件守护进程中。

安装完成后，刷新应用页面，进入模型供应商设置和工具管理界面，确认之前的模型配置和工具均已就位。

七、验证与收尾

升级完成后，建议进行以下验证：

1. 功能验证：创建新工作流，调用原有模型和工具，确认运行正常。
2. 数据一致性：检查历史应用、对话记录、知识库是否完整。

3. 日志检查：查看各容器日志，排除潜在报错：

   docker compose logs -f --tail=100

4. 回滚预案：如果发现严重问题，可停止新版本容器，将备份目录恢复为工作目录，重新启动旧版本。

八、经验总结与最佳实践

• 备份先行：永远不要在没有备份的情况下执行升级。
• 理解架构变化：大版本升级往往伴随数据模型、插件体系的调整，提前阅读发布说明可少走弯路。
• 分步验证：每完成一个步骤就验证一次，便于快速定位问题。
• 网络保障：插件提取与安装依赖公网访问，确保容器网络策略允许访问插件市场。
• 资源预留：提取和安装插件时并行度较高，建议在低峰期操作，避免影响线上业务。

通过以上八个环节的系统操作，你可以将旧版本的容器化部署平稳迁移至新版本，既保留了历史数据，又享受到了新架构带来的插件化扩展能力。升级不是终点，而是更稳定、更灵活运维的新起点。