跳转到内容

本页由英文页面机器翻译而来。内容以英文页面为准。 阅读英文页面

用 CAPTCHA 防范机器人(Turnstile / hCaptcha / reCAPTCHA)

CAPTCHA 默认关闭:设置 captcha 为 none。此时登录、注册和重置密码页面不会向第三方发送任何数据。 选择一个 CAPTCHA 服务后,该服务的组件会出现在三个表单上:登录(/auth/sign_in)、注册(/auth/sign_up)和申请重置密码链接 (/auth/forgot_password,仅限会发送邮件的服务器)。服务器通过该服务的 siteverify API 验证组件生成的令牌。 无法只保护其中一部分表单。

captcha 服务 费用 用户需要做什么
turnstile(推荐) Cloudflare Turnstile 免费,不限量 通常什么都不用做;仅在需要时勾选复选框
hcaptcha hCaptcha 有免费额度 勾选复选框,需要时还要完成图片挑战
recaptcha Google reCAPTCHA v2(复选框) 每月 10,000 次评估以内免费(见下文) 勾选复选框,需要时还要完成图片或音频挑战

不支持 reCAPTCHA v3(仅评分)和 reCAPTCHA Enterprise。

每个服务都会给你一对密钥:公开的站点密钥,以及只有服务器持有的私密密钥。将设置 host 的主机名(不含端口)注册为域名。如果 siteverify 响应中的主机名与 host 不一致,服务器会拒绝该令牌。

  • Turnstile:在 Cloudflare 控制台的“Turnstile”下添加组件并注册主机名。组件模式选择“Managed”。
  • hCaptcha:在 hCaptcha 控制台添加站点并注册主机名。私密密钥在账号设置中。
  • reCAPTCHA:在 Google reCAPTCHA 管理控制台中,选择带“I’m not a robot”复选框的类型“Challenge (v2)”,并注册域名。密钥属于某个 Google Cloud 项目。

各服务的测试密钥(始终验证成功的那种)适合用来确认组件能显示并生成令牌。但使用测试密钥时,siteverify 返回固定的主机名(Turnstile 为 example.com,hCaptcha 为 dummy-key-pass,等等),因此在本服务器上登录和注册都会失败,并提示“请完成人机验证,然后重试”。

终端窗口
MY_CAPTCHA=turnstile
MY_CAPTCHA_SITE_KEY=0x4AAAAAAA...
MY_CAPTCHA_SECRET_KEY_FILE=/run/secrets/my_captcha_secret_key
  • 私密密钥只能通过环境变量 MY_CAPTCHA_SECRET_KEY,或指向文件的 MY_CAPTCHA_SECRET_KEY_FILE 传入。日志中显示为 [REDACTED]。
  • 如果选择了 captcha 却缺少密钥,my config check 会报告问题,服务器也不会启动。
  • 服务器启动时不会试用密钥。当服务拒绝私密密钥或站点密钥时,第一次验证会记录 ERROR 日志“the CAPTCHA service refused the secret key or the site key”。在你修正之前,请求会按下文“服务无法访问时”的方式处理。
  • 修改在重启服务器后生效。
  • 顺序依次为:速率限制、CAPTCHA 验证,然后是密码检查、注册处理或发送重置邮件。超出速率限制的请求不会发送到服务。
  • 持有有效邀请码的注册同样需要验证。
  • 未通过验证的登录会计为该客户端 IP 地址的一次登录失败。它不计入账号的失败次数,因此任何人都无法把别人锁在外面。未通过验证的注册会计为一次注册尝试(见注册中的速率限制)。申请重置链接同样计为一次申请尝试。
  • 对于 Turnstile,组件会带上操作名(sign_in / sign_up / password_reset),服务器会检查响应中的操作是否相同。一个表单的令牌不能用在另一个表单上。
  • 服务器不会把用户的 IP 地址(remoteip)发送给服务。令牌只能使用一次,因此服务器不会重试。超时时间为 10 秒。

服务无法访问、超时、返回 5xx 或拒绝密钥时:

表单 处理方式
注册和申请重置链接 拒绝(503),并提示“请稍后再试”。否则机器人可能借此触发邮件和注册。
登录 不经 CAPTCHA 直接放行,服务器记录 WARN 日志“the CAPTCHA service could not check a sign-in; letting it through”。速率限制和密码检查仍然有效。

放行登录是为了避免服务故障或密钥错误把所有人(包括管理员)都锁在外面。如果 WARN 日志持续出现,请检查服务状态和密钥。

超出每月 10,000 次评估的免费额度后,reCAPTCHA 的 siteverify 总是验证成功(因此在这段时间内 CAPTCHA 不提供任何保护)。服务器无法察觉超额,请在 Google Cloud 控制台中查看用量。

  • 组件的语言跟随页面的语言,主题跟随浏览器的配色方案(浅色或深色)。 Turnstile 组件自己跟随配色方案。hCaptcha 和 reCAPTCHA 则根据浏览器发送的客户端提示 Sec-CH-Prefers-Color-Scheme 选择;不发送该提示的浏览器会得到浅色主题。
  • 组件旁边,页面会说明由哪个服务执行检查、该服务会收到 IP 地址和浏览器信息,并附上该服务的隐私政策链接 (hCaptcha 和 reCAPTCHA 还有服务条款链接)。对于 reCAPTCHA,这同时也是 Google 要求的那句话:“This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.”
  • 无法通过 CAPTCHA 的用户既不能注册,也不能登录, 你只能用其他方式帮助他们,例如用 my admin create 创建账号,或暂时设置 captcha = none。
  • 启用 CAPTCHA 期间,Content-Security-Policy(CSP)只在登录、注册和申请重置密码的页面上放宽。'unsafe-inline' 和 'unsafe-eval' 从不会被加入。 Web 客户端、客户端 API、授权确认页面、邮件确认页面和其他页面的 CSP 不会改变。
captcha 加入的来源
turnstile script-src、frame-src:https://challenges.cloudflare.com
hcaptcha script-src、frame-src、style-src、connect-src:https://hcaptcha.com、https://*.hcaptcha.com
recaptcha script-src:https://www.google.com/recaptcha/、https://www.gstatic.com/recaptcha/;frame-src:https://www.google.com/recaptcha/、https://recaptcha.google.com/recaptcha/;connect-src:https://www.google.com/recaptcha/

如果服务器前面的反向代理或 CDN 会覆盖 CSP,请为这三个页面加入同样的来源。

启用 CAPTCHA 后,任何打开登录、注册或申请重置密码页面的人,其浏览器都会直接连接到该服务,服务会收到 IP 地址、浏览器信息和 Cookie。实例的隐私政策(my instance set privacy_policy,见实例设置)由你自己撰写,服务器不会往里添加任何内容。隐私政策模板中有一行是为该服务准备的。至少写明以下内容。

供 LLM 和编程智能体使用:llms.txt,llms-full.txt, llms-small.txt

本站的访问分析