租户配置 API
租户配置 API
每个租户(Owner)拥有一份独立配置,保存在 Redis 中并在所有 XSI 实例间自动同步(发布订阅通知,另有每 3 分钟一次的版本巡检)。所有接口都要求调用者是租户所有者,且只作用于调用者自己的租户。
export XSI_BASE_URL="https://api.xsicontrol.com" # 或你自己的 API 域名
export XSI_API_KEY="sk-Xvs..." # 租户所有者的 Key| 接口 | 用途 |
|---|---|
GET/PUT/POST/DELETE /x-config | 租户配置的读取、整体写入与恢复默认(推荐) |
GET/POST /x-conf | 运行时状态查看、映射的增量修改并同步到子账号、运维指令 |
GET /x-info | 查询本租户内任一账号的详细信息 |
配置项
| 键 | 格式 | 说明 |
|---|---|---|
MODEL_MAPPER | from=to,from2=to2 | 模型改写,from 可含 * 通配;写入时检测循环引用 |
LEVEL_MAPPER | model=level,... | 按模型选择 Key 池分组;model 可含 *,多个通配同时命中时最长者优先 |
SWITCH_OVER | fromLevel=toLevel,... | 分组级故障切换;拒绝自引用与环 |
MODEL_FAILOVER | model=fallback,... | 模型级故障替换;fallback 必须是已定价模型;检测循环引用 |
STICKY_LEVELS | 1,2,3 | 全局粘性调度关闭(STICKY_SCHEDULER=false)时,仅这些 Level 启用粘性会话;* 清空 |
MODEL_LIMITS | JSON | 模型级限额 {"<上游模型名>": {"rpm": N, "rph": N, "rpd": N, "tpm": N, "tph": N, "tpd": N}};* 清空,-a,b 删除指定模型 |
PRICING | JSON | 价格覆盖,结构同 api/pricing.json,见下文 |
RESOURCES | 路径列表 | 租户级资源白名单。当前版本仅保存与展示,代理以账号级 Resources 为准 |
XAI_MAIL | 邮箱 | 租户通知收件人(未知模型、故障切换、支付通知等) |
EMAIL_SMTP、EMAIL_PORT、EMAIL_AUTH、EMAIL_PASS、EMAIL_SENDER | 字符串 | 租户自有 SMTP;未配置时使用部署的默认邮件配置。EMAIL_PASS 只写不读 |
SIGNUP_ALLOW_DOMAINS、SIGNUP_DENY_DOMAINS | 域名规则 | 自助注册的邮箱域名白名单与黑名单,仅 root 可读写 |
分隔符:,、; 或中文逗号 ,。语义细节见《路由与故障转移》《计费与价格》。
读取配置
curl "$XSI_BASE_URL/x-config" -H "Authorization: Bearer $XSI_API_KEY"{
"success": true,
"oid": 1,
"configs": {
"MODEL_MAPPER": {"gpt-latest": "gpt-6.2-sol"},
"MODEL_FAILOVER": {},
"LEVEL_MAPPER": {"gpt*": 1, "claude*": 2},
"SWITCH_OVER": {"1": 3},
"STICKY_LEVELS": "",
"STICKY_SCHEDULER": true,
"RESOURCES": {},
"MODEL_LIMITS": {"gpt-6.2-sol": {"rpm": 60, "rph": 3600, "rpd": 86400, "tpm": 1000000, "tph": 999999999999999999, "tpd": 999999999999999999}},
"PRICING": "",
"XAI_MAIL": "[email protected]",
"EMAIL_PORT": "465",
"EMAIL_SMTP": "smtp.example.com",
"EMAIL_AUTH": "[email protected]",
"EMAIL_SENDER": "XSI <[email protected]>"
}
}STICKY_SCHEDULER反映全局环境变量,只读。PRICING以原始 JSON 字符串返回。- 未配置的邮件字段返回部署的默认值。
写入配置
PUT 与 POST 等价。请求体是 {键: 字符串值},每个键整体替换:
curl -X PUT "$XSI_BASE_URL/x-config" \
-H "Authorization: Bearer $XSI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"LEVEL_MAPPER": "gpt*=1, claude*=2, deepseek*=3",
"MODEL_MAPPER": "gpt-latest=gpt-6.2-sol",
"SWITCH_OVER": "1=3",
"MODEL_LIMITS": "{\"gpt-6.2-sol\":{\"rpm\":60,\"tpm\":1000000}}"
}'{"success": true, "updated": {"LEVEL_MAPPER": "gpt*=1,claude*=2,deepseek*=3"}, "message": "Config updated successfully"}- 逐键校验;有效的键在一次原子操作中写入。
- 部分键无效时仍返回
200,但success为false,错误见errors;全部无效时返回400。 - 常见错误:
Invalid config key、Circular reference detected: a → b → a、Invalid switch configuration: ...、Invalid MODEL_LIMITS format: ...、Invalid sender address、Only root can modify this config。
PRICING
PRICING 的值与 api/pricing.json 同结构(顶层 ChatPricing、ImgPricing、VideoPricing、AudioPricing、RerankPricing、CallPricing、FineTuningPricing),按模型整条替换系统默认价格,也可新增模型:
{
"ChatPricing": {
"gpt-6.2-sol": {"InputText": 2, "CachedText": 0.1, "CacheWrite": 2.5, "OutputText": 10, "Rates": 8}
}
}- 原文 ≤ 128 KiB,条目 ≤ 1024 个;拒绝未知字段;数值必须为有限非负数。
- 整条替换意味着覆盖条目中未写的字段为 0。务必写出
Rates,否则该模型的 Token 费用为 0。 - 字段含义见《计费与价格》。
注册域名规则(仅 root)
{"SIGNUP_ALLOW_DOMAINS": "example.com, *.example.org", "SIGNUP_DENY_DOMAINS": "mailinator.com"}*.example.org或.example.org匹配全部子域名,同时匹配example.org本身;@、结尾的.会被去除。- 先检查白名单(非空时必须命中),再检查黑名单。
恢复默认
curl -X DELETE "$XSI_BASE_URL/x-config" \
-H "Authorization: Bearer $XSI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"keys": ["MODEL_FAILOVER", "STICKY_LEVELS"]}'响应:{"success": true, "deleted": ["MODEL_FAILOVER", "STICKY_LEVELS"], "message": "Config deleted successfully"}。
运行时控制 /x-conf
查看
curl "$XSI_BASE_URL/x-conf" -H "Authorization: Bearer $XSI_API_KEY"返回 Resources、LevelMapper、ModelMapper、ModelFailover、ModelLimits、SwitchOver,以及:
| 字段 | 说明 |
|---|---|
SleepingKeys | 本实例中正在休眠的 Key(含上游 Key 明文) |
DisabledKeys | 已禁用的 Key(含上游 Key 明文) |
UserMinBalance、UserApiBalance | 冻结阈值与管理者余额门槛(全局环境变量) |
修改
POST /x-conf 的映射写法是增量命令,并会把变更同步到子账号:
| 字段 | 写法 | 作用范围 |
|---|---|---|
ModelMapper | "a=b, c*=d" 设置;"-a" 删除;"*" 清空 | 租户 MODEL_MAPPER、所有者本人及全部后代账号 |
LevelMapper | 同上,值为 Level 整数;不存在的 Level 被忽略 | 租户 LEVEL_MAPPER 及 Gear ≤ 0 的后代账号 |
ModelLimits | JSON 对象,或 "-model"、"*" | 所有者本人及全部后代账号的账号级限额 |
ModelFailover | "a=b",整体替换 | 租户 MODEL_FAILOVER |
Resources | 路径列表,整体替换 | 租户 RESOURCES |
Gear、Level | 整数 | 定向:ModelMapper 给出 Gear 或 Level 即只修改匹配的后代、不改租户配置;LevelMapper 必须给出 Level 才定向(Gear 可进一步筛选) |
LoadKeys | true | 重新加载本租户 Key 池 |
DelKeys | true | 唤醒本实例中本租户全部休眠的 Key(不删除任何 Key) |
SaveCache | true | 立即把缓存的用户状态落盘 |
LogEnable | true/false | 切换本进程的请求体日志(不持久化,仅当前实例) |
curl -X POST "$XSI_BASE_URL/x-conf" \
-H "Authorization: Bearer $XSI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ModelMapper": "gpt-latest=gpt-6.2-sol, -legacy-model", "LoadKeys": true}'响应只包含本次处理过的字段。处理按固定顺序进行,中途出错返回 500,已生效的修改不回滚。
选择 /x-config 还是 /x-conf?
/x-config 是声明式的整体配置,只写租户配置本身,适合版本化管理;/x-conf 是命令式的增量修改,会同步改写子账号上的映射与限额,适合在线调整。账号会缓存模型别名的解析结果,因此修改 MODEL_MAPPER 后需要已有账号立即生效时,请使用 /x-conf。普通所有者单次同步最多覆盖 8192 个后代;root 通过 /x-conf 修改 ModelMapper 或 ModelLimits 时会作用于所有租户的账号,请谨慎使用。查询账号详情 /x-info
curl "$XSI_BASE_URL/x-info?u=dev-a" -H "Authorization: Bearer $XSI_API_KEY"- 参数
u(或user)为账号 ID 或账号名;缺少时返回400 User parameter is required。 - 可查询本租户任意深度的账号(包括所有者自己);其他租户的账号返回
404 User not found。 - 响应结构同
GET /dashboard/live(snake_case),包含当日、当月用量。