租户与多面板

读者：同一套 Master 对接多个业务源的管理员。

租户（Tenant） 代表一个独立的业务前端实例，例如一套 WHMCS、一个 Xboard 站、或自研订单系统。Master 通过租户实现数据隔离、独立 Token 与 Webhook 回流，使多面板并行接入而不互相串数据。

1. 适用场景

• 同时运营 WHMCS 与 Xboard，共用同一批 Host 但用户隔离
• 为代理商或子品牌开设独立租户，配额计入 套餐 租户数
• 测试环境与生产环境共用 Master（不推荐长期如此，但可用租户区分）

2. 核心概念

术语	说明
tenant_id	全局唯一标识，建议 [a-z0-9-]，≤32 字符，如 whmcs-main、xboard-cn
biz_ref	用户业务主键：{tenant_id}:{biz_type}:{biz_id}，如 whmcs-main:service:1234
Adapter Token	面板调 Master 用户 API 的 Bearer 凭证，按租户签发
Node Token	UniProxy 路径用的节点侧凭证（Xboard 等）
Webhook URL	Master 向业务系统推送流量/事件的目标地址

同一 biz_id 在不同租户下是不同用户；Master 内部用 master_user_id 保证全局唯一。

3. 创建租户

1. 控制台 → 租户 → 新建
2. 填写 tenant_id、展示名称、biz_type（whmcs / xboard / custom 等；存量 V2board 可填 v2board）
3. 配置 Webhook URL（可选，用于事件与流量回流）
4. 保存后进入 Token 子页

若 tenant_id 已被占用，API 返回冲突，请更换名称。

4. 签发 Token

在租户详情 → Tokens：

Token 类型	用途	典型 Scope
Adapter	用户 CRUD、订阅查询	users:rw、groups:r、events:r
Admin（租户级）	受限运维账号绑定租户	仅能见本租户数据

1. 点击 新建 Token，勾选所需 Scope
2. 复制明文 Token（只显示一次），写入面板插件或自研 Adapter 配置
3. 泄露或轮换时 吊销 旧 Token 再签新

面板插件中填写的 Master 根 URL 一般为 https://你的域名，API 前缀以插件文档为准（常见为 /api/v1/）。

5. 与逻辑节点、用户的关系

• 用户归属租户；Adapter 创建用户时必须带正确 tenant_id（由 Token 隐式限定）
• 逻辑节点准入可配置 tenant_acl：只允许指定租户的用户看见该线路
• 权限组（group_id）在租户内命名；与面板套餐等级对应，见 用户与权限组

多租户共享同一批 Host 时，靠 tenant_acl + group_ids 控制可见线路，而非复制节点。

6. 多面板并行示例

租户 whmcs-main  ──Adapter──► Master ◄──UniProxy── 租户 xboard-cn
                                      │
                                 共享 Host 池
                                      │
                              逻辑节点 + 同步下发

WHMCS 走 WHMCS 插件；Xboard 走 主流面板对接。各自使用不同租户与 Token。

7. 注意事项

• 租户数受 License 限制（Free 1 / Pro 1 / Team 3 / Ultra 无限）
• Token 只显示一次，请复制后妥善保存；勿发给无关人员，泄露后立即吊销并重新签发
• 删除租户前确认已迁移或清理用户，避免残留 biz_ref 订阅

8. 常见问题

Q：两个面板能用同一个 tenant_id 吗？
A：不行。一个 tenant 对应一套业务实例；第二套面板应新建租户。

Q：租户管理员账号是什么？
A：可在 Admin 用户上绑定 tenant_id，登录后控制台与审计自动按租户过滤。

Q：节点能不能只给某一个租户用？
A：在逻辑节点 tenant_acl 中限制；Host 本身不存租户准入。

相关链接

• 多面板接入概览
• Adapter API