> ## 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.