Issue

Use this article to troubleshoot third-party cloud management and cross-subnet VNC issues.

Environment

• Product: ZCF
• Component: Cloud
• Affected object: console/VNC
• Versions: 4.x, 5.x
• Scenario: Third-party cloud management/cross-subnet VNC

Symptoms

• The console displays a white screen, noVNC/VNC cannot open, or cross-subnet VNC fails from a third-party platform.
• The service network or VM itself might work normally, while the console connection path is unavailable.

Possible causes

• The console proxy address, management-node proxy, VNC port, firewall, cross-subnet route, or third-party cloud-management callback address is abnormal.
• In a dual-management-node environment, the proxy address and access entry are inconsistent.

Resolution

1. Record the console URL, host parameter, proxy address, access source, and target management node.
2. Verify the VNC port paths through the VIP, management node, physical host, and VM separately.
3. Check console proxy/noVNC/nginx/management-server logs.
4. In a third-party cloud-management scenario, also capture invocation parameters from the third-party platform.

Key command

ss -lntp | egrep '590|6080|7070|5443|5000'
grep -a -nE "novnc|vnc|console|proxy" /usr/local/zstack/apache-tomcat/logs/management-server.log* /var/log/nginx/* 2>/dev/null

Remediation

• Based on the troubleshooting result, repair the affected component, configuration, data state, or connection path.
• If databases, underlying storage, snapshot chains, VM disks, GPU passthrough, or management-service restarts are involved, first confirm backups, scope of impact, and rollback paths.

Verification

• Confirm that the symptom described in this article no longer occurs.
• UI, API, management-node logs, and underlying command output corroborate one another.
• Observe at least one related task or alarm cycle to confirm that the issue does not recur.

Risks and rollback

• Before remediation in production, confirm customer service impact, the change window, and the rollback plan.
• For data deletion, database modifications, snapshot-chain repairs, underlying file operations, or hardware operations, ZStack recommends contacting technical support for confirmation.

Notes

• For VM startup, migration, HA, Unknown status, or forced stop operations, first confirm the actual VM running location to prevent split-brain operation, dual writes, or unintended service interruption.
• For management networks, storage networks, service networks, DHCP/VNC, VLANs, bonds, port groups, or switch-side settings, retain an available management channel and preferentially perform changes during a maintenance window.
• If database modifications, underlying file operations, lock release, service restarts, driver or firmware upgrades, or bulk resource changes are required, contact ZStack technical support before proceeding.