登录鉴权

配置邮箱密码登录

完成后,用户可以注册账号、验证邮箱、登录,并重置忘记的密码。

邮箱密码是默认的登录方式。会话密钥在环境变量中设置,注册和邮箱验证的开关在后台中控制。

准备工作

  • 已完成迁移的数据库和第一个管理员,见 安装后的第一步。
  • 拥有 config.read 和 config.write 的管理员账号。
  • 一个邮件服务商,用于投递验证邮件和重置邮件,见 发送事务邮件。

设置会话密钥和基础 URL

设置会话密钥

在部署环境中把 BETTER_AUTH_SECRET 设为一个足够长的随机值,例如 node -e "console.log(crypto.randomUUID()+crypto.randomUUID())" 的输出。它是认证中唯一放在环境变量里的设置,因为读取数据库之前就要用到。非开发环境下缺少它,应用无法启动。

设置基础 URL

以管理员登录,进入 设置 → 认证配置(/admin/config/auth)。在 Better Auth 面板中把 基础 URL 设为部署的公网地址,例如 https://<your-domain>,点击 保存。页面显示 配置已保存。

选择账号规则

认证配置 页的 Better Auth 面板里是作用于所有账号的开关。

调整开关

  • 已启用:开启或关闭邮箱密码注册与登录。在这里保存会同步更新 邮箱登录 面板中的 已启用 开关,所以请在这里修改。
  • Delete account:允许已登录用户在 /app/profile 删除自己的账号。
  • 邮箱验证:开启时(默认),没有点过验证链接的用户无法登录,每次尝试登录都会重新发送验证邮件。

不要改动密钥

Secret 已经保存了 BETTER_AUTH_SECRET 的值,留空即保留原值。

保存

点击 保存。页面上每个面板只保存本面板的字段。

修改密钥会让所有人退出登录

在 Secret 中填入新值会替换原值,已有的登录会话全部失效。邮箱验证 开启但没有配置邮件服务商时,注册仍会成功,但新用户无法登录。

邮箱登录 面板中的 允许新用户注册 开关目前不会限制邮箱注册。

验证

注册账号

在浏览器无痕窗口中打开 /auth/sign-up 注册账号。表单提示账号已创建,并要求先验证邮箱。

验证并登录

打开验证邮件中的链接,它会进入 /auth/verify-email。然后在 /auth/sign-in 登录,登录后进入 /app/profile。

重置密码

退出登录,打开 /auth/forgot-password,为同一邮箱申请重置。重置邮件固定使用英文,其中的链接打开 /auth/reset-password,在那里设置新密码。

/setup 会显示会话密钥是否已设置,以及是否至少有一种可用的登录方式。要在命令行检查接入情况,运行 pnpm validate:auth。

常见问题

登录提示邮箱未验证

邮箱验证 处于开启状态,未验证的邮箱会被拒绝,每次尝试都会重新发送验证邮件。如果产品不需要验证邮箱,可在 认证配置 中关闭。收不到邮件时,检查 邮件配置 中的服务商,以及 /admin/email/deliveries 中的发送记录。

应用因会话密钥报错而无法启动

APP_ENV 不是 development,且 BETTER_AUTH_SECRET 未设置或仍为模板值。把它设为随机值。

登录后被带到 /system/rate-limited

每个 IP 加邮箱在 5 分钟内最多尝试登录 10 次。等窗口过去后再试。

已登录用户被跳转到 /system/session-expired

该账号的状态是 待审核。在后台的用户详情页把它改为 正常,见 管理用户、角色和权限。

参考

下一步