架构
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、账本 配置、缓存、用量、
计数、消息、邮件队列| 组件 | 镜像 | 职责 |
|---|---|---|
| API | proxyxai/xsi | 认证、准入、路由、转发、计量、计费与全部管理接口 |
| 控制台 | proxyxai/xsi-pages | 配置管理(Admin)与账户管理(Manage)两个静态站点,中英文各一份 |
| 邮件服务 | proxyxai/mail | 消费 Redis 邮件队列并通过 SMTP 投递;API 本身不直连 SMTP |
| PostgreSQL | postgres:18 | 账号、上游 Key、充值账本、通知发件箱 |
| Redis | redis:alpine | 租户配置、账号缓存、用量统计、限速计数、粘性绑定、跨实例消息;DB 1 为邮件队列 |
请求生命周期
请求 ─▶ 体积预检 ─▶ 认证 ─▶ 账号准入 ─▶ 模型解析 ─▶ 模型准入 ─▶ Level ─▶ 选 Key ─▶ 转发
│
结算 ◀─ 用量提取(旁路解析响应 / SSE) ◀─ 重试(同组换 Key,可跨组) ◀──────┘- 体积预检:声明的
Content-Length超过上限时,在认证前直接返回413。 - 认证:从
Authorization、x-api-key或x-goog-api-key读取 Key;内存命中直接放行,否则依次查 Redis 与 PostgreSQL。认证失败按 IP 计数并临时封禁。 - 账号准入:IP 白名单、账号状态与冻结、日/月额度、余额、账号级限速、资源白名单。
- 模型解析:一次扫描 JSON 顶层字段(
model、stream、prompt_cache_key、speed、service_tier),按映射规则得到上游模型名,并原地改写请求体或 URL。 - 模型准入:模型白名单与模型级限额。
- Level 与 Key 选择:按
LEVEL_MAPPER确定分组,在该组的 Key 池中按粘性会话或轮询选择 Key。 - 转发:剥离调用方凭证与转发头,按上游主机改写路径与鉴权头。
- 重试:上游返回可重试错误时,在向客户端写出任何字节之前换 Key 重试。
- 计量与结算:非流式响应在完整读取后解析用量;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:执行一次检查点(刷新用量队列、落盘账号状态、RedisSAVE),服务不中断。SIGTERM/SIGINT:停止接收新请求并等待在途请求(最多 20 秒),关闭 WebSocket 会话并等待结算,再执行最终检查点(最多 30 秒)。部署模板的stop_grace_period: 60s覆盖这两个阶段。- 进程被强制终止(
SIGKILL、OOM)时,在途请求不会结算。