适用场景
- 产品：HCI 旗舰版。
- 组件：ZStone。
- 版本：ZStone V5。
- 涉及对象：ZStone 管理系统、通用存储引擎或高性能存储引擎。
- 触发条件：需要根据目标交付包对现有 ZStone V5 环境进行版本内更新、跨版本升级，或升级高性能存储引擎。
本文不适用于 V4 升级至 V5、通用存储与高性能存储之间的数据迁移或存储引擎转换。是否支持从当前版本直接升级至目标版本，以目标版本的正式交付说明为准。
问题现象
- 计划升级 ZStone，但无法确定应执行管理系统更新、管理系统跨版本升级、通用存储专项升级，还是高性能存储升级。
- 环境同时使用 ZStone 管理系统与存储引擎，担心采用错误的升级路径导致升级失败或存储业务异常。
- 升级后需要确认管理服务、存储集群和已有业务均恢复正常。
判断方法
- 记录当前 ZStone 管理系统版本、目标版本和实际使用的存储引擎类型；通用存储与高性能存储应分别确认。
- 核对目标版本交付包、构建号、硬件架构及正式升级说明，确认当前版本支持直接升级至目标版本。
- 升级前检查集群健康状态：通用存储集群应为
HEALTH_OK，所有 OSD 为up、in；高性能存储集群应为ok。 - 对于管理系统跨版本升级或管理系统与高性能存储联合升级，在当前承载 ZStone VIP 的管理节点执行。
- 如计划升至 ZStone 5.3.0 且单网卡速率超过 10 Gb/s，确认对接云平台版本为 4.8.x 或 5.2.0 及之后版本，并确认对应授权已具备。
原因说明
ZStone 管理系统、通用存储与高性能存储使用不同的升级机制。版本内更新和跨版本升级使用不同的 zstnadm 操作；高性能存储可独立升级，也可在目标交付包支持时与管理系统联合升级。涉及通用存储引擎版本变化时，需要使用与操作系统和架构相匹配的专项方案，不能仅依赖管理系统升级命令。
解决方案
1. 执行前准备
- 在维护窗口执行。升级前建议联系官方技术支持进行评估。
- 完成适用于本次升级的数据库、配置和业务数据备份，并确认恢复方案、空间余量和节点访问权限。
- 从正式交付渠道获取目标 ZStone installer 包，核对版本、构建号、校验值和系统架构。
- 使用目标包生成配置模板，并逐项核对 VIP、管理节点、存储节点、数据库和网络配置；不要使用其他版本的配置文件覆盖当前模板。
- 升级前不得在非健康的通用存储或高性能存储集群上继续操作。
2. 选择升级路径
| 当前场景 | 升级路径 | 处理原则 |
|---|---|---|
| 通用存储环境，管理系统版本内更新 | 管理系统更新 | 使用目标包提供的 zstnadm update 流程。 |
| 通用存储环境，管理系统跨版本升级 | 管理系统跨版本升级 | 使用目标包提供的 zstnadm upgrade 流程。 |
| 通用存储引擎版本发生变化 | 通用存储专项升级 | 按目标操作系统、架构和交付包使用专项方案；联系官方技术支持确认后执行。 |
| 仅升级高性能存储引擎 | 高性能存储在线升级 | 更新目标 installer 后，在一个操作节点发起一次集群在线升级。 |
| 同时升级管理系统和高性能存储引擎 | 联合升级 | 仅在目标交付包明确支持时，使用带 --with-zbs-storage 的联合流程。 |
高性能存储环境升至 5.4.0 时，需先完成高性能存储升级和验收，再升级管理系统；联合升级前也应确认目标交付包满足这一要求。
3. 执行管理系统升级
- 在目标管理节点解压目标 installer 包，并进入
zstone-installer根目录。 - 根据第 2 节选择版本内更新或跨版本升级，使用目标包生成对应配置模板。
- 完成配置核对后执行目标包提供的升级命令：版本内更新使用
zstnadm update --config <更新配置文件>；跨版本升级使用zstnadm upgrade --config <升级配置文件>。 - 保存命令输出和任务日志。若执行失败，停止后续操作并根据失败阶段处理；不要直接使用旧版本安装包覆盖已升级环境。
4. 执行高性能存储升级
- 升级前确认集群健康状态为
ok，并记录当前版本。 - 在所有高性能存储节点分别核对
/etc/hosts，确保zbs.zstack.io映射为该节点自身的 cluster IP。 - 按目标交付包更新高性能存储 installer。高可用环境的两个 UI 节点均需完成 installer 更新。
- 在一个操作节点发起一次集群在线升级，不要在两个 UI 节点并行发起同一集群的升级任务。
- 升级期间持续检查集群健康状态和节点版本，确认每个阶段恢复健康后再继续。
5. 通用存储引擎版本变更
通用存储引擎版本变更涉及操作系统、架构、RPM 依赖和节点滚动顺序，本文不提供通用的 RPM 升级命令。请收集当前 Ceph 版本、操作系统、硬件架构、集群健康状态和目标交付包信息，联系官方技术支持获取适用的专项升级方案。
验证方法
- 升级任务：所选升级流程完成，无未处理错误。
- 管理系统：登录管理界面，确认版本和构建号符合目标交付包，管理节点及界面功能正常。
- 通用存储集群：执行
ceph -s、ceph osd tree，确认集群为HEALTH_OK，OSD 状态正常，MON 仲裁正常。 - 高性能存储集群：执行
zbs status cluster和zbs status chunkserver，确认集群健康状态为ok，节点版本符合目标版本。 - 业务功能：验证现有业务使用的存储访问正常，原有数据可读写，无持续异常延迟。
- 授权与告警：确认授权满足当前使用需求，无未处理的升级相关异常。
风险与回滚
- 管理系统升级、存储引擎升级和联合升级均可能影响管理面或业务性能，应根据实际负载安排维护窗口。
- 仅管理系统升级是否造成业务中断，以目标版本正式升级说明为准；高性能存储升级期间可能影响业务性能。
- 通用素材未提供可适用于所有版本的自动回滚或数据库降级命令。升级失败时，停止后续操作，保留 installer、任务输出和日志，并按升级前备份和目标版本支持的恢复方案处理。
- 不要根据不同版本资料中的备份目录或旧安装包示例执行删除、移动或覆盖操作；需要回退时请联系官方技术支持确认恢复步骤。