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(BSuser_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)会把这一点写进说明。