运维
健康检查
curl --fail http://127.0.0.1:5443/healthz # 200 OK/healthz 无需认证,适合负载均衡器与容器编排的存活探针。它只反映 HTTP 服务是否就绪,不检查上游可用性。
升级
docker compose pull
docker compose up -d
docker compose ps- 模板的
pull_policy: always会在up时拉取最新镜像;需要固定版本时,把镜像改为具体标签(如proxyxai/xsi:<version>)并去掉pull_policy。 - 数据库结构在 API 启动时自动迁移(GORM AutoMigrate);三个大表索引以
CREATE INDEX CONCURRENTLY创建,其余迁移仍可能短暂持锁,建议在低峰期升级。 - 升级前建议先执行一次检查点(见下文)并确认最近的备份可用。
检查点与优雅关闭
XSI 的余额与用量先在内存中累计,按批次写入 Redis 与 PostgreSQL。以下信号确保数据安全落盘:
| 信号 | 行为 |
|---|---|
SIGHUP | 立即执行一次检查点:刷新用量队列、落盘账号状态、Redis SAVE。服务不中断 |
SIGTERM、SIGINT | 停止接收新请求,等待在途 HTTP 请求(最多 20 秒),关闭 WebSocket 会话并等待结算,再执行最终检查点(最多 30 秒) |
SIGKILL、OOM | 在途请求不会结算,最近一个检查点之后的内存数据可能丢失 |
docker kill --signal=HUP xsirouter-xsi # 手动检查点
docker compose stop xsirouter-xsi # 优雅关闭(宽限期 60 秒)此外,XSI 每 2 小时 15 分钟自动执行一次完整的缓存落盘;也可以由租户所有者调用 POST /x-conf {"SaveCache": true} 触发。
请保留模板中的
stop_grace_period: 60s,并确保容器编排平台给予足够的终止宽限期,避免强制终止造成结算丢失。备份
模板包含两个备份服务,启动后立即执行一次,之后每 86400 秒执行一次:
| 服务 | 方式 | 输出 |
|---|---|---|
xsirouter-postgres-backup | pg_dump + gzip | backups/postgres/<时间戳>.sql.gz |
xsirouter-redis-backup | redis-cli --rdb | backups/redis/<时间戳>.rdb |
- 备份成功后才把临时文件重命名为正式文件;失败时可能留下
.tmp文件,需要手动清理。 - 按
find -mtime +N清理,N为BACKUP_RETENTION_DAYS(默认 3,按整天计)。 - 备份保存在宿主机的
backups/目录,请另行复制到异机或对象存储。
Redis 中保存着租户配置、用量统计与 DeepSeek 文件登记,与 PostgreSQL 同等重要,两者都需要备份。
恢复
docker compose stop xsirouter-xsi xsirouter-mail
# PostgreSQL
gunzip -c backups/postgres/<时间戳>.sql.gz | \
docker exec -i xsirouter-postgres psql -U postgres -d postgres
# Redis:停止 Redis,替换 RDB 后再启动
docker compose stop xsirouter-redis
docker run --rm -v xsi_redis_data:/data -v "$PWD/backups/redis:/backups" alpine \
cp /backups/<时间戳>.rdb /data/dump.rdb
docker compose up -d命名卷的实际名称以 docker volume ls 为准。恢复 PostgreSQL 前,如需全新恢复,请先清空目标数据库。
数据存储
| 数据 | 位置 |
|---|---|
| PostgreSQL | 命名卷挂载至 /var/lib/postgresql,数据目录为 /var/lib/postgresql/18/docker |
| Redis | 命名卷挂载至 /data |
删除容器不会删除命名卷;docker compose down -v 会删除卷中的全部数据。
日志
docker compose logs -f xsirouter-xsi
docker compose logs -f xsirouter-mail- API 日志包含启动、检查点、上游异常与告警信息。
LOG_ENABLE=true(或租户所有者POST /x-conf {"LogEnable": true})会记录请求体,仅在排障时短时开启。- 账号级的管理操作日志可通过
GET /dashboard/logs查看。
横向扩展
- 所有 API 实例连接同一个 PostgreSQL 与 Redis。
- 设置
SINGLE_MODE=false,使限速计数、粘性绑定、Key 与账号变更通知通过 Redis 共享。 - 在负载均衡器后运行多个实例;不需要会话保持,粘性会话由 XSI 自身保证。
多实例模式下,分组切换、模型故障替换与 Key 自动休眠仍由各实例独立判断。
容量建议
- 单个 API 实例即可承载大量并发流式连接;文件描述符上限应保持在模板的 1048576。
- PostgreSQL 负载主要来自账号与 Key 的读写,用量明细保存在 Redis;Redis 内存随账号数与统计天数增长。
- 上游连接复用依赖 keep-alive,避免在 API 与上游之间加入会关闭空闲连接的中间设备。