Applicable scenario

• Product: ZCF
• Component: Cloud
• Version: 4.4.x
• Storage: SharedBlock
• Architecture: ARM & x86
• Trigger: A VM reports a volume-count mismatch with the database definition after custom XML configuration.

Symptoms

• Starting a VM reports:

  number of volumes from database [1] not match with xml [0] volumes defined in database

• The issue occurs after custom XML configuration.

Determination method

1. Reproduce the VM startup failure and confirm that the error contains a volume-count mismatch.
2. Confirm that the management node is using the original mevoco-4.4.x.jar.
3. Replace the JAR, restart platform services, and verify that the issue is resolved.

Cause

The remediation requires manually updating mevoco-4.4.x.jar, indicating that the exception is related to the management-node logic package rather than an isolated corruption of VM configuration.

Resolution

1. Preparation

• Risk level: medium.
• Disable global VM HA.
• Back up the platform database.
• Upload the new mevoco-4.4.x.jar to /root/2026.3/ on the management node.

2. Procedure
3. Disable global VM HA.

• Expected result: HA actions are prevented during the change.

2. Back up the platform database:

   zstack-ctl dump_mysql

• Expected result: Database backup is complete.

3. Upload the new mevoco-4.4.x.jar to /root/2026.3/ on the management node.

• Expected result: The replacement file is ready.

4. Stop platform services:

• Single management node:

     zstack-ctl stop

• Dual management nodes:

     zsha2 stop-node

• Expected result: Platform services are stopped and the JAR can be replaced.

5. Back up the original JAR:

   cp /usr/local/zstack/apache-tomcat-8.5.87/webapps/zstack/WEB-INF/lib/mevoco-4.4.0.jar /root/2026.3/mevoco-4.4.0.jar.bak

• Expected result: The original file is retained for rollback.

6. Copy the new JAR to the target directory:

   cp /root/2026.3/mevoco-4.4.0.jar /usr/local/zstack/apache-tomcat-8.5.87/webapps/zstack/WEB-INF/lib/

• Expected result: The new logic package is replaced.

7. Adjust file ownership:

   chown zstack:zstack /usr/local/zstack/apache-tomcat-8.5.87/webapps/zstack/WEB-INF/lib/mevoco-4.4.0.jar

• Expected result: File permissions and ownership are correct.

8. Start platform services:

• Single management node:

     zstack-ctl start

• Dual management nodes:

     zsha2 start-node

• Expected result: The platform resumes operation.

9. Enable HA after replacement is complete.

• Expected result: The platform resumes normal operation.

Verification

• Start the target VM again and confirm that the volume-count/XML mismatch no longer occurs.
• Platform service status is normal.
• HA has returned to normal.

Risks and rollback

• Risk: Replacing a management-node core JAR can cause platform-service exceptions or node disconnection.
• Risk level: medium.
• Rollback: Restore the backed-up mevoco-4.4.x.jar.