本文引用的文件
本文说明基于 Sa-Token 的认证与会话方案:后端如何初始化认证拦截器、用户登录时 token 如何生成和存储、前端如何通过 x-token 携带会话访问接口;并解释“登录前校验账号是否正在使用”的逻辑、账号被顶下线或踢下线后如何释放其全部案件数据源,以及 Gateway 中如何解析和透传 token。文末给出常见问题的排查方法,包括 token 不一致、401/403、账号被顶下线等。
本项目涉及认证与会话的三个层次:
x-token 解析 userId、选择后端节点并把请求转发到具体服务实例。前端层(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/>会话监听释放"]
图示来源
章节来源
checkLogin(),白名单放行登录、健康检查、地图静态资源等。未登录时抛出异常,由全局异常处理器转为 HTTP 200 + body.code=401。/auth/login、/auth/logout、/auth/info、/auth/changePwd、/auth/verifyPwd。token 通过响应体返回,后续请求统一用 x-token 传递。x-token 选择固定后端节点,保证同一用户的请求落到有本地数据的节点。x-token 注入请求头,对 code=401 触发重新登录,对登录接口的 40901 业务码弹出“是否继续登录”。章节来源
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
图示来源
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"]
图示来源
章节来源
/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
图示来源
章节来源
LoginActivityService.isInUse(userId) 同时检查两件事:
zsjz:auth:last-active:,value 为最后活跃时间戳,TTL 即判定窗口。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
图示来源
章节来源
系统设计了四层释放机制,缺一不可:
/auth/logout。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
图示来源
章节来源
StickyRouteFilter 从请求头取 x-token;无 token 时按匿名请求选择健康节点。TokenResolver.resolveUserId(serviceId, token);解析失败则按匿名处理,后端返回 code=401。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
图示来源
章节来源
authenticationHeader=x-token,authenticationScheme 为空。x-token。登录接口使用 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["显示错误消息"]
图示来源
章节来源
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"
图示来源
章节来源
active-timeout=-1,表示长时间研判不会被“活跃超时”踢掉;因此“账号是否正在使用”改用独立的 Redis 活跃标记,避免依赖 Sa-Token 活跃策略。LoginActivityService.touch 对同一用户每分钟最多写一次 Redis,降低高频请求带来的 Redis 压力。TokenResolver 使用 24 小时 TTL 的 Redis 缓存,减少每次请求都查询 Sa-Token 的开销。章节来源
/auth/login,携带用户名和密码。force=true 再次提交,后端踢掉旧会话并创建新 token。x-token。章节来源
x-token。章节来源
force=true,后端调用 kickout 踢掉旧会话。章节来源
x-token,或 authenticationHeader 不是 x-token。x-token。authenticationHeader 是否为 x-token。gateway:token:{serviceId}:{token} 是否存在。章节来源
is-concurrent=false 是否符合预期。/user/kickout 或管理员重置密码。章节来源
/gateway/admin/** 时,用户不是管理员。gateway.admin.enabled 配置。gateway.admin.ip-whitelist。is_admin=1 且 status=1。章节来源
force=true。CaseSessionListener 或 CaseDataSourceReaper 回收。章节来源
CaseDataSourceReaper 的调度日志。zsjz.duckdb.max-open-cases 是否被占满。/case/exit 或 /auth/logout。章节来源
本项目的认证与会话方案以 Sa-Token 为核心,结合 Redis 管理会话和活跃标记,通过 Gateway 实现 token 解析与粘性路由,前端通过 Axios 统一注入 x-token。登录前校验账号占用避免了无声顶号,四重释放机制保障了 DuckDB 案件数据源的生命周期安全。生产环境默认单端登录,若需联调多端可通过环境变量临时开启;排查问题时建议从前端请求头、Gateway 缓存、Sa-Token Redis、后端会话监听与兜底回收器五个层面逐步定位。