账号体系
XSI 用一棵账号树承载多租户与多层分销:平台、租户、团队、成员或客户都是树上的账号。每一层都可以在上层授予的边界内,继续为下层分配额度、模型与权限。
角色
| 角色 | 判定 | 能力 |
|---|---|---|
| root | DNA == ".",由 INIT_USERS 中名为 root 的账号创建 | 平台超级管理员:系统公告、注册域名策略、管理全部账号 |
| 租户所有者(Owner) | ID == OID | 拥有独立的上游 Key 池、租户配置与价格;可直接发放额度 |
| 管理者(Manager) | 满足管理条件的任意账号 | 创建、更新、删除自己的后代账号,查看后代用量 |
| 普通账号 | 其他 | 调用模型,查看自己的用量,轮换自己的 Key |
管理条件:同时满足 TPD > 800000000、具备子账号能力(UserLimit > 0 或已有子账号)、余额高于 USER_API_BALANCE(默认 100)。root 不受此限制。
租户
| 部署模式 | 租户结构 |
|---|---|
单租户(SINGLE_TENANT=true,默认) | 自助注册的账号加入 root 租户,共享 root 的 Key 池与配置,适合企业内部或单一品牌的 API 服务。INIT_USERS 中除 root 外的账号会各自成为独立租户,若要所有账号共用 root 的 Key 池,只初始化 root 并在其下创建账号 |
多租户(SINGLE_TENANT=false) | 每个自助注册的用户成为一个独立租户,拥有自己的 Key 池(BYOK)、配置、价格与账号树,适合面向团队或服务商的云服务 |
租户之间完全隔离:Key、配置与价格按 OID 隔离,账号管理按 DNA 子树隔离。
账号标识
| 字段 | 说明 |
|---|---|
ID | 账号 ID |
PID | 直接父账号 ID |
OID | 所属租户所有者的 ID |
DNA | 祖先 ID 路径(不含自身) |
Name / Email | 全局唯一的账号名与邮箱 |
SecretKey | API Key,sk-Xvs 开头的 51 位字符串,只在创建或轮换时返回明文 |
PublicKey | 公开标识 pk-Xvs...,用于推荐注册 |
DNA
root 的 DNA 为 .;子账号的 DNA 为 父账号 DNA + 父账号 ID + "."。
root (ID 1) DNA = .
└─ team-a (ID 5) DNA = .1.
└─ dev-a (ID 9) DNA = .1.5.
└─ bot (ID 12) DNA = .1.5.9.- A 是 B 的祖先,当且仅当 B 的 DNA 包含
.A.ID.。 - 账号 X 的全部后代即 DNA 以
X.DNA + X.ID + "."开头的账号。 - 查询接口支持按 DNA 前缀筛选整条分支,例如
GET /x-dna/.1.5.。
继承与收窄
创建子账号时,以下属性继承父账号:Level、Gear、Role、日额度、资源白名单、IP 白名单、模型白名单、Level 白名单、模型限额、模型映射与 Level 映射。
之后由普通管理者进行的调整遵循“只能收窄,不能放大”(租户所有者可以在系统上限内独立设置后代的价格、路由档位与限速):
| 属性 | 规则 |
|---|---|
Rates | 不低于父账号 |
Factor | 父账号是租户所有者时不低于父账号;否则等于父账号 |
RPM … TPD | 不高于父账号(以操作者为准) |
Resources、AllowModels、AllowIPs | 与操作者的范围取交集 |
UserLimit | 不高于父账号;父账号非 root 且自身 UserLimit < 64 时子账号为 0 |
Level、Role、Factor、LevelMapper | 只有租户所有者可以修改 |
管理者可以管理任意深度的后代,钳制以操作者自己的边界为准。
额度流转
| 操作 | 租户所有者 | 普通管理者 |
|---|---|---|
| 给子账号发放额度 | 直接发放,不扣自身余额 | 从自身余额划转,按 子.Rates ÷ 父.Rates 折算,保留原额度的有效期与资金类型 |
| 扣回额度 | 直接从目标扣减 | 退回自身余额;每次更新收取一次 XAPI_FEE,扣回再额外收取一次 |
| 删除子账号 | 目标 TPD > 800000000 时剩余正余额折算退回操作者,否则作废;欠款由操作者承担 | 同左,且还须与目标 Level 相同才退回 |
删除账号是硬删除且不级联:被删账号的子账号保留在原分支中,由上层祖先继续管理。
计划跟随
父账号不是租户所有者的账号,其 Level 与价格跟随父账号(GET /dashboard/status 中 plan_follows_parent 为 true)。普通管理者更新一个 Level 与自己不同的子账号时,会先清空其正余额,再把它对齐到自己的 Level。
典型结构
企业内部
root
├─ 研发部(管理者,Level 1,月额度 ¥20,000)
│ ├─ 前端组
│ └─ 后端组
└─ 客服部(AllowModels: gpt-6-luna claude-haiku-5-5)API 分销
root
├─ 渠道 A(Rates 1.0)
│ └─ 客户 A1(Rates 1.2,差价归渠道 A)
└─ 渠道 B(Rates 1.1,Factor 0.9)