---
url: /docs/auth.md
---
# 账号认证概览

## 已接入的能力

认证服务使用 Better Auth，配置在 `apps/api/lib/auth.ts`，客户端在 `apps/app/lib/auth.ts`。账号包括密码登录、邮箱验证码、按凭据启用的 Google 和 GitHub 登录、通行密钥登录入口、组织及订阅插件。

| 方式 | 配置入口 | 当前边界 |
| --- | --- | --- |
| 密码 | `websiteConfig.auth.password` | 注册、登录、找回与重置；非开发环境要求邮箱验证 |
| 邮箱验证码 | `websiteConfig.auth.emailOtp` | 六位验证码，需邮件发送服务 |
| 第三方登录 | 服务端完整凭据组 | Google、GitHub；真实授权需分别验收 |
| 通行密钥 | `websiteConfig.auth.passkey` | 现有账号登录；凭据管理界面尚未完整接入 |
| 组织 | 组织插件及成员页面 | 创建与成员查询；邀请邮件尚未接入 |

关闭开关时，界面入口与相应服务端能力使用同一配置。客户端插件存在并不代表服务端启用，最终以服务器返回的能力和路由为准。

## 数据与请求

`user` 保存用户，`identity` 保存第三方账号或密码身份，`session` 保存会话，`verification` 保存验证信息；组织和通行密钥有独立表。表定义在 `db/schema/`，迁移由 Drizzle 管理。

认证路径是 `/api/auth/*`，`APP_ORIGIN` 定义允许来源、回调及通行密钥域名。`BETTER_AUTH_SECRET` 必须每个站独立生成，不放进前端。

## 会话与权限

界面只通过统一查询模块读取会话。路由守卫改善访问体验，服务端的私有操作仍校验身份和资源归属。活动组织 ID 只选择操作范围，不能替代实时成员校验。

完整本地预览捕获邮件，不验证真实 Resend 投递；开发服务与线上服务使用真实邮件。详见 [账号与邮件](../agentbuff-stack/auth-mail.md)。

## 排查顺序

先运行配置诊断，再检查浏览器请求、会话 cookie、数据库迁移和服务日志。分别测试成功、取消、过期及越权路径，不以按钮出现或登录页能打开判断功能已经完成。