外观
用户认证与权限
提供完整的用户认证和权限管理能力,包括注册登录、Session/JWT 双认证、OAuth 第三方登录、RBAC 角色权限控制。
概述
用户认证与权限系统是套件的核心基础能力,所有需要用户体系的产品都可以直接复用。
核心能力
1. 用户认证
| 方式 | 说明 | 关键文件 |
|---|---|---|
| Session 认证 | express-session + MySQL 持久化 | middlewares/SessionMiddleware.mts |
| JWT 令牌 | jsonwebtoken 签发和验证 | utils/JWTUtils.mts |
| OAuth 登录 | 第三方平台 OAuth 授权 | routes/oauth.mts、services/wechat.mts |
2. 用户管理
- 注册/登录(邮箱+密码、手机号+验证码)
- 密码找回(邮件/短信验证码)
- 用户信息管理(用户名、邮箱、手机号)
- 最后登录 IP 和时间记录
3. 验证码安全机制
- 图片验证码一次性:校验通过即作废 session 中的验证码,防止同一验证码被重复提交(防暴力穷举);发送短信/邮箱验证码接口不消费,保证“先发送、再提交”两步流程内同一验证码持续有效。
- 验证码失败上限:
phone_code/email_code记录失败次数(attempts列),累计达到CODE_MAX_ATTEMPTS(默认 5 次)即作废,需重新获取;重新发送验证码时计数重置。 - 发送频率限制:短信验证码受
SMS_CODE_MIN_INTERVAL_MINUTES最小发送间隔限制,邮箱验证码为 60 秒。
4. 角色权限(RBAC)
系统内置 6 个角色:
| 角色 | key | 说明 |
|---|---|---|
| 超级管理员 | super_admin | 全部权限 |
| 管理员 | admin | 后台管理权限 |
| 贵宾会员 | svip | 高级会员 |
| 会员用户 | vip | 付费会员 |
| 普通用户 | normal | 已注册用户 |
| 游客 | guest | 未登录用户 |
5. 权限控制
- 路由级:前端
meta.requireAuth控制页面访问 - 接口级:后端中间件验证用户角色和权限
- 操作级:敏感操作(角色修改、状态修改)的二次校验
6. 登录态跨端共享
- Web 端:同主域各应用共享
localStorage的token键,登录态天然一致。 - Android 壳内:各 flavor 为独立 APK,沙箱隔离,改用系统
AccountManager共享 token(账号类型com.verysites.shell);各 flavor 须使用同一签名证书。详见前端 SPA 的「Android 壳内跨应用登录态共享」。
7. 跨设备扫码登录
- 定位:同一账号体系下,未登录设备(发起端 A)展示二维码/配对码,由另一台已登录设备(授权端 B)扫码或输码确认后,A 端直接获得登录态。零第三方付费服务,全部基于现有 Express + Redis + JWT + 安卓壳自研。
- 适用场景:支持各 flavor 安卓壳的原生扫码 Activity(CameraX + zxing 解码);无相机或拒绝权限时降级为 6 位配对码;浏览器端仅配对码可用。
- 流程:
- A 端登录页「扫码登录」tab 调
POST /api/scan-login/create生成 ticket + 配对码,前端渲染二维码(内容vscan:1:{ticket}),并每 1.5s 轮询GET /api/scan-login/status。 - B 端已登录界面的【远程登录】入口(桌面站点在顶栏头像菜单,hear 在「我的」页)调原生扫码 Activity 或输入配对码(无原生扫码能力时直接进配对码),调
POST /api/scan-login/resolve解析并展示发起端设备信息(防钓鱼)。 - B 端确认 →
POST /api/scan-login/confirm置confirmed。 - A 端轮询到
confirmed,后端原子消费 ticket 并签发 JWT,A 端经useAuthSuccess完成登录。
- A 端登录页「扫码登录」tab 调
- 接口(
src/routes/scanLogin.mts):POST /api/scan-login/create(游客,限流)— 返回{ ticket, pairCode, expiresIn }GET /api/scan-login/status?ticket=(游客,限流)— 返回状态;confirmed时原子消费并返回{ status, token, user }POST /api/scan-login/resolve(需登录)— 解析 ticket/配对码,返回发起端设备信息POST /api/scan-login/confirm(需登录)— 确认/拒绝
- Redis:
scan:login:{ticket}(TTL 150s,confirmed 后 60s 供领取)、scan:pair:{pairCode};一次性消费走 Lua 脚本防重放(src/utils/RedisUtils.mts的redisConsumeScanTicket)。 - 安全:ticket 一次性消费;resolve/confirm 必须登录;B 端确认页展示发起端设备/IP/时间防误扫;创建与状态接口限流;同一设备(
deviceId)不可自授权。 - 多 flavor:二维码内容仅含 ticket,任意 flavor 的已登录 APP 均可扫码授权,共享同一后端与账号体系。
- 会话名额:
MAX_USER_SESSIONS(默认 3)维持现状,扫码登录占用一个槽位,确认页已提示。
数据库设计
user(用户表)
核心字段:id、username、email、phone、password、role_id、status(active/inactive/locked)
role(角色表)
核心字段:id、key(角色标识)、name(角色名称)、status
phone_code / email_code(验证码表)
核心字段:phone/email、code、attempts(校验失败次数,达到上限作废需重新获取)
相关文件
apps/_base/src/apis/auth.ts— 跨 SPA 复用的登录、注册、验证码、账号激活与找回密码请求apps/_base/src/apis/user.ts— 用户信息、退出登录、修改密码等请求apps/_base/src/features/auth/components/AuthForms/— 账号密码登录、短信登录、注册、账号激活和找回密码表单apps/_base/src/features/auth/components/AuthDialogs/— 跨 SPA 复用的修改密码弹框apps/_base/src/features/auth/scripts/useAuthSuccess.ts— 登录 / 注册成功后的统一登录态写入、未激活处理与?f=回跳src/services/user.mts— 用户业务逻辑src/controllers/user.mts— 用户接口控制器src/middlewares/AuthMiddleware.mts— 认证中间件src/middlewares/SessionMiddleware.mts— Session 中间件src/models/User.mts— 用户模型src/models/Role.mts— 角色模型typings/user.d.ts— 用户类型定义