---
title: Flarum
---

# Flarum

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

## 覆盖范围

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

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

通过 SSO / Auth Sync 提供方建立的已认证会话会被豁免 —— 详见下方 [SSO / Auth Sync](#sso-auth-sync)。

## 安装

### 1. 引入扩展

在 Flarum 安装目录下执行：

```bash
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`](https://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 免费额度为每月 10,000 次验证。

**能挡住垃圾注册吗？**

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

**能只在注册时启用吗？**

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

**支持 SSO / Auth Sync 吗？**

支持。SSO / Auth Sync 提供方建立的会话会跳过挑战。参见 [SSO / Auth Sync](#sso-auth-sync)。

**是开源的吗？**

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

## 源码

- 扩展仓库：[`github.com/Captcha-La/captchala-flarum`](https://github.com/Captcha-La/captchala-flarum)
- Packagist：[`captchala/flarum`](https://packagist.org/packages/captchala/flarum)
- 相关文档：[Web SDK](/zh-CN/web-sdk) · [PHP 服务端 SDK](/zh-CN/sdk/server-php) · [API 参考](/zh-CN/api-reference)