WHMCS 插件

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

读者：使用 WHMCS 收单、希望自动开通代理服务的运营商。

WHMCS 负责订单、账单与客户门户；XCTL Master 负责用户凭证、逻辑节点与实时下发。二者通过 WHMCS Server Module + Addon 对接 Master Adapter API，Master 本身不存储订单字段。

1. 适用场景

已有 WHMCS 卖 VPS / 代理套餐，希望付款后自动创建订阅用户
需要在 WHMCS 客户区展示订阅链接、流量用量
与 Xboard 等面板并行时，为 WHMCS 单独建租户（如 whmcs-main）

2. 架构角色

WHMCS 订单事件
    → Server Module（开通/暂停/续费/删除）
        → Master Adapter API（用户 CRUD）
            → 配置同步 → 节点

Master 流量/事件
    → Webhook 或 GET /api/v1/events
        → WHMCS Hook / Cron 回写用量

插件只做事件翻译：把 CreateAccount、SuspendAccount 等翻译成 Master 标准用户 API，不直接操作 3x-ui。

3. 前置条件

Master 已安装且授权有效
至少一条逻辑节点已绑定 Host 并同步成功
在 Master 创建租户 whmcs-main（名称可自定），签发 Adapter Token
WHMCS 版本与 PHP 环境满足插件要求（通常 PHP 7.4+、curl、openssl）

4. 安装插件

插件包一般包含：

modules/servers/XUICTLPlus/ — Server Module（产品开通生命周期）
modules/addons/xuictl_panel/ — Addon（Master 地址、全局配置）

典型步骤：

将模块目录解压到 WHMCS 的 modules/servers/ 与 modules/addons/
在模块目录执行 composer install --no-dev（若插件带 Composer 依赖）
WHMCS 后台 → 系统设置 → 插件模块 → 启用 XUI CTL+ Panel Addon
填写 Master URL、租户 ID、Adapter Token、Webhook Secret
系统设置 → 服务器 → 添加服务器，类型选 XUICTLPlus，主机名填 Master 域名

5. 配置产品（Product）

套餐 → 新增产品 → 模块选择 XUICTLPlus
Config Options 常见映射（以插件实际字段为准）：
- 权限组 / group_ref → 对应 Master 中用户 group_id，决定可见逻辑节点
- 流量配额（GB） → transfer_enable
- 到期日 → 随 WHMCS 账单周期写入 expired_at
- 设备数 / 限速 → device_limit、speed_limit
保存产品并测试下单

开通时插件构造 biz_ref，格式为 {tenant_id}:service:{serviceid}，保证与 Master 多租户规范一致。

6. 生命周期事件

WHMCS 动作	Master 侧效果
CreateAccount	创建或幂等恢复用户，下发同步
SuspendAccount	`banned=1`，停止可用
UnsuspendAccount	解除封禁
TerminateAccount	删除用户
ChangePackage / Renew	更新 `group_id`、流量、到期时间

流量与在线数据由 Master 汇总，经 Webhook 或定时 GET /api/v1/events 拉回 WHMCS 展示（具体以插件版本为准）。

7. 客户区订阅

订阅 URL 由 Master 签发（HMAC token），插件在 WHMCS 客户区嵌入或跳转
客户看到的线路列表 = 其 group_id 能匹配到的逻辑节点
勿让客户直接登录 3x-ui 面板

8. 注意事项

WHMCS 与 Master 之间必须 HTTPS 互通；内网部署注意证书链
开通失败时先查 Master 审计日志与 WHMCS Module Log，再查配置同步
升级 Master 后同步升级 WHMCS 模块，避免 API 字段不一致
WHMCS 与 Xboard 同时使用时务必不同租户、不同 Token

9. 常见问题

Q：付款成功但 WHMCS 显示开通失败？
A：检查 Adapter Token Scope 是否含 users:rw；biz_ref 是否重复；Master 授权是否有效。

Q：客户订阅为空？
A：用户 group_id 与逻辑节点 group_ids 准入不匹配；或逻辑节点未 enabled / 未同步。

Q：流量不同步？
A：确认 Webhook URL 可达、Secret 一致；或启用 Cron 拉取 events 兜底。