Flarum

CaptchaLa 官方 Flarum 扩展。为论坛上最容易被机器人盯上的操作 —— 注册、登录、找回密码与发帖 —— 加上 CAPTCHA 验证，并在后台提供按操作粒度的开关。

覆盖范围

下列每一项在 Admin → Extensions → CaptchaLa 中都是独立的开关。

• 注册
• 登录
• 找回密码
• 帖子回复
• 新建讨论
• 资料编辑

通过 SSO / Auth Sync 提供方建立的已认证会话会被豁免 —— 详见下方 SSO / Auth Sync。

安装

1. 引入扩展

在 Flarum 安装目录下执行：

composer require captchala/flarum

或在 Admin → Extension Manager 中将 captchala/flarum 粘贴到 Install 输入框。扩展要求 Flarum ≥ 1.8 与 PHP ≥ 8.1。

2. 在后台启用

打开 Admin → Extensions，找到 CaptchaLa，点击 Enable。

3. 配置

在扩展的设置面板中：

1. 粘贴来自 dash.captcha.la 的 App Key 与 App Secret。
2. 勾选要保护的操作。
3. 保存。

配置项

设置保存在 Flarum 标准 settings 表中，使用 captchala.* 前缀。

配置项	类型	默认值	说明
App Key	string	—	来自 CaptchaLa 控制台的公钥（cl_pub_…）。必填。
App Secret	string	—	服务端密钥。必填。仅服务端使用，用于调用 /v1/validate。
保护注册	bool	true	注册时触发挑战。
保护登录	bool	false	登录弹窗触发挑战。默认关闭，多数论坛通过限流保护登录。
保护找回密码	bool	true	请求重置邮件时触发挑战。
保护帖子回复	bool	false	发表回复时触发挑战。默认关闭；如论坛承压可开启。
保护新建讨论	bool	false	新建讨论时触发挑战。
验证模式	enum	popup	可选 popup、bind、embed。对应 Web SDK 的 product 选项。
主题	enum	auto	light、dark，或 auto。
跳过可信用户	bool	true	标记为可信的用户组（如版主）跳过挑战。

SSO / Auth Sync

扩展会配合 Flarum 标准的鉴权钩子（UserAuthenticated、第三方 Auth Sync 提供方、OAuth 桥接）协同工作。

• 用户通过已认证的 SSO 会话进入时，不会渲染挑战 —— 扩展将该会话视为已验证。
• 在 SSO 与本地登录混合的部署下，仅本地登录路径会触发挑战。
• 「跳过可信用户」开关在此基础上叠加：即便走的是本地登录，可信用户组依然会跳过挑战。

常见问题

扩展免费吗？

免费。Composer 包本身免费。CaptchaLa 免费额度为每月 1,000 次验证。

能挡住垃圾注册吗？

绝大多数自动化注册会在首轮风险评分时被挑战或拦截。没有任何 CAPTCHA 能 100% 阻断 —— 但在我们的测试论坛中，启用后垃圾注册量大致下降一个数量级。

能只在注册时启用吗？

可以。每个操作都是独立开关。默认配置只启用注册和找回密码。

支持 SSO / Auth Sync 吗？

支持。SSO / Auth Sync 提供方建立的会话会跳过挑战。参见 SSO / Auth Sync。

是开源的吗？

是的 —— PHP 扩展代码开源。验证调用走 CaptchaLa 托管服务。

源码

• 扩展仓库：github.com/Captcha-La/captchala-flarum
• Packagist：captchala/flarum
• 相关文档：Web SDK · PHP 服务端 SDK · API 参考