架构

XSI 是一个用 Go 编写的单进程 HTTP 服务:同一个端口既承载模型调用(数据面),也承载账号、Key 与配置管理(控制面)。状态保存在 PostgreSQL 与 Redis 中,两个静态控制台通过 HTTP API 与之交互。

组件

                 ┌──────────────────────────────┐
   应用 / SDK ──▶│                              │──▶ OpenAI / Azure
   Codex      ──▶│   XSI API(Go,:3443)        │──▶ Anthropic
   Claude Code ─▶│   ├─ 数据面:/v1/... 等       │──▶ Gemini / Vertex
   控制台     ──▶│   └─ 控制面:/x-*、/dashboard │──▶ DeepSeek / xAI / ...
                 └───────┬───────────────┬──────┘
                         │               │
                  PostgreSQL           Redis ──▶ 邮件服务(SMTP)
              账号、Key、账本      配置、缓存、用量、
                                   计数、消息、邮件队列
组件镜像职责
APIproxyxai/xsi认证、准入、路由、转发、计量、计费与全部管理接口
控制台proxyxai/xsi-pages配置管理(Admin)与账户管理(Manage)两个静态站点,中英文各一份
邮件服务proxyxai/mail消费 Redis 邮件队列并通过 SMTP 投递;API 本身不直连 SMTP
PostgreSQLpostgres:18账号、上游 Key、充值账本、通知发件箱
Redisredis:alpine租户配置、账号缓存、用量统计、限速计数、粘性绑定、跨实例消息;DB 1 为邮件队列

请求生命周期

请求 ─▶ 体积预检 ─▶ 认证 ─▶ 账号准入 ─▶ 模型解析 ─▶ 模型准入 ─▶ Level ─▶ 选 Key ─▶ 转发
                                                                                 │
        结算 ◀─ 用量提取(旁路解析响应 / SSE) ◀─ 重试(同组换 Key,可跨组) ◀──────┘
  1. 体积预检:声明的 Content-Length 超过上限时,在认证前直接返回 413。
  2. 认证:从 Authorization、x-api-key 或 x-goog-api-key 读取 Key;内存命中直接放行,否则依次查 Redis 与 PostgreSQL。认证失败按 IP 计数并临时封禁。
  3. 账号准入:IP 白名单、账号状态与冻结、日/月额度、余额、账号级限速、资源白名单。
  4. 模型解析:一次扫描 JSON 顶层字段(model、stream、prompt_cache_key、speed、service_tier),按映射规则得到上游模型名,并原地改写请求体或 URL。
  5. 模型准入:模型白名单与模型级限额。
  6. Level 与 Key 选择:按 LEVEL_MAPPER 确定分组,在该组的 Key 池中按粘性会话或轮询选择 Key。
  7. 转发:剥离调用方凭证与转发头,按上游主机改写路径与鉴权头。
  8. 重试:上游返回可重试错误时,在向客户端写出任何字节之前换 Key 重试。
  9. 计量与结算:非流式响应在完整读取后解析用量;SSE 流在转发的同时逐块解析,不缓存整个流。结算在请求结束时执行一次,客户端中途断开也会按实际用量结算。

状态与缓存

层级位置说明
账号热状态进程内存 → Redis → PostgreSQL读按此顺序回源;余额与用量先在内存累计,按批次落 Redis 与数据库
租户配置进程内快照来自 Redis,写时复制;通过发布订阅与每 3 分钟的版本巡检在实例间同步
Key 池进程内,每租户每 Level 一个轮询环懒加载,Key 变更时重建
运行时映射账号与租户的精确匹配缓存通配解析结果沉淀为精确项,避免重复匹配
价格进程内,每租户一份有效价格与模型匹配索引启动时加载 pricing.json,租户覆盖按需合并
用量统计进程内 + Redis每账号每日、每月一份,按模型细分
粘性绑定单实例在内存,多实例在 Redis默认保留 24 小时

PostgreSQL 只保存账号、Key 与账本等权威数据;高频变化的用量统计保存在 Redis。

加密模型

  • 每个租户拥有一把随机生成的租户密钥。上游 Provider Key 与 Vertex 私钥使用租户密钥加密后入库,算法为 XChaCha20-Poly1305。
  • 租户密钥本身用账号自己的 API Key 加密,保存在账号记录中。服务端不保存可直接解开租户密钥的明文材料。
  • 因此,某个租户的 Key 池在该租户有账号发起请求时才能被解密加载;数据库被单独拿走时,上游 Key 无法直接解密。
  • 账号 Key 轮换时,租户密钥会用新 Key 重新加密,旧 Key 立即失效。
  • 进程启动时禁用内存转储。

单实例与多实例

SINGLE_MODE 默认 true。单实例模式下,限速计数、粘性绑定与变更通知都在进程内完成,延迟最低。需要横向扩展时设为 false:

方面单实例(默认)多实例(SINGLE_MODE=false)
限速计数进程内Redis
Key 与账号变更通知进程内通道Redis 发布订阅
粘性绑定内存Redis
用量写入 Redis维护与落盘时每次更新
Key 自动禁用/删除广播—Redis 频道

多实例部署时,分组切换(SWITCH_OVER)、模型故障替换与失败计数仍按实例独立判断;自动休眠也只作用于触发它的实例。

高性能设计

  • 连接复用:所有 HTTP 上游请求共享一个 http.Transport(WebSocket 使用独立的拨号器)(每主机最多 256 个空闲连接、2048 个并发连接,启用 HTTP/2 与 TLS 会话缓存),读写缓冲各 64 KiB,并通过 sync.Pool 复用缓冲区。
  • 零拷贝流式:SSE 响应直接从上游复制到客户端,用量跟踪器在旁路逐块解析,不缓冲整个响应(XSI 请求上游不压缩;个别上游仍返回压缩流时,计量会缓存该响应)。
  • 最小化解析:请求体只扫描一次顶层字段,模型改写用原地 JSON 修改,不做完整反序列化。
  • 异步结算:用量计算、扣费与状态落盘由按账号分片的后台 worker 完成,不阻塞请求路径。
  • 热路径缓存:认证、配置、映射、Key 池与价格均在进程内命中;配置与 Key 池加载使用 singleflight 合并并发回源。
  • 无超时截断:HTTP 服务器只设置读头超时(15 秒)与空闲超时(2 分钟),长时间流式响应不会被服务器截断;上游响应头等待上限默认 1800 秒。

持久化与关闭

  • SIGHUP:执行一次检查点(刷新用量队列、落盘账号状态、Redis SAVE),服务不中断。
  • SIGTERM/SIGINT:停止接收新请求并等待在途请求(最多 20 秒),关闭 WebSocket 会话并等待结算,再执行最终检查点(最多 30 秒)。部署模板的 stop_grace_period: 60s 覆盖这两个阶段。
  • 进程被强制终止(SIGKILL、OOM)时,在途请求不会结算。

相关文档