跳过主要内容
文档目录

身份验证

学习如何在 MinuteShip 中使用 Better Auth 设置和使用身份验证

MinuteShip 使用 Better Auth 进行身份验证，这是一个 TypeScript 原生的身份验证库。

设置

环境变量

生成一个随机密钥并添加到环境变量文件中：

openssl rand -base64 32

.env

BETTER_AUTH_SECRET=your_generated_secret

网站配置

一般情况下，保持默认配置即可，如果需要更改，可以修改 src/config/website.ts 中 auth 配置：

export const websiteConfig: WebsiteConfig = {
  // ...
  auth: {
    enable: true,
    enableGoogleLogin: true,     // 是否启用 Google 登录
    enableCredentialLogin: true, // 是否启用邮箱密码登录
    enableDeleteAccount: true,   // 是否支持用户删除账号
  },
  // ...
};
选项类型默认值描述
enablebooleantrue启用/禁用身份验证
enableGoogleLoginbooleantrue启用 Google OAuth 登录
enableCredentialLoginbooleantrue启用邮箱密码登录
enableDeleteAccountbooleantrue允许用户删除账户

Google OAuth（可选）

如果启用了 Google 登录，需要配置 Google OAuth：

  1. 进入到 Google Cloud Console
  2. 创建新项目
  3. 导航到 APIs & Services > Credentials
  4. 点击 Create Credentials > OAuth client ID
  5. 如果需要，配置 OAuth 同意屏幕
  6. 选择 Web application 作为应用程序类型
  7. 将 http://localhost:3000 和 https://your-domain.com 添加到 Authorized JavaScript origins
  8. 将 http://localhost:3000/api/auth/callback/google 和 https://your-domain.com/api/auth/callback/google 添加到 Authorized redirect URIs
  9. 将 Client ID 和 Client Secret 添加到环境变量文件中：

.env

GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

Note

如果您正在设置环境，现在可以回到环境配置文档并继续。本文档的其余部分可以稍后阅读。

Google One Tap（可选）

Google One Tap 会向未登录访客展示 Google 账号选择器，让他们在任意页面直接登录，无需先打开登录页。它复用上面配置的 OAuth 客户端，只要设置了 VITE_GOOGLE_CLIENT_ID 就会生效。

.env

GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
VITE_GOOGLE_CLIENT_ID=your_google_client_id

VITE_* 会在构建期编译进浏览器包，修改后需要重新构建。该 client ID 是公开值，必须与 GOOGLE_CLIENT_ID 一致。

客户端选项位于 src/auth/client.ts：

oneTapClient({
  clientId: clientEnv.VITE_GOOGLE_CLIENT_ID ?? '',
  autoSelect: false,
  cancelOnTapOutside: true,
}),
  • clientId：公开的 OAuth 客户端 ID，为空时不展示提示。
  • autoSelect: false：必须由访客确认账号，不会静默登录。
  • cancelOnTapOutside: true：点击提示框外部即可关闭。

只有在 enableGoogleLogin、GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET 全部存在时，src/auth/auth.ts 才会注册服务端插件。根布局中的 GoogleOneTap 会对未登录访客在每次页面加载时提示一次，登录后跳转到 /dashboard；提示失败时登录页上的 Google 按钮仍然可用。

如果只想保留 Google 登录、去掉弹出提示，移除 VITE_GOOGLE_CLIENT_ID 并重新构建即可。

验证邮件与生产密钥

生产环境必须设置独立随机、至少 32 字符的 BETTER_AUTH_SECRET；默认值 better-auth-secret 或过短的值会被环境校验拒绝。上线前将密钥同步到 Worker，参见部署。

注册成功不代表邮件已送达。注册后和未验证邮箱登录时可重发验证邮件；服务接受请求后，按钮进入 60 秒冷却，投递失败则显示错误并允许重试。验证邮件与重置密码邮件最多尝试 3 次，间隔 250 毫秒。密码重置对不存在的账号与发送失败返回一致响应。真实收件箱投递及链接仍需单独验证，参见邮件。

身份验证系统架构

MinuteShip 中的身份验证系统包含以下组件：

  • src/
    • auth/
      • auth.ts: Better Auth 服务端配置
      • client.ts: Better Auth 客户端配置
      • types.ts: 身份验证类型定义
    • components/
      • auth/: 身份验证相关组件
    • routes/
      • auth/
        • login.tsx: 登录页面
        • register.tsx: 注册页面
        • forgot-password.tsx: 忘记密码页面
        • reset-password.tsx: 重置密码页面
    • middlewares/
      • auth-middleware.ts: 认证中间件
      • admin-middleware.ts: 管理员中间件

身份验证路由

MinuteShip 提供以下身份验证路由：

路由描述
/auth/login登录页面
/auth/register注册页面
/auth/forgot-password密码重置请求
/auth/reset-password密码重置表单
/auth/error错误页面

参考资料

下一步

现在您了解了 MinuteShip 中身份验证的工作原理，您可能想要探索这些相关功能：