修复 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*"。
四、排查方法(关键证据链)
对比官方 Pro 模板:解压 halo-pro jar 到本地,直接读 BOOT-INF/classes/templates/gateway_fragments/signup.html 与 login_email-code.html,确认 Pro 发送验证码必须携带 X-Altcha-Payload,取值来自 requestAltchaChallengeResult()。
读系统脚本:BOOT-INF/classes/static/js/altcha-utils.js 定义了 requestAltchaChallengeResult(创建不可见 altcha-widget 解题);main.js 的 sendVerificationCode 揭示了「假成功」的触发条件。
反编译确认字段兼容性:用 javap -p -c 反编译 run.halo.app.infra.actuator.GlobalInfo,确认 Pro 有 captchaProvider 字段且 toString() 包含 captchaProvider=ALTCHA;同时拉取开源版 GlobalInfo.java 源码,确认开源版没有该字段 → 直接访问 ${globalInfo.captchaProvider} 会让开源版渲染报错,必须用 toString() 包含判断来兼容两套。
校验编译产物: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)下是否真的不被依赖。
本笔记为草稿,记录于故障完全修复并验证通过之后。
- 作者: 薛柔零
- 链接: https://blog.xuezero.com/archives/3eGBwBGN
- 版权: 除特别声明外,本文采用 CC BY-NC-SA 4.0 许可协议进行许可,转载请注明出处。