问题说明

适用于排查升级后 qemu/libvirt 二进制或依赖异常、Repo 源异常、第三方认证同步失败、管理服务因授权无法启动、UKEY/信创授权不匹配、CPU 授权识别异常等问题。升级和授权类问题通常需要同时核对版本线、ISO/本地源、rpm 历史、许可证文件、机器指纹、服务依赖和产品兼容边界。

现象

• 升级 qemu 后二进制文件报错、库函数缺失、qemu 版本获取异常。
• 升级后物理机失联、依赖包找不到、Repo 源异常。
• 第三方认证/LDAP/SSO 升级后同步失败，日志出现 SSLHandshakeException。
• 管理节点重启后管理服务启动失败，报许可证/授权问题。
• 信创版 UKEY 无法识别、双管理节点重装后授权无法启动。
• 海光 CPU 服务器识别 socket 数异常，导致授权占用异常。

适用环境

• 产品：ZCF
• 组件：Cloud
• 涉及对象：ZStack Cloud；升级、qemu、libvirt、Repo/Yum、许可证、UKEY、LDAP/SSO、管理服务
• 版本：4.x-4.8.38

可能原因

• 升级 ISO、本地源、qemu-kvm-ev 源或 Repo 文件不一致，导致依赖包错误。
• qemu/libvirt 包升级不完整，动态库或函数符号与二进制不匹配。
• 第三方认证服务证书、域名/IP、SAN、SSL 策略与新版本校验逻辑不匹配。
• 许可证类型、机器指纹、授权文件数量、临时授权过期或双管理节点同步状态异常。
• 特定硬件/CPU 在当前版本识别逻辑中与授权计数不匹配。

排查步骤

1. 确认升级路径和版本信息

zstack-ctl status
yum history
rpm -qa | egrep "qemu|libvirt|zstack|nginx"
cat /etc/yum.repos.d/*.repo

• 记录升级前版本、升级后版本、ISO 名称、补丁包、是否使用过离线源或手工 rpm。
• qemu/libvirt 异常时，对比正常节点包版本和动态库路径。

2. 检查管理服务和依赖

zstack-ctl status
systemctl status zstack-ui-nginx --no-pager
journalctl -u zstack-ui-nginx --since "<start-time>"
grep -a -n "ERROR\|license\|SSLHandshake\|qemu" /usr/local/zstack/apache-tomcat/logs/management-server.log*

• 国防版或定制版依赖缺失时，确认系统 ISO 是否适配、是否误删 nginx/依赖包。
• 第三方认证失败时，检查证书 SAN、是否使用 IP 访问，以及证书校验策略是否满足当前版本要求。

3. 检查授权

• 确认授权类型、机器指纹、CPU socket 识别、临时授权文件数量、是否存在过期授权。
• 双管理节点重装或同步数据库后，避免直接清空授权相关数据，先确认 accesskey 和原授权保留策略。

4. 输出修复边界

• 涉及版本回退、补丁替换、许可证更新、依赖包修复、SSO 包重新编译时，需要明确适用版本和回退路径。
• qemu/libvirt 修复后，需要验证云主机启动、迁移、备份和灾备相关功能。

补充排查方法

基础排查命令

# 管理节点服务和集群基础状态
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*。
• 涉及数据库修复、资源强制删除、主存储/镜像服务器重连等操作时，先完成数据库备份并记录回退方案。

UI、账号、权限与许可证专项检查

# 管理服务、时间和前端访问
zstack-ctl status
date
chronyc sources -v 2>/dev/null || ntpq -p 2>/dev/null || true
curl -k -I https://<management-ip>:5000/ 2>/dev/null || curl -I http://<management-ip>:8080/

# 管理日志关键字
grep -iE 'login|token|license|permission|account|project|billing|invoice|ERROR|Exception' /usr/local/zstack/apache-tomcat/logs/management-server.log | tail -n 200

UI/权限类临时处理建议

• 登录或页面异常先排除浏览器缓存、客户端时间偏差、管理节点时间同步和反向代理/证书问题。
• 账号、项目、权限、计费或发票问题先记录账号 UUID、项目 UUID、操作路径和 API 返回；不要直接改数据库权限或计费记录。
• 许可证上传失败时先核对产品版本、授权文件有效期、机器码和管理节点时间；可临时回退到原授权或暂停升级变更窗口。

硬件、驱动、安全与升级专项检查

uname -a
rpm -qa | egrep 'zstack|qemu|libvirt|kernel|nvidia|vfio|spice|qxl' | sort
lspci -nn
lsmod | egrep 'vfio|kvm|nvidia|mlx|ixgbe|i40e|bnx|megaraid'
dmesg -T | grep -iE 'error|failed|reset|timeout|nmi|mce|iommu|vfio|gpu|driver' | tail -n 200
systemctl list-units --failed

硬件/升级类临时处理建议

• 驱动、GPU、外设或升级依赖异常时，先确认内核、驱动、固件和 ZStack 版本组合；不要在未确认兼容性前直接升级内核或替换驱动。
• 安全加固或漏洞修复后异常，优先核对防火墙、SELinux、系统库、端口监听和服务启动权限，必要时按变更方案回退加固项。
• 升级失败应保留升级日志、版本包、依赖检查输出和当前服务状态；只在确认继续条件满足时执行 continue/retry。

补充信息

• 排查结论需结合当前版本、服务状态、日志、集群健康、近期变更和现场影响面确认。
• 涉及数据库修改、强制删除、OSD/MON 重建、Pool 删除、服务重启或网络变更等高风险操作时，应先完成备份、审批和技术支持确认。