配置邮箱密码登录
完成后,用户可以注册账号、验证邮箱、登录,并重置忘记的密码。
邮箱密码是默认的登录方式。会话密钥在环境变量中设置,注册和邮箱验证的开关在后台中控制。
准备工作
设置会话密钥和基础 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
该账号的状态是 待审核。在后台的用户详情页把它改为 正常,见 管理用户、角色和权限。