---
title: WHMCS
---

# WHMCS

WHMCS 官方 CaptchaLa 插件模块。为 WHMCS 客户区——登录、注册、找回密码、联系表单、工单提交、购物车结账——添加人机验证,无需写代码。

不同于普通的 site-key 控件,每次挑战都由**服务端签发的一次性 token**(防重放)托底,且不加载任何第三方追踪。

## 覆盖范围

下面每一项都是模块设置里的独立开关——只开你想保护的。

- 登录
- 注册
- 找回密码
- 联系表单
- 工单提交
- 购物车结账

## 环境要求

- WHMCS 8.x 与 9.x(在 8.3 / 9.0 客户区测过;`six` 和 `twenty-one` 主题、开不开 Friendly URLs 都可)
- PHP 8.0+(WHMCS 9.0 本身要求 PHP 8.2+)
- 一个 CaptchaLa 账号——在 [`dash.captcha.la`](https://dash.captcha.la) 获取 **App Key** + **App Secret**

## 安装

### 1. 安装模块

1. 从 [releases](https://github.com/Captcha-La/captchala-whmcs/releases) 下载最新的 `whmcs-x.y.z.zip`。
2. 解压到你的 **WHMCS 根目录**,会得到 `modules/addons/captchala/`。
3. WHMCS 后台 **Setup → Addon Modules**,找到 **CaptchaLa**,点 **Activate**。

### 2. 配置

点 **Configure**,然后:

1. 填入 **App Key** 和 **App Secret**。
2. 选择**控件模式**和**主题**。
3. 勾选要保护的表单。
4. 点 **Save Changes**。

在后台侧边栏打开 **CaptchaLa** 页,可对 dashboard 做实时连接测试。

::: tip
激活后若控件不显示,把模块设置**重新保存一次**——WHMCS 只在模块(重新)激活/保存时才注册 `hooks.php`。
:::

## 配置项

全部在 **Setup → Addon Modules → CaptchaLa → Configure**。

| 设置 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| App Key | string | — | dashboard 的公开 key。必填。 |
| App Secret | string | — | 服务端密钥,用于签发与校验 token。必填;不会暴露给浏览器。 |
| 控件模式 | enum | `popup` | `popup`(触发条→全屏挑战)、`float`(内联面板)、`embed`(内联勾选框)、`bind`(隐形,拦截提交按钮)。 |
| 主题 | enum | `default` | 颜色预设:`default`、`dark`、`slate`、`emerald`、`amber`、`rose`。 |
| 语言 | string | `auto` | BCP-47 代码(如 `en`、`zh`、`de`)或 `auto` 跟随浏览器。 |
| 保护登录 | bool | 开 | 对客户区登录加验证。 |
| 保护注册 | bool | 开 | 对新账号注册加验证。 |
| 保护找回密码 | bool | 开 | 对找回密码表单加验证。 |
| 保护联系表单 | bool | 关 | 对联系表单加验证。 |
| 保护工单提交 | bool | 关 | 对工单提交的最终步加验证。 |
| 保护购物车结账 | bool | 关 | 对购物车结账加验证。 |
| 跳过已登录用户 | bool | 开 | 已有客户会话的访客不再验证。 |
| 失败提示 | string | — | 验证失败时显示的文案。 |

## 工作原理

在每个受保护的表单页,模块从 dashboard 签发一个绑定该表单 action 的**服务端 token(`sct_`)**,并把控件绑定到它。访客解题后,SDK 把一个**一次性 pass token(`pt_`)**写进表单。提交时,模块在 WHMCS 处理表单**之前**先服务端校验该 `pt_`;重放和 action 不匹配会被拒绝。

如果 dashboard 暂时不可达,模块会**失败放行**(让提交通过),这样客户区不会因上游抖动被锁死。

## FAQ

**模块免费吗?**

免费。模块本身免费。CaptchaLa 免费额度为每月 10,000 次验证 —— 仅在需要更高用量时才涉及付费计划。

**WHMCS 8 和 9 都支持吗?**

都支持——在 8.3 / 9.0 客户区、`six` 和 `twenty-one` 主题、开不开 Friendly URLs 都测过。

**控件不显示。**

把模块设置重新保存一次(Configure → Save Changes)。WHMCS 只在模块(重新)激活/保存时才注册 `hooks.php`。

## 源码

- 模块仓库:[`github.com/Captcha-La/captchala-whmcs`](https://github.com/Captcha-La/captchala-whmcs)
- 问题 / 需求反馈:在上面的仓库提
- 相关:[Web SDK](/zh-CN/web-sdk) · [PHP 服务端 SDK](/zh-CN/sdk/server-php) · [API 参考](/zh-CN/api-reference)