跳到主要内容

安装

本页将安装 Perfex CRM Integration for WHMCS 的两个组件。请按顺序操作。整个过程只需两个浏览器标签页加上主机面板的 File Manager 即可完成，无需 SSH，也无需命令行。

您应当已经解压了 upload.zip (themesic.com/marketplace/whmcs-perfex.zip)，得到两个文件：

文件安装到
🧩 perfex-module/module.zipPerfex CRM
⚙️ whmcs-addon/addon.zipWHMCS

快速安装（精简版）​

对于有经验的主机管理员来说，整个过程只需五步。请按此顺序操作。

  1. 🧩 先装 Perfex。 在 Perfex CRM 中，前往 Setup > Modules > Upload Module，上传 module.zip，然后点击 Activate。先安装 Perfex 端意味着在 WHMCS 发送任何内容之前，接收端点就已经存在。
  2. ⚙️ WHMCS 插件。 将 addon.zip 上传并解压到 modules/addons/，最终得到 modules/addons/perfexbridge/perfexbridge.php，然后在 System Settings > Addon Modules 下激活 Perfex CRM Bridge。
  3. 🔓 勾选 Access Control。 在插件的 Configure 界面上，勾选 Full Administrator（以及其他应当使用它的角色），然后点击 Save Changes。不做这一步，模块就不可见 - 它根本不会出现在 Addons 菜单中。
  4. 🔗 配对两端。 打开 Addons > Perfex CRM Bridge，把从 Perfex 复制的 Connection code 粘贴到 Quick setup 输入框中，然后点击 Connect。详见配置。
  5. ✅ 验证。 在 WHMCS 中创建一个测试客户，点击 Run Sync Now，并确认它出现在 Perfex 的 Customers 下。

每一次点击、每一个检查项以及完整的端到端验证，都在下面的详细步骤中。

详细步骤​

顺序很重要

请先安装 Perfex 配套模块。它会创建接收端点。如果先安装 WHMCS 插件并开始同步，在 Perfex 端就绪之前每个事件都会失败，您会浪费时间去排查一个尚未真正发生的问题。

第 1 步：安装 Perfex CRM 配套模块​

Perfex 配套模块是免费的，不需要授权密钥，完全在 Perfex 后台中完成安装。

  1. 以管理员身份登录 Perfex CRM。
  2. 前往 Setup > Modules。
  3. 点击 Upload Module 按钮。
  4. 在文件选择器中选择 module.zip 并上传。
  5. Perfex 会将该模块列为 WHMCS Bridge。如有提示请点击 Install，然后点击 Activate。
如果上传因文件过大被拒绝

Upload Module 按钮通过 PHP 提交压缩包，因此服务器的 upload_max_filesize 和 post_max_size 限制都必须大于该文件。如果上传失败，请在 PHP 配置中调高这两个限制，或采用下面的手动方案。

手动方案： 在您的电脑上解压 module.zip，然后通过 FTP 或主机面板的 File Manager 将得到的 whmcs_bridge 文件夹上传到 Perfex 安装目录的 modules/ 目录中。最终结果必须是 modules/whmcs_bridge/whmcs_bridge.php。然后回到 Setup > Modules 并点击 Activate。

确认 Perfex 端安装正确​

  • Perfex 的 Setup 菜单下会出现新的 WHMCS Bridge 条目。下一章将在该页面生成共享密钥。

第 2 步：安装 WHMCS 插件​

WHMCS 没有后台内置的模块安装器。您需要自己把文件放到磁盘上，然后在后台激活。主机面板的 File Manager 就能完成全部操作。

  1. 打开主机面板的 File Manager，进入 WHMCS 安装目录的 modules/addons/ 目录。
  2. 将 addon.zip 上传到 modules/addons/。
  3. 对上传的文件使用 File Manager 的 Extract 操作，解压到同一个 modules/addons/ 目录中。
  4. 确认最终结果是 modules/addons/perfexbridge/perfexbridge.php。如果得到的是 modules/addons/perfexbridge/perfexbridge/perfexbridge.php，说明解压时多嵌套了一层。请把内层文件夹上移一级，并删除多余的外层空文件夹。
  5. 解压成功后，从服务器上删除上传的 addon.zip。
FTP 替代方案

先在自己的电脑上解压 addon.zip，然后通过 FTP 将得到的 perfexbridge 文件夹上传到 modules/addons/。最终结果完全相同。

现在激活它：

  1. 在 WHMCS 中，前往 System Settings > Addon Modules。
  2. 在列表中找到 Perfex CRM Bridge 并点击 Activate。

第 3 步：勾选 Access Control，否则模块不会显示​

这是"安装没成功"报告中最常见的原因

激活后，WHMCS 会显示模块的配置面板，其中有一个 Access Control 区域，列出您的管理员角色。您必须至少勾选 Full Administrator，以及其他应当使用该模块的角色，然后点击 Save Changes。

在勾选任何角色之前，该模块完全不会出现在左侧的 Addons 菜单中。模块其实已经安装好，数据表已存在，设置页面也完全正常，但后台任何地方都没有指向它的链接。十有八九，"模块没装上"指的就是这个复选框从未被勾选。

具体操作：

  1. 仍在 System Settings > Addon Modules 页面，点击 Perfex CRM Bridge 旁的 Configure。激活后 WHMCS 通常会自动打开这个面板。
  2. 在 Access Control 下勾选 Full Administrator。同时勾选其他应当能够打开和配置该桥接模块的管理员角色。
  3. 点击 Save Changes。
  4. 刷新后台。Perfex CRM Bridge 现在会出现在 Addons 菜单下。
Configure 界面上只有 Access Control

该模块所有实际的设置都在模块自己的页面上，即 Addons > Perfex CRM Bridge，而不在 WHMCS 的 Configure 界面上。Configure 界面只保留 Access Control，因为它由 WHMCS 核心渲染，无法移动。如果您打开 Configure 想找 Perfex URL 或授权密钥，那就找错地方了。请参阅配置。

第 4 步：打开模块页面​

前往 Addons > Perfex CRM Bridge。

页面打开时会显示 Setup checklist（安装检查清单）。在全新安装上，它看起来是这样的：

检查项此时的预期状态
Module tables present🟢 对勾
Connection configured🔴 叉号，尚未配对
Connection verified⚪ 横线，从未检查过
Sync enabled🔴 叉号，直到您勾选 Enable Sync
Cron delivering🔴 叉号，尚未记录任何计划任务活动
License / plan⚪ 横线，免费版

对于刚安装且尚未配置的桥接模块来说，这就是正确的状态。每一项的含义都在配置中说明。

接下来，把两端配对起来：配置。

第 5 步：端到端验证首次同步​

请在配对完成后立即做一次，在您把真实数据托付给桥接模块之前。这只需两分钟，却能验证整条链路。

  1. 完成配置中描述的配对。检查清单中的 Connection configured 和 Connection verified 两项必须都是绿色。
  2. 在同一页面的 Settings > Sync behaviour 下，确认已勾选 Enable Sync，然后点击 Save Settings。Sync enabled 一项会变绿。
  3. 在 WHMCS 中创建一个测试客户。任意姓名和邮箱均可，例如公司名填 Bridge Test Ltd。
  4. 回到 Addons > Perfex CRM Bridge。页面上方的 Queue pending 计数器应至少显示 1。
  5. 点击 Run Sync Now。这会立即强制发起一次投递，而无需等待计划任务。页面会报告发送成功、失败和进入死信的事件数量。
  6. 在 Perfex CRM 中打开 Customers。测试客户现在应该已作为客户存在，并以 WHMCS 客户的姓名和邮箱作为主联系人。
  7. 确认两端日志都记录了这次操作：
    • WHMCS 端：模块页面下方的 Recent activity 表格中会出现一条状态为 ok 的 client.upsert 记录。
    • Perfex 端：Setup > WHMCS Bridge 的 Recent inbound events 面板中会出现一条对应的 client.upsert 记录，并带有绿色 ok 标记。
  8. 如果不想保留测试客户，请从两个系统中将其删除。
"Run Sync Now" 并不能证明您的计划任务正常

Run Sync Now 证明的是投递能力。它不会让检查清单中的 Cron delivering 变绿，因为该项有意只跟踪真实的 WHMCS 系统计划任务活动。如果一小时后该项仍为红色或琥珀色，说明您的 WHMCS 系统计划任务没有运行，任何内容都不会自动同步。请在正式上线前修复计划任务。请参阅故障排查。

升级到新版本​

两个模块使用相同的版本号，应始终一起更新。

Perfex 端。 通过 Setup > Modules > Upload Module 上传新的 module.zip，覆盖现有模块，然后打开任意后台页面。配套模块会检测到数据库版本过旧，并就地执行自己的迁移。如果您愿意，也可以改为停用再重新激活模块。两种方式都是安全的：每一条迁移语句都有保护判断，重复执行不会改动任何已经正确的内容。

WHMCS 端。 将新的 addon.zip 上传并解压覆盖到 modules/addons/perfexbridge/。WHMCS 检测到新版本号时会运行模块的升级流程。如有疑虑，可以在 System Settings > Addon Modules 下停用再重新激活该插件。

升级不会影响您的设置

设置、共享密钥、授权密钥、实体映射表和日志都保存在数据库表中，升级永远不会删除它们。停用 WHMCS 插件同样不会删除其数据。

卸载​

  1. WHMCS：System Settings > Addon Modules > Perfex CRM Bridge > Deactivate，然后从磁盘上删除 modules/addons/perfexbridge/。
  2. Perfex：前往 Setup > Modules，停用 WHMCS Bridge，然后移除该模块。
  3. 如果您也想清除数据，请在每个系统中删除该模块的数据库表（请先备份）。
  4. 如果之前激活了 Pro 授权，请在卸载之前移除密钥，以便释放激活名额，使该授权可以在别处重新使用。请参阅移除密钥并回退到免费版。