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 获取 App Key + App Secret

安装

1. 安装模块

1. 从 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
• 问题 / 需求反馈:在上面的仓库提
• 相关:Web SDK · PHP 服务端 SDK · API 参考