主流面板对接

读者：使用 Xboard 等开源面板的运营商。
说明：V2board 已停止维护，新店铺请部署 Xboard；下文「V2board」仅指存量兼容与全继承迁移场景。

Xboard 与 XCTL 对接时，先确认走哪一种接入方式（详见 多面板接入概览）：

方式	一句话
面板全继承	像 XrayR / SOGA：面板配什么协议，Master 就拉什么 config
面板插件 Adapter	面板管用户与计费，协议走 Master 目录 + 插件出订阅
全 Adapter API	不用面板 UniProxy 拉用户，业务直写 Master API（少见于此文）

下文重点讲前两种。

1. 支持的面板类型

面板生态	全继承（③）	插件 Adapter（②）	备注
Xboard	✅ UniProxy /user + /config	✅ /user + export 插件	新部署推荐
V2board（存量）	✅ 同上（NewV2board 协议）	⚠️ 视插件是否仍维护	已停更，建议迁 Xboard
V2RaySocks 等	✅ web_api.php 兼容路径	视插件支持	—
自研	—	—	→ 用 Adapter API

2. 方式 A：面板全继承（XrayR / SOGA 迁移）

适用

• 存量店铺已用 XrayR、SOGA 或仍在运行的 V2board，希望零插件、零改面板节点
• 接受协议能力受面板节点配置限制，暂不启用 XCTL 协议目录

Master 侧

1. 租户 → 填写与 XrayR 相同的 panel_api_host、panel_api_key
2. 创建 Node Group，sync_mode = panel_full（控制台若展示为「全继承面板」即此项）
3. 映射面板 panel_node_id（后台节点管理里的整数 ID）与 panel_node_type（Trojan / Vless / Shadowsocks…）
4. 绑定逻辑节点与 Host

Master 会：

• 定时拉 /UniProxy/user → 用户落库
• 定时拉 /UniProxy/config → 按面板 JSON 下发 inbound（不走协议模板）
• 向面板 /UniProxy/push 回流流量

面板侧

• 无需安装 XCTL 插件
• 节点管理、订阅生成保持面板原生，与 XrayR 时代一致
• 勿指望在 Master 协议目录改模板能影响该 Node Group（互斥）
• 面板不给 TLS 证书；要上正式证可在逻辑节点用 证书中心 引用证书，不必改面板

面板节点服务器端口须一致

多个面板 node_id 映射到同一 Node Group / 逻辑节点 / Host 时，面板节点管理里的 server_port 须相同（即 /UniProxy/config 里的监听端口，不是 Master API 地址）。否则多套 config 落到同一 inbound，易出现 drift 或配置被后一次 pull 覆盖。

Master 会检测并在控制台与 Telegram 告警，但不拦 pull 与 配置同步。仅作分线展示时填同一端口；真要不同端口请拆成不同逻辑节点。

能力边界（必读）

相对 XCTL 完整能力，全继承通常没有：

• 协议目录统一编排、多模板多 SNI
• 多 Host 池内配置字节级一致
• WireGuard 动态 peer 与 .conf
• Master 侧 group_ids 精细线路准入（用户按 Node Group 关联）

迁移后若要这些能力，请改配为 面板插件 Adapter（②）；新面板优先 Xboard。

3. 方式 B：面板插件 Adapter（推荐）

适用

• 使用 Xboard 做收银与用户体系（新部署默认路径）
• 希望用 XCTL 协议目录、逻辑节点 与多 Host 编排

Master 侧

1. 租户填写 panel_api_host / panel_api_key
2. Node Group 选 panel_users_only（「只同步用户」）
3. 在 Master 配置逻辑节点 + 协议模板，绑定 Host，同步成功
4. 在 Node Group 使用 export API（GET …/node-groups/{id}/export）导出订阅参数 JSON

Xboard 插件侧

1. 安装 XCTL 对接插件（版本见 集成与下载）
2. 将 export JSON 存到面板节点元数据（关联 panel_node_id）
3. 用户订阅时由插件用 export 的地址/inbound 参数 + 面板用户 uuid/密码 生成链接
4. 不要在面板后台改该节点的端口/协议（对 XCTL 无效，易混淆）

数据流

面板 /UniProxy/user  ──Master 定时拉──► 用户落库
Master 模板 render   ──同步下发──► Host 3x-ui
插件读 export        ──生成──► 用户订阅链接
Client 流量          ──Master push──► 面板计费

4. 方式 C：全 Adapter API（交叉引用）

若面板不参与 UniProxy 拉取（纯自研订单系统），不走本文，改读 Adapter API 或 WHMCS。

5. 权限组与线路

接入方式	谁能看到哪条线路
全 Adapter / WHMCS	用户 group_id 匹配逻辑节点 group_ids
面板全继承 / 插件 Adapter	用户经 Node Group 与面板 node_id 关联；面板侧仍按套餐展示节点

6. 注意事项

• 面板服务器需能访问 Master（出网 HTTPS）；Master 也需能访问面板 API（②③ 拉用户）
• 设备限制、流量累计以 Master 为准，面板展示为镜像
• 升级 Master 或插件前查看 更新日志
• V2board 存量：可先用 ③ 迁物理机，业务稳定后再迁 Xboard + ②

7. 常见问题

Q：还在用 V2board 怎么办？
A：可继续用 ③ 全继承 托管 Host；长期建议迁 Xboard，再配 ② 插件 Adapter 拿满协议目录能力。

Q：面板显示节点离线？
A：检查 Node Group 映射、panel_node_id、ApiKey；Host 上 Client 是否在线。

Q：全继承能后来改成插件 Adapter 吗？
A：可以，为同一租户新建 Node Group 选 panel_users_only，配好模板与插件后切流量；需规划订阅链接变更。

Q：和 WHMCS 能同时用吗？
A：可以，不同 租户 隔离；WHMCS 走 Adapter，Xboard 走 ② 或 ③。

相关链接

• 多面板接入概览
• Adapter API