问题说明

本文用于排查 镜像存储（ImageStore）备份目录位于 NFS 时，大容量或多硬盘备份长时间运行后失败，并显示 expect N block jobs, only found M 的问题。该错误表示进度监控期望查询到 N 个 libvirt block job，实际只查询到 M 个；它不能单独证明 NFS 网络超时是唯一根因。

现象

• 在 ZSphere 中创建全量备份，较小备份能够完成，大容量备份长时间运行后失败。
• 失败任务详情或 zstore 日志显示类似错误：

  expect 2 block jobs, only found 1

• 同一任务的错误链中可能出现 APICreateVmBackupMsg、zstcli ... batbak 和 CreateVmBackup。
• 现场可能同时观察到 镜像存储（ImageStore）备份服务器短暂失联，但应通过管理节点、ZSphere 主机和 镜像存储（ImageStore）备份服务器三端日志确认先后顺序。

适用环境

• 产品：ZVF ZSphere
• 版本：4.10.16.405（来源日志包文件名提供的现场构建；不外推到其它维护版本）
• 组件：虚拟机备份、镜像存储（ImageStore）备份服务器、NFS、zstcli/zstack-store、KVM/libvirt block job
• 部署形态：镜像存储（ImageStore）备份目录挂载在 NFS；已记录现场为包含两块硬盘的大容量全量备份

可能原因

该现象可能由以下一种或多种原因导致：

1. NFS 服务端存储性能、客户端链路或挂载状态不稳定，持续高延迟或重传使某个 block job 先于其它 job 异常。
2. 大容量、多硬盘或并发备份放大了 KVM、镜像存储（ImageStore）、NFS 和第三方备份软件之间的 I/O 压力。
3. 某块待备份硬盘没有建立对应 block job、job 提前退出，或查询时已不可见。
4. 管理节点请求中的硬盘集合与 虚拟机 当前 domain XML 不一致。

来源记录最终将现场方向收敛到存储和第三方备份软件，但没有证明唯一故障点。现场曾尝试调整 ZS_STORAGE_HEARTBEAT_TIMEOUT 和替换运行包，随后 5 TB 大文件仍然失败，因此本文不把调大 heartbeat timeout 或历史换包步骤作为通用解决方案。

排查步骤

1. 从任务详情记录检索条件

1. 在 ZSphere 中打开失败的“创建备份”任务详情。
2. 完整记录以下信息，不要只保存最后一行错误：

• 操作开始时间、失败时间和时区；
• apiId；
• 虚拟机 UUID；
• 所有待备份硬盘 UUID；
• 镜像存储（ImageStore）备份服务器 UUID；
• 期望和实际 block job 数量，例如 expect 2、only found 1。

3. 如果页面只显示简短错误，先复制完整任务详情或导出操作日志，再进入下一步。

• 预期结果：取得能唯一定位本次失败的时间窗口、apiId、虚拟机 UUID 和硬盘 UUID。
• 异常处理：缺少 apiId 时，以精确到分钟的失败时间、虚拟机 UUID 和备份名称组合检索；不要使用其它重试任务的 apiId 代替。

2. 在管理节点用 apiId 找到请求去向和 taskUuid

• 执行位置：运行该任务的管理节点。双管理节点环境如果第一台没有记录，应在另一台执行相同查询。
• 把任务详情中的实际值粘贴到变量中：

  KB_API_UUID='将任务详情中的apiId粘贴到这里'
  cd /usr/local/zstack/apache-tomcat/logs || exit 1
  ls -lh management-server.log*
  zgrep -a -n -C 5 "$KB_API_UUID" management-server.log*
  zgrep -a -n "$KB_API_UUID" management-server.log* | grep -E 'json POST|http response|taskuuid|taskUuid|error|fail'

• 阅读方法：

1. 先找包含 apiId 的 API 请求和最终错误。
2. 再找同一时间窗口内的 json POST；记录 URL、目标 IP 和请求体中的 taskuuid 或 taskUuid。
3. json POST 的目标 IP 决定下一步登录哪台 ZSphere 主机或 镜像存储（ImageStore）备份服务器；不同请求可能使用不同的 taskUuid，不要混用。

• 预期结果：定位到管理节点发往 KVM/镜像存储（ImageStore） 的请求、对应目标 IP、taskUuid 和完整 http response。
• 异常处理：当前日志没有命中时，确认故障日期后继续查询同目录的轮转文件和 .gz 文件；仍无记录时核对管理节点、时区和 apiId 是否属于同一次任务。

3. 在镜像存储（ImageStore）备份服务器查 zstore 日志

• 执行位置：第 2 步请求所指向的镜像存储（ImageStore）备份服务器。
• 优先使用发往镜像存储（ImageStore）请求中的 taskUuid；如果没有命中，再用虚拟机 UUID 和失败分钟交叉确认：

  # 将变量值替换为故障任务中的实际 UUID
  KB_TASK_UUID='task-uuid-placeholder'
  KB_VM_UUID='vm-uuid-placeholder'
  cd /var/log/zstack/zstack-store || exit 1
  ls -lh zstore*
  zgrep -a -n -C 8 "$KB_TASK_UUID" zstore*
  zgrep -a -n -C 8 "$KB_VM_UUID" zstore* | grep -iE 'batbak|block jobs|only found|not found|iohung|timeout|error|fail'

• 预期结果：找到 CreateVmBackup/batbak 的开始、进度和结束记录，并能确认哪一个 block job 缺失或最先报错。
• 异常分支：
• 日志先出现 NFS I/O、挂载或 镜像存储（ImageStore） 进程异常，随后才出现 block job 数量不一致：进入第 5 步重点检查 NFS。
• 镜像存储（ImageStore）全程在线，仅某个 block job 缺失：继续第 4 步核对 KVM 实际 job 和虚拟机硬盘。
• 当前 zstore.log 无记录：根据失败日期查询同目录轮转日志，不要只检查当前文件。

4. 在 ZSphere 主机核对 block job 和虚拟机硬盘

• 执行位置：第 2 步请求所指向的 虚拟机 当前所在 ZSphere 主机。
• 先用发往该 ZSphere 主机请求中的 taskUuid 查询 KVM Agent 日志：

  KB_TASK_UUID='将发往 KVM请求中的taskUuid 粘贴到这里'
  KB_VM_UUID='将失败任务中的虚拟机 UUID 粘贴到这里'
  cd /var/log/zstack || exit 1
  ls -lh zstack-kvmagent.log*
  zgrep -a -n -C 8 "$KB_TASK_UUID" zstack-kvmagent.log*
  zgrep -a -n -C 5 "$KB_VM_UUID" zstack-kvmagent.log* | grep -iE 'backup|block|qmp|libvirt|error|fail|timeout'

• 在问题正在复现时，连续查询 虚拟机 当前 block job；该命令只读，不会终止 job：

  KB_VM_UUID='将失败任务中的虚拟机 UUID 粘贴到这里'
  virsh qemu-monitor-command "$KB_VM_UUID" '{"execute":"query-block-jobs","arguments":{}}' --pretty
  virsh dumpxml "$KB_VM_UUID" | sed -n '/<disk /,/<\/disk>/p'

• 预期结果：每块待备份硬盘都存在对应 block job，数量与任务中的 N 一致，且进度持续变化；虚拟机 XML 中可找到所有待备份磁盘。
• 异常分支：
• 始终缺少同一块盘：记录该盘 UUID、虚拟机 XML 和日志，不要通过改库或重新挂载硬盘强行补 job。
• job 曾存在后消失：向前追查该 job 的第一条 error，而不是把最后的 only found M 当作根因。
• 所有 job 都存在但进度长时间不变：同时保留多次查询结果，进入第 5 步对齐 NFS 性能时间线。

5. 检查 NFS 挂载、容量、延迟和重传

• 执行位置：实际挂载 NFS 备份目录的镜像存储（ImageStore）备份服务器。
• 先从现有挂载列表确认真实备份目录，再把该目录填入变量；不要猜测路径：

  findmnt -t nfs,nfs4 -o TARGET,SOURCE,FSTYPE,OPTIONS
  nfsstat -m
  KB_BACKUP_PATH='将上一步确认的NFS备份目录粘贴到这里'
  findmnt -T "$KB_BACKUP_PATH" -o TARGET,SOURCE,FSTYPE,OPTIONS
  df -hT "$KB_BACKUP_PATH"
  command -v nfsiostat >/dev/null 2>&1 && nfsiostat 1 10 "$KB_BACKUP_PATH"
  command -v iostat >/dev/null 2>&1 && iostat -xz 1 10
  dmesg -T | tail -n 300 | grep -iE 'nfs|rpc|not responding|timed out|timeout|reset'

• 预期结果：备份目录仍挂载到预期 NFS、不是只读状态、可用空间充足；连续样本中没有与失败时间对齐的持续延迟、重传、server not responding、timeout 或底层磁盘饱和。
• 异常处理：
• 挂载缺失、只读或空间不足：停止新备份，先由存储管理员恢复 NFS 服务和容量。
• 延迟、重传或服务端磁盘饱和与失败同时出现：记录 NFS 客户端输出，并让存储管理员补充同一时间窗口的 NFS 服务端网络和磁盘指标。
• 客户端与服务端指标都正常：不要继续把问题归因于 NFS；回到第 4 步检查缺失的具体 block job、libvirt/qemu 版本和第三方备份软件日志。

6. 用低并发对照验证压力分支

1. 等待正在运行的备份/恢复任务正常结束；如必须取消，使用产品界面支持的取消操作，并确认任务已结束，不要直接 kill zstcli、qemu 或 libvirt 进程。
2. 暂停同一 镜像存储（ImageStore）备份服务器上的批量计划任务。
3. 在 NFS 状态稳定的维护窗口内，一次只对 1 台 虚拟机 发起同类型备份；保持 虚拟机、硬盘集合和目标备份服务器不变。
4. 同时执行第 2～5 步的日志和性能采集，比较低并发与原失败时段。

• 判断结果：
• 低并发完成，高并发或高峰期稳定失败：存储/链路/第三方软件的压力分支得到支持，进入第 7 步临时处置。
• 低并发仍在同一块盘、同一阶段失败：不要反复重试，提交三端日志、虚拟机 XML、NFS 指标和第三方软件日志给 ZStack 技术支持继续定位。

7. 临时处置、回退和验证

临时方案（Workaround）

• 适用条件：第 5、6 步已确认 NFS 或第三方存储在大容量/并发场景下出现性能压力，且没有残留的进行中备份、恢复或 block job。
• 临时执行：暂停批量计划，避开存储高峰；同一 镜像存储（ImageStore）备份服务器一次只运行 1 台虚拟机的备份，待前一任务成功结束后再启动下一任务。该方案只降低触发概率，不替代存储修复。
• 根因处理：由存储管理员修复已确认的 NFS 容量、网络、服务端磁盘或第三方备份软件性能问题；变更挂载、存储后端或第三方软件前，应另行制定维护窗口、备份和回滚计划。
• 不适用情形：低并发仍失败、虚拟机硬盘集合不一致、某个 block job 持续缺失，或根因尚未收敛时，不应通过反复重试、重启 镜像存储（ImageStore）、kill 进程、改库或删除备份数据绕过错误。
• 不使用的历史方案：不要自行替换 zstack-store.bin 或设置 ZS_STORAGE_HEARTBEAT_TIMEOUT。来源现场中这些动作没有稳定解决 5 TB 大文件失败；如支持人员需要诊断包，必须由其提供与现场构建匹配的包、替换范围、原文件备份、校验值和明确回滚步骤。
• 回退：临时方案只改变任务调度，不修改平台或主机配置。若低并发也失败，停止继续发起任务，保留原计划配置但继续暂停其执行，并升级支持；存储修复验证完成后再恢复原并发。
• 验证标准：相同虚拟机、相同硬盘集合和同一目标备份服务器能够完成一次全量备份；管理节点、KVM 和 zstore 日志不再出现 block job 数量不一致；备份期间 NFS 未出现与任务时间对齐的持续异常。

补充信息

• 提交支持时至少提供：失败任务详情、准确时间和时区、apiId、虚拟机/硬盘/备份服务器 UUID、管理节点 management-server.log、KVM zstack-kvmagent.log、镜像存储（ImageStore）zstore.log、虚拟机 XML、连续 block-job 查询、NFS 客户端与服务端指标、第三方备份软件日志。
• only found M 是进度监控看到的结果，不一定是第一故障点。应沿时间线向前找到最早的 I/O、NFS、libvirt/qemu 或第三方软件错误。
• 当前审阅的 zstack-store 代码每隔约 3 秒查询一次 block job，发现数量不一致后返回错误；该代码事实用于解释错误含义，不证明 4.10.16.405 现场一定由查询窗口导致。