租户配置 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_MAPPERfrom=to,from2=to2模型改写,from 可含 * 通配;写入时检测循环引用
LEVEL_MAPPERmodel=level,...按模型选择 Key 池分组;model 可含 *,多个通配同时命中时最长者优先
SWITCH_OVERfromLevel=toLevel,...分组级故障切换;拒绝自引用与环
MODEL_FAILOVERmodel=fallback,...模型级故障替换;fallback 必须是已定价模型;检测循环引用
STICKY_LEVELS1,2,3全局粘性调度关闭(STICKY_SCHEDULER=false)时,仅这些 Level 启用粘性会话;* 清空
MODEL_LIMITSJSON模型级限额 {"<上游模型名>": {"rpm": N, "rph": N, "rpd": N, "tpm": N, "tph": N, "tpd": N}};* 清空,-a,b 删除指定模型
PRICINGJSON价格覆盖,结构同 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 的后代账号
ModelLimitsJSON 对象,或 "-model"、"*"所有者本人及全部后代账号的账号级限额
ModelFailover"a=b",整体替换租户 MODEL_FAILOVER
Resources路径列表,整体替换租户 RESOURCES
Gear、Level整数定向:ModelMapper 给出 Gear 或 Level 即只修改匹配的后代、不改租户配置;LevelMapper 必须给出 Level 才定向(Gear 可进一步筛选)
LoadKeystrue重新加载本租户 Key 池
DelKeystrue唤醒本实例中本租户全部休眠的 Key(不删除任何 Key)
SaveCachetrue立即把缓存的用户状态落盘
LogEnabletrue/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),包含当日、当月用量。

相关文档