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: alwayspulls the latest images onup. To pin a version, change the image to a specific tag (such asproxyxai/xsi:<version>) and removepull_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:
| Signal | Behavior |
|---|---|
SIGHUP | Runs a checkpoint immediately: flushes the usage queue, persists account state, runs Redis SAVE. Service is not interrupted |
SIGTERM, SIGINT | Stops 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, OOM | In-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}.
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:
| Service | Method | Output |
|---|---|---|
xsirouter-postgres-backup | pg_dump + gzip | backups/postgres/<timestamp>.sql.gz |
xsirouter-redis-backup | redis-cli --rdb | backups/redis/<timestamp>.rdb |
- The temporary file is renamed to the final file only after a successful backup; a failure may leave a
.tmpfile behind that must be cleaned up manually. - Old backups are pruned with
find -mtime +N, whereNisBACKUP_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 -dCheck the actual names of the named volumes with docker volume ls. For a clean restore of PostgreSQL, empty the target database first.
Data storage
| Data | Location |
|---|---|
| PostgreSQL | Named volume mounted at /var/lib/postgresql; the data directory is /var/lib/postgresql/18/docker |
| Redis | Named 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'sPOST /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
- Connect all API instances to the same PostgreSQL and Redis.
- Set
SINGLE_MODE=falseso that rate limit counters, sticky bindings, and key and account change notifications are shared through Redis. - 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.