问题说明

本文用于排查 Vinchin 备份结束并删除虚拟机 Snapshot 后，页面 Snapshot Capacity 为 0 B，但 QueryPrimaryStorage.availableCapacity 仍低于备份前，后续备份被误判容量不足的场景。

现象

• ZSphere 5.0.3、SharedBlock/SAN 数据存储使用 Vinchin 备份。
• 备份过程中可用容量下降；Vinchin 删除快照后 UI 显示 Snapshot Capacity 0 B。
• CLI 查询的 availableCapacity 未回到备份前值，Capacity Percent Used 长时间偏高。
• 已记录案例中，修改 Overcommit Ratio 保存后再改回会触发容量重算并恢复；该方法会短时改变分配口径，只能作为受控 workaround，不能作为根因结论。

适用环境

• 产品：ZVF ZSphere
• 版本：5.0.3
• 组件：ZSphere SharedBlock/SAN 数据存储、容量统计和 Vinchin 快照流程
• 部署形态：Vinchin 备份会创建并在结束后删除虚拟机 Snapshot

可能原因

• 快照删除后的容量更新与 PrimaryStorageCapacityVO 重算没有及时同步。
• UI 使用的展示值与 CLI availableCapacity 读取时点不同。
• 当前证据只证明“触发重算后恢复”，尚不能确定容量更新在哪个环节丢失。

排查步骤

1. 记录一个完整备份周期的四组容量值

• 检查对象：目标数据存储及同一次 Vinchin 备份创建、删除的快照。
• 操作位置：分别在备份前、创建快照后、Vinchin 报告删除成功后、手动刷新后执行 QueryPrimaryStorage uuid=PRIMARY_STORAGE_UUID，记录 availableCapacity、availablePhysicalCapacity 和 totalCapacity；同步保存 UI 的 Snapshot Capacity、Free to Allocate 和 Capacity Percent Used。
• 预期结果：快照删除完成后，后端和 UI 的容量值均回到与实际分配一致的水平。
• 异常处理：若只有 UI 恢复为 0 B 而 availableCapacity 仍低于备份前值，继续确认快照和后台任务是否真正结束。

2. 排除真实快照残留或删除任务未完成

• 检查对象：虚拟机 Snapshot/VolumeSnapshot 列表、Vinchin 删除结果和 ZSphere 任务状态。
• 操作位置：按虚拟机 UUID、快照 UUID 和备份时间查询，并用下面的日志链确认删除请求真正完成：

1. 在 ZSphere 任务详情记录快照删除任务的 apiId、虚拟机 UUID、快照 UUID 和准确时间。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|capacity'

记录请求目标 ZSphere 主机、URI、taskuuid/taskUuid 和响应。若 Vinchin 侧只提供快照 UUID，则先用该 UUID 和准确时间检索 management-server.log*，再从命中行取得 apiUuid 与 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|capacity|error|fail|timeout'

3. 只有管理节点响应、KVM Agent 结束日志、Vinchin 结果和对象查询都表明删除完成，才能进入“容量未重算”分支。任一端仍为 Running、timeout 或 merge 未结束时，继续观察原任务，不触发容量重算 workaround。需要上下翻看当前日志时使用 vim -R 日志文件，输入 / 后粘贴 UUID 并按 Enter，按 n 看下一处，输入 :q! 退出。

• 预期结果：Vinchin 与 ZSphere 均确认目标快照已删除，UI Snapshot Capacity 为 0 B，且没有其他任务继续消耗容量。
• 异常处理：存在残留对象或后台任务时，先按该对象的删除流程处理；此时不能把容量偏低认定为“未重算”。

3. 优先调用受支持的容量同步接口

• 检查对象：目标数据存储 UUID 和同步前后的容量返回。
• 操作位置：代码提供 SyncPrimaryStorageCapacity API；由有权限的管理员在没有快照创建/删除任务时执行：

  SyncPrimaryStorageCapacity primaryStorageUuid=PRIMARY_STORAGE_UUID

• 预期结果：接口成功返回，随后 QueryPrimaryStorage 与 UI 的可用容量一致。
• 异常处理：接口失败或成功后容量仍不变时，保存请求/响应和同步前后值，不修改数据库，进入受控 workaround。

4. 必要时执行 Overcommit Ratio 受控 workaround

临时方案（Workaround）

• 支持协助方案：仅当原始 Overcommit Ratio 确认为 1:1、快照已删除、没有正在进行的容量分配，并且 SyncPrimaryStorageCapacity 未恢复容量时使用。先记录原值和容量快照；在维护窗口将目标 Data Storage 的 Overcommit Ratio 从 1:1 改为 1.2:1 并保存，观察容量重算完成后立即改回 1:1 再保存。
• 预期结果：改回原值后，availableCapacity、Free to Allocate 和 Capacity Percent Used 与实际使用量一致；后续一次小规模备份创建并删除快照后容量可以自动回落。
• 异常处理：修改期间不得启动新的备份或分配任务。容量未恢复、无法改回原值或出现新分配时立即停止并联系 ZStack 技术支持。该 workaround 只证明“重算可恢复数值”，不证明根因，也不能把 1.2:1 留作永久配置。

补充信息

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