问题说明

本文用于排查 ZMigrate、爱数或其他备份软件调用单硬盘快照 API 后，ZSphere 页面看不到快照、显示空 UUID/0 容量，或点击删除导致页面异常的场景。

现象

• 第三方任务报告已创建或删除快照，但 ZSphere 快照列表无对应记录。
• 页面显示 UUID 为空、容量为 0，点击删除后 UI 需要刷新。
• CLI/数据库可以查询到 VolumeSnapshotVO，但页面按快照组展示。
• 精简置备数据存储容量不足时，单硬盘快照删除可能返回超时或容量不足。

适用环境

• 产品：ZVF ZSphere
• 版本：5.0.3
• 组件：ZSphere 单硬盘快照 API、快照组 UI 和数据存储容量
• 部署形态：ZMigrate、爱数等第三方软件调用单硬盘快照 API

可能原因

当前代码分别处理 APICreateVolumeSnapshotMsg 和 APICreateVolumeSnapshotGroupMsg。已确认案例中，第三方调用前者创建系统盘单硬盘快照，而 ZSphere UI 以快照组为主要管理对象，因此单硬盘快照不会按正常快照组展示；页面 UUID 为空或容量为 0 不能证明底层快照不存在。

单硬盘快照删除失败还可能是另一条独立分支：精简置备数据存储的 PrimaryStorageCapacityVO.availableCapacity 小于待删除快照的 size，或 CLI 轮询先超时但后台合并仍在进行。

排查步骤

1. 确认第三方创建的是单硬盘快照还是快照组

• 检查对象：第三方任务、调用 API、虚拟机/硬盘 UUID、快照 UUID 和创建时间。
• 操作位置：从第三方任务日志确认调用的是 CreateVolumeSnapshot 还是 CreateVolumeSnapshotGroup，再通过 CLI 分别查询单硬盘快照与快照组。
• 预期结果：第三方调用和平台对象类型一致；快照组应有组 UUID，单硬盘快照应能按卷或快照 UUID 查询。
• 异常处理：若只存在单硬盘快照而 UI 只显示快照组，页面空白属于展示边界，继续走单硬盘快照处理分支；若快照属于快照组，不得用本文的单盘删除命令。

2. 删除前核对容量与后台任务

• 检查对象：PrimaryStorageCapacityVO.availableCapacity、目标快照 size、快照删除任务和 KVM Agent 日志。
• 操作位置：由支持人员只读查询并比较 availableCapacity > snapshot size；同时按下面步骤确认没有同一快照的删除任务仍在后台运行：

1. 在第三方任务和 ZSphere 任务详情记录 虚拟机 UUID、硬盘 UUID、快照 UUID、apiId 和准确时间。SSH 登录管理节点后执行：

     KB_API_UUID='将任务详情中的apiId粘贴到这里'
     cd /usr/local/zstack/apache-tomcat/logs || exit 1
     ls -lh management-server.log*
     zgrep -a -n -C 3 "$KB_API_UUID" management-server.log*
     zgrep -a -n "$KB_API_UUID" management-server.log* | grep -iE 'json POST|http response|snapshot|delete|merge|timeout'

如果第三方任务没有 ZSphere apiId，先将快照 UUID 作为检索值执行同样的 zgrep，结合准确时间找到对应请求，再记录日志中的 apiUuid、目标 ZSphere 主机和 taskuuid/taskUuid。

2. SSH 登录请求指向的 ZSphere 主机，用 taskuuid 查询当前和归档 KVM Agent 日志：

     KB_TASK_UUID='将management-server日志中的taskuuid粘贴到这里'
     cd /var/log/zstack || exit 1
     ls -lh zstack-kvmagent.log*
     zgrep -a -n -C 5 "$KB_TASK_UUID" zstack-kvmagent.log*
     zgrep -a -n "$KB_TASK_UUID" zstack-kvmagent.log* | grep -iE 'snapshot|delete|merge|error|fail|timeout'

3. 管理节点前台已经 timeout、但 KVM Agent 同一 taskuuid 仍有删除或 merge 进度时，继续观察原任务，不要重复提交删除。需要上下翻看当前日志时使用 vim -R 日志文件，输入 / 后粘贴 UUID 并按 Enter，按 n 看下一处，输入 :q! 退出。

• 预期结果：可用容量大于待删除快照大小，且目标快照没有正在执行的合并/删除任务。
• 异常处理：容量不足时先恢复足够可分配容量；CLI 返回超时但 KVM Agent 日志仍显示删除进度时继续观察原任务，不要重复提交。已记录案例明确 CLI 为异步轮询，前台超时不等于后台删除失败。

3. 由第三方或支持人员删除准确的单硬盘快照

临时方案（Workaround）

• 适用条件：后台查询已确认第三方创建的是单硬盘快照而非快照组，目标对象的删除状态和引用可以唯一确认，且当前异常仅为 UI 列表不可见或显示残留。
• 已验证自助方案：优先让创建该单硬盘快照的第三方软件使用其原 API/任务链删除，并记录返回的快照 UUID 和结果。
• 支持协助方案：第三方已返回删除成功但平台仍能查到单硬盘快照时，由 ZStack 技术支持再次确认 虚拟机、卷、快照 UUID、无快照组引用、容量和维护窗口，再通过准确版本 CLI 执行：

  BatchDeleteVolumeSnapshot uuids=SNAPSHOT_UUID

• 预期结果：请求针对的 UUID 与只读查询一致，后台删除任务完成，KVM Agent 日志没有继续合并该快照。
• 异常处理：不得根据 UI 的空 UUID 猜测删除对象，也不要通过修改全局 API timeout 反复提交。若容量不足且必须临时调整超分比例，应先记录原值、停止新分配、确保可用容量大于快照大小，并在删除完成后立即还原；此操作仅由支持人员受控执行。

4. 验证 UI、对象和容量三者一致

• 检查对象：单硬盘快照查询、快照组查询、数据存储容量和第三方任务。
• 操作位置：确认目标单硬盘快照已为 Deleted 或不存在、没有快照组引用；刷新 UI 并重新查询数据存储容量。
• 预期结果：UI 不再显示空 UUID/0 容量异常条目，容量在后台任务结束后恢复，第三方下一次任务不会重复引用已删除快照。
• 异常处理：对象已删除但 UI 仍异常时，保存浏览器/API 返回和查询结果后升级 UI 展示问题；对象仍存在则继续按后台删除状态排查，不直接改库。

补充信息

• 提交支持信息时，应包含准确时间窗、资源和任务 UUID、完整错误文本及相关组件日志。
• 不能从单个现场结果外推所有版本；根因未闭合或操作可能影响业务、数据时，应停止自助处理并提交本文列出的证据。