> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# reCAPTCHA

> 如何使用 Google reCAPTCHA 保護登入、註冊與密碼重設？

> [!NOTE]
>
> 此功能由 [ayaka-notes/ayakaleaf-pro](https://github.com/ayaka-notes/ayakaleaf-pro) 開發，自 v6.4.0 起提供。

電子郵件與密碼登入、LDAP 登入、註冊以及密碼重設，都可以要求通過 Google reCAPTCHA v2（隱形）驗證。此功能預設為關閉。大多數使用者不會看到任何東西：檢查會在使用者按下按鈕時執行，只有當 Google 認為該請求可疑時，才會顯示圖片驗證挑戰。SAML 與 OIDC 登入以及由管理員建立的帳號不受影響。

1. 在 [reCAPTCHA 管理主控台](https://www.google.com/recaptcha/admin)中，建立類型為 **reCAPTCHA v2**、**Invisible reCAPTCHA badge** 的金鑰，並加入您執行個體的網域。網域也涵蓋其子網域，例如 `example.com` 涵蓋 `latex.example.com`。
2. 在 `config/variables.env` 中設定這兩個金鑰，然後執行 `bin/up`：

```text theme={null}
RECAPTCHA_SITE_KEY=<site key>
RECAPTCHA_SECRET_KEY=<secret key>
```

| 變數 | 預設值 | 用途 |
| - | - | - |
| `RECAPTCHA_SITE_KEY` | 未設定 | 為登入、LDAP 登入、註冊與密碼重設啟用驗證碼。 |
| `RECAPTCHA_SECRET_KEY` | 未設定 | 同一組 reCAPTCHA 金鑰的密鑰，供伺服器檢查回應。 |
| `RECAPTCHA_ENDPOINT` | `https://www.google.com/recaptcha/api/siteverify` | 伺服器檢查回應的位置。若無法連線至 `www.google.com`，請使用 `https://www.recaptcha.net/recaptcha/api/siteverify`。 |
| `CAPTCHA_TRUSTED_USERS` | 未設定 | 以逗號分隔的電子郵件清單，伺服器會讓這些電子郵件直接通過，不檢查驗證碼。 |
| `CAPTCHA_TRUSTED_USERS_REGEX` | 未設定 | 用來比對這類電子郵件的正規表示式；必須比對整個電子郵件。 |
| `DEVICE_HISTORY_SECRET` | 未設定 | 64 個十六進位字元，例如由 `openssl rand -hex 32` 產生。讓曾以某個電子郵件登入的瀏覽器，在 90 天內以該電子郵件登入時略過驗證碼。若未設定，每次登入都需要通過驗證碼。 |

* 頁面會從 `www.recaptcha.net` 載入 reCAPTCHA 指令碼，在 `www.google.com` 遭封鎖的地方也能正常運作。
* 註冊與密碼重設每次都會要求驗證。LDAP 登入也每次都會要求驗證，即使設定了 `DEVICE_HISTORY_SECRET` 也一樣：因為它傳送的是使用者名稱，而非電子郵件。
* 登入同樣仍有頻率限制：每個 IP 位址每分鐘 20 次嘗試，每個電子郵件每 2 分鐘 10 次嘗試。
* Ayakaleaf Pro 只會檢查 Google 是否接受該回應。不支援 reCAPTCHA v3 的分數與門檻，何時顯示驗證挑戰由 Google 決定。
* 若要在取得金鑰前先試用，請使用 Google 的[測試金鑰](https://developers.google.com/recaptcha/docs/faq)：所有檢查都會通過，且小工具會顯示警告，因此請勿在正式環境中使用。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.