Skip to content

注册登录注销与请求处理全链路流程图 ​

基于 oauth21 SSO 中心 + 系统级 auth 框架的实际代码追踪绘制。 涵盖:注册、登录、设备指纹、注销、访问风险检测、请求处理全链路。 注册端点:POST /user/v1/register(user 域);登录端点:POST /oauth2.1/login(oauth21 域)。 两域共享:验证码(verify 域)、RSA 加解密(oauth21/crypto)、用户模型(user 域 DAO)。

范围说明:本仓只实现后端。图中标注「外部前端」的参与者(注册页 / 登录页 / 父窗口 / 个人中心)代表任意外部客户端,前端工程已于 2026-10-31 迁出本仓; 它们与后端之间的契约见 认证集成。


一、注册全链路 ​

1.1 注册时序图(前端 → 后端 → 数据库) ​

mermaid
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_userusername, email, uid(自动), status事务内 create用户基础信息,uid 为 UUID
user_identityuser_id, identity_type='password', identifier=email, credential=scrypt 哈希串事务内 create密码凭证,与 User 解耦(历史 bcrypt 串仍可校验,登录成功即透明升级)
iam_user_roleuser_id, role_id, app_id='GLOBAL'事务内 bulkCreate角色绑定,默认 code='user_normal'(不能按 rank_level=1 取:那是 user_banned)

事务保证:三张表同事务,任一失败全部回滚,不会出现"有用户无凭证"的脏数据。


二、登录验证全链路 ​

2.1 登录时序图(iframe SSO 场景) ​

mermaid
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 防重放decryptLoginRequest400 请求非法
异常暴力破解锁定(IP+账号维度)detectLoginAnomaly429 已锁定
身份密码 scrypt 校验(历史 bcrypt 只校验 + 透明升级)/ 邮箱码校验(绑 IP+UA 指纹 + sessionId 一致性)authenticateUser / verifyEmailCode401/404,指纹/sessionId 不符静默拒绝
客户端client_id 有效性ClientDao.findById400 无效客户端
授权用户是否授权该应用 + consentKey 绑客户端指纹ApprovalDao.getEffectiveApproval + clientFingerprint返回 consent 确认流程;confirm 指纹不符静默拒绝
来源bind-session 端点 Origin 白名单isAllowedOrigin403 来源不在允许列表
签名H5 签名验证(requireSignature,仅 /oauth2.1 前缀生效)verifySignature403(token_required / signature_required / request_expired / invalid_nonce);仅 GET/HEAD 引导放行,写方法不放行
限频端点级 IP 限频@fastify/rateLimit429 限频
postMessageorigin + source 双校验LoginModal.handleMessage静默丢弃

2.3 V1-V10 安全加固对照 ​

加固阶段防护机制
V1注册提交requireSignature=true,防绕过前端直接灌水
V2check-emailrequireSignature + 限频 10次/分,防邮箱枚举
V4验证码发码绑 IP+UA 指纹,用码回查,防异地冒用
V5consent 授权consentKey 绑客户端指纹,confirm 校验,防冒用绕过确认
V6登录爆破detectLoginAnomaly 锁定
V7postMessageorigin+source 双校验防伪造
V8注册审计logRegister 成功/失败全程记录(email 脱敏)
V9user_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 + 一次性 consumecaptcha/dao.js verifyAndSendEmail(发码时删)+ login.service(密码登录时删)防机器人 + 防图形码复用
2. 邮箱码正确性code === info.codeemail/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 + 指纹 + 一次性消费。


三、注册与登录的共享依赖 ​

mermaid
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 与凭证状态流转 ​

mermaid
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临时登录长期登录临时退出忘掉账号
sid30min30d清清
sid_r无30d(path 收窄)清清
k_<HMAC(uid)>无180d保留清

五、设备码 + 复合指纹链路 ​

设备识别是"同设备同用户只一条 session_token"和"访问风险检测"的基础。

5.1 两个值的区别 ​

值来源稳定性作用
device_idcookie device_id(首次登录生成 UUID,跨账号复用)跨浏览器版本/账号稳定session_token 幂等键(同 user+device 只一条)
device_fingerprintsha256(device_id + UA + uid) 算出绑设备+账号,换设备/换账号即变访问风险检测基准(基准在 Redis session 里)

5.2 登录时设备码写入流程 ​

mermaid
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 注销申请 + 拦截登录时序 ​

mermaid
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 → 正常登录
    end

6.2 正式执行注销(管理员/到期触发) ​

mermaid
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 注销数据清理范围 ​

scopeOAuth 授权sessionuser_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 风险检测时序 ​

mermaid
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: 响应
    end

7.2 风险规则与处理矩阵 ​

检测结果触发条件GET 读操作高风险操作(写)
safe已验证 / 基准缺失 / 都没变放行放行
infoIP 变指纹不变(梯子)/ 基准缺失放行 + 响应带 __risk__放行 + 响应带 __risk__
warn指纹变(换设备/UA)放行 + 响应带 __risk__403 拦截 + 验证链接

7.3 人机验证 + 基准更新流程 ​

mermaid
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 请求处理时序图 ​

mermaid
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—
2authSession/JWT 认证 → request.state.user;风险检测 → request.state.risk403(warn+高风险)
3@fastify/rateLimit全局 IP 限频429
4firewall五层拦截(限频/封禁/挑战/Bot/地理围栏)403/429

8.3 三级守卫层级(preHandler) ​

级别来源配置项作用范围
Systemsystem.jsonenabled, allowIps, requireLogin整个 API 域
GroupregisterGroupMetadata()enabled, allowIps, allowRoles一组路由
APIregisterSecureRoute()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,仅异步采集扫描陷阱/统计

基于 GPL-3.0 许可发布