身份验证

NextSaas 使用 Better Auth 处理身份验证。它开箱即用地支持 OAuth (Google, GitHub)、魔术链接 (Magic Links) 和通行密钥 (Passkey)。

设置

开始之前，请确保您已在 .env 文件中设置了环境变量：

BETTER_AUTH_SECRET="your_generated_secret"

[!TIP] 生成密钥：openssl rand -base64 32

社交服务提供商

我们已预配置 Google 和 GitHub 作为 OAuth 提供商。要启用它们，您需要从各自的开发者门户获取 Client ID 和 Secret。

Google

1. 前往 Google Cloud Console。
2. 创建新项目并配置 OAuth 同意屏幕。
3. 为 OAuth 客户端 ID (Web 应用程序) 创建凭据。
4. 添加已授权的重定向 URI: http://localhost:3000/api/auth/callback/google
5. 更新您的 .env 文件:

GOOGLE_CLIENT_ID="your_google_client_id"
GOOGLE_CLIENT_SECRET="your_google_client_secret"

GitHub

1. 前往 GitHub Developer Settings。
2. 创建 New OAuth App。
3. 将 Authorization callback URL 设置为: http://localhost:3000/api/auth/callback/github
4. 更新您的 .env 文件:

GITHUB_CLIENT_ID="your_github_client_id"
GITHUB_CLIENT_SECRET="your_github_client_secret"

魔术链接 (Magic Links)

魔术链接登录允许用户通过邮件链接免密码登录。

它使用 Resend 发送邮件。请确保您已配置 Resend API 密钥：

RESEND_API_KEY="re_123456789"
EMAIL_FROM="onboarding@resend.dev"

邮件发送逻辑位于 src/lib/email.ts。您可以在那里自定义邮件模板。

通行密钥 (Passkey / WebAuthn)

通行密钥认证允许用户使用生物识别（指纹、面部识别）或硬件安全密钥登录。

设置

通行密钥默认启用。要禁用它，请在 .env 中设置：

ENABLE_PASSKEY="false"

启用后，登录页面将显示通行密钥按钮，用户可以在仪表盘设置中注册通行密钥。

[!NOTE] 通行密钥在生产环境中需要安全上下文 (HTTPS)。本地开发时，localhost 是允许的。

功能开关

您可以通过环境变量控制身份验证功能：

这些标志在启动时生效。当功能被禁用时，相关的 UI 元素会自动隐藏。

路由保护

要保护页面或 API 路由，您可以使用 auth 助手。

import { auth } from "@/auth";
import { headers } from "next/headers";
import { redirect } from "next/navigation";

export default async function DashboardPage() {
  const session = await auth.api.getSession({
    headers: await headers(),
  });

  if (!session) {
    redirect("/");
  }

  return <div>欢迎, {session.user.name}</div>;
}

管理员角色

NextSaas 通过 Better Auth 的管理员插件包含了内置的管理员角色。管理员用户可以访问管理后台，包括以下功能：

• 用户管理：查看和管理所有注册用户
• 订单追踪：查看平台上的所有订单
• 邮件订阅管理：管理邮件订阅用户
• 积分管理：管理用户积分余额
• 数据概览：查看用户和订单趋势数据