身份验证

在 LaunchSaaS 中配置 Better Auth，支持社交登录（Google、GitHub）、魔术链接、角色权限控制和安全会话管理。

LaunchSaaS 使用 Better Auth 进行身份验证，提供灵活且安全的系统，支持多种身份验证方法、会话管理和基于角色的访问控制。

当前边界是：

apps/launchsaas/src/lib/auth/auth.ts 负责 Better Auth 的 server 构建
apps/launchsaas/src/lib/auth/auth-client.ts 负责 Better Auth 的 client 构建
apps/launchsaas/src/components/layout/better-auth-ui-provider.tsx 负责把 auth client 和 router、i18n、客户端可见的 auth UI 配置接起来
packages/design-system/ui/src/components/{auth,user,settings} 存放应用消费的 Better Auth UI source-vendor 组件

设置

BETTER_AUTH_SECRET 是用于加密和生成哈希的随机字符串。使用 VictoryHub 生成一个或运行：

openssl rand -base64 32

将其添加到你的 .env 文件：

BETTER_AUTH_SECRET="your-generated-secret-key"

Email/password 身份验证通过 auth.ts 中的 emailPasswordEnabled 标志默认启用。启用后配合邮件 Provider，用户可以注册、登录、验证邮箱和重置密码。

如需禁用，将标志设为 false：

// apps/your-app/src/lib/auth/auth.ts
const emailPasswordEnabled = false; // 默认为 true

当 emailPasswordEnabled 为 true 时，必须在 capabilities.ts 中配置邮件 Provider。否则，在尝试发送验证或重置邮件时 auth 会抛出错误。

Magic link 默认禁用。启用步骤：

const magicLinkEnabled = true; // 原来是 false

启用后，Better Auth 会向用户邮箱发送一次性登录链接，登录 UI 会自动显示 magic link 选项。

Magic link 依赖邮件 Provider。如果 capabilities.email 为 null，启用 magic link 时 Better Auth 会在启动时抛出错误。

前往 GitHub 开发者设置
点击"OAuth Apps"→"New OAuth App"
填写注册表单：
- 应用名称：你的应用名称
- 主页 URL：http://localhost:3000（或你的生产环境 URL）
- 授权回调 URL：http://localhost:3000/api/auth/callback/github
点击"Register application"
生成客户端密钥
添加到你的 .env 文件：

NEXT_PUBLIC_GITHUB_CLIENT_ID="your-client-id"
GITHUB_CLIENT_SECRET="your-client-secret"

为开发和生产环境创建单独的 OAuth 应用。它们需要不同的回调 URL。

前往 Google Cloud Console
创建新项目或选择现有项目
前往"凭据"→"创建凭据"→"OAuth 客户端 ID"
如果提示，配置 OAuth 同意屏幕
创建 OAuth 客户端 ID：
- 应用类型：Web 应用程序
- 已授权的 JavaScript 来源：http://localhost:3000
- 已授权的重定向 URI：http://localhost:3000/api/auth/callback/google
添加到你的 .env 文件：

NEXT_PUBLIC_GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="your-client-secret"

设置 CAPTCHA_SECRET_KEY 后，CAPTCHA 会自动激活，无需修改代码。

请参阅 CAPTCHA 配置指南了解支持的 Provider 和详细设置步骤。

LaunchSaaS 身份验证包括：

Email/Password - 注册、登录、邮箱验证和密码重置（默认启用；在 auth.ts 中将 emailPasswordEnabled 设为 false 以禁用）
Magic Link - 无密码身份验证（默认禁用；在 auth.ts 中将 magicLinkEnabled 设为 true 以启用）
社交登录 - Google 和 GitHub OAuth（添加 client ID 环境变量后启用）
CAPTCHA - 支持 Cloudflare Turnstile、Google reCAPTCHA、hCaptcha 和 CaptchaFox（添加 CAPTCHA_SECRET_KEY 后启用；详见 CAPTCHA 指南）
会话管理 - 服务器端会话处理
基于角色的访问 - 用户和管理员角色
App 持有 Auth Wiring - server、client 和 auth UI 都由你的 app 维护