Single-Node Upgrade

This section applies to a single-node environment deployed by Docker Compose or systemd.

Scenario

Use this procedure for a test environment, proof-of-concept environment, or single-node production environment that can accept a planned interruption.

Prerequisites

• Database backup, deployment directory backup, and entry configuration backup have completed.
• The target package or image has been obtained and verified.
• The upgrade window and rollback contact have been confirmed.

Procedure

1. Stop traffic or notify users.
2. Pull or import the new package.
3. Update configuration.
4. Run database migration.
5. Restart application components.
6. Perform upgrade verification.

Stop traffic or notify users:

If the gateway has no redundant instance, stop upstream traffic or notify users that model invocation may be interrupted during the upgrade.

Pull or import the new package:

For online environments, pull the new image:

docker pull {REGISTRY}/zstack-api-router:{TARGET_VERSION}

For offline environments, import the image:

docker load -i zstack-api-router-{TARGET_VERSION}.tar

Update configuration:

Compare the new example configuration with the current production configuration. Keep existing database, credential, domain name, TLS, and upstream model service settings, and add only required new configuration items.

Run database migration:

Run migration with the target version package. Do not manually edit historical migration files.

docker compose run --rm zr-migrate

If migration fails, stop immediately and keep the error log, migration version, and database backup path.

Restart services:

Restart the application components.

docker compose up -d zr-server zr-worker

Check service status:

docker compose ps
docker compose logs --tail=200 zr-server
docker compose logs --tail=200 zr-worker

Verification

After restart, verify health check, model invocation, Usage Log, Audit Log, Route Policy, quota, and metrics before restoring normal business traffic.