Operations

Health check

curl --fail http://127.0.0.1:5443/healthz   # 200 OK

/healthz requires no authentication and is suitable as a liveness probe for load balancers and container orchestrators. It only reflects whether the HTTP service is ready; it does not check upstream availability.

Upgrades

docker compose pull
docker compose up -d
docker compose ps
  • The template's pull_policy: always pulls the latest images on up. To pin a version, change the image to a specific tag (such as proxyxai/xsi:<version>) and remove pull_policy.
  • The database schema is migrated automatically when the API starts (GORM AutoMigrate); indexes on the three large tables are built with CREATE INDEX CONCURRENTLY, but other migrations may still hold locks briefly, so upgrade during off-peak hours.
  • Before upgrading, run a checkpoint (see below) and confirm that the latest backup is usable.

Checkpoints and graceful shutdown

XSI accumulates balances and usage in memory first and writes them to Redis and PostgreSQL in batches. The following signals make sure data is safely persisted:

SignalBehavior
SIGHUPRuns a checkpoint immediately: flushes the usage queue, persists account state, runs Redis SAVE. Service is not interrupted
SIGTERM, SIGINTStops accepting new requests, waits for in-flight HTTP requests (up to 20 seconds), closes WebSocket sessions and waits for their settlement, then runs a final checkpoint (up to 30 seconds)
SIGKILL, OOMIn-flight requests are not settled, and in-memory data since the last checkpoint may be lost
docker kill --signal=HUP xsirouter-xsi     # Manual checkpoint
docker compose stop xsirouter-xsi          # Graceful shutdown (60-second grace period)

In addition, XSI automatically flushes the full cache every 2 hours 15 minutes; a tenant owner can also trigger it with POST /x-conf {"SaveCache": true}.

Keep stop_grace_period: 60s from the template, and make sure your container orchestrator allows a long enough termination grace period, so that forced termination does not lose settlements.

Backups

The template includes two backup services. Each runs once immediately at startup and then every 86400 seconds:

ServiceMethodOutput
xsirouter-postgres-backuppg_dump + gzipbackups/postgres/<timestamp>.sql.gz
xsirouter-redis-backupredis-cli --rdbbackups/redis/<timestamp>.rdb
  • The temporary file is renamed to the final file only after a successful backup; a failure may leave a .tmp file behind that must be cleaned up manually.
  • Old backups are pruned with find -mtime +N, where N is BACKUP_RETENTION_DAYS (default 3, counted in whole days).
  • Backups are stored in the host's backups/ directory. Copy them to another machine or to object storage.

Redis holds tenant configuration, usage statistics, and DeepSeek file records, and is as important as PostgreSQL. Back up both.

Restore

docker compose stop xsirouter-xsi xsirouter-mail

# PostgreSQL
gunzip -c backups/postgres/<timestamp>.sql.gz | \
  docker exec -i xsirouter-postgres psql -U postgres -d postgres

# Redis: stop Redis, replace the RDB file, then start again
docker compose stop xsirouter-redis
docker run --rm -v xsi_redis_data:/data -v "$PWD/backups/redis:/backups" alpine \
  cp /backups/<timestamp>.rdb /data/dump.rdb
docker compose up -d

Check the actual names of the named volumes with docker volume ls. For a clean restore of PostgreSQL, empty the target database first.

Data storage

DataLocation
PostgreSQLNamed volume mounted at /var/lib/postgresql; the data directory is /var/lib/postgresql/18/docker
RedisNamed volume mounted at /data

Removing a container does not remove its named volumes; docker compose down -v deletes all data in the volumes.

Logs

docker compose logs -f xsirouter-xsi
docker compose logs -f xsirouter-mail
  • API logs include startup, checkpoints, upstream errors, and alerts.
  • LOG_ENABLE=true (or a tenant owner's POST /x-conf {"LogEnable": true}) logs request bodies; enable it only briefly while troubleshooting.
  • Account-level management operation logs are available through GET /dashboard/logs.

Horizontal scaling

  1. Connect all API instances to the same PostgreSQL and Redis.
  2. Set SINGLE_MODE=false so that rate limit counters, sticky bindings, and key and account change notifications are shared through Redis.
  3. Run multiple instances behind a load balancer. No session affinity is needed; XSI handles sticky sessions itself.

In multi-instance mode, group switchover, model failover, and key auto-sleep are still decided independently by each instance.

Capacity guidance

  • A single API instance can handle a large number of concurrent streaming connections; keep the file descriptor limit at the template's 1048576.
  • PostgreSQL load comes mainly from account and key reads and writes, while usage details live in Redis; Redis memory grows with the number of accounts and days of statistics.
  • Upstream connection reuse relies on keep-alive; avoid placing middleboxes that close idle connections between the API and the upstreams.