配置
本页所有内容都假定两个模块均已安装并激活，并且您可以在 WHMCS 中访问 Addons > Perfex CRM Bridge，在 Perfex CRM 中访问 Setup > WHMCS Bridge。如果其中任何一个不存在，请返回安装。在 WHMCS 中，通常的原因是 Access Control 复选框未勾选。
两端如何进行身份验证
两个端点都使用由共享密钥派生的 HMAC-SHA256 签名对每个请求进行身份验证。
用通俗的话说：发送方用密钥对请求正文签名，并打上时间戳。接收方用自己保存的那份密钥重新计算签名，凡是签名不匹配、或时间戳超过 300 秒的请求一律拒绝。正是这个时间戳窗口，阻止了他人在事后重放被截获的请求。
由此带来的结果是：两端的密钥必须逐字节完全一致，否则每一个请求都会返回 401 失败。此外，只要某一端自己的密钥为空，该端点就会拒绝所有流量，因此配置到一半的桥接是关闭状态而非开放状态。
两端在使用前都会去除首尾空白字符，所以复制粘贴时带上的多余空格或换行不会造成问题。但中间的内容必须完全一致。
共享密钥授予对 Perfex 客户和联系人的写入权限；在拥有 Pro 授权时，还包括两端的发票、付款、订单和工单。如果任何一个数据库或其备份曾经泄露，请立即在两端轮换该密钥。密钥以明文形式存储在 tbladdonmodules（WHMCS）和 tbloptions（Perfex）中，这是两个生态系统的通行做法，因此任何拥有数据库访问权限的人都能拿到密钥。
配对：快速方式（推荐）
您不需要手动来回复制设置。Perfex 会生成一个连接代码，其中同时包含 Perfex URL 和共享密钥，WHMCS 只需粘贴一次即可完成配置。
第 1 步：在 Perfex 中生成密钥
- 在 Perfex CRM 中，前往 Setup > WHMCS Bridge。
- 在 Shared Secret 旁点击 Generate。该字段会填入一个 64 位的强随机密钥，并以明文显示，方便您确认即将保存的内容。眼睛图标按钮可切换回隐藏状态。
- 点击 Save。
第 2 步：复制连接代码
页面重新加载后，会显示一个只读的 Connection code 字段。它的值是一串以 PBC1. 开头的字符串。
点击 Copy。当代码进入剪贴板时，按钮会闪现 "Copied!"。
该代码由 PBC1. 加上 base64url 编码的 JSON 组成，其中包含您的 Perfex URL 和共享密钥。这只是编码，不是加密。任何拿到该代码的人都能与您的桥接端点通信。请勿将其粘贴到公开工单、聊天频道、截图或支持请求中。
只有同时满足两个条件时才会显示该代码：您的 Perfex 安装通过 HTTPS 提供服务，并且已保存的共享密钥至少为 32 个字符。最常见的原因是点击了 Generate 却没有点击 Save。页面会告诉您是哪个条件未满足：
- "not served over HTTPS" - 配对需要 HTTPS。请改用手动配置，或修复证书。
- "shorter than 32 characters" - 点击 Generate，然后点击 Save，代码就会出现。
第 3 步：粘贴到 WHMCS 中
- 在 WHMCS 中，打开 Addons > Perfex CRM Bridge。
- 找到页面上方绿色的 Quick setup 区块。
- 将代码粘贴到输入框中。
- 点击 Connect。
Connect 实际做了什么
在一步之内，按以下顺序执行：
- 解码该代码并进行严格校验：
PBC1.前缀、严格的 base64url 编码、格式正确的 JSON 对象、以https://开头并通过 URL 校验的地址，以及至少 32 个字符的密钥。 - 使用解码得到的 URL 和密钥，向您的 Perfex 安装发送一个签名的 ping，并等待
pong响应。 - 只有在 ping 成功之后，才会在 WHMCS 端保存 Perfex CRM URL 和 Shared Secret。
- 仅在首次配对时，该 ping 还会携带您的 WHMCS 基础 URL，从而自动填好 Perfex 端的 WHMCS URL 字段。这只在您的 WHMCS 通过 HTTPS 提供服务时发生，并且永远不会覆盖已有的值。
- 记录这次成功的检查，因此在同一次页面加载中，检查清单的 Connection verified 一项就会变绿。
成功时会显示绿色横幅，并注明配对的 Perfex URL。失败时会显示红色横幅，准确说明问题所在，并且不会保存任何内容。校验失败的代码永远不可能覆盖当前正常工作的配置。
日后重新配对
WHMCS 配置完成后，Quick setup 区块会变成一个不显眼的 Re-pair 表单。每当您轮换密钥或把 Perfex 迁移到新域名时，都可以粘贴一个新的代码。同样的规则依然适用：校验失败的代码不会改变任何配置。
如果您在 Perfex 端点击了 Generate 和 Save，那么在您把新代码粘贴到 WHMCS 之前，所有现有的 WHMCS 请求都会立即以 HTTP 401 失败。请把这两步连续完成。轮换之前复制的旧代码会被拒绝，横幅会提示您 Perfex 返回了 401。
配对：手动备用方案
连接代码只是便利手段，并没有什么魔法。它所做的一切都可以手动完成；如果您的 Perfex 安装尚未启用 HTTPS，或者您的工作流程不允许粘贴组合凭据，就需要走这条路线。
- 生成一个至少 32 个字符的强随机密钥。可以使用 Perfex 设置页面上的 Generate 按钮，或您自己的工具，例如
openssl rand -hex 32。 - 在 Perfex 中，前往 Setup > WHMCS Bridge，将其粘贴到 Shared Secret 并点击 Save。
- 在 WHMCS 中，打开 Addons > Perfex CRM Bridge，滚动到 Settings > Connection，然后：
- 将 Perfex CRM URL 设为您的 Perfex 基础 URL，例如
https://crm.example.com，必须使用 HTTPS 且不带任何路径后缀； - 将同一个密钥粘贴到 Shared Secret。
- 将 Perfex CRM URL 设为您的 Perfex 基础 URL，例如
- 点击 Save Settings。
- 点击页面顶部的 Test Connection。您需要看 到绿色的 "Connection OK" 横幅。
- 如需使用 Pro 双向同步，还要在 Perfex 设置页面上设置 WHMCS URL。如果使用配对方式，这一步会自动完成。
WHMCS 设置逐节说明
请打开 Addons > Perfex CRM Bridge 并滚动到 Settings。不要去 System Settings > Addon Modules 下的 WHMCS Configure 界面查找；该界面只保留 Access Control，它由 WHMCS 核心渲染，无法移动。
点击 Save Settings 生效。该表单是全有或全无：任何一项无效输入（例如非 HTTPS 的 URL）都会导致整个提交被拒绝，任何内容都不会改变。
Shared Secret 和 Pro License Key 始终渲染为空，这样已保存的凭据就不会出现在每个能打开该模块的管理员所看到的页面源码中。留空表示保持当前值不变。输入内容则表示替换该值。若要彻底移除 Pro 密钥，请勾选 Remove the stored key。
Connection
| 设置项 | 作用 | 建议默认值 |
|---|---|---|
| Perfex CRM URL | 您 Perfex 安装的基础 URL，例如 https://crm.example.com。必须是 HTTPS：桥接模块拒绝通过纯 HTTP 发送。 | 由配对自动设置 |
| Shared Secret | HMAC 密钥。必须与 Perfex 中 Setup > WHMCS Bridge 下配置的密钥一致。留空则保持已存储的值。 | 由配对自动设置 |
Sync behaviour
| 设置项 | 作用 | 建议默认值 |
|---|---|---|
| Enable Sync | 总开关。取消勾选可暂停所有出站投递。暂停期间事件仍会继续入队，因此不会丢失任何内容；重新启用后，它们会在下一次触发时投递。 | 配置完成后开启 |
| Order Sync Target (Pro) | 决定 WHMCS 订单在 Perfex 中变成什么。lead 表示为每个订单创建一个 Perfex 潜在客户，note 表示改为在 Perfex 客户上添加一条备注，off 表示完全不同步订单。 | lead |
| Two-Way Conflict Policy (Pro) | 当两个系统在上次同步之后都修改了同一个客户或联系人时，以哪一端为准。详见下文。 | newest_wins |
冲突策略选项，每项一句话说明：
newest_wins（默认） - 将传入的 Perfex 事件时间与上次同步时间进行比较，较新的修改胜出。whmcs_wins- 保留 WHMCS 数据，丢弃冲突的 Perfex 修改。perfex_wins- 用 Perfex 的修改覆盖 WHMCS 数据。
它仅在两端自上次成功同步以来都修改了同一条记录时才适用。如果只有一端做了普通修改而另一端未被改动，该修改始终会被应用。您选择的不是哪个系统在总体上"胜出"，而只是如何打破平局。
newest_wins 与服务器时钟的说明"较新"是将发送方服务器的时间戳与接收方服务器的上次同步时间作比较，因此两台主机的时钟很重要。请让两台服务器都使用 NTP 校时。如果您无法控制 WHMCS 主机与 Perfex 主机之间的时钟偏差，请优先选择 whmcs_wins 或 perfex_wins，这两者的结果是确定的。
Tickets
| 设置项 | 作用 | 建议默认值 |
|---|---|---|
| Ticket Reply Admin (Pro) | 当 Perfex 员工的回复被同步到 WHMCS 工单时所使用的 WHMCS 管理员用户名。留空则改为以该 Perfex 员工的姓名署名，并作为非管理员回复发布。 | 留空 |
Pro licence
| 设置项 | 作用 | 建议默认值 |
|---|---|---|
| Pro License Key | 使用免费版时留空。将您的 Pro 密钥粘贴到此处即可解锁 Pro 功能。密钥以 sk_ 开头。保存一个发生变化的密钥时会立即进行在线验证。 | 留空（免费版） |
| Remove the stored key | 仅 在已存储密钥时才出现的复选框。勾选并保存后，安装会回退到免费版，同时释放本站点的激活名额，使该授权可以在别处使用。 | 不勾选 |
| Check licence now（按钮，位于页面顶部） | 忽略每天一次的频率限制，立即强制重新检查已存储的密钥。 | - |
| Upgrade to Pro / Buy a Pro licence（链接） | 打开结账页面。在非 Pro 安装上，这些链接会出现在密钥输入框旁、授权检查项一行以及 Pro 功能提示框中。 | - |
完整说明请参阅授权与 Pro 激活。
Order Sync Target、Two-Way Conflict Policy 和 Ticket Reply Admin 在免费版安装上都可以正常保存。它们只是在有效授权激活之前不会生效，页面也会在每个字段下方说明这一点。如果您愿意，可以提前配置好。
Perfex CRM 设置逐项说明
在 Perfex 后台中打开 Setup > WHMCS Bridge，然后点击 Save。
Connection
| 字段 | 作用 | 默认值 / 回退行为 |
|---|---|---|
| Shared Secret | 必须与 WHMCS 端的 Shared Secret 一致。可使用 Generate 生成一个强密钥，然后点击 Save。眼睛图标按钮可显示或隐藏它。此项为空时，端点会拒绝所有流量。 | 留空，端点关闭 |
| Connection code | 只读。当已保存的密钥达到 32 个字符或更长、且 Perfex 使用 HTTPS 时出现。将其复制到 WHMCS 的 Quick setup 输入框中。 | 自动渲染 |
| WHMCS URL | 运行该插件的 WHMCS 安装的基础 URL。仅在 Perfex 向 WHMCS 发送流量时需要，这属于 Pro 功能。必须以 https:// 开头，否则不会保存。 | 首次配对时自动填入，一旦设置便不会被覆盖 |
Ticket sync (Pro)
| 字段 | 作用 | 默认值 / 回退行为 |
|---|---|---|
| Department mapping (WHMCS to Perfex) | 将每个 WHMCS 工单部门映射到一个 Perfex 部门。当部门目录可以成功获取时，渲染为每个 WHMCS 部门一行下拉菜单；否则渲染为手动填写的文本框。 | 留空，全部 未映射 |
| Default department for unmapped WHMCS tickets | 对于部门不在映射表中的 WHMCS 工单，所使用的 Perfex 部门。 | "Lowest department id (automatic)" |
| Staff author for synced WHMCS staff replies | 被镜像到 Perfex 的 WHMCS 员工回复所署名的 Perfex 员工。 | "First active admin (automatic)" |
| Create a Perfex task per synced ticket | 勾选后，每个同步的工单都会关联一个 Perfex 任务，您的员工便可用 Perfex 原生工时表针对它记录工时。 | 关闭 |
部门映射的渲染方式
正常情况下您会看到下拉菜单。设置页面加载时，会通过签名桥接通道获取您的 WHMCS 支持部门目录，并为每个 WHMCS 部门渲染一行，配上一个包含您 Perfex 部门的下拉菜单。为每一行选择一个目标部门，或保持 - not mapped - 不变，然后点击 Save。
该获取操作需要连接正常并且 WHMCS 端已获得 Pro 授权，因为部门目录与工单同步位于同一道授权门槛之后。当它无法执行时，页面会自动回退到手动文本框，并说明原因：
| 您看到的内容 | 含义 |
|---|---|
| 下拉菜单，每个 WHMCS 部门一行 | 一切正常 |
| 文本框，"Couldn't fetch WHMCS departments (needs Pro + working connection)" | 桥接尚未配置、Perfex 服务器无法访问 WHMCS，或 WHMCS 安装使用的是免费版 |
| 文本框，"Connection OK, but WHMCS has no support departments yet" | 获取成功。请在 WHMCS 的 Support > Support Departments 下创建部门，然后重新加载本页面 |
该获取操作有几秒钟的超时上限，因此即使 WHMCS 无法访问，也只会让设置页面稍微变慢，绝不会卡死。
手动格式为每行一条映射，左侧是 WHMCS 部门 ID，右侧是 Perfex 部门 ID：
1=2
2=5
3=5
在显示下拉菜单的情况下，Advanced: edit the mapping manually 链接会打开同一个文本框。只要该手动编辑器处于打开状态，保存时以其中的文本为准，会覆盖下拉菜单中的选择。
传入工单的部门解析顺序：
- 映射表中的精确匹配。
- 否则使用配置的 Default department。
- 否则自动选择 ID 最小的 Perfex 部门。
某一行映射写错时会平滑退回到上述回退方案，既不会导致保存失败，也不会中断同步。
这个可选的 Perfex 任务的存在，是为了让您的员工能针对工单使用 Perfex 原生工时表。这些工时记录不会同步回 WHMCS，并且工单关闭时任务也不会自动关闭。
同一页面上的面板
Setup > WHMCS Bridge 页面的右栏包含三个只读面板：
- WHMCS plan - WHMCS 端最近一次报告的版本（Pro、Free 或 Unknown）、授权的最近检查时间，以及在有可购买内容时显示的 Upgrade to Pro 按钮。
- Outbound queue - 等待推送到 WHMCS 的 Perfex 端变更，包含待处理和死信数量、重试次数、下次尝试时间以及每行的最近一次错误。
- Recent inbound events - WHMCS 已发送到此 Perfex 安装的内容，包含状态和消息。
这些是您在 Perfex 端的诊断工具。请参阅工作原理与日常使用。
安装检查清单逐项说明
WHMCS 模块页面打开时会显示一个六行的 Setup checklist。每一行都带有绿色对勾、琥珀色警告、红色叉号或灰色 横线，并附上一句提示。如果全部为绿色（使用免费版时授权那一行为灰色），说明桥接运行正常。
| 检查项 | 绿色表示 | 其他状态表示 |
|---|---|---|
| Module tables present | 发件箱表、映射表和日志表都已存在。 | 🔴 缺少某张表。请在 System Settings > Addon Modules 下停用并重新激活该模块以重新创建它。 |
| Connection configured | Perfex URL 和共享密钥都已设置。 | 🔴 尚未设置。请把连接代码粘贴到 Quick setup 中，或在 Settings > Connection 下填写这两个字段。 |
| Connection verified | 签名 ping 收到了 pong 响应，该行会显示距今多久。 | 🔴 最近一次检查失败，该行会显示错误信息。修复后点击 Test Connection。⚪ 从未检查过，或最近一次检查已超过 24 小时。点击 Test Connection 刷新。 |
| Sync enabled | 出站投递已开启。 | 🔴 同步已暂停。事件仍在入队，但不会被投递。请在 Settings > Sync behaviour 下勾选 Enable Sync 并保存。 |
| Cron delivering | WHMCS 系统计划任务最近确实执行了桥接工作，该行会显示距今多久。 | 🟠 有一段时间没有计划任务活动了。请检查 WHMCS 系统计划任务是否在运行。🔴 从未记录到任何计划任务活动。在全新安装上，首次投递之前出现这种情况是正常的；如果持续存在，说明您的计划任务没有运行。 |
| License / plan | Pro 已激活。 | ⚪ 没有授权密钥，也就是免费版，这是本模块完全受支持的一种运行方式。🔴 已设置密钥但校验不通过。请检查密钥，然后点击 Check licence now。 |
只有真正的 WHMCS 系统计划任务触发才会让该行变绿。Run Sync Now 会投递您排队的事件，也能证明投递功能正常，但它不会影响这一行。这正是设计意图所在：该行回答的是"没人盯着的时候它还会继续工作吗？"，而按一下按钮无法回答这个问题。
该行跟踪的是实际的桥接工作：队列清空、日志清理和对账处理。因此，一个长期空闲但完全健康的安装可能会一直显示琥珀色，而实际上没有任何需要修复的地方，只是因为确实无事可做。
Connect（配对）和 Test Connection 都会刷新 Connection verified 这一行。
接下来做什么
- 端到端验证整条链路：安装，第 5 步。
- 解锁双向同步、发票和工单：授权与 Pro 激活。
- 了解哪些数据会同步，以 及日志在哪里：工作原理与日常使用。