认证总览

vibestrap 用 Better Auth 1.4 把邮箱密码、邮箱验证、忘记密码、 修改密码、Google + GitHub OAuth、Google One-Tap、admin 角色、以及一个 openAPI 接口参考全部 接好了——你不用自己写一行认证代码。 这一页是已经接好的功能地图，告诉你哪些可以改、哪些别动。各 provider 的细节有专门的页： Google OAuth、GitHub OAuth、One-Tap。

​

已经接好的功能

打开 src/lib/auth.ts 看一眼，那里就是单一来源。简而言之：

• 邮箱 + 密码，最小密码长度 8，注册成功 autoSignIn: true。
• 邮箱验证注册时发出，链接 24 小时过期，验证后自动登录。
• 重置密码通过邮件链接，由 src/mail 的 sendForgotPasswordEmail 发送。
• 社交登录 provider 在对应 env（GOOGLE_*、GITHUB_*）存在时自动启用。
• 账号合并对受信任的 provider（google、github）开启——同邮箱归一人。
• Admin 插件默认角色 user，管理员角色 admin。
• One-Tap 插件在 siteConfig.features.enableOneTap 且有 GOOGLE_CLIENT_ID 时挂载。
• openAPI 插件，可以在 /api/auth/reference 浏览所有认证 REST 接口。
• 删除用户已启用——GDPR 数据删除流程依赖它。

​

前置条件

• 一个能通过 DATABASE_URL 连上的 Postgres。
• 已经跑过 pnpm db:push（创建 user、session、account、verification）。
• 一个至少 16 位的 BETTER_AUTH_SECRET（openssl rand -hex 32 就行）。
• BETTER_AUTH_URL 或 NEXT_PUBLIC_APP_URL 指向站点。
• 邮件流程：RESEND_API_KEY + 已经验证过的 RESEND_FROM_EMAIL。

​

一步步配置

1. 生成 secret，写到 .env.local：
   BETTER_AUTH_SECRET=$(openssl rand -hex 32)
   BETTER_AUTH_URL=http://localhost:3000
   
2. 同步 schema。这会创建 Better Auth 的四张表，和 vibestrap 自己的表并存。
   pnpm db:push
   
3. 挑你要的认证方式。src/config/site.ts：
   features: {
     enableCredentialLogin: true,
     enableEmailVerification: true,
     enableGoogleLogin: true,
     enableGithubLogin: true,
     enableOneTap: true,
   }
   
4. 配上你开启的 provider。各有专门的页：
   • Google OAuth
   • GitHub OAuth
   • One-Tap
5. （可选）把自己提成 admin。把邮箱填进 ADMIN_EMAILS（逗号分隔）， 注册后钩子会自动把 role 设为 admin：
   ADMIN_EMAILS=[email protected],[email protected]
   

​

角色系统

只有两个角色：user（默认）和 admin。重活由 admin 插件干；vibestrap 多加了一招—— src/lib/auth.ts 里的 databaseHooks.user.create.after 钩子会拿新用户邮箱比对 ADMIN_EMAILS， 命中就提权。 Server action 可以用 src/lib/safe-action.ts 的 adminActionClient 做权限拦截—— /admin 下的页都是这么写的。

​

会话配置

src/lib/auth.ts 的默认值： cookie cache 意味着一个刚被吊销的 session 最多可能”还活着”一小时。如果你要立即吊销 （企业级场景），把 cookieCache 的 TTL 调短或者直接关掉。

​

审计字段

user 表里有 lastLoginAt、lastLoginIp、lastLoginUserAgent——每次成功登录都会被 Better Auth 的 session 钩子写入。用来发安全提醒邮件（“新设备登录提示”）或者给 admin 用户列表展示很方便。别在热路径上 query 它，要做报表才考虑加索引。

​

验证是否生效

1. pnpm dev，访问 /register，注册一个账号。
2. 看 dev console——Resend 应该把验证邮件 log 出来。
3. 点验证链接 → 落到 /dashboard，已经登录。
4. 打开 /api/auth/reference 浏览 openAPI 文档，确认接口能响应。

​

常见坑

• BETTER_AUTH_SECRET 太短。少于 16 位会在启动时直接抛错。
• 生产环境 BETTER_AUTH_URL 不对。Cookie 是按这个 URL 作用域的——协议和 host 必须一字不差，否则 session 留不住。
• 邮箱验证发不出。检查 RESEND_FROM_EMAIL 的域名在 Resend 里有没有验证，没验证 API 会静默丢消息。
• 提了 admin 但看不到管理界面。钩子只在注册时跑。已存在的用户得用 SQL 改，或者删了重建。
• 升级 Better Auth 后表结构对不上。开发环境重跑 pnpm db:push，生产生成 migration。

​

官方文档

• Better Auth — better-auth.com/docs
• Admin 插件 — better-auth.com/docs/plugins/admin
• One-Tap 插件 — better-auth.com/docs/plugins/one-tap
• openAPI 插件 — better-auth.com/docs/plugins/open-api