修复 Halo Pro 注册页邮箱验证码 ALTCHA 失效的完整排查记录

分类 记录
标签 AI生成Halo
修复 Halo Pro 注册页邮箱验证码 ALTCHA 失效的完整排查记录

AI 整理声明:本文由 Trae AI(Trae 团队自研模型) 基于本次 Halo 注册页邮箱验证码 / ALTCHA 故障的排查过程整理生成,内容仅供学习与参考;文中涉及的代码片段、配置项与结论,请读者结合自身 Halo 版本与实际运行环境自行核实。

PS:我靠,没事不要太高度定制认证页面,修不完的 bug 啊,去使用插件:登录工坊 吧🥴

一、背景

站点运行 Halo Pro(版本 ≥2.27,启用 ALTCHA 人机验证),使用自定义 Astro 主题 theme-astro-demo。注册页「发送邮箱验证码」功能异常,排查中发现三层相互掩盖的故障,全部修复并验证通过。本文记录完整的因果链、排查方法与改动点,供后续同类问题复用。

二、现象演进(三层故障)

阶段一:点击发送报 altchaPayload is not defined

浏览器控制台抛 ReferenceError,发送按钮无反应。

阶段二:提示「发送成功」,响应体却是 400 Invalid captcha(假成功)

阶段一修掉引用错误后,点击发送会弹成功 toast 并开始 60s 倒计时,但实际收不到邮件。抓包 /signup/send-email-code 返回:

{
  "detail": "Invalid captcha",
  "status": 400,
  "type": "https://www.halo.run/probs/invalid-captcha"
}

请求未携带有效的人机验证 payload,前端却把失败当成了成功。

阶段三:输入验证码后提示「请与请求的格式匹配」

前两阶段修复后邮件能收到,但填入数字验证码点击提交时被浏览器原生校验拦下(HTML5 patternMismatch 默认文案),请求根本未发出。

三、根因分析

根因 1:主题误删了 ALTCHA 挑战请求

提交 fa0c170「移除多余的 ALTCHA 人机验证相关代码」删除了发送验证码前的两行关键逻辑:

const altchaEnabled = /*[[${#strings.contains(globalInfo.toString(), 'captchaProvider=ALTCHA')}]]*/ false;
const altchaPayload = altchaEnabled ? await requestAltchaChallengeResult() : '';

却残留了 fetch 请求头里的 'X-Altcha-Payload': altchaPayload 引用 → 阶段一的 ReferenceError。若再把这行残留引用删掉(对齐开源版模板),就变成完全不发 payload → 阶段二的 400。

关键点:开源版 Halo 没有 ALTCHA,其 signup.html 本就不发该头;而 Halo Pro 的 /signup/send-email-code 端点强制校验 X-Altcha-Payload。绝不能拿开源版模板覆盖 Pro 的行为。

根因 2:错误处理漏判 json.detail,导致假成功

Pro 的 sendVerificationCode(/js/main.js)只在 sendRequest() reject 时才弹错误 toast,否则就弹成功。而 signup 原错误处理只检查 json.errors,captcha 失败返回的是 RFC 7807 问题详情 {"detail": "Invalid captcha"},没有 errors 数组,于是没抛错 → sendRequest resolve → 弹「发送成功」。

根因 3:HTML pattern 写成了双反斜杠

验证码输入框写成 pattern="\\d*"(双反斜杠)。Astro 对属性值原样输出(不会像 JS 字符串那样把两个连续反斜杠转成一个),所以编译产物里也是双反斜杠。HTML5 的 pattern 是正则,双反斜杠 + d + 星号 匹配的是「一个字面反斜杠 + 若干字母 d」,不匹配数字 → 输入数字时触发 patternMismatch。

这是潜伏 bug:前两阶段没修好时用户走不到填码这一步,所以一直没暴露。官方模板(Pro / OSS)此处都是单反斜杠 pattern="\d*"。

四、排查方法(关键证据链)

  1. 对比官方 Pro 模板:解压 halo-pro jar 到本地,直接读 BOOT-INF/classes/templates/gateway_fragments/signup.html 与 login_email-code.html,确认 Pro 发送验证码必须携带 X-Altcha-Payload,取值来自 requestAltchaChallengeResult()。

  2. 读系统脚本:BOOT-INF/classes/static/js/altcha-utils.js 定义了 requestAltchaChallengeResult(创建不可见 altcha-widget 解题);main.js 的 sendVerificationCode 揭示了「假成功」的触发条件。

  3. 反编译确认字段兼容性:用 javap -p -c 反编译 run.halo.app.infra.actuator.GlobalInfo,确认 Pro 有 captchaProvider 字段且 toString() 包含 captchaProvider=ALTCHA;同时拉取开源版 GlobalInfo.java 源码,确认开源版没有该字段 → 直接访问 ${globalInfo.captchaProvider} 会让开源版渲染报错,必须用 toString() 包含判断来兼容两套。

  4. 校验编译产物:astro build 后检查 templates/gateway_fragments/signup.html,确认 Thymeleaf 内联表达式 /*[[...]]*/ 未被 strip-html-comments 误删、pattern 的反斜杠数量正确。

五、修复方案与改动点

文件:src/pages/gateway_fragments/signup.astro 的发送验证码脚本:

const altchaEnabled = /*[[${#strings.contains(globalInfo.toString(), 'captchaProvider=ALTCHA')}]]*/ false;
const altchaPayload = altchaEnabled ? await requestAltchaChallengeResult() : '';

const response = await fetch('/signup/send-email-code', {
  method: 'POST',
  body: JSON.stringify({ email: email }),
  headers: {
    'Content-Type': 'application/json',
    [headerName]: token,
    'X-Altcha-Payload': altchaPayload,
  },
});

if (!response.ok) {
  const json = await response.json();
  if (json.errors && json.errors.length) {
    throw new Error(json.errors[0]);
  }
  if (json.detail) {
    throw new Error(json.detail);   // 兜底 RFC 7807 问题详情
  }
  throw new Error(i18nResources.sendVerificationCodeFailed);
}

文件:src/pages/gateway_fragments/signup.astro 与 totp.astro 的验证码输入框:

pattern="\d*"       // signup 邮箱验证码,原为双反斜杠
pattern="\d{6}"     // totp 两步验证码,原为双反斜杠

六、验证

  • pnpm exec astro build 通过;产物中 altchaEnabled / altchaPayload / X-Altcha-Payload / json.detail 文本完整,pattern 为单反斜杠。

  • pnpm check(astro check):179 个文件 0 错误 0 警告。

  • 实际注册流程:发送验证码 → 静默完成一次不可见 altcha 解题 → 携带 payload 请求成功 → 收到邮件 → 填入数字验证码通过浏览器校验 → 提交注册成功。

七、经验与避坑清单

  • 区分开源版与 Pro 模板:Halo 的模板在 GitHub 开源仓与 Pro jar 中可能不同(Pro 多了 captcha、phone、域名限制等逻辑)。覆盖主题片段时,以目标运行环境的真实模板为准,不要只看开源仓。

  • 跨版本兼容用 toString() 防御:访问仅 Pro 存在的模型字段时,优先 #strings.contains(globalInfo.toString(), '...') 而非直接属性访问,避免开源版渲染抛 SpEL 错误。

  • Astro 属性值原样输出:pattern 等属性里的反斜杠不会被转义,要一个反斜杠就写一个,不要写成两个。改完务必检查编译产物。

  • 错误处理要覆盖 detail:Halo Pro 的错误响应常是 RFC 7807(detail 字段)而非 errors 数组;只判 errors 会把失败当成功。可参考主题自身 login_email-code.astro 的写法。

  • 不要在未闭环时删「多余」代码:提交 fa0c170 误以为 altcha 逻辑多余而删除,是本次故障的源头。删除前先确认该逻辑在目标环境(Pro)下是否真的不被依赖。

本笔记为草稿,记录于故障完全修复并验证通过之后。