Rollback

Rollback Principles

When an upgrade exception occurs, determine the rollback level based on the failure point.

Roll Back the Entry Layer

If only part of the traffic is abnormal, first remove the upgraded instance from Nginx, Ingress, or the load balancer, and route traffic back to the old healthy instance.

This method applies to:

• New version health check failure.
• New version has increased model invocation error rate.
• Console UI loading failure.
• Metrics or log collection failure on one instance.

Roll Back the Application Layer

If the new application fails to start or cannot serve traffic but the database migration has not changed schema or data semantics, restore the old image, application package, and configuration.

docker compose down
docker tag {REGISTRY}/zstack-api-router:{OLD_VERSION} zstack-api-router:current
docker compose up -d

After application rollback, re-run health check, model invocation, Usage Log, and Audit Log verification.

Restore the Database

If migration has changed schema or data semantics and the old application cannot work with the new schema, restore the database from the pre-upgrade backup during an approved maintenance window.

pg_restore -h {DB_HOST} -p {DB_PORT} -U {DB_USER} -d {DB_NAME} --clean --if-exists zstack-api-router-{TIME}.backup

Before database restore, stop all application instances that can write to the database to avoid mixed old and new data.