故障排查

请按顺序阅读本页。前三节涵盖了绝大多数支持请求。

在做任何事情之前，请先在 WHMCS 中打开 Addons > Perfex CRM Bridge，并查看 Setup checklist。它的设计目的就是直接指向问题所在，每一项的含义都在配置中说明。

速查表

症状	最可能的原因	解决办法
模块未出现在 WHMCS 的 Addons 菜单中	Access Control 下未勾选任何管理员角色	勾选 Access Control
每次发送都立即失败	Perfex URL 以 http:// 开头	使用 HTTPS
Perfex 入站日志中出现 auth.rejected 记录	共享密钥不匹配	重新配对
Perfex 出站队列显示 "Two-way sync requires Pro"	WHMCS 端使用的是免费版	激活 Pro
事件在排队但从未投递	同步已暂停，或 WHMCS 计划任务未运行	检查计划任务
某张发票始终无法送达并不断重试	Perfex 中不存在该发票的货币	添加货币
授权无法激活	缺少密钥，或无法连接到授权服务	看横幅颜色
Perfex 页面上没有 Connection code	Perfex 未使用 HTTPS，或已保存的密钥太短	Generate 后 Save
部门映射显示为文本框而不是下拉菜单	免费版，或 Perfex 无法访问 WHMCS	映射回退方案
记录卡在 dead 状态	因同一原因失败了 15 次	重放死信记录

模块未出现在 Addons 菜单中

症状。 您在 System Settings > Addon Modules 下激活了 Perfex CRM Bridge，WHMCS 提示激活成功，但左侧 Addons 菜单中却找不到该模块。

原因。 没有为任何管理员角色授予访问权限。WHMCS 会对未勾选的角色完全隐藏插件模块，因此模块虽然已安装且功能完好，但后台任何地方都没有指向它的链接。这是"安装没成功"报告中最常见的情形。

解决办法。

1. 前往 System Settings > Addon Modules。
2. 点击 Perfex CRM Bridge 旁的 Configure。
3. 在 Access Control 下勾选 Full Administrator，以及其他应当使用该模块的角色。
4. 点击 Save Changes。
5. 刷新后台。该模块现在会出现在 Addons 下。

那个 Configure 界面上没有其他内容

所有实际的设置都在模块自己的页面上，即 Addons > Perfex CRM Bridge。Configure 界面只保留 Access Control，因为它由 WHMCS 核心渲染，无法移动。

每次发送都立即失败，或 URL 被拒绝

症状。 事件入队后立即失败。Recent activity 日志中充满连接错误。或者 Perfex CRM URL 字段根本无法保存。

原因。 HTTPS 是设计上的硬性要求。 HTTP 传输层被固定为 https 协议并验证 TLS 证书。http:// 地址会导致每一次发送都失败；同样，Perfex 端的 WHMCS URL 字段也会拒绝保存不以 https:// 开头的地址。

解决办法。

1. 在 WHMCS 端把 Perfex CRM URL 设为 https:// 地址。
2. 在 Perfex 端把 WHMCS URL 设为 https:// 地址。
3. 确认两个证书在对方服务器上确实能通过验证，而不仅仅是在您的浏览器中。只有当发起调用的服务器信任自签名证书时，它才能正常工作。
4. 在 WHMCS 模块页面上点击 Test Connection。

没有关闭 HTTPS 验证的设置

这是有意为之。您的共享密钥和客户数据都要经过这条通道传输。如果证书无法通过验证，请修复证书。

Perfex 日志中的 auth.rejected 记录

症状。 WHMCS 报告 HTTP 401 错误。在 Perfex 的 Setup > WHMCS Bridge > Recent inbound events 中出现红色的 auth.rejected 记录。

原因。 两端的共享密钥不一致，或者请求时间戳超出了 300 秒的窗口。实际情况中几乎总是密钥问题：有人在一端重新生成了密钥，却没有对另一端重新配对。

快速解决办法。

1. 在 Perfex 中，前往 Setup > WHMCS Bridge，复制当前的 Connection code。
2. 在 WHMCS 中，前往 Addons > Perfex CRM Bridge，把它粘贴到 Re-pair 输入框中并点击 Connect。
3. 点击 Test Connection。您需要看到绿色的 "Connection OK" 横幅。
4. 点击 Run Sync Now。此前失败的排队事件现在会成功投递。

手动解决办法。 把完全相同的密钥重新粘贴到两端的 Shared Secret 字段中，并在两端保存。首尾空白字符会被自动去除，但中间的内容必须逐字符一致。

如果问题不在密钥上。 请检查两台服务器的时钟。两者之间超过 300 秒的偏差会导致每个请求都被当作重放攻击而拒绝。请让两台主机都使用 NTP 校时。

被拒绝的记录有写入频率限制

Perfex 每分钟最多记录 10 条 auth.rejected，因此配置错误的发送方不会塞满您的磁盘。如果您在一分钟内正好看到 10 条，请假定实际数量更多。

Perfex 出站队列显示 "Two-way sync requires Pro"

症状。 您在 Perfex 中编辑了一个客户。Setup > WHMCS Bridge 上的 Outbound queue 面板显示该记录带有 "Two-way sync requires Pro on the WHMCS side." 消息和一个 Upgrade to Pro 链接。尝试次数不断增加，最终该记录进入死信状态。

原因。 双向同步是 Pro 功能，而授权存在于 WHMCS 端。您的 WHMCS 安装使用的是免费版，因此它的入站端点会对任何来自 Perfex 的变更返回 403。Perfex 配套模块通过排队和重试的方式做出了正确的响应。

解决办法。 在 WHMCS 端激活 Pro 授权。请参阅授权与 Pro 激活。Pro 激活后，WHMCS 会立即把新的版本状态推送给 Perfex，升级提示随即消失，待处理记录会在 Perfex 下一次计划任务运行时投递。

在您使用免费版期间已经进入死信状态的记录不会自行重试。请参阅记录卡在 dead 状态。

先看版本面板

WHMCS plan 面板就位于 Perfex 设置页面上 Outbound queue 的正上方，正是为此而设。如果它显示 Free，那么您不用读任何一条队列记录就已经知道答案了。

完全不同步

症状。 事件出现在队列中，Queue pending 持续上升，却始终没有内容到达 Perfex。没有报错，只是一片沉寂。

原因有两种，检查清单可以区分它们。

原因 A：同步已暂停

检查清单中的 Sync enabled 一行为红色。

解决办法。 在 WHMCS 模块页面的 Settings > Sync behaviour 下勾选 Enable Sync 并点击 Save Settings。暂停期间没有丢失任何内容；事件一直在排队，现在会开始投递。

原因 B：WHMCS 系统计划任务未运行

检查清单中的 Cron delivering 一行为红色或琥珀色。

解决办法。

1. 点击 Run Sync Now 以验证桥接本身正常工作。如果队列被清空，说明投递功能没有问题，问题确实出在计划任务上。
2. 在 Utilities > System > System Health Status 下查看 WHMCS 自身的计划任务状态。WHMCS 会显示系统计划任务最近一次运行的时间。
3. 如果计划任务近期没有运行过，请在服务器层面修复它。WHMCS 计划任务命令位于主机面板的计划任务管理器或服务器的 crontab 中。WHMCS 官方文档给出了适用于您所用版本的确切命令。
4. 计划任务恢复运行后，在真正执行过桥接工作之后的下一次页面加载时，Cron delivering 一行就会变绿。

Run Sync Now 无法让计划任务那一行变绿

该行有意只跟踪真实的 WHMCS 系统计划任务活动，因为它回答的是"没人盯着的时候它还会继续工作吗？"。按一下按钮无法回答这个问题。如果 Run Sync Now 能正常工作，但该行连续数小时保持红色，说明您的计划任务没有运行。

琥珀色的计划任务行未必是问题

该行跟踪的是实际的桥接工作：队列清空、日志清理和对账。一个健康但空闲、没有任何内容需要同步的安装，可能会一直显示琥珀色，而实际上没有任何需要修复的地方。

某张发票卡住，始终无法到达 Perfex

症状。 某一张发票反复失败。日志消息中提到某种货币，该记录以逐渐延长的间隔持续重试。

原因。 该发票的货币未在 Perfex 中配置。Perfex 正确地拒绝了这张发票，因为它无法用一种自己不认识的货币来记录金额。

解决办法。

1. 在 Perfex 中前往 Setup > Finance > Currencies。
2. 添加该货币，使用与 WHMCS 完全一致的 ISO 代码，例如 EUR 或 USD。
3. 其他什么都不用做。排队的事件会按自己的时间表重试，并在下一次尝试时成功。

您大约有 40 小时的时间

重试机制允许 15 次尝试，跨度约 40 小时。请在这个时间窗口内添加货币，否则该记录会进入死信状态，需要手动重放。如果您即将回填历史发票，请先把客户使用的每一种货币都添加好。

相关情形："Not mapped (will retry)"

某条子记录先于其上级记录到达：联系人的客户尚未进入 Perfex、发票的客户尚未映射，或者工单回复所属的工单尚未同步。

这种情况通常会自行恢复。队列按顺序投递，上级记录到达后，子记录会在下一次尝试时成功。只有当上级记录永远不会同步时才会真正成为问题，例如您回填了服务却没有回填客户。这种情况下，请把上级记录入队（在 WHMCS 中编辑该客户，或运行一次 Clients 回填），子记录随后就会跟上。

授权无法激活

症状。 您粘贴了密钥，但安装仍显示为免费版。

启用 Pro 需要两个条件：有效的密钥以及从您的 WHMCS 服务器到授权服务的连通性。请看横幅颜色，它会告诉您缺的是哪一个。

横幅	含义	解决办法
🔴 红色	授权服务器明确拒绝了该密钥，消息中会说明原因。	请从购买邮件中一次性重新复制完整密钥。密钥为 32 个字符，可能包含标点符号，因此不要删减或重新排版。如果消息中提到安装数量或配额，请从不再需要它的安装中移除密钥以释放一个激活名额。
🟠 琥珀色	您的服务器无法连接到授权服务。这不是拒绝。	密钥已保存并会继续重试。请在 WHMCS 服务器上的出口防火墙或代理中放行到 api.freemius.com 的出站 HTTPS。然后点击 Check licence now。
⚪ 完全没有横幅	您保存的是已经存储的同一个密钥，因此没有重新检查。	点击 Check licence now。
标题显示 "awaiting first verification"	已存储密钥但从未被确认。	点击 Check licence now。

其他检查项：

• 请确认密钥填在模块自己页面上 Settings > Pro licence 下的 Pro License Key 中，而不是 WHMCS Configure 界面的某个位置。
• 点击 Check licence now 后，两次点击之间请等待几秒。快速的第二次点击会回应"刚刚已检查过"，而不会发出请求。
• 如果 WHMCS 中 Pro 已激活但 Perfex 仍显示 Free，请在 WHMCS 中点击 Check licence now 或 Test Connection，两者都会立即把版本状态送达 Perfex。然后重新加载 Perfex 设置页面。

完整说明请参阅授权与 Pro 激活。

Perfex 中没有出现 Connection code

症状。 您在 Setup > WHMCS Bridge 页面保存了密钥，但没有 Connection code 字段，只有一段灰色提示。

原因与解决办法。 提示本身会告诉您属于哪种情况。

提示	原因	解决办法
"not served over HTTPS"	配对要求 Perfex 安装使用 HTTPS。	修复证书，或使用手动配置。
"shorter than 32 characters"	已保存的密钥太短。最常见的原因是点击了 Generate 却没有点击 Save。	点击 Generate，然后点击 Save。重新加载后代码就会出现。

配对失败并提示 "the shared secret does not match"

症状。 您把连接代码粘贴到 WHMCS 后，收到提到 HTTP 401 的红色横幅。

原因。 该代码携带的密钥 Perfex 已经不再持有。几乎总是因为这个代码是在后来的 Generate 和 Save 之前复制的，或者执行了 Generate 却从未保存。

解决办法。 在 Perfex 中，在设置页面上点击 Save，确保当前密钥确实已被存储，然后复制一个新的 Connection code 并粘贴使用。失败的尝试不会在 WHMCS 端存储任何内容，因此您之前可用的配置依然完好。

部门映射显示为文本框而不是下拉菜单

症状。 Perfex 设置页面上的部门映射显示为一个普通文本框，而不是每个 WHMCS 部门一行下拉菜单。

原因。 页面无法获取您的 WHMCS 支持部门目录。文本框下方的提示会说明属于哪种情况：

提示	原因	解决办法
"Couldn't fetch WHMCS departments (needs Pro + working connection)"	桥接尚未配置、Perfex 服务器无法访问 WHMCS，或 WHMCS 使用的是免费版。部门目录与工单同步位于同一道授权门槛之后。	完成配对，检查 Perfex 能否通过 HTTPS 访问您的 WHMCS URL，并激活 Pro。
"Connection OK, but WHMCS has no support departments yet"	获取成功；只是暂时没有可映射的内容。	在 WHMCS 的 Support > Support Departments 下创建部门，然后重新加载 Perfex 页面。

在此期间，手动填写的 whmcs_deptid=perfex_department_id 文本框始终可用，每行一条映射。同步不会因此中断：未映射的工单会退回到您设置的默认部门，或退回到 ID 最小的 Perfex 部门。

记录卡在 dead 状态

症状。 WHMCS 模块页面上的 Dead events 计数器，或 Perfex Outbound queue 面板上的 dead 计数大于零。

原因。 这些记录在大约 40 小时内因同一原因失败了 15 次。死信记录永远不会自动重试，也永远不会被清理，这是有意为之，以便您进行检查。

解决办法。

1. 先弄清原因。打开 WHMCS 中的 Recent activity，或 Perfex 中 Outbound queue 的 "Last error" 列，阅读受影响记录上的错误信息。原因几乎总是以下之一：Perfex 中缺少某种货币、密钥不匹配、免费版拦截了 Pro 事件，或者 Perfex 曾经离线。

2. 先修复该根本原因。 在没有修复原因的情况下重放记录，只会再白白消耗 40 小时。

3. 重新将该工作入队。最稳妥的方式不需要数据库访问权限：

   • 对于客户、联系人、发票、服务和域名，重新触发事件即可。在 WHMCS 中编辑并保存该记录，或者以 Only new (not yet synced) 模式运行回填向导。
   • 对于 Perfex 端的变更，再次编辑该 Perfex 记录即可产生一个新事件。

4. 如果您更希望重放原始记录，并且拥有数据库访问权限，可以把它重置为 pending。请先做好备份：

   UPDATE mod_perfexbridge_outbox
      SET status = 'pending', attempts = 0, next_attempt_ts = 0
    WHERE id = 123;

   请把 123 替换为您要重放的记录 ID。Perfex 端对应的数据表是 tblwhmcs_bridge_outbox，需加上您的 Perfex 表前缀。

Perfex 中的变更始终无法到达 WHMCS

请按以下顺序逐项排查：

1. WHMCS 端是 Pro 吗？ 查看 Perfex 设置页面上的 WHMCS plan 面板。双向同步仅限 Pro 版。
2. Perfex 端设置了 WHMCS URL 吗？ 前往 Setup > WHMCS Bridge > WHMCS URL，必须是 HTTPS 且不带路径后缀。配对通常会在首次配对时自动填入，但它永远不会覆盖已有的值。
3. Perfex 服务器能通过 HTTPS 访问 WHMCS 吗？ Perfex 的推送客户端与 WHMCS 端一样，强制使用 HTTPS 并验证证书。
4. Perfex 计划任务在运行吗？ Perfex 端产生的变更由 Perfex 计划任务投递，而不是 WHMCS 的。请检查您的 Perfex 计划任务。
5. 该记录已映射吗？ 只有从 WHMCS 同步过来的客户才有映射。直接在 Perfex 中创建的客户没有对应的 WHMCS 记录，因此永远不会被推送。同样，直接在 Perfex 中创建的工单也只留在 Perfex 中。
6. 阅读 Outbound queue 面板。 它会列出每条记录最近一次的错误。

某个变更被回弹并覆盖了我的编辑

症状。 您在一个系统中编辑了某条记录，它却变回了另一个系统中的值。

原因。 自上次同步以来，两端都修改了同一条记录，而您的 Two-Way Conflict Policy 决定了谁胜出。

解决办法。 在 WHMCS 模块页面的 Settings > Sync behaviour 下，选择符合您团队工作方式的策略：

• newest_wins（默认） - 较新的修改胜出。要求两台服务器的时钟都准确。
• whmcs_wins - 始终以 WHMCS 为准。
• perfex_wins - 始终以 Perfex 为准。

如果两台主机的时钟不在您的掌控范围内，请避免使用 newest_wins：时钟偏差会让它的判定结果随偏差量一起偏移。

一条工单回复让客户收到两封邮件

症状。 某位 Perfex 员工回复了一个已同步的工单，客户收到了两条通知。

原因。 Perfex 发送了自己的工单回复邮件，而同步到 WHMCS 的那条回复又让 WHMCS 发送了自己的通知。这是有据可依的行为，不是同步循环。邮件抑制机制只覆盖 WHMCS 到 Perfex 这个方向。

解决办法。 如果您的客户主要使用 WHMCS 客户门户，请在 Perfex 的 Setup > Email Templates > Tickets 下停用 Perfex 的 ticket-reply 邮件模板。

仍未解决：联系支持前需要准备什么

准备好以下内容，通常第一次回复就能得到答案：

• 两个模块的版本号，当前为 1.3.4，并确认两端版本一致。
• WHMCS 版本、Perfex CRM 版本，以及两台服务器上的 PHP 版本。
• WHMCS 模块页面上 Setup checklist 的截图。
• Queue pending 和 Dead events 的计数。
• WHMCS 中 Recent activity 和 Perfex 中 Recent inbound events 的相关记录，需包含完整的 message 列。
• 出现故障时您正在做什么操作，以及它此前是否曾经正常工作过。

切勿发送您的共享密钥或连接代码

连接代码中包含您的共享密钥。这两者都不应出现在支持工单、截图或聊天消息中。支持人员在诊断问题时从来不需要它们。