运维

健康检查

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-backuppg_dump + gzipbackups/postgres/<时间戳>.sql.gz
xsirouter-redis-backupredis-cli --rdbbackups/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 查看。

横向扩展

  1. 所有 API 实例连接同一个 PostgreSQL 与 Redis。
  2. 设置 SINGLE_MODE=false,使限速计数、粘性绑定、Key 与账号变更通知通过 Redis 共享。
  3. 在负载均衡器后运行多个实例;不需要会话保持,粘性会话由 XSI 自身保证。

多实例模式下,分组切换、模型故障替换与 Key 自动休眠仍由各实例独立判断。

容量建议

  • 单个 API 实例即可承载大量并发流式连接;文件描述符上限应保持在模板的 1048576。
  • PostgreSQL 负载主要来自账号与 Key 的读写,用量明细保存在 Redis;Redis 内存随账号数与统计天数增长。
  • 上游连接复用依赖 keep-alive,避免在 API 与上游之间加入会关闭空闲连接的中间设备。

相关文档