# 认证与会话管理 **本文引用的文件** - [StickyRouteFilter.java](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java) - [LoginRequestFilter.java](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java) - [LoginResponseFilter.java](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java) - [UserRouteService.java](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java) - [TokenResolver.java](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java) - [SaTokenWebConfig.java](file://ai-server/src/main/java/com/zsjz/ai/common/config/SaTokenWebConfig.java) - [LoginActivityService.java](file://ai-server/src/main/java/com/zsjz/ai/common/auth/LoginActivityService.java) - [SysUserService.java](file://ai-server/src/main/java/com/zsjz/ai/module/plat/service/SysUserService.java) - [CaseDataSourceReaper.java](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceReaper.java) - [CaseDataSourceRegistry.java](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceRegistry.java) - [application.yaml](file://ai-server/src/main/resources/application.yaml) - [application-dev.yaml](file://ai-server/src/main/resources/application-dev.yaml) - [application-pro.yaml](file://ai-server/src/main/resources/application-pro.yaml) - [authApi.ts](file://ai-electron/frontend/src/core/api/auth/authApi.ts) - [account.ts](file://ai-electron/frontend/src/core/store/modules/account.ts) - [axios/index.ts](file://ai-electron/frontend/src/core/utils/http/axios/index.ts) - [ai-gateway-user-sticky-routing.md](file://docs/design/ai-gateway-user-sticky-routing.md) ## 目录 1. [引言](#引言) 2. [项目结构](#项目结构) 3. [核心组件](#核心组件) 4. [架构总览](#架构总览) 5. [详细组件分析](#详细组件分析) 6. [依赖关系分析](#依赖关系分析) 7. [性能与存储特性](#性能与存储特性) 8. [故障排查指南](#故障排查指南) 9. [安全建议](#安全建议) 10. [结论](#结论) ## 引言 本文说明基于 Sa-Token 的认证与会话管理机制,覆盖用户登录流程、Token 生成与校验、会话状态在 Redis 中的存储方式、客户端 `x-token` 与服务端会话的关联关系,以及网关粘性路由与服务端鉴权的协作方式。同时解释账号被顶下线或踢下线后如何释放案件数据源,并给出 Token 泄露处理、会话超时配置、敏感接口鉴权模式和调试方法等实践建议。 ## 项目结构 本项目中认证与会话相关代码分布在三个层次: - 前端 Electron/Vue:负责发起登录、缓存 `token`、请求时注入 `x-token` 头,并在登录失效时清理本地状态。 - 网关 ai-gateway:负责按用户名绑定节点、解析 `x-token` 到 userId、把请求转发到指定 ai-server 节点。 - 后端 ai-server:使用 Sa-Token 完成登录、会话校验、活跃标记、登出及案件数据源释放。 ```mermaid graph TB Client["客户端
Electron / Web"] --> Gateway["网关 ai-gateway
StickyRouteFilter / LoginRequestFilter / LoginResponseFilter"] Gateway -->|按 x-token 解析 userId| Node1["ai-server 节点-1
Sa-Token 会话"] Gateway -->|按 x-token 解析 userId| Node2["ai-server 节点-2
Sa-Token 会话"] Node1 --> Redis["共享 Redis
sa-token 会话 + 路由缓存"] Node2 --> Redis Node1 --> PG["共享 PostgreSQL
用户与路由映射"] Node2 --> PG ``` **图示来源** - [StickyRouteFilter.java:22-57](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L22-L57) - [TokenResolver.java:14-34](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L14-L34) - [SaTokenWebConfig.java:10-34](file://ai-server/src/main/java/com/zsjz/ai/common/config/SaTokenWebConfig.java#L10-L34) - [ai-gateway-user-sticky-routing.md:18-46](file://docs/design/ai-gateway-user-sticky-routing.md#L18-L46) **章节来源** - [ai-gateway-user-sticky-routing.md:1-46](file://docs/design/ai-gateway-user-sticky-routing.md#L1-L46) ## 核心组件 - 网关登录预处理:`LoginRequestFilter` 仅对登录路径生效,从请求体解析 `username`,并把响应编码改为 `identity`,避免后续响应解析失败。 - 网关粘性路由:`StickyRouteFilter` 根据登录用户名或 `x-token` 决定目标 ai-server 节点,并在节点不可用时返回明确 503,不自动切换。 - 网关登录响应处理:`LoginResponseFilter` 在登录成功时把用户绑定到选定节点,并把 `x-token → userId` 写入网关 token 缓存。 - 网关 token 解析:`TokenResolver` 优先查 `gateway:token:{serviceId}:{token}`,未命中再调用 Sa-Token 的 `getLoginIdByToken`,兼容旧 token。 - 服务端会话拦截器:`SaTokenWebConfig` 注册 Sa-Token 拦截器,对所有业务接口做登录校验,并在已登录请求上记录活跃度。 - 登录占用判断:`LoginActivityService` 用 Redis 维护用户“半小时内是否活跃”,用于登录前提示“账号正在其他设备使用”。 - 登录服务:`SysUserService.login` 实现密码校验、占用确认、强制接管、Sa-Token 登录、活跃标记和登录结果封装。 - 案件数据源保护:`CaseDataSourceRegistry` 管理已打开 DuckDB 数据源;`CaseDataSourceReaper` 兜底回收会话过期但未触发监听器的数据源。 **章节来源** - [LoginRequestFilter.java:19-116](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java#L19-L116) - [StickyRouteFilter.java:22-178](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L22-L178) - [LoginResponseFilter.java:16-174](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java#L16-L174) - [TokenResolver.java:14-98](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L14-L98) - [SaTokenWebConfig.java:10-63](file://ai-server/src/main/java/com/zsjz/ai/common/config/SaTokenWebConfig.java#L10-L63) - [LoginActivityService.java:13-104](file://ai-server/src/main/java/com/zsjz/ai/common/auth/LoginActivityService.java#L13-L104) - [SysUserService.java:44-132](file://ai-server/src/main/java/com/zsjz/ai/module/plat/service/SysUserService.java#L44-L132) - [CaseDataSourceRegistry.java:16-42](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceRegistry.java#L16-L42) - [CaseDataSourceReaper.java:12-34](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceReaper.java#L12-L34) ## 架构总览 整体认证与会话流程分为两段: 1. 网关层负责“把请求送到正确的节点”和“快速判断 token 对应的用户”。 2. 后端层负责“真正校验 token 是否有效”,并维护 Sa-Token 会话、活跃标记和业务资源。 ```mermaid sequenceDiagram participant C as "客户端" participant G as "网关 StickyRouteFilter" participant LRF as "网关 LoginRequestFilter" participant LRSF as "网关 LoginResponseFilter" participant T as "网关 TokenResolver" participant S as "后端 SysUserService" participant A as "后端 SaTokenWebConfig" participant R as "Redis" C->>G: POST /js/a/auth/login {username,password} G->>LRF: 解析 username LRF-->>G: 设置 LOGIN_USERNAME G->>G: 选择候选节点 G->>S: 转发登录请求 S->>A: Sa-Token 拦截器(白名单跳过) S->>S: 校验密码、账号状态 S->>S: 检查 LoginActivityService.isInUse S->>R: 写入活跃标记 zsjz:auth:last-active:userId S->>S: StpUtil.login(userId) S-->>G: Result{code=200, data.token, data.userId, data.username} G->>LRSF: 捕获登录响应 LRSF->>T: cacheToken(serviceId, token, userId) LRSF->>R: 写 gateway:token:serviceId:token LRSF-->>C: 原样返回登录响应 C->>G: 业务请求(携带 x-token) G->>T: resolveUserId(serviceId, x-token) T->>R: 读 gateway:token:serviceId:token T->>S: Sa-Token getLoginIdByToken(未命中时) S-->>T: userId G->>G: 按 userId 选节点并转发 G->>S: 业务请求 S->>A: checkLogin() S-->>G: 业务响应 ``` **图示来源** - [LoginRequestFilter.java:47-116](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java#L47-L116) - [StickyRouteFilter.java:59-128](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L59-L128) - [LoginResponseFilter.java:58-155](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java#L58-L155) - [TokenResolver.java:27-71](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L27-L71) - [SysUserService.java:83-132](file://ai-server/src/main/java/com/zsjz/ai/module/plat/service/SysUserService.java#L83-L132) - [SaTokenWebConfig.java:36-63](file://ai-server/src/main/java/com/zsjz/ai/common/config/SaTokenWebConfig.java#L36-L63) - [LoginActivityService.java:54-104](file://ai-server/src/main/java/com/zsjz/ai/common/auth/LoginActivityService.java#L54-L104) ## 详细组件分析 ### 用户登录流程 用户登录不是单纯的密码校验,还包含账号占用判断和会话顶号控制: 1. 前端调用 `/auth/login`,携带 `username`、`password`,可选 `force=true`。 2. 网关 `LoginRequestFilter` 读取登录路径的请求体,解析 `username`,并把响应编码改为 `identity`。 3. 网关 `StickyRouteFilter` 先查该用户名是否已有节点绑定;若无则选择一个健康候选节点,但不立即写绑定。 4. 后端 `SysUserService.login` 校验用户名和密码、账号状态,再调用 `LoginActivityService.isInUse`。 5. 如果账号正在使用且未带 `force=true`,返回业务码 `40901`,前端弹出确认框。 6. 确认后带 `force=true` 重新登录,后端先 `StpUtil.kickout(userId)` 踢掉旧会话,再执行 `StpUtil.login(user.getId())`。 7. 登录成功后,网关 `LoginResponseFilter` 把用户绑定到之前选择的节点,并把 `x-token → userId` 写入网关 token 缓存。 ```mermaid flowchart TD Start(["开始登录"]) --> ReadBody["网关解析登录请求体中的 username"] ReadBody --> ChooseNode{"用户名是否已绑定节点?"} ChooseNode -->|是| UseBound["使用已绑定节点"] ChooseNode -->|否| SelectCandidate["选择健康候选节点"] UseBound --> ForwardLogin["转发登录请求到后端"] SelectCandidate --> ForwardLogin ForwardLogin --> CheckPassword["后端校验用户名和密码"] CheckPassword --> AccountStatus{"账号是否停用?"} AccountStatus -->|是| Error["返回用户名或密码错误"] AccountStatus -->|否| CheckInUse["检查账号是否正在使用"] CheckInUse --> InUse{"是否正在使用?"} InUse -->|是| ForceCheck{"是否 force=true?"} ForceCheck -->|否| Return40901["返回 code=40901 提示继续登录"] ForceCheck -->|是| KickOld["踢掉旧会话"] InUse -->|否| DoLogin["执行 StpUtil.login"] KickOld --> DoLogin DoLogin --> WriteActivity["写入活跃标记 zsjz:auth:last-active:userId"] WriteActivity --> BuildResult["构造登录结果"] BuildResult --> BindNode["网关绑定用户到候选节点"] BindNode --> CacheToken["网关缓存 x-token → userId"] CacheToken --> End(["结束"]) Return40901 --> End Error --> End ``` **图示来源** - [LoginRequestFilter.java:47-116](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java#L47-L116) - [StickyRouteFilter.java:61-86](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L61-L86) - [SysUserService.java:83-132](file://ai-server/src/main/java/com/zsjz/ai/module/plat/service/SysUserService.java#L83-L132) - [LoginActivityService.java:79-104](file://ai-server/src/main/java/com/zsjz/ai/common/auth/LoginActivityService.java#L79-L104) - [LoginResponseFilter.java:119-155](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java#L119-L155) **章节来源** - [SysUserService.java:83-132](file://ai-server/src/main/java/com/zsjz/ai/module/plat/service/SysUserService.java#L83-L132) - [LoginActivityService.java:54-104](file://ai-server/src/main/java/com/zsjz/ai/common/auth/LoginActivityService.java#L54-L104) - [LoginRequestFilter.java:47-116](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java#L47-L116) - [LoginResponseFilter.java:58-155](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java#L58-L155) ### Token 生成与校验 - Token 生成由 Sa-Token 的 `StpUtil.login(userId)` 完成,后端返回给前端的 `token` 字段来自 `StpUtil.getTokenValue()`。 - 前端将 `token` 存入本地缓存,并在每次请求时通过 axios 拦截器注入请求头 `x-token`。 - 网关收到请求后: - 先查 `gateway:token:{serviceId}:{token}`; - 未命中时调用 Sa-Token 的 `getLoginIdByToken`,并把结果回填到网关 token 缓存,TTL 为 24 小时; - 解析不出 userId 时按匿名请求处理,透传给后端,由后端返回 `code=401`。 - 后端所有业务接口默认都需要登录,`SaTokenWebConfig` 通过 `StpUtil.checkLogin()` 校验;未登录时统一转成 HTTP 200 + body.code=401,前端据此跳转登录页。 ```mermaid flowchart TD Request["业务请求携带 x-token"] --> GatewayRead["网关读取 x-token"] GatewayRead --> CacheHit{"gateway:token:serviceId:token 命中?"} CacheHit -->|是| UserIdFromCache["得到 userId"] CacheHit -->|否| SaTokenQuery["调用 StpUtil.getLoginIdByToken"] SaTokenQuery --> ValidToken{"Sa-Token 认为 token 有效?"} ValidToken -->|是| CacheWrite["写入网关 token 缓存 TTL 24h"] ValidToken -->|否| Anonymous["按匿名请求处理"] CacheWrite --> Route["按 userId 选节点转发"] UserIdFromCache --> Route Anonymous --> BackendAuth["后端 Sa-Token checkLogin 返回 401"] Route --> BackendAuth ``` **图示来源** - [TokenResolver.java:27-71](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L27-L71) - [StickyRouteFilter.java:94-128](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L94-L128) - [SaTokenWebConfig.java:36-63](file://ai-server/src/main/java/com/zsjz/ai/common/config/SaTokenWebConfig.java#L36-L63) - [axios/index.ts:163-178](file://ai-electron/frontend/src/core/utils/http/axios/index.ts#L163-L178) **章节来源** - [TokenResolver.java:14-98](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L14-L98) - [SaTokenWebConfig.java:10-63](file://ai-server/src/main/java/com/zsjz/ai/common/config/SaTokenWebConfig.java#L10-L63) - [axios/index.ts:163-178](file://ai-electron/frontend/src/core/utils/http/axios/index.ts#L163-L178) ### 会话状态在 Redis 中的存储 Sa-Token 的会话和 token 都存储在共享 Redis 中,关键行为如下: - 生产环境默认 `is-concurrent=false`,同一账号新登录会顶掉旧 token,旧 token 下次请求时会被识别为被替换。 - 开发环境也配置 `is-concurrent=false`,但可通过环境变量临时开启多端。 - 活跃标记独立于 Sa-Token 活跃超时:`LoginActivityService` 使用 `zsjz:auth:last-active:{userId}`,TTL 等于判定窗口(默认 30 分钟),用于判断“账号是否正在使用”。 - 网关额外维护 `gateway:token:{serviceId}:{token}`,TTL 24 小时,避免每个请求都调用 Sa-Token。 - 用户路由缓存包括 `gateway:route:user:{serviceId}:{userId}` 和 `gateway:route:name:{serviceId}:{lower(username)}`,无 TTL,PostgreSQL 是事实来源。 | Redis 键 | 值 | TTL | 用途 | |---|---|---|---| | `gateway:token:{serviceId}:{token}` | userId | 24 小时 | 网关 token 快速解析 | | `gateway:route:user:{serviceId}:{userId}` | nodeId | 无 | 普通请求热路径 | | `gateway:route:name:{serviceId}:{lower(username)}` | nodeId | 无 | 登录请求热路径 | | `zsjz:auth:last-active:{userId}` | 时间戳字符串 | 判定窗口分钟数 | 账号是否正在使用 | **章节来源** - [TokenResolver.java:27-71](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L27-L71) - [UserRouteService.java:14-44](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java#L14-L44) - [LoginActivityService.java:30-52](file://ai-server/src/main/java/com/zsjz/ai/common/auth/LoginActivityService.java#L30-L52) - [application-dev.yaml:62-67](file://ai-server/src/main/resources/application-dev.yaml#L62-L67) - [application-pro.yaml:73-78](file://ai-server/src/main/resources/application-pro.yaml#L73-L78) - [application.yaml:160-168](file://ai-server/src/main/resources/application.yaml#L160-L168) ### 客户端 x-token 与服务端会话关联 - 前端登录成功后把 `token` 写入本地认证缓存,并通过 `setAuthCache(TOKEN_KEY, result.token)` 持久化。 - axios 请求拦截器从本地获取 token,并以 `authenticationHeader` 作为请求头名写入 `x-token`。 - 网关从 `x-token` 解析 userId,再按 userId 查用户路由缓存或数据库,最终转发到对应 ai-server 节点。 - 后端 Sa-Token 拦截器再次校验当前请求是否属于有效会话,从而形成“网关快速路由 + 后端真实鉴权”的双重机制。 ```mermaid sequenceDiagram participant FE as "前端 account.ts" participant AX as "axios 拦截器" participant GW as "网关 StickyRouteFilter" participant TR as "网关 TokenResolver" participant SA as "后端 Sa-Token 拦截器" FE->>FE: login() 写入 TOKEN_KEY FE->>AX: 发起业务请求 AX->>AX: getToken() 取本地 token AX->>GW: 发送请求头 x-token GW->>TR: 解析 x-token → userId TR-->>GW: userId GW->>GW: 选择节点并转发 GW->>SA: 业务请求到达后端 SA->>SA: checkLogin() 校验会话 SA-->>GW: 通过或返回 401 ``` **图示来源** - [account.ts:56-103](file://ai-electron/frontend/src/core/store/modules/account.ts#L56-L103) - [axios/index.ts:163-178](file://ai-electron/frontend/src/core/utils/http/axios/index.ts#L163-L178) - [StickyRouteFilter.java:94-128](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L94-L128) - [TokenResolver.java:27-71](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L27-L71) - [SaTokenWebConfig.java:36-63](file://ai-server/src/main/java/com/zsjz/ai/common/config/SaTokenWebConfig.java#L36-L63) **章节来源** - [authApi.ts:1-124](file://ai-electron/frontend/src/core/api/auth/authApi.ts#L1-L124) - [account.ts:56-103](file://ai-electron/frontend/src/core/store/modules/account.ts#L56-L103) - [axios/index.ts:163-178](file://ai-electron/frontend/src/core/utils/http/axios/index.ts#L163-L178) ### 与网关 StickyRouteFilter 的协作关系 - 网关职责: - 登录请求:按 `username` 查找绑定节点;未绑定时选择候选节点,等待登录成功后再落库。 - 普通请求:按 `x-token` 解析 userId;若用户无绑定节点且没有 default-node,返回 503。 - 节点健康:只选择启用且健康的节点;已绑定节点 DOWN 时直接失败,不自动切换。 - 响应头:附加 `X-Gateway-Node`,便于定位请求落到哪个节点。 - 后端职责: - 实际 Token 校验:`SaTokenWebConfig` 调用 `checkLogin()`。 - 业务权限:`SysUserService` 中仅保留管理员判断,不做完整权限体系。 - 会话副作用:登录活跃标记、顶号、踢号、登出释放资源。 ```mermaid classDiagram class StickyRouteFilter { +filter(exchange, chain) +decideForLogin(exchange, service) +decideForNormal(exchange, service) +route(exchange, chain, service, nodeId) } class LoginRequestFilter { +filter(exchange, chain) +parseUsername(bytes) } class LoginResponseFilter { +filter(exchange, chain) +parseAndBind(serviceId, chosenNodeId, body) } class TokenResolver { +resolveUserId(serviceId, token) +cacheToken(serviceId, token, userId) } class UserRouteService { +findNodeIdByUserId(serviceId, userId) +findNodeIdByUsername(serviceId, username) +bindIfAbsent(serviceId, userId, username, nodeId) } StickyRouteFilter --> LoginRequestFilter : "使用 LOGIN_USERNAME" StickyRouteFilter --> UserRouteService : "查询用户路由" StickyRouteFilter --> TokenResolver : "解析 x-token" LoginResponseFilter --> UserRouteService : "绑定用户" LoginResponseFilter --> TokenResolver : "缓存 token" ``` **图示来源** - [StickyRouteFilter.java:22-178](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L22-L178) - [LoginRequestFilter.java:19-116](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java#L19-L116) - [LoginResponseFilter.java:16-174](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java#L16-L174) - [TokenResolver.java:14-98](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L14-L98) - [UserRouteService.java:14-115](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java#L14-L115) **章节来源** - [StickyRouteFilter.java:22-178](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L22-L178) - [ai-gateway-user-sticky-routing.md:33-120](file://docs/design/ai-gateway-user-sticky-routing.md#L33-L120) ### 账号被顶下线或踢下线后释放案件数据源 当账号被新登录顶下线、被管理员踢下线,或主动登出时,系统需要释放该用户打开的案件数据源,防止 DuckDB 实例长期占用内存: 1. 主动登出:`SysUserService.logout` 先释放当前 token 打开的案件,再执行 `StpUtil.logout()`。 2. 被顶下线或被踢下线:由 Sa-Token 的会话监听触发释放逻辑。 3. 会话自然过期:Sa-Token 的 Redis 会话自然过期不会回调监听器,因此 `CaseDataSourceReaper` 定期扫描已打开案件,检查归属 token 是否仍有效;无效且没有在途任务时关闭数据源并清理缓存。 4. 保守策略:查询会话状态失败、探针异常时一律不释放,宁可多占内存也不误关正在使用的案件。 ```mermaid flowchart TD SessionEnd["会话结束:登出 / 被顶 / 被踢 / 过期"] --> Triggered{"是否触发表面事件?"} Triggered -->|登出| LogoutRelease["SysUserService.logout 释放当前 token 的案件"] Triggered -->|被顶或被踢| ListenerRelease["会话监听释放旧会话打开的案件"] Triggered -->|自然过期| ReaperScan["CaseDataSourceReaper 定期扫描"] ReaperScan --> CheckToken{"归属 token 是否仍有效?"} CheckToken -->|是| KeepOpen["保持数据源打开"] CheckToken -->|否| HasWork{"是否有在途任务?"} HasWork -->|是| SkipReap["本轮跳过回收"] HasWork -->|否| CloseCase["关闭数据源并清理缓存"] LogoutRelease --> Done["完成"] ListenerRelease --> Done KeepOpen --> Done SkipReap --> Done CloseCase --> Done ``` **图示来源** - [SysUserService.java:134-148](file://ai-server/src/main/java/com/zsjz/ai/module/plat/service/SysUserService.java#L134-L148) - [CaseDataSourceRegistry.java:28-42](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceRegistry.java#L28-L42) - [CaseDataSourceReaper.java:12-123](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceReaper.java#L12-L123) **章节来源** - [SysUserService.java:134-148](file://ai-server/src/main/java/com/zsjz/ai/module/plat/service/SysUserService.java#L134-L148) - [CaseDataSourceRegistry.java:28-42](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceRegistry.java#L28-L42) - [CaseDataSourceReaper.java:12-123](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceReaper.java#L12-L123) ### 登录失效时前端清理缓存的注意事项 - 登录成功后,前端必须把 `token` 和用户信息写入本地缓存,否则后续请求无法携带 `x-token`。 - 登录失败时不应误判为成功;当前 `loginApi` 要求 `code=200` 且存在 `data.token`。 - 登录失效后,前端应清理本地 `TOKEN_KEY` 和 `USER_INFO_KEY`,避免残留状态导致页面误以为已登录。 - 登出时先调用后端 `/auth/logout`,即使网络失败也要清理本地状态,避免卡在失效登录态。 - 刷新页面后通过 `/auth/info` 恢复用户态;如果接口返回 401,axios 会跳转到登录页。 **章节来源** - [authApi.ts:1-124](file://ai-electron/frontend/src/core/api/auth/authApi.ts#L1-L124) - [account.ts:56-114](file://ai-electron/frontend/src/core/store/modules/account.ts#L56-L114) - [axios/index.ts:44-96](file://ai-electron/frontend/src/core/utils/http/axios/index.ts#L44-L96) ## 依赖关系分析 - 网关模块依赖: - Spring Cloud Gateway 过滤器链; - Redis 用于 token 缓存和用户路由缓存; - PostgreSQL 用于用户路由事实来源; - Sa-Token 用于回退解析 token。 - 后端模块依赖: - Sa-Token 提供登录、会话、踢号、登出能力; - Redis 存储会话、活跃标记; - PostgreSQL 存储用户信息和路由映射; - DuckDB 通过 `CaseDataSourceRegistry` 管理进程内案件数据源。 - 前端模块依赖: - Axios 拦截器注入 `x-token`; - Pinia store 管理用户状态; - 本地缓存存储 token 和用户信息。 ```mermaid graph LR Frontend["前端 authApi.ts / account.ts / axios"] --> Gateway["网关 StickyRouteFilter / TokenResolver / UserRouteService"] Gateway --> Redis["Redis"] Gateway --> Postgres["PostgreSQL"] Gateway --> Backend["后端 SysUserService / SaTokenWebConfig"] Backend --> Redis Backend --> Postgres Backend --> DuckDB["DuckDB 案件数据源"] ``` **图示来源** - [authApi.ts:1-124](file://ai-electron/frontend/src/core/api/auth/authApi.ts#L1-L124) - [account.ts:1-114](file://ai-electron/frontend/src/core/store/modules/account.ts#L1-L114) - [StickyRouteFilter.java:22-178](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L22-L178) - [TokenResolver.java:14-98](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L14-L98) - [UserRouteService.java:14-115](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java#L14-L115) - [SysUserService.java:44-148](file://ai-server/src/main/java/com/zsjz/ai/module/plat/service/SysUserService.java#L44-L148) - [CaseDataSourceRegistry.java:16-120](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceRegistry.java#L16-L120) **章节来源** - [ai-gateway-user-sticky-routing.md:18-46](file://docs/design/ai-gateway-user-sticky-routing.md#L18-L46) - [application.yaml:1-31](file://ai-server/src/main/resources/application.yaml#L1-L31) ## 性能与存储特性 - 网关 token 解析优先走 Redis 缓存,避免每次请求都调用 Sa-Token;未命中才回源 Sa-Token,并回填 24 小时缓存。 - 用户路由缓存采用 Redis 两级缓存:先查 Redis,未命中查 PostgreSQL,再回填 Redis。 - 活跃标记按用户节流:同一节点每分钟最多写一次 Redis,降低高频请求对 Redis 的压力。 - 会话超时方面,Sa-Token 的 `active-timeout` 当前配置为 `-1`,长时间研判不会被活跃超时踢掉;`timeout` 为 2592000 秒,即约 30 天。 - 案件数据源有上限:`max-open-cases` 默认 8,超过直接拒绝开案,避免无限增长。 - 兜底回收器默认启动延迟 60 秒,每 5 分钟扫描一次,避免频繁扫描影响调度线程池。 **章节来源** - [TokenResolver.java:14-34](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L14-L34) - [UserRouteService.java:14-44](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java#L14-L44) - [LoginActivityService.java:43-52](file://ai-server/src/main/java/com/zsjz/ai/common/auth/LoginActivityService.java#L43-L52) - [application-dev.yaml:62-67](file://ai-server/src/main/resources/application-dev.yaml#L62-L67) - [application-pro.yaml:73-78](file://ai-server/src/main/resources/application-pro.yaml#L73-L78) - [application.yaml:72-82](file://ai-server/src/main/resources/application.yaml#L72-L82) - [CaseDataSourceRegistry.java:90-120](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceRegistry.java#L90-L120) - [CaseDataSourceReaper.java:40-54](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceReaper.java#L40-L54) ## 故障排查指南 - 登录后仍提示未登录: - 检查前端是否正确写入 `TOKEN_KEY`; - 检查 axios 拦截器是否正确注入 `x-token`; - 检查网关 `gateway:token:{serviceId}:{token}` 是否存在; - 检查后端 Sa-Token 会话是否有效。 - 登录后请求总是跳到另一个节点: - 检查 `gateway:route:user:{serviceId}:{userId}` 是否已写入; - 检查 `gateway:route:name:{serviceId}:{lower(username)}` 是否已写入; - 检查是否首次登录尚未绑定成功。 - 登录后请求报 503 用户未绑定节点: - 检查服务是否配置了 `default-node-id`; - 检查是否登录成功但没有触发 `LoginResponseFilter` 的绑定逻辑; - 检查登录响应是否满足 `code=200` 且包含 `userId`、`username`。 - 账号被顶下线后案件数据源未释放: - 检查是否在登出时被顶下线; - 检查是否有在途任务使回收器跳过; - 检查归属 token 是否仍被 Sa-Token 认为有效; - 查看兜底扫描日志,确认是否因会话查询失败而保守不释放。 - 登录提示“账号正在其他设备使用”: - 检查 Redis 中 `zsjz:auth:last-active:{userId}` 是否存在; - 检查 Sa-Token 是否仍有该用户的 token; - 确认是否需要带 `force=true` 重新登录。 **章节来源** - [StickyRouteFilter.java:94-178](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L94-L178) - [LoginResponseFilter.java:58-174](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java#L58-L174) - [TokenResolver.java:27-98](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L27-L98) - [CaseDataSourceReaper.java:40-123](file://ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceReaper.java#L40-L123) - [LoginActivityService.java:54-104](file://ai-server/src/main/java/com/zsjz/ai/common/auth/LoginActivityService.java#L54-L104) ## 安全建议 - Token 泄露处理: - 一旦怀疑 token 泄露,应尽快让原用户登出或强制踢下线,使旧 token 失效; - 由于网关 token 缓存 TTL 为 24 小时,建议配合后端登出或会话失效机制,不要只依赖缓存过期; - 检查是否有人通过代理或日志获取了 `x-token`,收敛日志中敏感头输出。 - 会话超时配置: - 当前 Sa-Token `active-timeout=-1`,长时间研判不会被活跃超时踢掉,适合长任务场景; - 如需限制会话有效期,应调整 Sa-Token 的 `timeout`,并结合前端在超时后主动清理缓存; - 注意 `active-timeout` 与 `zsjz.auth.in-use-window-minutes` 语义不同:前者是会话活跃超时,后者只是“账号是否正在使用”的判断窗口。 - 敏感接口鉴权模式: - 当前 `SaTokenWebConfig` 只做登录校验,不做角色或权限注解; - 管理员接口如 `/user/**` 由 `SysUserService.assertAdmin()` 通过 `is_admin` 字段保护; - 新增敏感接口应显式检查管理员身份或扩展 Sa-Token 权限模型,不建议仅凭 URL 白名单。 - 调试方法: - 查看网关响应头 `X-Gateway-Node`,确认请求落到哪个节点; - 检查 Redis 中 `gateway:token:*`、`gateway:route:user:*`、`gateway:route:name:*`、`zsjz:auth:last-active:*`; - 联调时可暂时开启 Sa-Token 多端登录,但生产应保持 `is-concurrent=false`; - 前端登录接口使用 `isTransformResponse:false`,以便拿到 `code=40901` 等业务码。 **章节来源** - [TokenResolver.java:14-34](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L14-L34) - [application-dev.yaml:62-67](file://ai-server/src/main/resources/application-dev.yaml#L62-L67) - [application-pro.yaml:73-78](file://ai-server/src/main/resources/application-pro.yaml#L73-L78) - [application.yaml:160-168](file://ai-server/src/main/resources/application.yaml#L160-L168) - [SaTokenWebConfig.java:10-63](file://ai-server/src/main/java/com/zsjz/ai/common/config/SaTokenWebConfig.java#L10-L63) - [SysUserService.java:150-166](file://ai-server/src/main/java/com/zsjz/ai/module/plat/service/SysUserService.java#L150-L166) - [authApi.ts:39-54](file://ai-electron/frontend/src/core/api/auth/authApi.ts#L39-L54) ## 结论 本系统的认证与会话管理采用“网关粘性路由 + 后端 Sa-Token 鉴权”的分层设计:网关负责按用户名和 `x-token` 把请求稳定转发到用户所属的 ai-server 节点,后端负责真正的会话有效性、活跃标记和资源释放。Redis 同时承担 Sa-Token 会话、网关 token 缓存、用户路由缓存和账号活跃标记的作用。为保障数据安全与内存安全,系统在顶下线、踢下线、登出和会话过期四种场景下释放案件数据源,并通过兜底回收器处理自然过期的孤儿会话。未来应重点关注 Token 泄露处置、会话超时策略、敏感接口权限扩展以及多节点部署下的缓存一致性。