问题说明

适用于排查 UI 详情页加载慢、资源列表或详情页显示不一致、监控数据不准确、报警确认状态异常、审计页面白屏、权限按钮不可见或角色权限异常等问题。此类问题需要区分前端显示、后端 API、监控指标口径、权限模型、浏览器缓存和实际业务状态。

现象

• 云主机详情页加载慢或无登录界面显示。
• 首页 TOP 指标与详情页监控指标不一致。
• 报警消息次数、确认状态、事件详情或邮件模板内容不符合预期。
• admin 用户审计页面白屏，F12 显示前端数据异常。
• 项目角色、权限修改、负载均衡后端服务器权限显示异常。
• 导出云主机信息、管理标签、DNS、CDP 详情等 UI 显示异常。

适用环境

• 产品：ZCF
• 组件：Cloud
• 涉及对象：ZStack Cloud；UI、监控、报警、权限、审计、云主机详情页、API、浏览器
• 版本：4.x-4.8.38

可能原因

• 首页和详情页使用不同 metricName、聚合口径或时间窗口。
• 云主机性能优化工具、内部监控转发服务或相关组件异常，导致 UI 等待数据。
• 前端 chunk、分页、缓存、浏览器状态或接口返回 undefined 引发白屏。
• 权限模型中平台角色、项目角色、子 API 权限或资源可见性存在差异。
• 报警确认、事件详情、模板标签或告警次数统计逻辑与用户预期不同。
• UI bug 或已知问题，需要升级或补丁修复。

排查步骤

1. 区分显示问题和真实状态

• 同一资源在列表页、详情页、CLI/API、数据库或底层命令中交叉验证。
• 使用无痕浏览器、清缓存、更换浏览器或账号复测，排除本地缓存影响。

2. 检查前端和 API

• 浏览器 F12 查看 Console、Network、接口返回和失败请求。
• 使用 API Inspector 或管理日志确认后端是否正常返回。
• 若接口返回正常但 UI 显示异常，优先按前端问题记录。

3. 检查监控链路

ps -ef | grep light
ip netns list
grep -a -n "<vmUuid-or-metricName>" /usr/local/zstack/apache-tomcat/logs/management-server.log*

• 内部监控无数据时，检查性能优化工具、DHCP/userdata、转发服务和指标采集路径。
• 指标不一致时，先确认是否为不同指标或不同聚合口径。

4. 检查权限和角色

• 记录用户、角色、项目、资源、按钮/API 和期望权限。
• 核对是否为平台角色才具备的权限，或某个子 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 QueryVmInstance uuid=<vm-uuid>
zstack-cli QueryHost uuid=<host-uuid>
zstack-cli QueryVolume vmInstanceUuid=<vm-uuid>
virsh list --all
virsh domstate <vm-name-or-id>
virsh dumpxml <vm-name-or-id> > /tmp/vm.xml
systemctl status libvirtd zstack-kvmagent 2>/dev/null || true
grep -iE 'ERROR|Exception|failed|timeout|qmp|libvirt|domain' /var/log/zstack/zstack-kvmagent.log | tail -n 200
grep -iE '<vm-uuid>|<vm-name>' /usr/local/zstack/apache-tomcat/logs/management-server.log | tail -n 200

云主机类临时处理建议

• 云主机状态异常时先比对管理面、libvirt、QEMU 进程和业务侧状态，避免只根据 UI 状态执行停止或删除。
• 控制台黑屏优先检查 VNC/SPICE 端口、代理、浏览器、物理机 agent 和虚拟机显卡配置；业务正常时可先规避为 SSH/RDP 登录。
• 启动失败或异常关机应先保护 XML、agent 日志和管理日志；必要时先迁移/重连/刷新状态，强制操作需确认磁盘和快照链完整。

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 返回；不要直接改数据库权限或计费记录。
• 许可证上传失败时先核对产品版本、授权文件有效期、机器码和管理节点时间；可临时回退到原授权或暂停升级变更窗口。

补充信息

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