安全核心
2026-11-21·8 分钟
登录授权:邮箱密码与 Google / Facebook
Better Auth 驱动的现代化认证:邮箱密码、Google / Facebook 社交登录、弹窗认证与 RBAC 守卫的完整接入用法。
登录方式总览#
系统通过 Better Auth 统一收敛所有认证入口,全部登录方式共享同一套会话体系(session 表 + HttpOnly Cookie),业务代码无需区分用户来自哪个渠道:
会话机制
登录成功后颁发
better-auth.session_token(HttpOnly Cookie),默认 7 天滑动续期;用户可在控制台“设备与安全”中随时吊销任意会话。| 登录方式 | 渠道标识 | 所需环境变量 | 适用场景 |
|---|---|---|---|
| 邮箱 + 密码 | BETTER_AUTH_SECRET | 通用注册登录,本地开发默认方式 | |
| Google 登录 | GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET | 海外用户一键授权,转化率最高 | |
| Facebook 登录 | FACEBOOK_CLIENT_ID / FACEBOOK_CLIENT_SECRET | 欧美社交用户群覆盖 | |
| 两步验证 2FA | totp | 无(用户在控制台自助开启) | 高价值账号安全加固 |
邮箱密码登录用法#
客户端统一通过 lib/auth-client.ts 导出的 signIn / signUp / signOut 调用,全部方法返回 { data, error } 结构,配合全局 AuthModalProvider 弹窗开箱即用:
本地预置管理员
本地 PGlite 环境已预置超管账号,登录后可直接访问
/zh/admin 运营面板:账号:
admin@admin.com密码:
admin123typescript注册 / 登录 / 登出(客户端组件)
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>;
}弹窗化认证体验(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;
}
Google / Facebook 社交登录接入#
社交登录在环境变量配好后即刻生效:登录弹窗自动出现对应平台按钮,回调路由
/api/auth/callback/{provider}由 Better Auth 全权托管,首次授权自动建号并绑定account表:http://localhost:3000/api/auth/callback/google,Google / Facebook 开发者后台均允许配置 localhost 测试回调。