适用场景

• 产品：ZCF
• 组件：ZStack Cloud
• Cloud 版本：4.8.x 升级至 5.5.x
• 操作系统：h84r
• 部署形态：双管理节点
• 触发条件：需要把双管理平台升级到 5.5.x，并同步升级 qemu/libvirt 到 LTS 版本。

问题现象

• 当前平台版本为 4.8.x，已非 LTS。
• 需要升级到 5.5.x。
• 升级不仅包括平台主控，还包括 qemu、libvirt 组件。
• 还列出了 experimental repo、userspace-rcu 残留和 virtio-vga 等专项兼容风险。

判断方法

1. 升级前先执行自检并检查 check.log。
2. 升级后先重连一台非核心业务物理机做灰度验收。
3. 组件升级前先确认是否命中专项兼容场景。

原因说明

该升级是完整的双管理灰度升级，并且组件升级部分不只是常规 qemu/libvirt 提升，还要兼顾历史 experimental repo、特定包残留和迁移模块缺失等复杂兼容性，因此必须分阶段推进并逐步放量。

解决方案

1. 升级前准备

• 风险等级：高
• 仅适用于 x86 + h84r 环境。
• 先关闭全局高可用。
• 申请 1 台非核心业务物理机作为灰度重连验证对象。
• 停止所有备份任务。

2. 环境预处理
3. 运行升级自检：

   tar -zxvf zstack-upgrade-check-master.tar.gz
   cd zstack-upgrade-check-master && bash exec_tool.sh -p <管理节点管理员密码>
   cat ./log/check.log

• 预期结果：确认升级环境无阻断项。

2. 调整数据库超时：

   wait_timeout=28800
   interactive_timeout=28800

然后执行：

   systemctl restart mariadb.service

• 预期结果：减少升级中数据库超时风险。

3. 修改全局配置：

   UpdateGlobalConfig category=storageDevice name=enable.multipath value=ignore
   UpdateGlobalConfig category=applianceVm name=connect.timeout value=1200
   UpdateGlobalConfig name=update.os.parallelismDegree category=cluster value=5 或者 10
   UpdateGlobalConfig name=update.os.parallelismDegree category=host value=10

• 预期结果：升级和重连参数准备完成。

4. 备份双管理数据库：

   zstack-ctl dump_mysql --file-name zstack-baskup-master-20260122
   zstack-ctl dump_mysql --file-name zstack-backup-slave-20260122

• 预期结果：具备平台回退基础。

3. 平台灰度升级到 5.5.x
4. 双管理节点更新源：

   bash zstack-upgrade -r ZStack-Cloud-x86_64-DVD-5.3.42-h84r.iso

• 预期结果：升级源切换完成。

2. 查询 VIP 所在节点：

   zsha2 status

• 预期结果：明确 HA 升级执行节点。

3. 解压 HA 包并赋权：

   tar zxvf ZStack-Multinode-HA-Suite.tar.gz
   chmod +x zsha2 zstack-hamon

• 预期结果：HA 工具准备完成。

4. 两个管理节点停止 MN 服务：

   zsha2 stop-node

• 预期结果：节点进入升级状态。

5. VIP 节点执行：

   ./zsha2 upgrade-ha -gencfg=true

• 预期结果：HA 套件升级成功。

6. 执行平台灰度升级：

   zsha2 upgrade-mn -grayscale -yes -db-root-pw <数据库_root_密码> -peerpass <对端数据库_root_密码> ZStack-Cloud-installer-5.5.0.bin

• 预期结果：平台升级到 5.5.x。

7. 升级完成后检查：

   zstack-ctl status
   zsha2 status

• 预期结果：管理服务与 HA 正常。

4. 灰度验收
5. 登录 UI 检查物理机、主存储、镜像服务器等状态为“已连接”。

• 预期结果：管控面资源正常。

2. 先手动重连一台非核心业务主机。

• 预期结果：该主机升级状态变为“已升级”。

3. 检查：

   zstack-cli QueryAgentVersion

• 预期结果：agent 版本记录正确。

4. 根据存储类型检查：

• SharedBlock：vgs、lsblk、multipath -ll、I/O 错误日志
• Ceph：ceph -s
• 本地存储：xfs、盘符和路径相关日志
• 云主机：控制台 ping 检查网络
• 预期结果：业务与存储状态正常。

5. 无异常后，依次重连其他物理机。
6. 全局升级完成后关闭灰度开关：

   QueryGlobalConfig category=upgradeControl name=grayscaleUpgrade
   UpdateGlobalConfig name=grayscaleUpgrade category=upgradeControl value=false

7. 开启全局高可用。

• 预期结果：平台升级阶段收口完成。

5. 分阶段升级 qemu / libvirt
6. 登录 zstack-cli，先开启灰度变量：

   QueryGlobalConfig category=upgradeControl name=grayscaleUpgrade
   UpdateGlobalConfig name=grayscaleUpgrade category=upgradeControl value=true

• 预期结果：组件灰度升级开关开启。

2. 单台先升级：

• qemu-storage-daemon
• qemu-kvm
• libvirt
• glib2
• 预期结果：先在单主机完成验证。

3. 验证无异常后关闭灰度变量，并进行集群升级。

• 预期结果：组件批量升级启动。

4. 使用：

   QueryLongJob uuid=<job_uuid>

观察升级进度。

5. 批量检查版本：

• rpm -q qemu-kvm libvirt glib2 的批量 ssh 检查方式。
• 预期结果：主机侧版本一致。

6. qemu 升级完成后通过热迁移或重启让云主机生效新版本，并用：

   virsh qemu-monitor-command $VMuuid --hmp info version

检查实际版本。

• 预期结果：VM 使用新的 QEMU 版本。

6. 特殊兼容事项
7. 若环境曾通过 experimental 源升级，需重新启用：

   UpdateGlobalConfig name="zstack.experimental.repo" value=true category=cluster

2. 若环境使用 ZCE-X 5.2.x，需确认 userspace-rcu / userspace-rcu-devel 是否已完整卸载，避免依赖切换异常。

3. 若 ARM 环境跨集群迁移出现 virtio-vga 缺失，则在新集群手工安装 qemu-system-x86_64 并重启 libvirtd。

验证方法

• 检查平台版本已升级到 5.5.x。
• 检查首台灰度主机和后续批量重连主机状态正常。
• 检查 QueryAgentVersion 正确。
• 检查 qemu/libvirt/glib2 版本与目标版本一致。
• 检查特殊兼容场景未触发升级冲突。

风险与回滚

• 风险：升级期间管理节点不可访问，无法申请资源，也不能使用第三方 API。
• 风险：组件升级涉及多项兼容性条件，未提前识别可能导致迁移、加主机或依赖冲突问题。
• 风险等级：高。
• 回滚：双管理解耦为单管理、恢复旧源和旧 installer、执行 restore_mysql 的完整回退路径。