设置 OAuth 登录

创建并验证真实账户

身份验证意味着证明谁在使用该应用程序。启动 Postgres 并首先使用数据库指南运行迁移，然后保持 Web 服务器运行。打开http://localhost:3000/auth,选择电子邮件/密码注册，输入您的姓名、电子邮件和密码，然后提交。保留 EMAIL_PROVIDER=local 进行第一次测试。

当流程请求电子邮件代码时，请在另一个浏览器选项卡中打开 http://localhost:3000/mail-preview，找到该地址的最新消息并将其代码复制回登录表单。如果代码过期，请请求新的代码。这些消息保留在本地发件箱中；反复检查外部收件箱将找不到它们。注销，然后再次登录以确认数据库支持的帐户正常工作。

如果注册报告数据库连接或缺少表错误，请完成数据库设置而不是启用社交登录。 Google、GitHub、Apple、X 和 Microsoft 按钮需要自己的提供商应用程序和回调设置；仅在其提供程序指南完成后才启用它。 Better Auth 是出厂默认引擎，不需要付费身份验证帐户即可进行本地电子邮件登录。

• 创建账户前启动Postgres
• 电子邮件登录代码的使用和故障排除
• 配置Google登录
• 添加 Google 登录
• 添加 GitHub 登录
• 添加 Apple 登录

选择启用的登录方式

基础包含邮箱/密码、OTP 与可配置的社交认证。Better Auth 负责身份与会话，应用则组合供应商配置与 OTP 的事务性投递。

只启用你已配置的社交供应商。供应商客户端密钥与认证密钥留在服务端。

把身份连接到工作区

已认证的 handler 在访问工作区记录之前先解析会话状态。工作区开通必须保持幂等，使重放生命周期钩子不会创建重复的归属记录。

验证会话行为

测试登录、无效或过期 OTP、一次性消费、退出与匿名访问拒绝。内存适配器测试覆盖 handler 语义；生产数据库持久化与真实供应商回调需要单独验收。

安装与配置

1. 将 AUTH_SECRET 设置为至少 32 个随机字符；可以运行 openssl rand -hex 32 生成。

2. 在各服务商的开发者控制台创建 OAuth 应用，并注册回调 URL：默认 AUTH_PROVIDER=better-auth 时为 {APP_URL}/api/auth/callback/<provider>。如果服务商只允许一个回调地址，请为本地和生产环境分别创建应用；docs/github-auth-setup.md 提供完整的 GitHub 配置流程。

3. 打开对应服务商开关并设置客户端 ID 和密钥：例如 AUTH_GOOGLE_ENABLED、GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET；Apple、GitHub、Microsoft 和 Twitter 使用对应变量。开关开启但缺少凭据会导致启动失败，并指出缺少的变量。

4. Microsoft 的回调地址会随认证引擎变化：Better Auth 使用 /api/auth/callback/microsoft，Auth.js 使用 /api/auth/callback/microsoft-entra-id。

AUTH_SECRET=<at-least-32-random-characters>
AUTH_PASSKEY_ENABLED=true
EARLY_ACCESS_INVITE_ONLY=false

AUTH_GOOGLE_ENABLED=true
GOOGLE_CLIENT_ID=…
GOOGLE_CLIENT_SECRET=…

AUTH_GITHUB_ENABLED=true
GITHUB_CLIENT_ID=…
GITHUB_CLIENT_SECRET=…

# AUTH_APPLE_ENABLED / AUTH_MICROSOFT_ENABLED / AUTH_TWITTER_ENABLED
# follow the same pattern:
# MICROSOFT_CLIENT_ID=…  MICROSOFT_CLIENT_SECRET=…
# TWITTER_CLIENT_ID=…    TWITTER_CLIENT_SECRET=…

# Workspace connected accounts (Settings → Connections):
# CONNECTED_X_CLIENT_ID=          CONNECTED_X_CLIENT_SECRET=
# CONNECTED_GOOGLE_CLIENT_ID=     CONNECTED_GOOGLE_CLIENT_SECRET=
# CONNECTED_MICROSOFT_CLIENT_ID=  CONNECTED_MICROSOFT_CLIENT_SECRET=

# Callbacks to register (Better Auth):
#   {APP_URL}/api/auth/callback/google
#   {APP_URL}/api/auth/callback/apple
#   {APP_URL}/api/auth/callback/github
#   {APP_URL}/api/auth/callback/twitter
#   {APP_URL}/api/auth/callback/microsoft   (Auth.js: microsoft-entra-id)

实现流程

工作区的外部账户是另一项功能：CONNECTED_X_*、CONNECTED_GOOGLE_* 和 CONNECTED_MICROSOFT_* 凭据供“设置 → 连接”使用，回调地址位于 {APP_URL}/api/accounts/{x|google|microsoft}/callback。客户端 ID 为空时，对应连接流程会关闭；不要复用登录应用的凭据。

客户端密钥只保留在服务器端，和 AUTH_SECRET 一样；不要放进 NEXT_PUBLIC_ 或 EXPO_PUBLIC_ 变量。

登录流程已运行？继续阅读《设置 AI》。

验证与排障

测试首次登录、已有会话、取消授权以及禁用服务商的情况。最常见的问题是回调地址不匹配——注册地址必须与 APP_URL 和认证引擎的回调路径完全一致；修改环境变量后还要重启应用。