身份认证架构
梳理 Better Auth 入口、会话行为与角色中间件边界。
MuseMVP 的权限架构核心基于 Better Auth 框架构建，提供了安全、灵活且易于扩展的身份验证解决方案。我们通过统一的配置文件和中间件，实现了从用户登录、会话管理到权限控制的全链路覆盖。
设计原则
采用基于中间件的轻量级权限控制，业务决策放在 layout/page 层，避免 middleware 承担过多逻辑。
认证入口
服务端配置
src/backend/auth/auth.ts — 定义 Better Auth 核心选项、插件（admin、2FA、emailOTP、captcha、apiKey）及 Drizzle 数据库适配器。
客户端辅助
src/backend/auth/client.ts — 提供前端使用的 hooks 和工具函数（useSession、signIn、signOut）。
API 路由挂载
src/backend/api/routes/auth.ts — 将 Better Auth 处理逻辑挂载到 Hono API。
核心配置
认证行为在 packages/config 的 auth 对象中配置，分为 auth.gates 与 auth.lifecycle。
功能开关
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
gates.allowRegister | boolean | true | 是否开放新用户注册。关闭后仅管理员可添加用户。 |
gates.allowSocialSignIn | boolean | true | 是否启用社交登录（GitHub、Google）。需配置 OAuth 环境变量。 |
gates.allowPasswordSignIn | boolean | true | 是否允许邮箱/密码登录。 |
gates.allowTwoFactorAuth | boolean | true | 是否启用双因素认证（2FA）。 |
会话与跳转
| 配置项 | 默认值 | 说明 |
|---|---|---|
lifecycle.redirectAfterLogin | "/app" | 登录成功后跳转路径。 |
lifecycle.redirectAfterSignOut | "/" | 退出登录后跳转路径。 |
lifecycle.redirectWhenSessionExpired | "/auth/login" | 会话过期或未登录时的重定向路径。 |
lifecycle.sessionTtlSeconds | 30天 | 会话 Cookie 有效期（秒）。 |
配置示例
// packages/config
auth: {
gates: {
allowRegister: true,
allowSocialSignIn: true,
allowPasswordSignIn: true,
allowTwoFactorAuth: true,
},
lifecycle: {
redirectAfterLogin: "/app",
redirectAfterSignOut: "/",
redirectWhenSessionExpired: "/auth/login",
sessionTtlSeconds: 60 * 60 * 24 * 30,
},
}角色与管理员权限
采用基于中间件的轻量级权限控制：
用户鉴权 (src/backend/api/middleware/auth.ts)：拦截未登录请求并返回 401，验证会话有效性。
管理员鉴权 (src/backend/api/middleware/admin.ts)：在验证登录基础上检查 admin 角色，保护管理后台路由。
中间件链
管理路由使用 adminMiddleware，先验证会话，再检查 session.user.role === "admin"。非管理员用户将收到 403 Forbidden。
| 中间件 | 应用范围 | 行为 |
|---|---|---|
authMiddleware | /api/assets、/api/api-keys、/api/upload 等 | 要求有效会话，缺失则返回 401 |
adminMiddleware | /api/admin/*、/api/openapi、/api/docs | 要求会话 + admin 角色，非管理员返回 403 |
扩展点
- 添加社交登录：在
src/backend/auth/auth.ts中配置新 Provider，并在环境变量中添加对应 Key。 - 自定义鉴权逻辑：通过编写自定义中间件或 Better Auth 插件扩展复杂权限（如基于组织的权限）。
- 文案国际化：派生认证文案在两语言
packages/i18n/src/translations/{en,zh}/mvp.json覆盖模板的auth键；没有单独的auth.json。
相关文档
当前组合边界
Better Auth 插件/适配器工厂在 packages/auth/src/create-auth.ts，应用 src/backend/auth/auth.ts 只注入本应用的 DB、邮件、captcha、存储和合约处理。OAuth 凭据控制 provider UI，allowTwoFactorAuth 控制设置入口但不移除插件。页面守卫保留 getSessionState() 三态；后端路由必须独立校验 session、admin 和数据归属。