---
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-TW/web-sdk) · [PHP 伺服端 SDK](/zh-TW/sdk/server-php) · [API 參考](/zh-TW/api-reference)