工作原理与日常使用
桥接完成配对并启用同步后，它就会自行运行。本页解释它实际在做什么，这样当出现异常时，您知道该去哪里查看，而不必凭猜测排查。
用通俗语言讲解同步引擎
1. 变更产生事件
WHMCS 中每一次相关变更都会触发一个 WHMCS 钩子：新增或编辑客户、创建联系人、开具发票、收到付款、下单、开通或暂停服务、创建工单或回复工单。
该钩子不会发起 HTTP 调用。它会把一个小事件写入**发件箱（outbox）**表（mod_perfexbridge_outbox）并立即返回。
如果 WHMCS 钩子直接调用 Perfex，那么响应缓慢或无法访问的 Perfex 服务器会阻塞 WHMCS 后台页面或客户的结账流程。写入本地表只需一毫秒，且绝不会因为别人的网络问题而失败。之后的一切都在后台进行。
2. 计划任务清空队列
每次 WHMCS 系统计划任务触发时，调度器都会从发件箱中取出一批到期事件，并通过 HTTPS 将每个事件 POST 到您的 Perfex 安装。
每个请求除 JSON 正文外还携带两个请求头：一个时间戳，以及基于该时间戳加上完整请求正文、使用您的共享密钥计算出的 HMAC-SHA256 签名。Perfex 会用自己保存的那份密钥重新计算签名，凡是不匹配、或时间戳超过 300 秒的请求一律拒绝。
您随时可以在 WHMCS 模块页面上点击 Run Sync Now 强制立即清空队列。
3. 失败先重试，然后进入死信
发送失败的事件不会丢失，也不会被密集循环重试。它会按指数退避重新排期：首次失败后约 60 秒，然后 2 分钟、4 分钟、8 分钟，依此类推，两次尝试之间的间隔上限为 6 小时。
在 15 次尝试（大约跨越 40 小时）之后，该记录会被标记为死信（dead）。死信记录永远不会自动重试，也永远不会被清理。它们就是您的死信抽屉：WHMCS 模块页面顶部的 Dead events 计数器 告诉您有多少条，日志行则告诉您原因。
进入死信状态意味着同一个事件因同一原因失败了将近两天。原因几乎总是以下四种之一：Perfex 中缺少某种货币、密钥不匹配、免费版拦截了 Pro 事件，或者 Perfex 处于离线状态。请修复根本原因，然后重新将该工作入队。请参阅故障排查。
4. 暂停不会丢失任何内容
取消勾选 Enable Sync 只会暂停投递。钩子仍会继续把事件写入发件箱，因此暂停期间不会丢失任何内容。重新启用后，积压内容会在下一次触发时清空，或者点击 Run Sync Now 立即清空。
5. 回声抑制阻止无限循环
双向同步带来一个显而易见的风险：WHMCS 应用了一个来自 Perfex 的变更，这次写入又触发了 WHMCS 自己的钩子，于是该变更立刻被弹回去。如果放任不管，一次编辑就会永远来回往返。
桥接通过在两端应用多层防护来防止这种情况：
- 请求内来源标记，在桥接应用入站变更期间设置，这样它自己所做的写入就不会被当作用户的新编辑。
- 实体与回复 ID 映射查找，这样桥接刚刚创建的工单回复会被识别出来，而不会作为新内容再次发送。
- 校验和比对，当数据已经等于上次同步的状态时，事件会变成空操作。
两端各有自己的来源标记，而校验和则是在标记被绕过时的兜底手段。这些防护机制被有意设计为失败时放行：如果某个防护无法做出判断，宁可多发送一次无害的请求，也不要悄悄丢弃一次更新。
6. 日常维护
两端都会运行自我节流的每日清理，最多每 24 小时执行一次：
- 删除超过 7 天的已投递发件箱记录；
- 删除超过 90 天的日志记录；
- 待处理和死信记录永远不会被清理，因为待处理代表尚未投递的工作，而死信是您的死信抽屉。
哪些数据会同步，以及同步方向
从 WHMCS 到 Perfex CRM
| 数据 | 免费版 | Pro 版 | 在 Perfex 中生成的内容 |
|---|---|---|---|
| 👥 客户 | ✅ | ✅ | 一个 Perfex 客户，外加一个携带该客户姓名和邮箱的主联系人 |
| 👤 联系人 | ✅ | ✅ | 同一个 Perfex 客户下的额外联系人 |
| 🗑️ 客户删除 | ✅ | ✅ | Perfex 客户被停用，而不是被销毁 |
| 📄 发票 | ➖ | ✅ | 一张 Perfex 发票，包含行项目、税费行、一致的合计金额、状态，以及管理备注中的 WHMCS 发票号 |
| 💳 付款与交易 | ➖ | ✅ | 针对镜像发票的付款记录，包含支付网关和交易 ID。重复记录会被拒绝 |
| 💸 退款 | ➖ | ✅ | Perfex 中的镜像记录被取消并加上备注 |
| 🛒 订单 | ➖ | ✅ | 按 Order Sync Target 的设置，每个订单生成一个 Perfex 潜在客户、一条客户备注，或者不生成任何 内容 |
| 📦 服务 | ➖ | ✅ | 客户 WHMCS 选项卡上的记录行：产品名称、域名、状态、计费周期、金额和下次到期日 |
| 🌐 域名 | ➖ | ✅ | 同一选项卡上的记录行：注册商、状态、过期时间和下次到期日 |
| 🎫 工单与回复 | ➖ | ✅ | 该客户下的一个 Perfex 工单，位于映射的部门中，包含回复和状态 |
在免费版中，客户的状态和备注虽然包含在数据负载里，但不会写入 Perfex。只有客户删除会作用于 Perfex 记录，即停用该客户。
从 Perfex CRM 到 WHMCS（仅 Pro 版）
| 在 Perfex 中所做的变更 | 在 WHMCS 中发生什么 |
|---|---|
| 编辑客户公司信息 | WHMCS 客户记录被更新，受冲突策略约束 |
| 编辑主联系人 | WHMCS 的客户身份字段被更新，因为主联系人就代表客户身份 |
| 编辑非主联系人 | 对应的 WHMCS 联系人被更新 |
| 员工回复镜像工单 | 该回复出现在 WHMCS 工单上；如果设置了 Ticket Reply Admin 则以该管理员署名，否则以 Perfex 员工姓名署名 |
| 修改工单状态 | WHMCS 工单状态随之变化 |
在 Perfex 中删除客户或记录不会删除 WHMCS 中的任何内容。无论 CRM 中发生什么，计费记录都会被保留。这是有意为之，且不可配置。
在依赖本产品之前值得了解的已知行为
以下都是有据可依的设计决定，而不是缺陷：
- 直接在 Perfex 中创建的工单只留在 Perfex 中。 它们永远不会在 WHMCS 中创建，因为 WHMCS 工单需要客户账户和支持部门，而 CRM 端创建的工单未必具备这些信息。
- 通过 Perfex 完整工单设置表单修改的工单状态不会传播。 单个工单的状态下拉菜单、回复、批量状态变更和自动关闭都能正确同步。
- 记录在单工单 Perfex 任务上的工时不会同步回 WHMCS。 该任务的存在是为了支持 Perfex 原生工时表报表。
- 未对定期发票的周期建模。 WHMCS 发票会镜像为普通的一次性 Perfex 发票。
- 不支持合并两个 WHMCS 客户。 合并之后，请重新映射或删除被并入客户的映射记录。
- Perfex 员工在已同步的工单上回复可能会产生两封客户邮件，一封来自 Perfex，一封来自 WHMCS。如果您的客户主要使用 WHMCS 客户门户，请在 Setup > Email Templates > Tickets 下停用 Perfex 的
ticket-reply邮件模板。
日志在哪里
这一节最能节省时间。人们习惯性地会找错地方。
WHMCS 端：模块自己的页面
前往 Addons > Perfex CRM Bridge 并滚动到 Recent activity。
桥接不会写入 Utilities > Logs 下的 WHMCS Activity Log。它有自己的数据表，渲染为模块页面上的 Recent activity 面板，这是 WHMCS 端唯一需要查看的位置。
该表格显示最近 50 条事件，包含以下列：
| 列 | 含义 |
|---|---|
| Time | 该记录写入的时间 |
| Dir | out 表示 WHMCS 到 Perfex，in 表示 Perfex 到 WHMCS |
| Event | 例如 client.upsert、invoice.upsert、cron.drain |
| Entity | client、contact、invoice、ticket 等 |
| WHMCS ID | 该记录的 WHMCS ID |
| Status | 绿色 ok 或红色 error |
| Message | 处理结果，或确切的错误文本 |
在它上方的标题行会显示 Queue pending 和 Dead events 计数。这两个数字就是您的健康概览：待处理数量应在一两个计划任务周期内降到零，死信数量应始终保持为零。
Perfex 端：设置页面上的两个面板
前往 Setup > WHMCS Bridge。
Recent inbound events 列出 WHMCS 发送到此 Perfex 安装的内容，包含 事件类型、WHMCS ID、映射到的 Perfex ID、状态标记和消息。被拒绝的请求会在这里显示为 auth.rejected 记录，表示签名或时间戳有问题，几乎总是密钥不匹配所致。被拒绝的记录每分钟最多写入 10 条，以免大量请求塞满您的磁盘。
Outbound queue 列出等待推送到 WHMCS 的 Perfex 端变更，包含：
- 面板标题中的 pending 和 dead 计数；
- 每个排队变更一行，显示事件、实体、状态、尝试次数、下次尝试时间和最近一次错误；
- 在原因已知时，用通俗易懂的说明代替原始错误。例如，来自未授权 WHMCS 的 403 会显示为 "Two-way sync requires Pro on the WHMCS side" 并附带升级链接，而不是一堆 JSON 转储内容。
只显示最新的 20 条记录。已投递的记录会在 7 天后自动清除；待处理和死信记录会保留。
哪个日志回答哪个问题
| 问题 | 查看位置 |
|---|---|
| 📤 我在 WHMCS 中的变更发出去了吗？ | WHMCS：Recent activity，方向为 out |
| 📥 Perfex 接收了吗？ | Perfex：Recent inbound events |
| 🔑 我的共享密钥是不是错了？ | Perfex：Recent inbound events 中的 auth.rejected 记录 |
| 🔁 我在 Perfex 中的编辑到达 WHMCS 了吗？ | Perfex：Outbound queue，然后查看 WHMCS：Recent activity，方向为 in |
| ⏰ 计划任务在运行吗？ | WHMCS：检查清单中的 Cron delivering 一行 |
| 🔇 双向同步为什么没有动静？ | Perfex：WHMCS plan 面板。如果显示 Free，那就是答案 |
回填向导（Pro）
实时同步只处理新增的活动。如果您在一套已经运营的 WHMCS 安装上部署桥接，那么在完成回填之前，您现有的客户和发票都不会出现在 Perfex 中。
Backfill wizard 位于 WHMCS 模块页面上、设置表单的下方。它会把您现有的记录排入实时同步所使用的同一个发件箱，因此它们同样享有相同的签名、重试、退避和死信机制。
范围
勾选一项或多项：
| 范围 | 会排队什么 |
|---|---|
| Clients + contacts | 范围内的每一个客户。联系人会自动随其客户一同处理 |
| Invoices | 范围内的每一张发票 |
| Services + domains | 范围内的每一项服务和域名，用于填充 Perfex 的 WHMCS 选项卡 |
历史工单不会同步。桥接上线后，只有新的工单活动才会流转过去。这是有据可依的限制，而不是配置问题。
模式
| 模式 | 行为 |
|---|---|
| All history | 所选范围内的全部记录 |
| Date range | 仅限在 YYYY-MM-DD 起止时间窗口内创建的记录。无效的范围（例如起始日期晚于结束日期）会被拒绝并给出明确提示，且不会排队任何内容 |
| Only new (not yet synced) | 跳过已经映射过的记录。重复运行时应使用此模式 |
500 条实体上限以及如何续跑
每次运行最多排队 500 条实体，因此在大型安装上执行回填不会冲垮队列或拖垮您的计划任务。
达到上限时，向导会提示您。标准做法是：
- 点击 Queue Backfill。信息横幅会报告计划处理了多少条、成功排队多少条、出错多少条，以及本次运行是否被截断。
- 观察页面顶部的 Queue pending 计数器逐步下降，可以等待计划任务，也可以点击 Run Sync Now。
- 以 Only new (not yet synced) 模式重新运行向导。
- 重复上述步骤，直到某次运行不再计划任何新记录为止。
不存在产生重复数据的风险。已映射的记录会被跳过，而数据已与 Perfex 端一致的事件会被作为空操作处理。
两条能为您省时间的顺序规则
如果某条子记录的上级客户尚未进入 Perfex，系统会回复"未映射，将重试"，该记录会留在队列中直到上级记录到达。通常队列自身的排序就能解决这个问题。但如果您在一套从未同步过客户的安装上只回填服务或发票，这些事件会重试大约 40 小时，然后进入死信状态。
请在同一次运行中同时勾选 Clients + contacts，或者先回填客户。
如果发票使用了 Perfex 不认识的货币，该发票会被拒绝并重试，约 40 小时后进入死信状态。在回填发票之前，请在 Perfex 的 Setup > Finance > Currencies 下添加您 WHMCS 客户所使用的每一种货币，并使用准确的 ISO 代码。
历史已付发票
回填时，在 WHMCS 中已经付款的发票会在 Perfex 中通过一条合成付款记录完成结清，因此它们显示为已付款而不是逾期。重复运行回填不会产生重复的付款记录。
日常运维
配置完成后基本无需操作。每周花很短时间看一眼 WHMCS 模块页面就足够了：
| 查看内容 | 健康状态 |
|---|---|
| Setup checklist | 全部为绿色；如果使用免费版，授权那一行为灰色 |
| Queue pending | 数量很小，且在两次计划任务之间持续下降 |
| Dead events | 0 |
| Recent activity | 绝大多数为 ok 记录 |
| Perfex 的 Outbound queue | 在 Pro 双向同步安装上，pending 为 0，dead 为 0 |
如果上述任何一项不符合预期，故障排查中列出了原因和解决办法。