跳到主要内容

0014 注册与验证码

  • 状态:已接受(2026-10-23)
  • 相关:ADR 0012;设计文档 02 §1.1(F02、F03、F04)、§4(配置映射)、03(S01、S05)

背景​

M1 第二部分:开放注册(F02),以及注册与多次登录失败后的验证码(F03、F04)。Blessing Skin 内置图形验证码,并可选 reCAPTCHA;社区多次提出要支持 Cloudflare Turnstile(issue #623、#633)。站长大多在中国大陆,Google 的服务直连不可用。

决策​

  • Provider 抽象(internal/captcha),由运行时设置 captcha.provider 选择,热切换:
    • image(默认):内置图形验证码。5 个字符,取自去掉易混字符的 27 个字母数字,按拒绝采样均匀抽取(crypto/rand);用 Go Bold 字体逐字旋转、缩放、抖动排布,加干扰曲线、整体正弦扭曲与噪点。答案只存在服务端内存(5 分钟、最多 2 万条);每个挑战只能尝试一次,无论对错都作废,因此无法暴力猜测。
    • turnstile / recaptcha / hcaptcha:三家共用 siteverify 协议,一套实现。reCAPTCHA 的脚本与校验都用 recaptcha.net(中国大陆可访问)。site key 进入公开的 bootstrap,secret key 只在服务端。
    • 服务不可达、或返回"密钥错误"类错误码时视为服务不可用(503,日志告警),而不是访客答错;任何情况下都不放行(fail closed)。
  • 注册(POST /api/v1/auth/register):
    • 受 auth.registration(open / closed)控制;站点完成安装前一律拒绝,第一个账号只能来自安装页。
    • 先校验字段,再校验验证码,最后才计算密码哈希:一次性的验证码不会浪费在必然失败的表单上,昂贵的 argon2 只为通过验证码的人计算。
    • auth.registrations_per_ip:同一地址 24 小时内的注册数。数据库按精确地址计数(重启后仍有效),内存另按 IPv6 /64 计数。
    • 新账号获得 score.initial(BS user_initial_score),注册后自动登录。
    • 注册接口必然会暴露"邮箱已注册"(S05 的例外):靠验证码与按地址限流约束枚举速度;邮件验证上线后可改为统一的"请查收邮件"。
  • 登录验证码(auth.login_captcha_after,默认 3):同一客户端对同一账号失败达到次数后要求验证码;同一账号在所有地址上合计失败 20 次后,所有客户端都要验证码。启用验证码时,账号维度不再锁定(ADR 0012 中的 100 次锁定只在 captcha.provider = none 时生效),所以分布式攻击也无法把真正的用户挡在门外。客户端维度的硬上限(每 15 分钟同一地址 50 次、同一地址对同一账号 10 次)不变。
  • 验证码缺失或错误统一返回 422,错误位置 body.captcha:前端据此显示或刷新验证码,与其它字段错误走同一条路径。

备选方案​

  • 引入现成的 Go 验证码库:体积大(自带字体)、风格难以与站点统一,并且我们只需要很小的一部分功能。
  • 无状态的签名挑战(答案哈希放进令牌):天然跨副本,但无法做到"只能尝试一次",除非再引入已用令牌表。单副本是当前部署形态,多副本请改用第三方验证码(文档已说明)。
  • 只支持第三方验证码:中国大陆的可用性没有保证,且增加了站长的配置负担。

影响​

  • 新增依赖 golang.org/x/image(字体与仿射变换)。
  • 前端组件 Captcha 统一渲染四种验证码,按需加载第三方脚本;插件前端(P2)可以复用它。
  • 后端多副本部署时,图形验证码需要会话保持;Helm(M4)会把这一点写进说明。