文档中心知识库安全API Explorer
文档中心›KB›ZStack Cloud 镜像模板与镜像服务器异常排查KB
文档目录

问题说明

适用于排查镜像上传、模板封装、基于镜像创建云主机、镜像列表查询、镜像服务器重连等异常。此类问题通常与镜像来源、模板封装步骤、Guest OS 初始化工具、镜像服务器状态、数据库权限或镜像链式文件有关。

现象

  • 从 VMware Workstation 导出的 Windows 镜像上传后，创建云主机并安装性能优化工具，重启后无法进入系统。
  • 使用模板封装镜像创建云主机后，IP、网关或网络配置被还原，云主机网络不通。
  • 调用查询镜像列表 API 失败，UI 也无法正常返回镜像列表。
  • 镜像服务器重连失败，或基于镜像创建云主机时报错。
  • 镜像服务器与主存储、镜像缓存或镜像链式文件状态不一致。

适用环境

  • 产品：ZCF
  • 组件：Cloud
  • 涉及对象：ZStack Cloud；镜像、模板、镜像服务器、ImageStore、Cloudbase-Init、性能优化工具、数据库权限
  • 版本：4.x-4.8.38

可能原因

  • 源镜像内已安装 Cloudbase-Init、VMware Tools、第三方驱动或初始化脚本，与 ZStack 性能优化工具冲突。
  • 模板封装前未清理系统网络配置、cloud-init 配置、udev 规则、主机名或 SSH key，导致基于模板创建的新云主机继承旧配置。
  • 镜像服务器不可用、重连失败、镜像缓存损坏或 ImageStore 元数据异常。
  • ZStack 数据库用户权限异常，导致镜像列表查询和镜像服务器操作失败。
  • 镜像来源存在内部快照、链式 backing file 或格式不符合当前平台预期。

排查步骤

1. 明确镜像来源和故障入口

  • 记录镜像 UUID、镜像格式、镜像来源、上传方式、镜像服务器类型和所在区域。
  • 区分异常发生在上传镜像、创建云主机、模板封装、安装性能优化工具、查询镜像列表还是镜像服务器重连阶段。
  • 如果 UI 和 API 查询镜像列表同时异常，优先检查管理日志、数据库权限和镜像服务器状态。

2. 检查模板封装和 Guest OS 初始化工具

  • Windows 镜像重点检查 Cloudbase-Init、性能优化工具、virtio 驱动、网卡驱动、SID、主机名和自动初始化脚本。
  • Linux 镜像重点检查 cloud-init、NetworkManager、udev 网卡规则、/etc/fstab、SSH key、hostname 和 DHCP 配置。
  • 对从 VMware 导出的镜像，先确认 VMware Tools、旧平台驱动和初始化工具是否已按迁移规范卸载或禁用。

3. 检查镜像服务器和镜像列表查询

zstack-ctl status
grep -a -n "image\|backup storage\|ImageStore\|permission" /usr/local/zstack/apache-tomcat/logs/management-server.log*
zstack-cli
QueryImage uuid=<image-uuid>
QueryBackupStorage uuid=<backup-storage-uuid>
  • 如果 UI 与 API 都无法返回镜像列表，需确认是否为镜像服务器不可用、数据库权限异常或管理服务异常。
  • 如果重连镜像服务器失败，需要继续检查镜像服务器地址、挂载路径、网络连通性、服务进程和存储空间。

4. 检查镜像文件和链式关系

qemu-img info <image-file>
qemu-img info -backing-chain <image-file>
qemu-img check <image-file>
  • 镜像存在 backing chain、内部快照或格式异常时，不建议直接作为生产模板使用。
  • 对链式镜像或从云主机制作的镜像，需要结合快照链、ImageStore 元数据和镜像缓存继续确认。

5. 验证修复结果

  • 使用修复后的镜像创建测试云主机，验证启动、网卡、磁盘、密码注入、监控和业务访问。
  • 对模板镜像，建议至少验证一次关机、重启、迁移、克隆和网络重配。
  • 如果问题与数据库权限或镜像服务器状态有关，修复后需同时验证 UI 查询和 API 查询。

补充排查方法

基础排查命令

# 管理节点服务和集群基础状态
zstack-ctl status
systemctl status zstack-ha.service 2>/dev/null || true
systemctl status mariadb.service mysqld.service 2>/dev/null || true
zsha2 status 2>/dev/null || true

# 管理节点主日志和近期错误
ls -lh /usr/local/zstack/apache-tomcat/logs/management-server.log*
grep -iE 'ERROR|WARN|Exception|failed|timeout' /usr/local/zstack/apache-tomcat/logs/management-server.log | tail -n 200

# 基础资源与系统状态
df -hT
free -m
top -b -n 1 | head -n 30
journalctl -p warning --since '2 hours ago' --no-pager | tail -n 200

临时解决方案

  • 先区分管理面显示异常、资源状态异常和底层业务异常；只在确认底层状态正常时，才考虑重连、刷新缓存、重试任务或重启管理服务。
  • 如需重启管理节点服务，先确认 HA 状态、当前任务和业务窗口，优先单节点逐台处理，并保留 /usr/local/zstack/apache-tomcat/logs/management-server.log*。
  • 涉及数据库修复、资源强制删除、主存储/镜像服务器重连等操作时，先完成数据库备份并记录回退方案。

备份、迁移与镜像专项检查

zstack-cli QueryLongJob state!=Succeeded
zstack-cli QueryTaskProgress 2>/dev/null || true
zstack-cli QueryBackupStorage
zstack-cli QueryImage name~=<keyword>
grep -iE 'backup|cdp|image|migration|snapshot|qemu-img|nbd|ERROR|Exception|timeout' /usr/local/zstack/apache-tomcat/logs/management-server.log | tail -n 300
ps -ef | egrep 'qemu-img|qemu-nbd|rsync|backup|zstack' | grep -v grep
df -hT

备份/迁移类临时处理建议

  • 备份、CDP、迁移或镜像任务失败时，先确认任务是否仍在运行和是否存在后台 qemu-img/rsync 进程，避免重复发起导致并发放大。
  • 镜像服务器或备份服务器异常时，先检查容量、网络、挂载和任务队列；业务高峰期优先暂停非必要备份或降低并发。
  • 快照链、备份链或迁移链路异常时，先保留链路信息和日志，禁止直接删除中间文件或强制清理任务记录。

补充信息

  • 排查结论需结合当前版本、服务状态、日志、集群健康、近期变更和现场影响面确认。
  • 涉及数据库修改、强制删除、OSD/MON 重建、Pool 删除、服务重启或网络变更等高风险操作时，应先完成备份、审批和技术支持确认。
上一篇ZStack Cloud HTTP 通知对象告警内容为空排查下一篇安装管理节点服务时数据库安装失败，如何解决？
ZStack Cloud 镜像模板与镜像服务器异常排查 | 故障排查 · KB | ZStack 资源中心