身份验证

TanStarter 使用 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, // 是否启用邮箱密码登录
  },
  // ...
};

选项	类型	默认值	描述
enable	boolean	true	启用/禁用身份验证
enableGoogleLogin	boolean	true	启用 Google OAuth 登录
enableCredentialLogin	boolean	true	启用邮箱密码登录

Google OAuth（可选）

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

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

.env

GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

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

环境配置

设置环境变量

验证邮件与生产密钥

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

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

身份验证系统架构

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

auth.ts

client.ts

types.ts

身份验证路由

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

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