问题说明

提供 ZStack Cloud 云主机控制台打开后黑屏的结构化排查流程。控制台黑屏不一定表示云主机未启动，也可能是控制台协议、显卡类型、Guest OS 图形界面、迁移后驱动、GPU 透传、Windows 工具或系统内部程序异常导致。

现象

• 云平台控制台窗口可以打开，但画面全黑或长时间无登录界面。
• 云主机可通过 SSH、远程桌面或业务端口访问，但 VNC/控制台黑屏。
• 迁移或导入后的 Linux/Windows 云主机启动后控制台黑屏。
• GPU 透传云主机或安装性能优化工具后的云主机重启黑屏。
• 修改启动项、关闭 virtio 或恢复快照后仍然黑屏。

适用环境

• 产品：ZCF
• 组件：Cloud
• 涉及对象：ZStack Cloud；云主机、控制台、VNC/SPICE、显卡类型、性能优化工具、GPU 透传
• 版本：4.x-4.8.38
• 部署形态：KVM 云主机、本地存储/共享存储/分布式存储均可能涉及

可能原因

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

• 控制台协议或显卡类型不兼容：云主机控制台选择 SPICE 后黑屏，切换为 VNC 后恢复；GPU 或图形场景下 cirrus、qxl、vga 兼容性不同。
• Guest OS 图形界面异常：Linux 图形化桌面无法启动，但命令行或 SSH 正常；Windows 内部程序崩溃或安全软件占用资源导致控制台迟迟不显示。
• 迁移或导入兼容性问题：从 VMware 或 v2v 工具迁移后，virtio、CPU 模式、显卡类型、Guest OS 版本不匹配。
• Windows 性能优化工具或驱动异常：性能优化工具安装故障、virtio/QGA/网卡驱动异常，导致重启后进入修复或黑屏。
• GPU 透传或 CPU 模式不匹配：GPU 透传场景下图形界面无法工作，需要检查 CPU 模式、显卡类型和 Guest 驱动。
• Guest OS 架构不支持：相关场景中 ARM 架构 Windows 云主机在当前云平台适配边界外，创建后控制台黑屏。
• 控制台代理或物理机网络异常：控制台代理端口、物理机防火墙、iptables、VNC 端口或控制台代理地址异常。

排查步骤

按顺序执行以下检查。每一步都应确认当前状态是否符合预期，或指出下一步处理动作。

1. 判断云主机是否只是控制台黑屏

• 检查项：确认云主机本身是否仍在运行，业务是否可访问。
• 命令/UI 路径：
• 云平台查看云主机状态、物理机、IP、最近任务和告警。
• 从业务网络测试 SSH、RDP、ICMP 或应用端口。
• Linux 云主机可尝试 Ctrl+Alt+F2 切换 TTY。
• 预期结果：能够区分“仅控制台显示异常”和“云主机启动/系统异常”。
• 异常处理：
• 如果业务访问正常，只控制台黑屏，优先排查控制台协议、显卡类型、代理和 Guest 图形界面。
• 如果业务也不可访问，转入云主机启动失败、系统异常或存储/网络排查。

2. 检查控制台协议和显卡类型

• 检查项：确认控制台协议是否为 VNC，显卡类型是否与 Guest OS/业务场景兼容。
• 命令/UI 路径：
• 云平台云主机详情页查看控制台类型。
• 集群高级设置或云主机相关配置中查看启动显卡类型。
• 预期结果：普通场景优先使用 VNC；显卡类型根据 Guest OS 和图形需求选择。
• 异常处理：
• 如果控制台选择 SPICE 且打开黑屏，变更为 VNC 后重启云主机验证。
• 如果 GPU 或图形桌面场景使用 cirrus 黑屏，可在业务窗口内测试 qxl。
• 显卡类型变更通常需要停止/重启云主机，应先确认业务窗口。

3. 检查 Guest OS 图形界面和系统内部状态

• 检查项：确认黑屏是否由 Guest OS 图形界面、桌面服务、系统程序或安全软件引起。
• 命令/UI 路径：
• Linux：通过 SSH 或 TTY 登录，检查图形服务、默认启动目标和系统日志。
• Windows：通过 RDP 登录，检查事件查看器、资源占用、安全软件和最近安装程序。
• 预期结果：Guest OS 可登录，系统无持续崩溃、资源耗尽或桌面服务异常。
• 异常处理：
• Linux 图形界面异常但命令行正常时，可临时切换到命令行模式验证系统是否能正常启动。
• Windows 出现大量程序崩溃、内存溢出或安全软件占用过高时，先从 Guest OS 内部处理程序异常。
• 涉及系统文件缺失或软件安装故障时，优先快照/备份后再修复。

4. 排查迁移或导入后的兼容性问题

• 检查项：确认云主机是否来自 VMware/v2v/手动导入，导入后是否首次启动即黑屏。
• 命令/UI 路径：
• 核对源端 OS 版本、迁移工具支持范围、磁盘控制器、网卡模型、CPU 模式和显卡类型。
• 检查云主机是否启用 virtio、是否安装性能优化工具。
• 预期结果：Guest OS、驱动、CPU 模式和显卡类型均在支持范围内。
• 异常处理：
• 从 VMware 迁移的 CentOS 8 类云主机，可测试关闭 virtio、设置 CPU 模式为直通或调整显卡类型。
• v2v 迁移的 Linux 云主机如 SSH 正常但控制台黑屏，可先确认图形桌面是否正常，再按需切换命令行启动。
• 变更 CPU 模式、virtio 或显卡类型前应保留快照并安排业务窗口。

5. 排查 Windows 性能优化工具和驱动问题

• 检查项：确认是否刚安装、升级或重装性能优化工具，是否进入 Windows 自动修复或反复黑屏。
• 命令/UI 路径：
• 云平台检查云主机 virtio、云盘 virtio、网卡类型。
• Windows 安全模式或恢复环境中检查驱动、事件日志和工具安装状态。
• 预期结果：Windows 可正常启动，virtio/QGA/网卡驱动状态正常。
• 异常处理：
• 相关场景中关闭云主机 virtio、云盘 virtio，并将网卡类型调整为 e1000 后重新安装性能优化工具可恢复。
• 如果恢复快照仍黑屏，需确认快照时间点是否已经包含异常驱动或系统损坏。
• Windows 驱动和性能优化工具修复前建议先备份系统盘。

6. 排查 GPU 透传和图形兼容性

• 检查项：确认云主机是否绑定 GPU、vGPU 或 A40 等透传设备。
• 命令/UI 路径：
• 云平台查看云主机规格、透传设备和启动显卡类型。
• Guest OS 内检查 GPU 驱动和图形服务。
• 预期结果：GPU 驱动加载正常，CPU 模式和显卡类型适配当前 Guest OS。
• 异常处理：
• Ubuntu 透传 GPU 后黑屏但可切换 TTY 时，优先判断为图形界面或 GPU 驱动问题。
• 相关场景中将云主机 CPU 模式设置为 host-passthrough 后恢复。
• GPU 云主机控制台黑屏可测试将启动显卡类型从 cirrus 调整为 qxl。

7. 检查控制台代理、VNC 端口和物理机防火墙

• 检查项：确认控制台代理地址、物理机 VNC 端口、iptables/firewalld 是否正常。
• 命令/UI 路径：
• 在云主机所在物理机检查 VNC 端口监听。
• 检查物理机防火墙或 iptables 是否放行控制台相关端口。
• 对比迁移到其他物理机后控制台是否恢复。
• 预期结果：控制台代理可达，VNC 端口存在，防火墙规则未阻断。
• 异常处理：
• 如果迁移到其他物理机正常，迁回原物理机仍黑屏，重点检查原物理机防火墙、iptables 和控制台代理。
• 如果控制台代理地址不正确，需检查管理节点下发配置和物理机网络。

8. 收集支持信息

• 云主机信息：UUID、名称、OS 类型、来源镜像、迁移来源、是否 GPU、CPU 模式、显卡类型、控制台协议。
• 时间窗口：黑屏首次出现时间、最近安装驱动/工具/补丁/迁移/重启时间。
• 管理节点日志：/usr/local/zstack/apache-tomcat/logs/management-server.log*
• 计算节点日志：/var/log/zstack/zstack-kvmagent.log*
• Guest OS 证据：Windows 事件日志、Linux journalctl、图形服务日志、RDP/SSH 是否可用。
• 物理机证据：VNC 端口监听、防火墙规则、控制台代理配置、云主机 qemu 进程和日志。

补充排查方法

基础排查命令

# 管理节点服务和集群基础状态
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 日志和管理日志；必要时先迁移/重连/刷新状态，强制操作需确认磁盘和快照链完整。

补充信息

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