Adapter API

This page is not available in English yet. Showing Simplified Chinese.

读者：对接自研商城、App 会员等业务系统的技术人员。

Adapter API 是业务系统与 Master 之间的标准接口：把开通、续费、封禁等事件转成用户增删改，Master 负责节点编排与实时下发。请求路径前缀一般为 /api/v1/。

在三种接入方式中，本文对应 ① 全 Adapter API 自研（与「面板全继承」「面板插件 Adapter」并列）。协议与 inbound 由 Master 协议目录管理，不从面板 /UniProxy/config 继承。

1. 适用场景

自研商城、App 会员、内部 BSS
现有插件无法覆盖的定制流程
编写 WHMCS / 面板之外的辅助工具（对账、批量导入）

2. 认证

在租户下签发 Adapter Bearer Token：

Authorization: Bearer <adapter_token>

常见 Scope：

Scope	能力
`users:rw`	用户增删改
`users:r`	用户与订阅只读
`groups:r`	权限组只读
`traffic:r`	流量查询
`events:r`	事件 polling 兜底

明文 Token 只显示一次，请立即复制保存；泄露后在控制台吊销并重新签发。

3. 核心端点（用户）

POST   /api/v1/users
PATCH  /api/v1/users/{biz_ref}
DELETE /api/v1/users/{biz_ref}
GET    /api/v1/users/{biz_ref}
GET    /api/v1/users/{biz_ref}/subscribe
GET    /api/v1/users/{biz_ref}/wireguard/{logical_node_id}.conf

biz_ref 格式：{tenant_id}:{biz_type}:{biz_id}，例如 custom:order:20260605-001。

创建用户示例（字段名以实际接口为准）：

{
  "biz_ref": "custom:member:42",
  "group_id": "premium",
  "transfer_enable": 109951162777600,
  "expired_at": 1780000000,
  "device_limit": 3,
  "banned": false
}

4. 事件回流（Master → 业务）

主路径：Webhook — 在租户配置 webhook_url，Master 对流量等事件 HMAC 签名推送。

兜底：

GET /api/v1/events?cursor=<cursor>
Authorization: Bearer <token with events:r>

轮询增量事件，适合无法公网收 Webhook 的环境。

5. 节点侧 UniProxy（面板用）

Xboard 等使用 Node Token 访问：

GET/POST /api/v1/server/UniProxy/user
GET/POST /api/v1/server/UniProxy/config
POST     /api/v1/server/UniProxy/alivelist

自研若不走 UniProxy，可仅用用户 API + 订阅 URL，由客户端直接拉 Master 订阅。

6. 对接清单

创建租户与 Token
定义 biz_type 与 biz_ref 生成规则
映射套餐 → group_id（对齐逻辑节点准入）
实现开通 / 续费 / 封禁 / 删除调用
实现 Webhook 或 events 消费流量
用测试用户拉订阅验证

7. 注意事项

勿在 Adapter 中直接调 3x-ui API；违反分层，且无法多节点一致
幂等：重复 POST 同一 biz_ref 应返回已有用户或 409，由你方处理
限速：批量导入时遵守 Master per-tenant 限流，分批提交

8. 常见问题

Q：和 Admin API 区别？
A：Adapter 面向业务租户；/api/v1/admin/* 面向运维（主机、逻辑节点、租户管理），用 AdminBearer。

Q：订阅 token 怎么生成？
A：使用 GET .../subscribe 返回的带 HMAC 的 URL；勿自己拼 uuid。