注册登录注销与请求处理全链路流程图
基于 oauth21 SSO 中心 + 系统级 auth 框架的实际代码追踪绘制。 涵盖:注册、登录、设备指纹、注销、访问风险检测、请求处理全链路。 注册端点:
POST /user/v1/register(user 域);登录端点:POST /oauth2.1/login(oauth21 域)。 两域共享:验证码(verify 域)、RSA 加解密(oauth21/crypto)、用户模型(user 域 DAO)。范围说明:本仓只实现后端。图中标注「外部前端」的参与者(注册页 / 登录页 / 父窗口 / 个人中心)代表任意外部客户端,前端工程已于 2026-10-31 迁出本仓; 它们与后端之间的契约见 认证集成。
一、注册全链路
1.1 注册时序图(前端 → 后端 → 数据库)
sequenceDiagram
autonumber
actor U as 用户
participant FE as 注册页<br/>(外部前端,已迁出本仓)
participant VAPI as verify API<br/>/verify/v1/*
participant SMTP as SMTP 邮件
participant RDS as Redis<br/>(email_code store)
participant UAPI as user API<br/>/user/v1/register
participant DAO as UserDao
participant CRYPT as RSA 解密<br/>(oauth21/crypto)
participant AUDIT as audit-logger<br/>(logRegister)
participant DB as MySQL<br/>(User/UserIdentity/UserRole)
Note over U,FE: 阶段 0:进入注册页(H5 签名自动注入)
U->>FE: 打开注册页,填用户名/邮箱/密码
FE->>VAPI: GET /verify/v1/generate-captcha
Note right of FE: 前端拦截器读 _m_h5_tk cookie<br/>自动加 X-Sign/X-Timestamp/X-Nonce
VAPI->>RDS: captchaStore.set(captchaKey, value, TTL)
VAPI-->>FE: { captchaKey, captchaImage }
Note over U,FE: 阶段 1:图形验证码 + 发邮箱码(绑指纹 + sessionId)
U->>FE: 输图形码 + 邮箱,点"发送验证码"
FE->>FE: 保留 captchaKey(注册提交时回传,后端校验 sessionId 一致性)
FE->>VAPI: POST /verify/v1/verify-captcha<br/>{captchaKey, captchaValue, email, type:'register'}<br/>+ H5 签名头
VAPI->>VAPI: verifySignature 校验(requireSignature)
VAPI->>RDS: captchaStore.get → 校验图形码
alt 图形码错误
VAPI-->>FE: 400 验证码错误
else 图形码正确
VAPI->>VAPI: emailDao.sendCode(email, sessionId=captchaKey, store,<br/>{ip, ua, deviceFp}) 绑定客户端指纹
VAPI->>RDS: emailCodeStore.set(email,<br/>{code, sessionId:captchaKey, fingerprint:SHA256(IP|UA)}, 5min)
VAPI->>SMTP: 发送邮箱验证码
VAPI->>RDS: captchaStore.consume(captchaKey) 销毁图形码(一码一用)
VAPI-->>FE: { emailSent: true }
end
Note over U,FE: 阶段 2:提交注册(H5 签名 + 限频 + captchaKey 回传)
U->>FE: 输邮箱验证码,点"注册"
FE->>FE: rsaEncrypt(password)<br/>+ getCachedKid()<br/>+ 取 onCaptchaSuccess 保留的 captchaKey
FE->>UAPI: POST /user/v1/register<br/>{username, email, password(密文), code, kid, captchaKey, role_ids?}<br/>+ H5 签名头
Note right of UAPI: 限频 5次/分钟<br/>超限 429
Note over UAPI,DB: 阶段 3:后端校验邮箱码(回查 sessionId + 指纹)
UAPI->>RDS: emailDao.verifyCode(email, code, store,<br/>{ip, ua, deviceFp, sessionId:captchaKey})
alt 邮箱码错误/过期
RDS-->>UAPI: 校验失败
UAPI->>AUDIT: logRegister(success:false, reason:验证码错误)
UAPI-->>FE: 400 验证码错误
else sessionId 不符(跨流程复用)
RDS-->>UAPI: 静默拒绝
UAPI->>AUDIT: logRegister(success:false, reason:sessionId 不符)
UAPI-->>FE: 400 验证码错误
else 邮箱码正确 + sessionId + 指纹一致
RDS-->>UAPI: 通过
else 指纹不符(异地冒用)
RDS-->>UAPI: 静默拒绝("验证码错误或已过期")
UAPI->>AUDIT: logRegister(success:false, reason:指纹不符)
UAPI-->>FE: 400 验证码错误
end
Note over UAPI,DB: 阶段 4:createUser 预检
UAPI->>DAO: createUser(request)
DAO->>DB: User.findOne({where:{email}})
alt 邮箱已存在
DB-->>DAO: user
DAO-->>UAPI: throw REGISTER_FAILED:邮箱已存在
UAPI->>AUDIT: logRegister(success:false, reason:邮箱已存在)
UAPI-->>FE: 400 注册失败(业务错误 400)
else 邮箱可用
DB-->>DAO: null
end
Note over UAPI,DB: 阶段 5:registerUser 事务(核心)
DAO->>CRYPT: decrypt(encryptedPassword, kid)
CRYPT-->>DAO: 明文 password
DAO->>DAO: validatePasswordStrength(password)
alt 复杂度不足
DAO-->>UAPI: throw REGISTER_FAILED
UAPI->>AUDIT: logRegister(success:false, reason:复杂度不足)
UAPI-->>FE: 400 注册失败
else 通过
DAO->>DAO: hashPassword(password)<br/>scrypt(N=16384,r=8,p=1)+ 并发背压
DAO->>DB: BEGIN TRANSACTION
DAO->>DB: User.create({username, email})
DB-->>DAO: user (含 id, uid)
DAO->>DB: UserIdentity.create<br/>{user_id, identity_type:'password',<br/>identifier:email, credential:hash}
alt 指定 role_ids
loop 每个 role_id
DAO->>DB: UserRole.create<br/>{user_id, role_id, app_id:'GLOBAL'}
end
else 未指定角色
DAO->>DB: Role.findOne<br/>{code:'user_normal', app_id:'GLOBAL'}
alt user_normal 角色存在
DB-->>DAO: user_normal 角色
DAO->>DB: UserRole.bulkCreate(默认 user_normal)
else user_normal 缺失(V9 加固)
DB-->>DAO: null
DAO-->>UAPI: throw REGISTER_FAILED:默认角色未初始化
Note right of DAO: 事务回滚,不创建无角色脏数据
UAPI->>AUDIT: logRegister(success:false, reason:user_normal缺失)
UAPI-->>FE: 400 注册失败
end
end
DAO->>DB: COMMIT
DB-->>DAO: user
end
DAO-->>UAPI: user 实例
UAPI->>AUDIT: logRegister(success:true, userId)
Note right of AUDIT: email 脱敏记录<br/>写 DB(AuditLog) + Redis
UAPI-->>FE: 200 注册成功 {user}
FE->>FE: 跳回登录页1.2 注册涉及的数据写入
| 表 | 字段 | 写入时机 | 说明 |
|---|---|---|---|
user_user | username, email, uid(自动), status | 事务内 create | 用户基础信息,uid 为 UUID |
user_identity | user_id, identity_type='password', identifier=email, credential=scrypt 哈希串 | 事务内 create | 密码凭证,与 User 解耦(历史 bcrypt 串仍可校验,登录成功即透明升级) |
iam_user_role | user_id, role_id, app_id='GLOBAL' | 事务内 bulkCreate | 角色绑定,默认 code='user_normal'(不能按 rank_level=1 取:那是 user_banned) |
事务保证:三张表同事务,任一失败全部回滚,不会出现"有用户无凭证"的脏数据。
二、登录验证全链路
2.1 登录时序图(iframe SSO 场景)
sequenceDiagram
autonumber
actor U as 用户
participant IFRAME as 登录页<br/>(iframe 内,外部前端)
participant OAPI as oauth21 API<br/>/oauth2.1/login
participant DEC as decryptLoginRequest
participant ANOM as anomaly-detector
participant AUTH as AuthorizationService
participant CLI as ClientDao
participant APR as ApprovalDao
participant ISS as issueDirectTokens
participant PARENT as 父窗口宿主页<br/>(任意外部前端)
participant BAPI as auth API<br/>/auth/v1/bind-session
participant CKA as Cookie 写入
Note over U,IFRAME: 阶段 0:iframe 加载登录页
U->>IFRAME: 填账号/密码(或邮箱+码),勾"保持登录"
IFRAME->>IFRAME: rsaEncrypt(password) + kid
IFRAME->>OAPI: POST /oauth2.1/login<br/>{client_id, scope, 加密body, keepLogin}
Note over OAPI,ANOM: 阶段 1:解密 + 图形码校验 + 异常检测
OAPI->>DEC: decryptLoginRequest(request)
DEC->>DEC: RSA 解密 + 时间戳校验 + Nonce 防重放
alt 解密/签名失败
DEC-->>OAPI: success:false
OAPI-->>IFRAME: 400 请求非法
else 解密成功
DEC-->>OAPI: {username, password, type, email, code, keepLogin}
end
OAPI->>OAPI: 图形码校验(按 type 分支)
alt type='password'(密码登录)
OAPI->>RDS: captchaStore.get(captchaKey) 校验 verified
alt 未验证/过期
RDS-->>OAPI: 失败
OAPI-->>IFRAME: 400 请先完成图形验证
else 已验证
OAPI->>RDS: captchaStore.delete(captchaKey) 一次性消费
end
else type='email'(邮箱码登录)
Note right of OAPI: 图形码已在发邮箱码时消费<br/>此处只校验邮箱码(阶段 2)
end
OAPI->>ANOM: detectLoginAnomaly({email, ip, ua})
ANOM-->>OAPI: BLOCK / PASS
alt 暴力破解锁定
OAPI-->>IFRAME: 429 已锁定
end
Note over OAPI,AUTH: 阶段 2:验证用户身份
alt type='email'(邮箱验证码登录)
OAPI->>OAPI: verifyEmailCode(email, code, request)<br/>校验 sessionId(captchaKey) + 指纹一致性
OAPI->>AUTH: UserDao.findByEmail(email)
AUTH-->>OAPI: user 或 404 未注册
else 账号密码登录
OAPI->>AUTH: authenticateUser(username, password)
AUTH->>AUTH: decrypt 密码 + verifyPassword()<br/>scrypt 校验(兼容历史 bcrypt 只校验)
alt 密码错误
AUTH-->>OAPI: null
OAPI-->>IFRAME: 401 账号或密码错误
else 验证通过
AUTH-->>OAPI: user
end
end
Note over OAPI,APR: 阶段 3:客户端 + 授权检查
OAPI->>CLI: client_id 校验(一方应用/ClientDao.findById)
alt 无效 client
CLI-->>OAPI: null
OAPI-->>IFRAME: 400 无效客户端
end
OAPI->>APR: getEffectiveApproval(user.id, client_id)
alt 未授权(三方应用)
APR-->>OAPI: null
OAPI->>OAPI: 生成 consentKey + 绑定客户端指纹<br/>{userId, clientId, scopes, fingerprint:SHA256(IP|UA)}
OAPI-->>IFRAME: {action:'consent', consentKey}
Note right of IFRAME: 需用户确认授权<br/>(一方应用跳过此步)
Note over IFRAME,APR: 确认授权:POST /login/consent/confirm<br/>后端校验 consentKey 指纹一致(V5 防 consentKey 泄露被冒用)
else 已授权/一方应用
APR-->>OAPI: approval
end
Note over OAPI,ISS: 阶段 4:签发令牌 + 建 Session
OAPI->>ISS: issueDirectTokens(user, client_id, scope, {rememberMe:keepLogin})
ISS->>ISS: createSession(user) → Redis session
ISS->>CKA: setCookie('sid', signed, HttpOnly)
alt keepLogin=true(保持登录)
ISS->>CKA: setCookie('sid_r', refreshToken, path:/auth/v1/refresh-session)
ISS->>CKA: setCookie('k_<HMAC(uid)>', refreshToken, HttpOnly)
Note right of CKA: 凭证 cookie 供免切<br/>accountKey=uid 返回前端
end
ISS-->>OAPI: {access_token, refresh_token, session_token, user, accountKey, rememberMe}
OAPI-->>IFRAME: 200 {accessToken, sessionToken, user, accountKey, rememberMe}
Note over IFRAME,PARENT: 阶段 5:postMessage 通知父窗口
IFRAME->>PARENT: postMessage({type:'LOGIN_SUCCESS',<br/>token, sessionToken, user})
Note right of PARENT: 校验 origin + source<br/>(防伪造)
Note over PARENT,CKA: 阶段 6:父窗口换 cookie + 记录账号
PARENT->>BAPI: POST /auth/v1/bind-session<br/>{session_token}
BAPI->>BAPI: isAllowedOrigin 校验(白名单)
BAPI->>CKA: 在父域写 sid/sid_r/k_<HMAC(uid)>
BAPI-->>PARENT: {user(含uid), accountKey, rememberMe}
PARENT->>PARENT: addSavedAccount(user, accountKey, rememberMe)
PARENT->>PARENT: emit('login-success') → 关弹窗,刷新应用状态2.2 登录验证的安全检查点
| 阶段 | 检查项 | 实现位置 | 失败结果 |
|---|---|---|---|
| 解密 | RSA 签名 + 时间戳 + Nonce 防重放 | decryptLoginRequest | 400 请求非法 |
| 异常 | 暴力破解锁定(IP+账号维度) | detectLoginAnomaly | 429 已锁定 |
| 身份 | 密码 scrypt 校验(历史 bcrypt 只校验 + 透明升级)/ 邮箱码校验(绑 IP+UA 指纹 + sessionId 一致性) | authenticateUser / verifyEmailCode | 401/404,指纹/sessionId 不符静默拒绝 |
| 客户端 | client_id 有效性 | ClientDao.findById | 400 无效客户端 |
| 授权 | 用户是否授权该应用 + consentKey 绑客户端指纹 | ApprovalDao.getEffectiveApproval + clientFingerprint | 返回 consent 确认流程;confirm 指纹不符静默拒绝 |
| 来源 | bind-session 端点 Origin 白名单 | isAllowedOrigin | 403 来源不在允许列表 |
| 签名 | H5 签名验证(requireSignature,仅 /oauth2.1 前缀生效) | verifySignature | 403(token_required / signature_required / request_expired / invalid_nonce);仅 GET/HEAD 引导放行,写方法不放行 |
| 限频 | 端点级 IP 限频 | @fastify/rateLimit | 429 限频 |
| postMessage | origin + source 双校验 | LoginModal.handleMessage | 静默丢弃 |
2.3 V1-V10 安全加固对照
| 加固 | 阶段 | 防护机制 |
|---|---|---|
| V1 | 注册提交 | requireSignature=true,防绕过前端直接灌水 |
| V2 | check-email | requireSignature + 限频 10次/分,防邮箱枚举 |
| V4 | 验证码 | 发码绑 IP+UA 指纹,用码回查,防异地冒用 |
| V5 | consent 授权 | consentKey 绑客户端指纹,confirm 校验,防冒用绕过确认 |
| V6 | 登录爆破 | detectLoginAnomaly 锁定 |
| V7 | postMessage | origin+source 双校验防伪造 |
| V8 | 注册审计 | logRegister 成功/失败全程记录(email 脱敏) |
| V9 | user_normal 角色 | 缺失抛错回滚,防无角色脏数据(错误文案:默认角色未初始化,请联系管理员运行角色同步) |
2.4 验证码一次性消费链路(贯穿全流程)
核心规则:1 图形码 → 只发 1 次邮箱码;1 邮箱码 → 只登录或注册 1 次。
verify-captcha 发邮箱码:
verify 图形码(标记 verified)→ 发邮箱码 → consume 删除图形码(一次性)
→ 邮箱码存 sessionId=captchaKey + 指纹
注册 /user/v1/register:
emailDao.verifyCode 校验邮箱码 + sessionId(captchaKey) 一致 + 指纹
→ 通过 → delete 邮箱码(一次性,注册后不能复用登录)
登录 /oauth2.1/login:
type=email:不校验图形码(已消费),verifyEmailCode 校验邮箱码 + sessionId + 指纹
→ 通过 → delete 邮箱码(一次性)
type=password:校验图形码 verified → delete 图形码(一次性)| 层 | 校验项 | 实现位置 | 防御目标 |
|---|---|---|---|
| 1. 图形码 | verify + 一次性 consume | captcha/dao.js verifyAndSendEmail(发码时删)+ login.service(密码登录时删) | 防机器人 + 防图形码复用 |
| 2. 邮箱码正确性 | code === info.code | email/dao.js verifyCode | 防瞎猜 |
| 3. sessionId 一致性 | captchaKey 回查 | email/dao.js verifyCode | 防跨流程复用 |
| 4. 客户端指纹 | IP+UA(+device 启用时)回查 | email/dao.js fingerprint | 防异地冒用 |
| 5. 一次性消费 | store.delete(图形码 + 邮箱码各一次) | verifyAndSendEmail + verifyCode + login.service | 防重放 |
注:
/verify/v1/check-email-code端点会消费邮箱码,注册流程勿在 register 前调用。 登录与注册逻辑一致:均校验邮箱码 + sessionId + 指纹 + 一次性消费。
三、注册与登录的共享依赖
graph LR
subgraph 系统级["系统级框架(卸载 app 不影响)"]
AUTH[framework/security/auth<br/>session/cookie/risk]
VERIFY[framework/security/verify<br/>captcha/email]
DB[framework/persistence/db<br/>Sequelize + getModel]
RDS2[framework/persistence/redis<br/>email_code store]
end
subgraph oauth21["oauth21 app"]
CRYPT2[crypto/encryption<br/>RSA 解密]
LOGIN[login.service<br/>directLogin]
ISS2[token-issuer<br/>issueDirectTokens]
end
subgraph user["user app"]
REG[user.dao<br/>createUser/registerUser]
UMODEL[User/UserIdentity<br/>模型]
end
subgraph 前端["前端(iframe 内)"]
REGPAGE[注册页<br/>rsaEncrypt]
LOGINPAGE[登录页<br/>rsaEncrypt]
end
REGPAGE -->|POST /user/v1/register| REG
LOGINPAGE -->|POST /oauth2.1/login| LOGIN
REGPAGE -.->|GET /verify/v1/generate-captcha| VERIFY
REGPAGE -.->|POST /verify/v1/verify-captcha| VERIFY
VERIFY --> RDS2
VERIFY -->|SMTP| MAIL[(邮件)]
REG --> CRYPT2
REG --> UMODEL
REG --> DB
LOGIN --> CRYPT2
LOGIN --> AUTH
LOGIN --> ISS2
ISS2 --> AUTH
ISS2 -->|写 cookie| COOKIE[(HttpOnly Cookie)]关键边界:
- 注册走 user 域(
/user/v1/register),用 user.dao + oauth21/crypto 的 RSA 解密 - 登录走 oauth21 域(
/oauth2.1/login),用 login.service + token-issuer + framework/security/auth - 验证码走 verify 域(
/verify/v1/*),注册和登录共用,存 Redis email_code store - RSA 解密是 oauth21/crypto 提供的共享能力,user.dao 和 login.service 都依赖它
四、Cookie 与凭证状态流转
stateDiagram-v2
[*] --> 未登录
未登录 --> 临时登录 : 登录(未勾保持)<br/>写 sid(30min)
未登录 --> 长期登录 : 登录(勾保持)<br/>写 sid(30d)+sid_r+k_HMAC
临时登录 --> 未登录 : sid 过期 / 退出
长期登录 --> 长期登录 : sid 过期 → sid_r 自动刷新
长期登录 --> 长期登录 : switchAccount 免切(读 k_HMAC 轮转)
长期登录 --> 临时退出 : 退出登录<br/>清 sid/sid_r,保留 k_HMAC
临时退出 --> 长期登录 : 免切回来(用 k_HMAC)
临时退出 --> 未登录 : 忘掉账号(revokeSavedAccount 清 k_HMAC)
临时登录 --> 未登录 : 退出登录(无 k_HMAC 可留)Cookie 生命周期:
| Cookie | 临时登录 | 长期登录 | 临时退出 | 忘掉账号 |
|---|---|---|---|---|
sid | 30min | 30d | 清 | 清 |
sid_r | 无 | 30d(path 收窄) | 清 | 清 |
k_<HMAC(uid)> | 无 | 180d | 保留 | 清 |
五、设备码 + 复合指纹链路
设备识别是"同设备同用户只一条 session_token"和"访问风险检测"的基础。
5.1 两个值的区别
| 值 | 来源 | 稳定性 | 作用 |
|---|---|---|---|
device_id | cookie device_id(首次登录生成 UUID,跨账号复用) | 跨浏览器版本/账号稳定 | session_token 幂等键(同 user+device 只一条) |
device_fingerprint | sha256(device_id + UA + uid) 算出 | 绑设备+账号,换设备/换账号即变 | 访问风险检测基准(基准在 Redis session 里) |
5.2 登录时设备码写入流程
sequenceDiagram
autonumber
participant FE as 前端
participant ISS as token-issuer
participant DEV as device.js
participant SES as session.js createSession
participant RDS as Redis session
participant DB as MySQL session_tokens
participant CKA as Cookie
FE->>ISS: 登录请求
ISS->>ISS: resolveDeviceId(request, reply)
alt cookie 有 device_id(跨账号复用)
ISS->>DEV: getDeviceId 读 cookie
DEV-->>ISS: web-<uuid>
else x-device-id 头有
ISS-->>ISS: 用头值(带平台前缀)
else 首次登录(都无)
ISS->>DEV: generateDeviceCookie() UUID
ISS->>CKA: setCookie('device_id', uuid, 10年)
ISS-->>ISS: web-<新uuid>
end
ISS->>DEV: computeDeviceFingerprint({deviceId, UA, uid})
DEV-->>ISS: 32位复合指纹
ISS->>SES: createSession({deviceId, deviceFingerprint, ip, UA, ...})
SES->>RDS: sessionStore.set(sessionId, {...deviceFingerprint, ip, deviceId}, TTL)
SES->>DB: SessionToken upsert(同 user+device 只一条)<br/>写 device_id + device_fingerprint
Note right of DB: findOrCreate 命中则 update,避免按登录次数堆积5.3 关键设计
- cookie device_id 跨账号复用:同一浏览器登录过 A 账号写过 cookie,退出再登录 B 账号时复用同一 device_id(设备不变)
- session_tokens 表幂等:
findOrCreate({user_id, device_id})命中 update 不 create,同设备同账号始终一条 - 基准写 Redis:
device_fingerprint存 session 数据里,访问时getSession直接取,零 DB 查询 - DB session_tokens 同步:登录时 upsert 写入,作为持久备份(访问检测不依赖它)
六、用户注销全链路
注销流程:申请 → 拒登录(7天撤销期)→ 到期正式执行。 scope=app:清该 app 的 OAuth 授权 + 吊销该 app session;scope=all:清所有 + 软删 user_user。
6.1 注销申请 + 拦截登录时序
sequenceDiagram
autonumber
actor U as 用户
participant FE as 个人中心
participant UAPI as user API<br/>/user/v1/deactivation
participant DAO as deactivationDao
participant DB as MySQL<br/>user_deactivation
participant LOGIN as login.service
participant SVC as deactivationService
Note over U,FE: 阶段 1:提交注销申请
U->>FE: 选 scope(app/all)+ app_id + reason
FE->>UAPI: POST /user/v1/deactivation/apply
UAPI->>SVC: applyDeactivation(user, {scope, app_id, reason})
SVC->>SVC: validateAppId(scope=app 时校验 OAuth client 存在)
SVC->>DAO: createRequest(防重复 PENDING 申请)
DAO->>DB: INSERT user_deactivation<br/>{user_id, uid, scope, app_id, status=1,<br/>scheduled_at=now+7d}
DAO-->>UAPI: 申请记录
UAPI-->>FE: 201 已提交,7天内可撤销
Note over U,FE: 阶段 2:注销中再次登录 → 拦截 + 提示撤销
U->>FE: 重新登录(注销申请未撤销)
FE->>LOGIN: POST /oauth2.1/login
Note over LOGIN: 拿到 user + client 后<br/>调 deactivationService.checkLoginBlocked
LOGIN->>SVC: checkLoginBlocked(userId, client.client_id)
SVC->>DAO: findBlockingPending(scope=all 拦所有 / scope=app 仅拦该 app)
alt 有 PENDING 申请
SVC-->>LOGIN: pendingDeactivation
alt body 带 confirmRevoke=true
LOGIN->>SVC: forceRevokeForLogin(撤销申请)
Note over LOGIN: 继续登录流程,签发令牌
else 未带 confirmRevoke
LOGIN-->>FE: 403 {action:'deactivation_pending', deactivationId, scheduled_at}
Note right of FE: 前端弹"是否撤销注销"<br/>确认 → 带 confirmRevoke 重发登录
end
else 无 PENDING
SVC-->>LOGIN: null → 正常登录
end6.2 正式执行注销(管理员/到期触发)
sequenceDiagram
autonumber
participant ADMIN as 管理员/定时任务
participant AAPI as admin API<br/>/admin/user/v1/deactivation
participant SVC as deactivationService
participant DB as MySQL
participant RDS as Redis session
participant U as user_user
ADMIN->>AAPI: POST /admin/user/v1/deactivation/execute/:id {force?}
AAPI->>SVC: executeDeactivation(id, {force})
alt 未到期且非 force
SVC-->>AAPI: 400 申请未到期
else 到期/强制
alt scope=app
SVC->>SVC: executeAppDeactivation(userId, uid, appId)
SVC->>DB: OauthApproval.destroy(sub=uid, app_id=appId)
SVC->>DB: OauthConsent.destroy(sub=uid, client_id=appId)
SVC->>DB: OauthToken.update(revoked=true)(该 client)
SVC->>DB: SessionToken.update(revoked=true)(该 app)
SVC->>RDS: kickRedisSessionsByApp(逆索引遍历 + 按 appId 过滤删 session)
else scope=all
SVC->>SVC: executeAllDeactivation(userId, uid)
SVC->>DB: 清所有 app 的 approval/consent/token
SVC->>DB: SessionToken.update(revoked=true)(所有)
SVC->>RDS: kickAllSessions(userId) 踢所有
SVC->>U: user.status=-1 + user.destroy()(软删 delete_version)
end
SVC->>DB: markExecuted(id)(status=3, executed_at=now)
end
SVC-->>AAPI: 执行结果(清理明细)
AAPI-->>ADMIN: 200 注销已执行6.3 注销数据清理范围
| scope | OAuth 授权 | session | user_user |
|---|---|---|---|
app | 该 app 的 approval/consent/token | 该 app 的 session_tokens + Redis | 不动 |
all | 所有 app 的 approval/consent/token | 所有 session + Redis | 软删(status=-1, delete_version) |
七、访问风险检测全链路
每次请求比对当前 device_id/IP/UA 与 Redis session 里的基准,指纹突变弹人机验证,IP 变(梯子)不拦。
7.1 风险检测时序
sequenceDiagram
autonumber
participant REQ as 请求
participant AUTH as auth/index.js<br/>onRequest
participant SES as getSession
participant DEV as device.js
participant ANOM as anomaly-detector
participant RDS as Redis safe_verify
participant GUARD as guard preHandler
participant BIZ as 业务 handler
participant RES as onSend
REQ->>AUTH: 带 sid cookie 的请求
AUTH->>SES: getSession(读 Redis session)
SES-->>AUTH: sessionData(含 deviceFingerprint/ip 基准)
AUTH->>DEV: getDeviceId(读 cookie)+ computeDeviceFingerprint
DEV-->>AUTH: 当前 device_id + 当前指纹
AUTH->>ANOM: detectSessionRisk({userId, deviceId, ip, fingerprint,<br/>baselineFingerprint, baselineIp})
ANOM->>RDS: 查 verified:<userId>:<deviceId> 标记
alt 已验证过(30min 内)
RDS-->>ANOM: 命中
ANOM-->>AUTH: safe(直接放行)
else 未验证
ANOM->>ANOM: 组合判定
alt 指纹变(fpChanged)
ANOM-->>AUTH: warn + verify{url, header, token}
Note right of ANOM: 签发 verifyToken 存 Redis
else IP 变指纹不变
ANOM-->>AUTH: info(梯子,不拦)
else 基准缺失/无变动
ANOM-->>AUTH: safe/info
end
end
AUTH->>AUTH: request.state.risk = risk
alt warn + 高风险操作(非GET) + 无 verify-token 头
AUTH-->>REQ: 403 + __risk__{verifyUrl, verifyHeader, verifyToken}
Note right of REQ: 前端弹人机验证框
else 其他情况(GET / info / 带 verify-token)
AUTH->>GUARD: 三级守卫(IP/登录/角色/权限)
GUARD->>BIZ: 通过 → 执行业务
BIZ-->>RES: 响应
RES->>RES: info 级 → 响应体加 __risk__(前端弹框但不阻断)
RES-->>REQ: 响应
end7.2 风险规则与处理矩阵
| 检测结果 | 触发条件 | GET 读操作 | 高风险操作(写) |
|---|---|---|---|
safe | 已验证 / 基准缺失 / 都没变 | 放行 | 放行 |
info | IP 变指纹不变(梯子)/ 基准缺失 | 放行 + 响应带 __risk__ | 放行 + 响应带 __risk__ |
warn | 指纹变(换设备/UA) | 放行 + 响应带 __risk__ | 403 拦截 + 验证链接 |
7.3 人机验证 + 基准更新流程
sequenceDiagram
autonumber
participant FE as 前端
participant VAPI as auth API<br/>/auth/v1/verify-challenge
participant ANOM as anomaly-detector
participant SES as updateSessionBaseline
participant RDS as Redis
participant DB as MySQL session_tokens
FE->>VAPI: POST /verify-challenge<br/>header: x-verify-token: <verifyToken>
Note over VAPI: 带 verify-token 头豁免风险拦截<br/>(否则验证端点自己被拦死锁)
VAPI->>ANOM: confirmVerifyToken(verifyToken)
ANOM->>RDS: get vtoken:<token> → {userId, deviceId}
alt token 无效/过期
ANOM-->>VAPI: false → 400 令牌无效
else token 有效
ANOM->>RDS: set verified:<userId>:<deviceId>(30min 免验)
ANOM->>RDS: delete vtoken:<token>(一次性)
ANOM-->>VAPI: true
end
VAPI->>SES: updateSessionBaseline(sessionId, 新基准)
SES->>RDS: 读 session → 更新 deviceFingerprint/ip/deviceId/UA → 写回(保留 TTL)
SES->>DB: SessionToken.update(device_fingerprint, ip, user_agent)(同 user+device)
Note right of DB: Redis + DB 基准同步更新为新环境
VAPI-->>FE: 200 验证通过
FE->>FE: 重发原被拦请求(基准已是新环境 → safe)7.4 防误杀设计要点
| 场景 | 判定 | 处理 | 防误杀依据 |
|---|---|---|---|
| 换设备登录 | 指纹变 | warn,写操作拦 | 账号被盗高风险,必须验证 |
| 同设备换账号 | device_id 不变,指纹变(uid 变) | warn | 正常行为,但该账号首次访问需验证基准 |
| 梯子/IP 变 | IP 变指纹不变 | info,不拦 | 梯子常见,拦则误杀大量正常用户 |
| 浏览器更新 | UA 变 → 指纹变 | warn | 误杀风险,但有 cookie device_id 兜底(基准从 Redis 取,UA 变不影响 device_id) |
| 旧 session 无指纹字段 | 基准缺失 | info | 登录早于功能上线,降级放行不误判 |
八、请求处理全链路
从 HTTP 请求进入到响应返回的完整链路:onRequest 认证 → preHandler 守卫 → handler → onSend → onResponse。
8.1 请求处理时序图
sequenceDiagram
autonumber
participant CLI as 客户端
participant FW as Fastify
participant CK as @fastify/cookie
participant AUTH as auth 插件<br/>onRequest
participant RL as @fastify/rateLimit
participant FIRE as firewall 五层管道
participant GUARD as guard 三级守卫<br/>preHandler
participant SIG as verifySignature<br/>(OAuth21 路由)
participant BIZ as 业务 handler
participant RES as onSend
participant RESP as onResponse
CLI->>FW: HTTP 请求(带 cookie/header)
Note over FW,SIG: 阶段 1:onRequest 钩子链(按注册顺序)
FW->>CK: 解析 cookies(request.cookies)
FW->>AUTH: Session/JWT 认证
AUTH->>AUTH: 优先级:Bearer Token > access_token Cookie > sid Cookie > sid_r 刷新
alt sid 有效
AUTH->>AUTH: getSession → sessionData → request.state.user
AUTH->>AUTH: 风险检测(detectSessionRisk)→ request.state.risk
alt warn + 高风险操作
AUTH-->>CLI: 403 + __risk__(提前返回,不进后续链路)
end
else sid 过期 + sid_r 有效
AUTH->>AUTH: refreshSession 自动刷新 sid
else 无凭证
AUTH->>AUTH: request.state.user = null(匿名)
end
FW->>RL: 全局限频(所有请求)
alt 超限
RL-->>CLI: 429 限频
end
FW->>FIRE: 五层拦截管道(所有请求都过)
FIRE->>FIRE: 连接追踪 → 全局封禁 → 挑战 Cookie → Bot 检测 → 地理围栏/端点限频
alt 命中封禁/扫描陷阱
FIRE-->>CLI: 403/429
end
Note over FW,BIZ: 阶段 2:preHandler 钩子链
FW->>GUARD: 三级权限守卫
GUARD->>GUARD: System 级(system.json)→ Group 级(registerGroupMetadata)→ API 级(registerSecureRoute)
alt enabled=false
GUARD-->>CLI: 403 节点已禁用
else IP 白名单不符
GUARD-->>CLI: 403 IP 无权
else requireLogin 但未登录
GUARD-->>CLI: 401 未登录
else allowRoles 不符
GUARD-->>CLI: 403 角色不足
else permission 不符
GUARD-->>CLI: 403 权限不足
else 全通过
GUARD->>SIG: (仅 OAuth21 路由)H5 签名验证
alt 签名无效
SIG-->>CLI: 403 签名无效
end
end
Note over FW,RESP: 阶段 3:handler 执行
GUARD->>BIZ: 业务路由 handler
BIZ->>BIZ: 执行业务逻辑(DB/Redis/外部 API)
BIZ-->>FW: reply.result.success/fail
Note over FW,RESP: 阶段 4:onSend 钩子链
FW->>RES: 日志记录 + 连接释放
RES->>RES: info 级风险 → 响应体加 __risk__
RES-->>CLI: 响应
Note over FW: 阶段 5:onResponse 钩子
FW->>RESP: 扫描陷阱检测(404/403 命中 → 加封禁名单)
Note right of RESP: onResponse 无 reply,仅异步采集8.2 onRequest 钩子顺序与职责
| 顺序 | 钩子 | 职责 | 失败结果 |
|---|---|---|---|
| 1 | @fastify/cookie | 解析 cookies 到 request.cookies | — |
| 2 | auth | Session/JWT 认证 → request.state.user;风险检测 → request.state.risk | 403(warn+高风险) |
| 3 | @fastify/rateLimit | 全局 IP 限频 | 429 |
| 4 | firewall | 五层拦截(限频/封禁/挑战/Bot/地理围栏) | 403/429 |
8.3 三级守卫层级(preHandler)
| 级别 | 来源 | 配置项 | 作用范围 |
|---|---|---|---|
| System | system.json | enabled, allowIps, requireLogin | 整个 API 域 |
| Group | registerGroupMetadata() | enabled, allowIps, allowRoles | 一组路由 |
| API | registerSecureRoute() | enabled, allowIps, allowRoles, requireLogin, permission | 单个路由 |
校验链:每级独立执行 applyGuardLogic(enabled → IP 白名单 → 登录态+角色 → 权限),任一级拦截即 403/401。
8.4 风险拦截在请求链路中的位置
请求进入
│
├─ onRequest: auth 认证 + 风险检测
│ ├─ warn + 高风险操作(POST/PUT/DELETE) + 无 verify-token 头 → 403 拦截(在此终止)
│ ├─ info / warn+GET → request.state.risk 记录,继续
│ └─ safe → 继续
│
├─ onRequest: rateLimit 限频
├─ onRequest: firewall 五层拦截
│
├─ preHandler: guard 三级守卫(IP/登录/角色/权限)
├─ preHandler: verifySignature(仅 OAuth21 路由)
│
├─ handler: 业务逻辑
│
├─ onSend: 日志 + 风险信息注入响应体(info 级加 __risk__)
│
└─ onResponse: 扫描陷阱检测(404/403 命中 → 异步加封禁名单)设计要点:
- 风险检测在 auth onRequest 阶段(最早),warn+高风险操作直接 403,不进守卫/handler,性能最优
- info 级不拦,但 onSend 注入
__risk__到响应体,前端弹框(不阻断读操作) - 验证端点带
x-verify-token头豁免风险拦截(否则验证端点 POST 自己被拦,死锁) - onResponse 只做异步采集(扫描陷阱),无 reply,不影响响应
8.5 各阶段 reply 能力
| 阶段 | 能否提前返回 | 典型用途 |
|---|---|---|
| onRequest | ✅ reply.send() 终止链路 | 认证失败/风险拦截/限频 |
| preHandler | ✅ reply.send() 终止链路 | 守卫拦截/签名失败 |
| handler | ✅ 正常返回 reply.result.* | 业务响应 |
| onSend | ⚠️ 可改 payload 但不建议终止 | 修改响应体(加 __risk__) |
| onResponse | ❌ 无 reply,仅异步采集 | 扫描陷阱/统计 |