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

> 在 Kubernetes 部署中使用 Google reCAPTCHA 保护登录、注册和密码重置。

**web** 服务（`login-register` 模块）会在邮箱登录、LDAP 登录、注册和密码重置时要求通过 reCAPTCHA v2（隐形）验证。请在 [reCAPTCHA](https://ayakaleaf-pro.mintlify.site/zh-CN/on-premises/configuration/overleaf-toolkit/authentication/recaptcha.md) 中创建密钥并了解每项设置的作用；本页介绍如何将其放入 Kubernetes。

| | |
| - | - |
| 服务 | web，位于每个 Ayakaleaf Pro Pod 中；在 web 启动时读取 |
| Pod → Google | `RECAPTCHA_ENDPOINT`（默认为 `https://www.google.com/recaptcha/api/siteverify`），每个需要检查的请求都会访问 |
| 浏览器 → Google | 来自 `www.recaptcha.net` 的组件脚本 |
| 状态 | Redis 中的速率限制；加密 Cookie 中“此浏览器已通过验证”的设备历史记录 |
| 定期任务 | 无 |

### 配置

**1. 将站点密钥放入 ConfigMap**

```yaml theme={null}
  RECAPTCHA_SITE_KEY: <site key>
  # optional
  # RECAPTCHA_ENDPOINT: https://www.recaptcha.net/recaptcha/api/siteverify
  # CAPTCHA_TRUSTED_USERS: robot@example.com
```

站点密钥是公开的：每个登录页面都会显示它。

**2. 将密钥和设备历史密钥放入 Secret**

```bash theme={null}
kubectl -n overleaf patch secret overleaf-secrets --type merge -p '{"stringData":{
  "RECAPTCHA_SECRET_KEY":"<secret key>",
  "DEVICE_HISTORY_SECRET":"'"$(openssl rand -hex 32)"'"}}'
```

请同时设置这两个密钥：如果只有站点密钥而没有密钥，每次检查都会失败，任何人都无法使用密码登录、注册或重置密码。`DEVICE_HISTORY_SECRET` 必须是 64 个十六进制字符；容器不会自动生成它。

**3. 应用并重启**

```bash theme={null}
kubectl apply -f 30-config.yaml
kubectl -n overleaf rollout restart deployment/overleaf     # or statefulset/overleaf
```

然后检查每个 Pod 是否都能访问该端点。每次连接尝试大约一秒后 Pod 就会放弃，而无法完成检查的登录会因错误而失败：

```bash theme={null}
for p in $(kubectl -n overleaf get pod -l app=overleaf -o name); do   # app=overleaf-ha for several replicas
  kubectl -n overleaf exec "$p" -- curl -sS -o /dev/null -w "$p %{http_code}\n" \
    https://www.google.com/recaptcha/api/siteverify
done
```

### 多个副本

所有副本必须共享 `DEVICE_HISTORY_SECRET`，当它位于 Secret 中时即可满足这一点。如果值不同，在一个副本上已通过验证的浏览器在另一个副本上会再次遇到验证码。速率限制在 Redis 中跨所有副本统计。

### 在 Kubernetes 上的测试

针对 Google 验证端点的模拟服务（通过来自 `overleaf-certs` 的 `NODE_EXTRA_CA_CERTS` 信任），在 Kubernetes 1.37 上，我们针对 reCAPTCHA 的端到端测试全部通过（13 个用例）：在一个副本上，登录、注册和密码重置在没有验证码或验证失败时均被拒绝，在验证通过时被接受；来自 `DEVICE_HISTORY_SECRET` 的设备历史记录让浏览器跳过验证码；以及 `CAPTCHA_TRUSTED_USERS`；在位于 HAProxy 之后的三个副本上，带验证码的 LDAP 登录。


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