多面板接入概览

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

读者：需要把现有业务系统接到 XCTL Master 的技术人员。

XCTL 作为控制平台，不负责收银与套餐 UI。业务面板（WHMCS、Xboard、自研商城；存量 V2board 见兼容说明）通过不同接入方式连到 Master，由 Master 统一调度 Host、Client 与配置下发。

1. 三种接入方式（先选路径）

接入方式	典型场景	用户从哪来	协议/Inbound 从哪来	面板要不要插件
① 全 Adapter API 自研	WHMCS、自研 BSS、完全自控业务流	业务系统 `POST /api/v1/users`	Master 协议目录 + 模板 render	WHMCS 模块 / 自研 Adapter
② 面板插件 Adapter	继续用 Xboard 收银，但要 XCTL 协议能力	Master 定时拉面板 `/UniProxy/user`	Master 协议目录 + 模板 render；插件读 export 生成订阅	需要（Xboard 插件）
③ 面板全继承	从 XrayR / SOGA 等后端零改造迁移	Master 定时拉面板 `/UniProxy/user`	Master 定时拉面板 `/UniProxy/config`，跟面板节点配置走	不需要

同一租户下可为不同 Node Group 选不同方式（便于渐进迁移），但同一个 Node Group 只能选一种。

怎么选

想要协议目录、多模板、多 SNI、WireGuard、Host 池一致下发 → 选 ① 或 ②（开源面板新部署推荐 ② + Xboard）
只想把物理机托管到 XCTL，面板节点配置完全不动 → 选 ③（迁移兜底）
没有开源面板、订单在自己系统里 → 选 ①

2. 架构角色

┌──────────────┐   ① Adapter API / ②③ UniProxy pull   ┌─────────────┐
│ WHMCS / 面板 │ ◄────────────────────────────────────► │ XCTL Master │
│  业务与订单  │   流量 push / alive（②③）              │ 租户·同步   │
└──────────────┘                                        └──────┬──────┘
                                                                 │ WebSocket
                                                          ┌──────▼──────┐
                                                          │   Client    │
                                                          │  + 3x-ui    │
                                                          └─────────────┘

组件	职责
业务面板	用户注册、套餐、支付；②③ 还承担节点展示与（③）协议配置
Master	多租户、逻辑节点、用户落库、实时下发、设备限制
Client	部署在 Host 上，执行 inbound / 用户同步，上报状态与流量

3. ③ 面板全继承：与 XrayR / SOGA 的关系

面板全继承相当于把 XrayR、SOGA 一类后端的角色交给 XCTL Master：

面板后台照旧配「83 号节点」的端口、协议、TLS/Reality 等
Master 像 XrayR 一样按 node_id 拉 /UniProxy/user 与 /UniProxy/config
Client 仍连 Master，不再每台 VPS 单独跑 XrayR 进程

优点：面板与订阅习惯几乎不用改，迁移成本低。

会缺少或弱化的 XCTL 特性（相对 ①②）：

能力	全继承（③）	插件 Adapter（②）/ 全 API（①）
协议能力目录统一编排	❌ 受面板节点配置能力限制	✅
同逻辑节点多模板 / 多 SNI	❌	✅
多 Host 池内 inbound 字节级一致（DNS 多 A 均衡）	❌ 难保证	✅
WireGuard `peers[]` 动态注入与 `.conf` 交付	❌ 通常不可用	✅
逻辑节点 `group_ids` / `tenant_acl` 精细准入	⚠️ 改走 Node Group 用户关联	✅
订阅由 Master/catalog 统一生成	❌ 仍由面板原生生成	✅（② 经插件 export）
新协议跟 catalog 发版即可上线	❌ 需面板节点类型支持	✅

因此：全继承适合「先迁机器、后迁能力」；若目标是 XCTL 全套协议与编排能力，请规划到 ② 或 ①。

全继承运营约束：面板服务器端口一致

同一 Node Group 下多个面板 node_id 的 server_port 须相同，否则易 drift。Master 只告警、不拦同步。详见主流面板对接。

4. ② 面板插件 Adapter（推荐 Xboard 店铺）

V2board 已停止维护，新部署请用 Xboard。存量 V2board 仍可通过 ③ 全继承 迁到 XCTL，或逐步改配 ②。

面板只管计费与用户 ID；协议统一由 Master 管理：

在 Master 配好逻辑节点与协议模板，完成配置同步
Master 定时从面板拉用户列表，写入本库（与③用户链路相同）
Inbound 不走面板 config，走 Master 模板 render
安装 面板插件，调用 Master export API，把模板快照存到面板节点元数据
用户订阅时由插件拼链接（不用面板原生协议字段）

详见主流面板对接。

5. ① 全 Adapter API 自研

业务系统直接调 Adapter API：

开通 / 续费 / 封禁 → POST/PATCH /api/v1/users
用户带 group_id，由逻辑节点准入过滤
流量 / 事件经 Webhook 或 GET /api/v1/events 回流

WHMCS 走专用模块，本质也是 Adapter 路径，见 WHMCS 插件。

6. 与 Master 内部模型的对应

面板概念	Master 概念
面板节点 ID（如 83）	Node Group 映射的 `panel_node_id`（②③）
节点 / 线路展示	逻辑节点；③ 展示仍跟面板，② 经插件 export
权限组 / 套餐	① `group_id` → 逻辑节点准入；②③ 用户按 Node Group 关联
一套 WHMCS / 一个 Xboard 站（存量 V2board 同理）	租户（Tenant）
VPS	Host + Client

7. 接入前准备

Master 已安装且授权有效
至少一台 Host 在线；①② 需逻辑节点绑定 Host 且同步成功
在 Master 创建租户与凭证（Adapter Token 或面板 ApiHost / ApiKey）
按选定接入方式配置面板插件或 WHMCS 模块

8. 常见问题

Q：我现在用 XrayR，最少改动能怎么迁？
A：选 ③ 面板全继承：面板节点配置不动，Master 填与 XrayR 相同的 ApiHost、ApiKey、NodeID。后续再评估是否升到 ② 以启用协议目录。

Q：② 和 ③ 用户同步一样吗？
A：一样，都是 Master 定时拉 /UniProxy/user 落库；差别只在 inbound 走模板还是走面板 /config。

Q：多个面板会抢同一批 Host 吗？
A：不会。靠租户与 Node Group / group_id 隔离；不同租户可复用同一批 Host，可见线路不同。

下一步

主流面板对接（②③ 配置步骤）
Adapter API（①）
租户与多面板