Sa-Token 认证与会话管理.md 30 KB

Sa-Token 认证与会话管理

本文引用的文件

  • SaTokenWebConfig.java
  • AuthController.java
  • SysUserService.java
  • LoginActivityService.java
  • AccountInUseException.java
  • CaseSessionListener.java
  • CaseDataSourceRegistry.java
  • CaseDataSourceReaper.java
  • application-pro.yaml
  • application-dev.yaml
  • TokenResolver.java
  • StickyRouteFilter.java
  • AdminAuthWebFilter.java
  • axios/index.ts
  • authApi.ts

目录

  1. 简介
  2. 项目结构定位
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与资源特性
  8. 典型流程
  9. 故障排查指南
  10. 结论

简介

本文说明基于 Sa-Token 的认证与会话方案:后端如何初始化认证拦截器、用户登录时 token 如何生成和存储、前端如何通过 x-token 携带会话访问接口;并解释“登录前校验账号是否正在使用”的逻辑、账号被顶下线或踢下线后如何释放其全部案件数据源,以及 Gateway 中如何解析和透传 token。文末给出常见问题的排查方法,包括 token 不一致、401/403、账号被顶下线等。

项目结构定位

本项目涉及认证与会话的三个层次:

  • 网关层(ai-gateway):负责按 x-token 解析 userId、选择后端节点并把请求转发到具体服务实例。
  • 业务服务层(ai-server):基于 Sa-Token 维护会话、执行登录/登出、校验账号占用、管理 DuckDB 案件数据源生命周期。
  • 前端层(ai-electron/frontend):在请求头中注入 x-token,并在 401 或业务码 40901 时做登录跳转与确认处理。

    graph TB
    FE["前端 Axios<br/>注入 x-token"] --> GW["Gateway StickyRouteFilter<br/>解析 x-token → userId"]
    GW --> TR["TokenResolver<br/>缓存 + sa-token 查询"]
    GW --> SVC["ai-server 后端"]
    SVC --> ST["Sa-Token<br/>Redis 会话"]
    SVC --> CDR["CaseDataSourceReaper<br/>兜底回收"]
    SVC --> CSL["CaseSessionListener<br/>会话监听释放"]
    

图示来源

  • StickyRouteFilter.java:1-180
  • TokenResolver.java:1-100
  • SaTokenWebConfig.java:1-65
  • CaseDataSourceReaper.java:1-125
  • CaseSessionListener.java:1-109

章节来源

  • StickyRouteFilter.java:1-180
  • TokenResolver.java:1-100
  • SaTokenWebConfig.java:1-65

核心组件

  • Sa-Token Web 配置:注册 SaInterceptor,对所有路径做 checkLogin(),白名单放行登录、健康检查、地图静态资源等。未登录时抛出异常,由全局异常处理器转为 HTTP 200 + body.code=401。
  • 认证控制器:暴露 /auth/login、/auth/logout、/auth/info、/auth/changePwd、/auth/verifyPwd。token 通过响应体返回,后续请求统一用 x-token 传递。
  • 登录活跃服务:用 Redis 记录“半小时内是否活跃”,用于判断账号是否正在其他设备使用。
  • 会话监听器:捕获登出、被踢、被顶下线事件,释放该用户打开的案件数据源。
  • 案件数据源注册表与回收器:注册已打开 DuckDB 数据源;定时扫描失效 token 对应的案件,兜底关闭泄漏的数据源。
  • Gateway Token 解析器:优先从 Redis 缓存读取 userId,否则走 Sa-Token;失败返回空,让后端按 401 处理。
  • Gateway 粘性路由:根据 x-token 选择固定后端节点,保证同一用户的请求落到有本地数据的节点。
  • 前端 Axios:把 x-token 注入请求头,对 code=401 触发重新登录,对登录接口的 40901 业务码弹出“是否继续登录”。

章节来源

  • SaTokenWebConfig.java:1-65
  • AuthController.java:1-82
  • LoginActivityService.java:1-106
  • CaseSessionListener.java:1-109
  • CaseDataSourceRegistry.java:1-200
  • CaseDataSourceReaper.java:1-125
  • TokenResolver.java:1-100
  • StickyRouteFilter.java:1-180
  • axios/index.ts:1-326

架构总览

Sa-Token 在本项目中承担认证与会话存储职责,但不提供角色权限体系;权限仅以管理员标志控制少数接口。会话状态保存在 Redis 中,因此多实例部署共享同一会话空间。

sequenceDiagram
    participant FE as "前端"
    participant GW as "Gateway"
    participant SVC as "ai-server"
    participant RT as "Sa-Token / Redis"

    FE->>GW: POST /gateway/admin/auth/login<br/>请求体:username + password
    GW->>SVC: 转发登录请求
    SVC->>RT: StpUtil.login(userId)
    SVC-->>GW: {code:200, data:{token,...}}
    GW-->>FE: 返回 token
    FE->>FE: 保存 token,后续请求自动带 x-token

    FE->>GW: GET /gateway/admin/...<br/>请求头:x-token
    GW->>GW: StickyRouteFilter 解析 x-token
    GW->>RT: getLoginIdByToken(token)
    RT-->>GW: userId 或 null
    GW->>SVC: 转发到选定节点
    SVC->>SVC: SaInterceptor.checkLogin()
    SVC-->>FE: 业务结果或 code=401

图示来源

  • StickyRouteFilter.java:1-180
  • TokenResolver.java:1-100
  • SysUserService.java:1-200
  • SaTokenWebConfig.java:1-65

详细组件分析

Sa-Token 后端初始化与白名单

  • 配置类实现 WebMvcConfigurer,注册 SaInterceptor,调用 StpUtil.checkLogin() 完成认证。
  • 白名单包含 /auth/login、/sys/health、/sys/checkAuth、/sys/info、/sys/code、/sys/noNet、/sys/map/**、/error。
  • 每个已登录请求都会调用 LoginActivityService.touch(userId),用于记录活跃时间。
  • Sa-Token 配置文件设置 token-name=x-token、active-timeout=-1、is-concurrent=false。

    flowchart TD
    Start["请求进入 Spring MVC"] --> CheckWL["是否在 Sa-Token 白名单?"]
    CheckWL -->|是| Pass["直接放行 Controller"]
    CheckWL -->|否| LoginCheck["StpUtil.checkLogin()"]
    LoginCheck -->|成功| Touch["记录登录活跃"]
    Touch --> Controller["执行业务 Controller"]
    LoginCheck -->|失败| GlobalEx["全局异常转 HTTP 200 + code=401"]
    

图示来源

  • SaTokenWebConfig.java:1-65
  • application-pro.yaml:69-78
  • application-dev.yaml:58-67

章节来源

  • SaTokenWebConfig.java:1-65
  • application-pro.yaml:69-78
  • application-dev.yaml:58-67

登录流程与 token 生成

  • 前端调用 /auth/login,请求体为用户名和密码。
  • 后端先校验用户名、密码、账号状态;若账号在其他设备且半小时内活跃过,则抛出 AccountInUseException,前端收到 HTTP 200 + code=40901。
  • 用户确认后带 force=true 重新提交,后端先 kickout(user.getId()) 踢掉旧会话,再 StpUtil.login(user.getId()) 生成新 token。
  • 登录后更新最后登录时间,并通过 LoginVO 返回 token、userId、用户名等信息。
  • Sa-Token 默认单端登录:新登录会顶掉旧 token,旧 token 下次请求抛 NotLoginException(BE_REPLACED)。

    sequenceDiagram
    participant FE as "前端"
    participant AC as "AuthController"
    participant SU as "SysUserService"
    participant LAS as "LoginActivityService"
    participant ST as "Sa-Token"
    
    FE->>AC: POST /auth/login {username,password}
    AC->>SU: login(dto)
    SU->>LAS: isInUse(userId)
    LAS-->>SU: true/false
    alt 账号正在使用且非 force
        SU-->>AC: 抛出 AccountInUseException(code=40901)
        AC-->>FE: HTTP 200 + code=40901
        FE->>FE: 弹窗确认“是否继续登录”
        FE->>AC: 再次提交 force=true
    else 可登录
        SU->>ST: StpUtil.login(userId)
        SU->>LAS: touch(userId)
        SU-->>AC: LoginVO{token,...}
        AC-->>FE: HTTP 200 + token
    end
    

图示来源

  • AuthController.java:1-82
  • SysUserService.java:1-200
  • LoginActivityService.java:1-106
  • AccountInUseException.java:1-19

章节来源

  • AuthController.java:1-82
  • SysUserService.java:1-200
  • LoginActivityService.java:1-106
  • AccountInUseException.java:1-19
  • authApi.ts:1-124

账号占用检测逻辑

  • LoginActivityService.isInUse(userId) 同时检查两件事:
    1. Sa-Token 中该用户是否还有有效 token。
    2. Redis 中是否存在“半小时内活跃”标记。
  • Redis key 前缀为 zsjz:auth:last-active:,value 为最后活跃时间戳,TTL 即判定窗口。
  • 写操作有节点内节流:同一用户每 60 秒最多写一次 Redis。
  • Redis 异常不阻断主流程,按“不在使用中”处理,避免登录不可用。

    flowchart TD
    Enter["isInUse(userId)"] --> HasToken{"Sa-Token 中仍有有效 token?"}
    HasToken -->|否| ReturnFalse["返回 false"]
    HasToken -->|是| ReadRedis["读取 zsjz:auth:last-active:userId"]
    ReadRedis --> HasValue{"值存在且非空?"}
    HasValue -->|是| ReturnTrue["返回 true"]
    HasValue -->|否| ReturnFalse
    

图示来源

  • LoginActivityService.java:1-106

章节来源

  • LoginActivityService.java:1-106

会话失效与案件数据源释放

系统设计了四层释放机制,缺一不可:

  1. 用户主动退出案件。
  2. 用户调用 /auth/logout。
  3. Sa-Token 会话监听器捕获“被顶下线/被踢下线”。
  4. 会话自然过期后,由定时任务兜底回收。

CaseSessionListener 在登出、被踢、被顶下线时遍历已打开案件,匹配归属用户;若当前 token 与归属 token 不同,在多端联调场景下不会误关另一会话的案件。若案件有后台任务,则跳过释放,交给 CaseDataSourceReaper 下一轮兜底。

CaseDataSourceReaper 定期扫描所有已打开案件,按“打开该案件的 token 是否仍然有效”判断;如果失效且没有在途任务,就关闭数据源并清理相关缓存。

flowchart TD
    Start["定时任务 reap()"] --> Count{"是否有打开案件?"}
    Count -->|否| End["结束"]
    Count -->|是| Loop["遍历 caseId"]
    Loop --> Owner{"有归属用户?"}
    Owner -->|否| Next["下一个 caseId"]
    Owner -->|是| Alive{"归属 token 仍有效?"}
    Alive -->|是| Next
    Alive -->|否| Busy{"有在途任务?"}
    Busy -->|是| LogSkip["日志记录本轮跳过"] --> Next
    Busy -->|否| Close["关闭数据源 + 清理缓存"] --> Next
    Next -->|更多| Loop
    Next -->|结束| End

图示来源

  • CaseDataSourceReaper.java:1-125
  • CaseSessionListener.java:1-109
  • CaseDataSourceRegistry.java:1-200

章节来源

  • CaseSessionListener.java:1-109
  • CaseDataSourceReaper.java:1-125
  • CaseDataSourceRegistry.java:1-200

Gateway 中 token 解析与透传

  • StickyRouteFilter 从请求头取 x-token;无 token 时按匿名请求选择健康节点。
  • 有 token 时调用 TokenResolver.resolveUserId(serviceId, token);解析失败则按匿名处理,后端返回 code=401。
  • 解析成功后查找用户绑定节点;若无绑定则绑定到 default-node。
  • 最终将请求转发到选定的后端节点,并把 X-Gateway-Node 写入响应头。
  • TokenResolver 先用 gateway:token:{serviceId}:{token} 缓存 userId,TTL 24 小时;缓存未命中则调用 Sa-Token 的 getLoginIdByToken。

    sequenceDiagram
    participant FE as "前端"
    participant GW as "StickyRouteFilter"
    participant TR as "TokenResolver"
    participant ST as "Sa-Token"
    participant SVC as "后端节点"
    
    FE->>GW: 普通请求 + x-token
    GW->>TR: resolveUserId(serviceId, token)
    TR->>TR: 查 gateway:token:serviceId:token
    alt 缓存命中
        TR-->>GW: userId
    else 缓存未命中
        TR->>ST: getLoginIdByToken(token)
        ST-->>TR: loginId 或 null
        TR->>TR: 写入缓存
        TR-->>GW: userId 或 empty
    end
    alt userId 有效
        GW->>GW: 选择绑定节点
        GW->>SVC: 转发请求
    else 解析失败
        GW->>SVC: 匿名转发
        SVC-->>GW: code=401
    end
    

图示来源

  • StickyRouteFilter.java:1-180
  • TokenResolver.java:1-100

章节来源

  • StickyRouteFilter.java:1-180
  • TokenResolver.java:1-100

前端如何通过 x-token 携带会话

  • Axios 配置 authenticationHeader=x-token,authenticationScheme 为空。
  • 请求拦截器从前端 token 存储读取值,并写入请求头 x-token。
  • 响应拦截器对 code=401 调用统一未授权处理,跳转到登录页。
  • 登录接口使用 isTransformResponse:false,以便拿到后端返回的 40901 业务码,而不是被 axios 当成错误吞掉。

    flowchart TD
    CallAPI["调用 defHttp"] --> Interceptor["请求拦截器"]
    Interceptor --> HasToken{"是否携带 withToken?"}
    HasToken -->|是| Inject["读取前端 token → 写入 x-token"]
    HasToken -->|否| Skip["跳过注入"]
    Inject --> Send["发送请求"]
    Skip --> Send
    Send --> Resp["响应拦截器"]
    Resp --> Code200{"code=200?"}
    Code200 -->|是| ReturnData["返回业务数据"]
    Code200 -->|否| Is401{"code=401?"}
    Is401 -->|是| Redirect["跳转登录页"]
    Is401 -->|否| ShowError["显示错误消息"]
    

图示来源

  • axios/index.ts:1-326
  • authApi.ts:1-124

章节来源

  • axios/index.ts:1-326
  • authApi.ts:1-124

依赖关系分析

classDiagram
    class SysUserService {
        +login(LoginDTO) LoginVO
        +logout() void
        +info() UserVO
        +changePwd(ChangePwdDTO) void
        +verifyPwd(String) boolean
    }
    class LoginActivityService {
        +touch(Long) void
        +isInUse(Long) boolean
    }
    class CaseSessionListener {
        +doLogout(loginType, loginId, tokenValue) void
        +doKickout(loginType, loginId, tokenValue) void
        +doReplaced(loginType, loginId, tokenValue) void
    }
    class CaseDataSourceRegistry {
        +open(caseId, dbPath, ownerUserId, ownerToken) void
        +close(caseId) void
        +openedCaseIds() Set~Long~
        +ownerOf(caseId) Long
        +ownerTokenOf(caseId) String
    }
    class CaseDataSourceReaper {
        +reap() void
        -isOwnerSessionAlive(ownerUserId, caseId) boolean
    }
    class AuthController {
        +login(LoginDTO) Result
        +logout() Result
        +info() Result
        +changePwd(ChangePwdDTO) Result
        +verifyPwd(VerifyPwdDTO) Result
    }
    class StickyRouteFilter {
        +filter(exchange, chain) Mono~Void~
    }
    class TokenResolver {
        +resolveUserId(serviceId, token) Mono~Long~
        +cacheToken(serviceId, token, userId) Mono~Boolean~
    }

    SysUserService --> LoginActivityService : "使用"
    SysUserService --> CaseDataSourceRegistry : "登出时释放"
    CaseSessionListener --> CaseDataSourceRegistry : "会话结束时释放"
    CaseDataSourceReaper --> CaseDataSourceRegistry : "定时扫描"
    AuthController --> SysUserService : "委托"
    StickyRouteFilter --> TokenResolver : "解析 token"

图示来源

  • SysUserService.java:1-200
  • LoginActivityService.java:1-106
  • CaseSessionListener.java:1-109
  • CaseDataSourceRegistry.java:1-200
  • CaseDataSourceReaper.java:1-125
  • AuthController.java:1-82
  • StickyRouteFilter.java:1-180
  • TokenResolver.java:1-100

章节来源

  • SysUserService.java:1-200
  • CaseSessionListener.java:1-109
  • CaseDataSourceReaper.java:1-125
  • StickyRouteFilter.java:1-180

性能与资源特性

  • Sa-Token 的 active-timeout=-1,表示长时间研判不会被“活跃超时”踢掉;因此“账号是否正在使用”改用独立的 Redis 活跃标记,避免依赖 Sa-Token 活跃策略。
  • LoginActivityService.touch 对同一用户每分钟最多写一次 Redis,降低高频请求带来的 Redis 压力。
  • TokenResolver 使用 24 小时 TTL 的 Redis 缓存,减少每次请求都查询 Sa-Token 的开销。
  • 案件数据源采用按案件物理 key 注册,配合内存预算、线程数限制;同时通过四重释放机制防止 DuckDB 连接泄漏。
  • 兜底回收器默认初始延迟 60 秒、间隔 300 秒,可按配置调整。

章节来源

  • application-pro.yaml:69-78
  • application-dev.yaml:58-67
  • LoginActivityService.java:1-106
  • TokenResolver.java:1-100
  • CaseDataSourceReaper.java:1-125

典型流程

典型登录请求流程

  1. 前端调用 /auth/login,携带用户名和密码。
  2. 后端校验用户名、密码、账号状态。
  3. 若非强制登录且账号正在使用,返回 HTTP 200 + code=40901。
  4. 用户确认后带 force=true 再次提交,后端踢掉旧会话并创建新 token。
  5. 前端保存 token,后续请求自动注入 x-token。

章节来源

  • AuthController.java:1-82
  • SysUserService.java:1-200
  • authApi.ts:1-124

会话失效处理流程

  1. 前端发起业务请求,携带 x-token。
  2. Gateway 解析 token;若无效则按匿名转发。
  3. 后端 Sa-Token 拦截器检测到未登录,抛出异常。
  4. 全局异常处理器返回 HTTP 200 + code=401。
  5. 前端 axios 识别 401,跳转到登录页。

章节来源

  • StickyRouteFilter.java:1-180
  • SaTokenWebConfig.java:1-65
  • axios/index.ts:1-326

重复登录冲突处理流程

  1. 用户 A 已在某设备登录。
  2. 用户 B 在同一账号上再次登录。
  3. 首次登录提示“账号正在其他设备使用”,需要用户确认。
  4. 确认后 force=true,后端调用 kickout 踢掉旧会话。
  5. 新 token 生效,旧 token 下次请求变为未登录。

章节来源

  • SysUserService.java:1-200
  • LoginActivityService.java:1-106
  • authApi.ts:1-124

故障排查指南

token 不一致

  • 现象:前端请求能到达后端,但后端认为未登录。
  • 可能原因:
    • 前端没有注入 x-token,或 authenticationHeader 不是 x-token。
    • 前端 token 存储被清空,但请求仍尝试访问受保护接口。
    • Gateway 缓存中的 token→userId 映射与后端 Redis 不一致。
  • 排查步骤:
    1. 检查浏览器网络面板,确认请求头包含 x-token。
    2. 检查前端 Axios 配置中 authenticationHeader 是否为 x-token。
    3. 检查 Gateway 缓存 key gateway:token:{serviceId}:{token} 是否存在。
    4. 检查 Sa-Token Redis 中该 token 是否仍对应有效 loginId。

章节来源

  • axios/index.ts:1-326
  • TokenResolver.java:1-100

401 未登录

  • 现象:后端返回 HTTP 200 + body.code=401,前端跳转到登录页。
  • 可能原因:
    • 用户未登录。
    • token 过期。
    • token 被单端登录顶掉。
    • token 被管理员强制踢下线。
  • 排查步骤:
    1. 确认前端是否保存了 token。
    2. 确认 Sa-Token 配置 is-concurrent=false 是否符合预期。
    3. 检查是否触发了 /user/kickout 或管理员重置密码。
    4. 检查后端全局异常是否把未登录转换为 code=401。

章节来源

  • SaTokenWebConfig.java:1-65
  • application-pro.yaml:69-78
  • axios/index.ts:1-326

403 权限不足

  • 现象:请求被拒绝,提示需要管理员权限或 IP 不在白名单。
  • 可能原因:
    • 访问 /gateway/admin/** 时,用户不是管理员。
    • 管理接口未启用或来源 IP 不在白名单。
  • 排查步骤:
    1. 确认访问路径是否属于管理接口。
    2. 检查 gateway.admin.enabled 配置。
    3. 检查来源 IP 是否在 gateway.admin.ip-whitelist。
    4. 检查数据库中用户是否 is_admin=1 且 status=1。

章节来源

  • AdminAuthWebFilter.java:1-90

账号被顶下线

  • 现象:原设备 token 突然失效,请求返回 401。
  • 可能原因:
    • 同一账号在新设备登录,且已确认接管。
    • 管理员重置密码或强制踢下线。
  • 排查步骤:
    1. 查看后端日志中是否出现“被新登录顶下线”或“被踢下线”。
    2. 检查是否有新的登录请求带 force=true。
    3. 检查用户管理接口是否调用过 resetPwd 或 kickout。
    4. 确认案件数据源是否已被 CaseSessionListener 或 CaseDataSourceReaper 回收。

章节来源

  • CaseSessionListener.java:1-109
  • CaseDataSourceReaper.java:1-125
  • SysUserService.java:1-200

案件数据源泄漏

  • 现象:同时打开案件数达到上限,新用户无法开案。
  • 可能原因:
    • 用户关闭浏览器后 token 过期,但没有触发会话监听。
    • 后台治理或清洗任务仍在运行,导致数据源被保守保留。
  • 排查步骤:
    1. 查看 CaseDataSourceReaper 的调度日志。
    2. 检查 zsjz.duckdb.max-open-cases 是否被占满。
    3. 确认是否有在途任务探针返回“案件繁忙”。
    4. 检查是否应手动调用 /case/exit 或 /auth/logout。

章节来源

  • CaseDataSourceReaper.java:1-125
  • CaseDataSourceRegistry.java:1-200

结论

本项目的认证与会话方案以 Sa-Token 为核心,结合 Redis 管理会话和活跃标记,通过 Gateway 实现 token 解析与粘性路由,前端通过 Axios 统一注入 x-token。登录前校验账号占用避免了无声顶号,四重释放机制保障了 DuckDB 案件数据源的生命周期安全。生产环境默认单端登录,若需联调多端可通过环境变量临时开启;排查问题时建议从前端请求头、Gateway 缓存、Sa-Token Redis、后端会话监听与兜底回收器五个层面逐步定位。