Issue

Use this article to troubleshoot a UI blank page or reverse-proxy port conflict.

Environment

• Product: ZCF
• Component: Cloud
• Affected object: UI/nginx
• Versions: 4.x, 5.x
• Scenario: UI blank page or reverse-proxy port conflict

Symptoms

• The UI displays a blank page, remains loading, cannot open part of a page, or returns an API exception.
• The behavior can differ after changing browsers, switching the VIP, or accessing different management nodes.

Possible causes

• UI frontend resources, nginx/reverse proxy, the node hosting the VIP, or the management service is abnormal.
• Browser cache, frontend chunks, API exceptions, or static resource inconsistencies after upgrade are present.

Resolution

1. Record the access address, the node hosting the VIP, and browser F12 Console/Network errors.
2. Access through the VIP and the real IP addresses of both management nodes separately to confirm whether the issue is node-bound.
3. Check UI/nginx/management-server status and logs.
4. If the issue occurred after an upgrade or patch, verify the static resource version and patch package.

Key command

zsha2 status
systemctl status zstack-ui nginx --no-pager
grep -a -nE "error|chunk|nginx|ui|proxy" /var/log/nginx/* /usr/local/zstack/apache-tomcat/logs/management-server.log* 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.
• Before adjusting management services, databases, certificates, permissions, auditing, or security settings, confirm the HA state, service window, rollback plan, and compliance-retention requirements.
• 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.