用户与权限组
读者：管理终端用户的运维人员；对接自研系统时另阅 Adapter API。
Master 统一管理终端用户（凭证、流量、到期、封禁）与权限组（group_id，决定可见 逻辑节点）。业务面板通过 Adapter API 同步用户；也可在控制台手工维护（适合内测）。
1. 适用场景
Section titled “1. 适用场景”- 自研商城 / 会员系统对接 Master
- 在控制台创建测试账号验证订阅
- 调整用户
group_id实现升档 / 降档线路 - 查看单用户流量、重置 UUID、封禁滥用账号
2. 权限组（group）
Section titled “2. 权限组（group）”权限组是线路档位的抽象，与逻辑节点准入 group_ids 对应：
| 概念 | 说明 |
|---|---|
group_id | 字符串或数字 ID，租户内唯一语义由你定义 |
逻辑节点 group_ids | 允许使用该线路的组列表；空表示不限制该维度 |
| 面板套餐 | 通常一个套餐绑定一个 group_id |
控制台 → 权限组（或集成相关页）可只读查看组列表；创建用户时指定 group_id 即可。
3. 用户字段（常用）
Section titled “3. 用户字段（常用）”| 字段 | 说明 |
|---|---|
biz_ref | 业务主键，{tenant}:{biz_type}:{biz_id} |
group_id | 权限组，决定订阅里有哪些逻辑节点 |
transfer_enable / 已用流量 | 流量配额与统计 |
expired_at | 到期时间 |
banned | 封禁后不可用 |
device_limit | 在线设备上限，见 设备限制 |
speed_limit | 限速（若启用） |
用户变更后进入 配置同步，更新各 Host 上 3x-ui 中的 client 列表。
4. Adapter 同步用户
Section titled “4. Adapter 同步用户”自研系统应调用 Adapter API（Bearer Token 见 租户）：
POST /api/v1/users 创建PATCH /api/v1/users/{biz_ref} 更新DELETE /api/v1/users/{biz_ref} 删除GET /api/v1/users/{biz_ref}/subscribe 订阅内容请求体携带 group_id、流量、到期等字段；biz_ref 必须含租户前缀。字段说明见 Adapter API。
5. 控制台手工操作
Section titled “5. 控制台手工操作”- 用户 → 新建：选租户、填
biz_ref、group_id、流量与到期 - 保存后复制 订阅链接 到客户端测试
- 重置 UUID / 重置流量：运维动作，会写审计
- 封禁：立即生效，client 同步后断开
6. 注意事项
Section titled “6. 注意事项”- 同一租户内
biz_ref唯一；跨租户可重复业务 ID - 改
group_id会改变可见线路，但不清除已用流量 - 面板与控制台同时改同一用户时，以最后写入为准；建议单一真相源（面板或 Master 择一）
7. 常见问题
Section titled “7. 常见问题”Q：订阅里没有某条线路？
A：检查用户 group_id 是否在逻辑节点 group_ids 内；租户是否匹配 tenant_acl。
Q：Xboard 用户和 Adapter 用户冲突吗？
A：不同租户隔离；同一租户应只由一个 Adapter 写入。