ZStack API Router Installation and Deployment Guide

Product Version

This document applies to ZStack API Router 1.0.0.

Intended Audience

This document describes environment preparation, installation, deployment, and post-deployment validation. It is intended for:

• Deployment and operations engineers.
• Platform administrators.
• Technical support engineers.
• Delivery engineers responsible for model gateway deployment.

Deployment Modes

Components

Supported Operating Systems

Component Versions

Hardware Requirements

Network and Port Requirements

TLS and Domain Requirements

Prepare the following for production:

• Public or internal domain, for example api-router.example.com.
• Valid TLS certificate.
• DNS record pointing to Nginx, Ingress, or load balancer.
• Path routing for /api/zr/*, /v1/*, /openai/v1/*, /healthz, /readyz, and /metrics.

Permission and Directory Requirements

Scenario

Use this mode for trial, demo, feature validation, and small environments.

Prerequisites

• Docker and Docker Compose are installed.
• The current user can run Docker commands.
• Local port 3080 and the configured PostgreSQL port are available.

Procedure

1. Enter the deployment directory:

   cd zstack-router

2. Review the environment template:

   sed -n '1,120p' .env.example

3. Start services:

   docker compose up --build -d

4. Check service status:

   docker compose ps

5. View logs:

   docker compose logs -f zr-server
   docker compose logs -f zr-worker

Verification

curl -fsS http://127.0.0.1:3080/healthz
curl -fsS http://127.0.0.1:3080/readyz
curl -fsS http://127.0.0.1:3080/api/zr/openapi.json

Notes

• The Compose default configuration is for validation and should not be used directly for large production deployments.
• Use an independent PostgreSQL instance and configure backups for production.
• If only APIs are required, the console static directory can remain disabled.

Scenario

Use this mode for production workloads with independent PostgreSQL, zr-server, optional zr-worker, and an ingress proxy.

Prerequisites

• Production PostgreSQL is ready.
• Backup strategy is prepared.
• Domain, TLS certificate, and ingress proxy are ready.
• Dedicated runtime user and deployment directories are prepared.

Prepare Database

create user zstack_router with password 'CHANGE_ME';
create database zstack_router owner zstack_router;

Verify connectivity:

psql 'postgres://zstack_router:CHANGE_ME@{DB_HOST}:5432/zstack_router' -c 'select now();'

Configure Environment Variables

Create /etc/zstack-router/zstack-router.env:

ZR_DATABASE_URL=postgres://zstack_router:CHANGE_ME@{DB_HOST}:5432/zstack_router
ZR_BIND_ADDR=0.0.0.0:3080
ZR_PROVIDER_MODE=openai
ZR_CLOUD_TOKEN=Bearer {CLOUD_TOKEN}
ZR_DISCOVERY_TOKEN=Bearer {DISCOVERY_TOKEN}
ZR_CONSOLE_DIST_DIR=/usr/share/zstack-router-console
ZR_PROVIDER_FAILURE_DUMP_DIR=/var/lib/zstack-router/provider-failures

Set permissions:

chmod 600 /etc/zstack-router/zstack-router.env
chown zstack-router:zstack-router /etc/zstack-router/zstack-router.env

Apply Database Migration

export $(grep -v '^#' /etc/zstack-router/zstack-router.env | xargs)
zr-migrate

Start Services

Start zr-server with systemd or a container platform. Start zr-worker if model synchronization and channel health probing are required.

Configure Ingress Proxy

Nginx or Ingress should forward:

Disable response buffering for streaming APIs.

Verification

• Access /healthz and /readyz from the entry domain name.
• Use a test API Key to call /v1/chat/completions.
• Open the console and confirm that Channel, Model, Route Policy, Usage Log, and Audit Log pages can be accessed.
• Confirm that metrics are collected by the monitoring system.

Scenario

Use this mode in air-gapped environments or data centers that cannot access public image registries.

Prerequisites

• Offline deployment package is available.
• Docker and Docker Compose are installed, or prerequisites are included in the package.
• PostgreSQL is prepared or the package-provided database configuration is accepted.

Procedure

1. Upload the offline package to the target server.
2. Extract the package to the deployment directory.
3. Review env.example, docker-compose.yml, and load-and-run.sh.
4. Create and edit .env.
5. Load images and start services:

   bash load-and-run.sh

6. Run health checks.

Notes

• Ensure all deployment files come from the same package version.
• Offline environments still require database backups.
• Include Docker and Compose prerequisites when packaging if the target environment does not provide them.

/readyz Is Abnormal

Possible causes:

• ZR_DATABASE_URL is incorrect.
• PostgreSQL is unreachable.
• zr-migrate has not been executed or failed.

Verify database connectivity, review zr-server logs, and rerun zr-migrate.

Data Plane Cannot Reach Upstream Models

Possible causes:

• Upstream URL is unreachable.
• Credential is incorrect.
• SSRF policy blocks the URL.
• Channel has not synchronized models.

Check network access, channel configuration, model synchronization, Usage Log records, and upstream failure diagnostic files.

Streaming Responses Are Unstable

Possible causes:

• Nginx or Ingress buffers streaming responses.
• Process file descriptor limit is too low.
• PostgreSQL connection pool is insufficient.

Disable buffering for streaming paths, raise LimitNOFILE or container nofile, and tune the database pool.