问题说明

适用于排查云主机克隆失败、创建云主机镜像失败、快照无法删除、快照达到配额上限、快照链过长和 LVM 锁冲突等问题。此类问题经常发生在克隆、创建镜像、扩容、重置、快照回滚、备份软件调用快照 API 等场景。

现象

• 创建根云盘镜像失败，报错 snapshot.volume.num 超过配额。
• 克隆云主机失败，提示无法从某个 volume snapshot 创建模板。
• 将云主机制作成系统镜像时报错，提示无法从本地存储上传数据到镜像仓库。
• 调用 API 批量删除快照报错 LV is already locked with incompatible mode。
• 快照链过长、快照关联异常或管理面与数据面显示不一致。

适用环境

• 产品：ZCF
• 组件：Cloud
• 涉及对象：ZStack Cloud；云主机、云盘、快照、克隆、镜像制作、ImageStore、LVM、Ceph/ZCE
• 版本：4.x-4.8.38

可能原因

• 云盘或云主机快照数量过多，达到账号配额或导致合并、上传、索引过程超时。
• 克隆、创建镜像、扩容、重置、快照回滚等操作生成自动快照，长期未清理。
• 云主机存在较长快照链，ImageStore 计算 Hash、切片上传或生成元数据时异常。
• 镜像服务器类型与主存储不匹配，或镜像服务器可用容量小于云盘容量、快照链容量或厚置备卷实际需求，导致克隆前置镜像创建失败。
• 本地存储、LVM 或 zsblk 自动加锁与离线删除快照操作并发，导致锁模式冲突。
• 第三方备份软件调用快照 API 后任务超时或回滚异常，导致快照残留、删除按钮灰色或管理面与数据面状态不一致。
• 云盘 XML、UI 管理面、主存储实际文件或 backing chain 不一致。

排查步骤

1. 明确失败操作和对象

• 记录云主机 UUID、云盘 UUID、快照 UUID、账号 UUID、镜像服务器 UUID、主存储类型和故障时间。
• 区分失败操作是克隆、创建系统镜像、创建云盘镜像、删除快照还是备份软件调用快照。
• 检查任务错误信息中是否包含快照配额、ImageStore 上传、volume snapshot、LVM lock 或 backing file。

2. 检查快照数量、配额和自动快照

zstack-cli
QueryVolumeSnapshot volumeUuid=<volume-uuid>
QueryQuota identityUuid=<account-uuid>
QueryGlobalConfig category=primaryStorage name=undo.tempSnapshot

• 如果账号快照数量达到上限，先清理不再需要的快照或调整配额，再重试创建镜像/克隆。
• 如需减少创建镜像和全量克隆产生的一次性自动快照，可结合当前版本能力评估 primaryStorage.undo.tempSnapshot 全局配置。
• 清理快照前需确认业务可恢复边界，避免删除仍被备份、克隆链或回滚流程依赖的快照。

3. 检查快照链和镜像制作链路

qemu-img info -backing-chain <volume-file>
grep -a -n "<snapshot-uuid-or-volume-uuid>" /usr/local/zstack/apache-tomcat/logs/management-server.log*
grep -a -n "<snapshot-uuid-or-volume-uuid>" /var/log/zstack/zstack-kvmagent.log*

• 如果存在长快照链，优先评估删除无用快照、合并快照或改用新的完整备份/镜像制作流程。
• ImageStore 上传失败时，需同时检查主存储文件、镜像服务器空间、imf2 元数据和网络传输日志。

4. 检查 LVM 锁和存储侧状态

lvmlockctl -i
journalctl -u lvmlockd --since "<start-time>" --until "<end-time>"
grep -a -n "LV is already locked\|lock" /var/log/zstack/zsblk-agent.log*

• 如果为 LVM 锁冲突，避免重复并发删除同一快照，先确认锁状态、历史操作和后台任务。
• 相关场景中离线删除根快照遇到 zsblk 自动加锁时，临时处理为等待锁释放后再次执行删除。

解决步骤

1. 快照数量或配额超限

适用现象：

• 创建根云盘镜像失败，报错 snapshot.volume.num 超过配额。
• 创建镜像或克隆前自动创建快照失败。
• 快照数量明显大于业务实际需要。

处理步骤：

1. 在 UI 或 CLI 中确认目标账号、云盘和云主机当前快照数量。
2. 与业务方确认哪些快照仍需保留；涉及回滚、备份、克隆链依赖的快照不要直接删除。
3. 对不再需要的快照，优先通过 UI 删除；UI 不可操作时，再使用 CLI 删除。
4. 删除后重新查询配额和快照数量，确认 Current used 已低于配额上限。
5. 如果业务确实需要保留当前快照数量，可由管理员按实际容量和管理策略调整快照数量配额。
6. 重新执行创建镜像或克隆任务。

如果问题来自创建镜像或全量克隆产生的一次性自动快照，可评估开启自动清理临时快照：

zstack-cli
QueryGlobalConfig category=primaryStorage name=undo.tempSnapshot
UpdateGlobalConfig category=primaryStorage name=undo.tempSnapshot value=true

说明：

• 该配置主要用于减少创建云盘镜像和全量克隆产生的一次性自动快照残留。
• 快速全量克隆、链接克隆或快照回滚等场景是否生效需以当前版本能力为准。
• 开启前需确认现场版本、克隆方式和业务回滚要求。

2. 快照链过长导致克隆或制作镜像失败

适用现象：

• 克隆失败，提示 failed to create template from the volume snapshot。
• 创建云主机镜像或云盘镜像失败，但主存储和镜像服务器基础服务正常。
• 云盘存在多层快照链，或者每块磁盘有多个历史快照。

处理步骤：

1. 先确认云主机业务状态是否正常，并确认当前快照是否仍需作为回滚点。
2. 查询目标云盘快照链，确认快照数量、创建时间和父子关系。
3. 对业务明确不再需要的快照，先删除较旧或无业务价值的快照，缩短快照链。
4. 如果快照删除动作耗时较长，避免重复发起删除；等待当前任务完成后再继续处理下一层快照。
5. 删除后重新检查 qemu-img info -backing-chain，确认链路缩短且 backing file 正常。
6. 再次执行克隆或创建镜像。

如果云主机非常关键，建议先完成业务备份或在维护窗口操作；不要为了克隆任务直接批量删除未确认用途的快照。

3. 镜像服务器容量或类型不满足克隆要求

适用现象：

• 克隆失败，提示找不到可用镜像服务器或无法创建中间镜像。
• 云主机磁盘较大，例如厚置备系统盘或多块大容量数据盘。
• 主存储和镜像服务器类型组合不匹配，或镜像服务器容量小于云盘/快照链需求。

处理步骤：

1. 确认云主机克隆流程是否需要先在镜像服务器创建临时镜像。
2. 检查目标云主机所有磁盘容量、快照链容量和镜像服务器可用容量。
3. 确认镜像服务器类型是否支持当前主存储类型；不兼容的镜像服务器不能作为该克隆任务的目标。
4. 如果镜像服务器容量不足，先清理无用镜像、扩容镜像服务器，或新增容量足够且类型兼容的镜像服务器。
5. 如果快照容量被计入克隆前置检查，先按“快照链过长”分支清理无用快照，再重试克隆。

4. ImageStore 上传或 imf2 元数据异常

适用现象：

• 制作系统镜像时报 无法从本地存储上传数据到镜像仓库。
• 云主机存在快照链，镜像制作时需要切片、计算 Hash、生成索引并上传至 ImageStore。
• 报错集中在 ImageStore 元数据、Hash、索引或上传阶段。

处理步骤：

1. 检查镜像服务器剩余空间和网络连通性，排除容量不足和网络中断。
2. 使用 qemu-img info -backing-chain <volume-file> 确认快照链完整。
3. 检查对应目录中是否存在异常的 imf2 元数据文件。
4. 如确认是 imf2 元数据异常，应先备份相关 imf2 文件，再由技术支持确认是否需要重新生成 ImageStore 元数据。
5. 元数据修复后重新创建镜像，并从新镜像创建测试云主机验证启动。

注意：

• imf2 文件和 ImageStore 索引属于镜像仓库内部数据，不建议在未确认链路和备份前直接删除。
• 如果快照链较长，建议优先缩短快照链或重新制作干净模板镜像。

5. LVM 锁冲突导致删除快照失败

适用现象：

• 删除快照或批量删除快照时报 LV is already locked with incompatible mode。
• 日志中存在 lvmlockd、zsblk 自动加锁、deactive installPath failed 等信息。
• 同一时间存在多个快照删除、备份、迁移、克隆或存储任务。

处理步骤：

1. 停止重复提交同一快照的删除请求，避免加重锁冲突。
2. 检查当前任务中心，确认是否存在克隆、迁移、备份、快照合并或删除任务。
3. 检查锁状态和相关日志：

lvmlockctl -i
journalctl -u lvmlockd --since "<start-time>" --until "<end-time>"
grep -a -n "LV is already locked\|deactive\|lock" /var/log/zstack/zsblk-agent.log*
grep -a -n "<snapshot-uuid-or-volume-uuid>" /var/log/zstack/zstack-kvmagent.log*

4. 如果判断为临时锁转换冲突，等待锁释放后再次执行删除。
5. 如果多次重试仍失败，收集 lvmlockctl、management-server、zsblk-agent 和 KVM agent 日志，由技术支持确认是否需要处理锁服务或存储侧残留。

注意：

• 不建议在生产环境直接杀 lvmlockd、sanlock 或手动删除 LV。
• 涉及锁服务重启、LV 重命名、LV 删除等动作必须先确认业务影响、备份和回退方案。

6. 快照残留、删除按钮灰色或管理面与数据面不一致

适用现象：

• 快照大小显示为 0，删除按钮灰色。
• 第三方备份软件创建快照组超时，回滚异常后残留快照。
• UI 中显示快照，但云主机 XML 或底层 backing chain 中已无该快照。
• 删除快照报找不到 LV、找不到 image 或数据面对象不存在。

处理步骤：

1. 先确认云主机 XML 和云盘 backing chain，判断该快照是否仍在当前磁盘链路中。

qemu-img info -backing-chain <volume-file>
virsh dumpxml <vm-uuid>

2. 如果快照仍在链路中，不要直接清理管理面记录，应按正常快照删除流程等待合并完成。
3. 如果确认快照已不在链路中，但 UI 或数据库仍显示残留，优先尝试通过 CLI 删除该快照记录。
4. 如果 CLI 删除成功，再检查 UI、任务中心和云盘快照列表是否恢复一致。
5. 如果底层仍存在疑似残留 LV 或文件，先重命名或隔离观察，不要立即彻底删除；观察期内确认无业务引用后，再由技术支持执行清理。
6. 对第三方备份残留快照，建议按快照名称、创建时间和 volumeUuid 定期巡检，并与备份任务记录交叉确认。

注意：

• 数据库修改、LV 重命名、LV 删除、手动清理快照残留均为高风险动作。
• 客户侧 KB 仅建议完成证据确认和正常删除；无法正常删除时应联系技术支持处理。

7. 第三方备份软件调用快照 API 导致残留

适用现象：

• 备份软件频繁创建和删除快照。
• 删除快照失败，报 batch delete volume snapshot error、deactive installPath failed 或删除超时。
• 管理面中出现以备份软件命名规则创建的残留快照。

处理步骤：

1. 对照备份软件任务时间和云平台任务时间，确认残留快照是否来自备份任务。
2. 检查故障时间点管理节点日志和 KVM agent 日志，确认是否为某台物理机执行 deactive 或合并任务超时。
3. 检查相关物理机的 KVM agent 状态、内存占用和系统资源。
4. 如果只是残留快照且链路安全，使用 CLI 对残留快照逐个删除。
5. 与备份软件侧确认后续 API 调用方式，优先使用产品推荐的快照组接口，避免单盘快照残留导致 UI 展示和删除路径不一致。
6. 对频繁残留的环境，建立定期巡检：检查备份任务残留快照、KVM agent 资源趋势、快照删除任务耗时。

8. 修复后验证克隆和镜像制作结果

• 清理或修复后，先对测试对象重试克隆/创建镜像。
• 从新镜像创建云主机，验证启动、磁盘、网络和业务可用性。
• 对备份软件触发的快照流程，需验证创建、挂载、卸载、删除快照和删除临时云盘全链路。

注意事项

• 排查结论需结合当前版本、服务状态、日志、集群健康、近期变更和现场影响面确认。
• 涉及数据库修改、快照记录修复、LV 重命名/删除、锁服务重启、强制删除、OSD/MON 重建、Pool 删除、服务重启或网络变更等高风险操作时，应先完成备份、审批和技术支持确认。
• 以上信息仅作为排查方向参考，不能替代当前现场日志、快照链、XML、存储侧状态和业务验证结果。