SaasOne v2.0 Docs
安全核心
2026-11-21·8 分钟

登录授权:邮箱密码与 Google / Facebook

Better Auth 驱动的现代化认证:邮箱密码、Google / Facebook 社交登录、弹窗认证与 RBAC 守卫的完整接入用法。

登录方式总览#

系统通过 Better Auth 统一收敛所有认证入口,全部登录方式共享同一套会话体系(session 表 + HttpOnly Cookie),业务代码无需区分用户来自哪个渠道:

会话机制
登录成功后颁发 better-auth.session_token(HttpOnly Cookie),默认 7 天滑动续期;用户可在控制台“设备与安全”中随时吊销任意会话。
登录方式渠道标识所需环境变量适用场景
邮箱 + 密码emailBETTER_AUTH_SECRET通用注册登录,本地开发默认方式
Google 登录googleGOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET海外用户一键授权,转化率最高
Facebook 登录facebookFACEBOOK_CLIENT_ID / FACEBOOK_CLIENT_SECRET欧美社交用户群覆盖
两步验证 2FAtotp无(用户在控制台自助开启)高价值账号安全加固

邮箱密码登录用法#

客户端统一通过 lib/auth-client.ts 导出的 signIn / signUp / signOut 调用,全部方法返回 { data, error } 结构,配合全局 AuthModalProvider 弹窗开箱即用:

本地预置管理员
本地 PGlite 环境已预置超管账号,登录后可直接访问 /zh/admin 运营面板:
账号:admin@admin.com
密码:admin123
typescript注册 / 登录 / 登出(客户端组件)
import { signIn, signUp, signOut } from '@/lib/auth-client';

// 注册(成功即登录,自动种下会话 Cookie)
await signUp.email({
  name: '开发者',
  email: 'dev@example.com',
  password: 'at-least-8-chars',
});

// 登录
const { error } = await signIn.email({ email: 'dev@example.com', password: '***' });
if (error) showError(error.message); // "账号或密码错误" 等文案直接可用

// 登出并清理本地会话
await signOut();
typescript服务端会话读取(RSC / Server Action / API)
import { getSession } from '@/lib/session';

export default async function DashboardPage() {
  const session = await getSession();
  if (!session) redirect('/login');
  return <div>你好,{session.user.name}</div>;
}

Google / Facebook 社交登录接入#

社交登录在环境变量配好后即刻生效:登录弹窗自动出现对应平台按钮,回调路由 /api/auth/callback/{provider} 由 Better Auth 全权托管,首次授权自动建号并绑定 account 表:

本地开发提示
本地调试无需内网穿透:回调地址直接填 http://localhost:3000/api/auth/callback/google,Google / Facebook 开发者后台均允许配置 localhost 测试回调。
env.env.local(社交登录段)
# Google OAuth(console.cloud.google.com 创建 OAuth 2.0 客户端 ID)
GOOGLE_CLIENT_ID=xxxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-...
# 授权回调地址:{BETTER_AUTH_URL}/api/auth/callback/google

# Facebook 登录(developers.facebook.com 创建应用 → Facebook 登录产品)
FACEBOOK_CLIENT_ID=1234567890
FACEBOOK_CLIENT_SECRET=...
# 授权回调地址:{BETTER_AUTH_URL}/api/auth/callback/facebook
typescript发起社交授权(一键跳转)
import { signIn } from '@/lib/auth-client';

// 跳转平台授权页,成功后自动回到 callbackURL 并完成注册/登录
await signIn.social({ provider: 'google', callbackURL: '/dashboard' });
await signIn.social({ provider: 'facebook', callbackURL: '/dashboard' });

弹窗化认证体验(Auth Modal)#

全局内置 AuthModalProvider:任意页面点击“登录 / 注册”均以居中对话框展开,支持 ?auth=login、?auth=register URL 参数直开弹窗,登录成功后就地跳转控制台,零页面跳出:

typescript在任意客户端组件中调起弹窗
import { useAuthModal } from '@/components/auth/auth-modal';

export function LoginButton() {
  const { openLogin, openRegister } = useAuthModal();
  return (
    <>
      <button onClick={openLogin}>登录</button>
      <button onClick={openRegister}>免费注册</button>
    </>
  );
}

RBAC 权限模型与管理员守卫#

系统区分两级核心权限:
1. 普通用户 (`user`):访问 /dashboard 控制台、管理个人资料、查看消费账单、使用 AI 网关与技能商店。

2. 超级管理员 (`admin`):额外开放 /admin/* 全部运营面板 —— 全站用户明细、交易对账、AI 额度调整与资产上下架。

守卫位置约束
权限判断必须放在服务端(RSC 组件顶层或 API Handler 开头)执行;客户端传来的任何角色信息仅可用于 UI 展示,绝不能作为接口放行依据。
typescript服务端权限守卫(页面与 API 通用)
import { getSession } from '@/lib/session';
import { redirect } from '@/i18n/navigation';

export async function requireAdmin() {
  const session = await getSession();
  if (!session || session.user.role !== 'admin') {
    redirect('/login');
  }
  return session.user;
}