Introduction

Product Version

This document applies to ZStack API Router preview.

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 Overview

ZStack API Router can run as a standalone API gateway or as part of a ZStack AIOS or LobsterPool inference path. The core service is zr-server. PostgreSQL is used as the runtime database. Database migration must be applied before startup. The optional worker component synchronizes models and probes channel health.

Deployment Modes

Components

Environment Preparation

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

Pre-deployment Checks

Complete these checks before installation:

Single-node Docker Compose Deployment

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.

Production Deployment

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.

Offline Deployment

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.

Post-deployment Validation

Troubleshooting

/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.

Appendix: Common Operations Commands

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/metrics

Query recent usage:

select endpoint, status, upstream_status, count(*) as requests,
       max(created_at) as last_seen
from zr_usage_logs
where created_at >= now() - interval '30 minutes'
group by endpoint, status, upstream_status
order by last_seen desc;