> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibestrap.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 认证总览

> Vibestrap 如何接入 Better Auth——开了哪些功能、装了哪些插件、角色和会话模型长什么样。

认证是每个产品都必须做、又没有任何差异化价值的工作 —— 但自己搭一套通常要花 indie
开发者 1-2 周,而且常常带一两个不易察觉的 bug。vibestrap 用 [Better Auth](https://www.better-auth.com)
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`：

   ```bash theme={null}
   BETTER_AUTH_SECRET=$(openssl rand -hex 32)
   BETTER_AUTH_URL=http://localhost:3000
   ```

2. **同步 schema**。这会创建 Better Auth 的四张表，和 Vibestrap 自己的表并存。

   ```bash theme={null}
   pnpm db:push
   ```

3. **挑你要的认证方式**。`src/config/site.ts`：

   ```ts theme={null}
   features: {
     enableCredentialLogin: true,
     enableEmailVerification: true,
     enableGoogleLogin: true,
     enableGithubLogin: true,
     enableOneTap: true,
   }
   ```

4. **配上你开启的 provider**。各有专门的页：
   * [Google OAuth](/zh/auth/google-oauth)
   * [GitHub OAuth](/zh/auth/github-oauth)
   * [One-Tap](/zh/auth/one-tap)

5. **（可选）把自己提成 admin**。把邮箱填进 `ADMIN_EMAILS`（逗号分隔），
   注册后钩子会自动把 `role` 设为 `admin`：

   ```bash theme={null}
   ADMIN_EMAILS=you@example.com,cofounder@example.com
   ```

## 角色系统

只有两个角色：`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` 的默认值：

| 配置                   | 值    | 为什么                    |
| -------------------- | ---- | ---------------------- |
| `expiresIn`          | 7 天  | 短一点——token 被偷也能重新登录捕获。 |
| `updateAge`          | 1 天  | 用户活动会顺势把过期时间往后推。       |
| `cookieCache.maxAge` | 1 小时 | 省掉每次页面加载都打 DB。         |

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](https://www.better-auth.com/docs)
* Admin 插件 — [better-auth.com/docs/plugins/admin](https://www.better-auth.com/docs/plugins/admin)
* One-Tap 插件 — [better-auth.com/docs/plugins/one-tap](https://www.better-auth.com/docs/plugins/one-tap)
* openAPI 插件 — [better-auth.com/docs/plugins/open-api](https://www.better-auth.com/docs/plugins/open-api)