[Java/权限认证] Sa-Token:轻量一站式的 Java 权限认证框架 —— 深度调研、与 Spring Security 的全维对比及若依生态的落地实践

0 序

  • 调研契机: 公司项目中使用的 Ruoyi-Cloud-Plus (v2.6.0/jdk17),而若依框架的权限管控是基于 Sa-Token 框架(1.44.0)来实现的。为此需要了解一二。

  • 调研策略:

调研对象:人工 + AI
调研对象:dromara/Sa-Token(开源、Apache-2.0)
调研基准版本:Sa-Token v1.45.0 / v1.46.0(官方两站点显示的版本号不一致,见 1.2 说明)
取证时间:2026-11-11(仓库统计取自 ungh.cc 实时快照,源码取自 GitHub raw 原文)
文档性质:技术调研报告(Markdown)。文中「已查证」= 有官方文档/源码/接口原文支撑;「一方称」= 仅厂商/项目方自述,未做双向核实。


1 概述

1.1 产品介绍(必读)

定位:Sa-Token 是一个「零依赖内核 + 静态工具类 API」的 Java 权限认证框架,把登录认证、权限认证、分布式会话、SSO、OAuth2.0、微服务网关鉴权收进一套 API,追求「一行代码解决一个鉴权诉求」。

诞生的背景与解决的核心问题

传统方案的痛点 Sa-Token 的对应设计 证据
Shiro / Spring Security 概念多、配置链长,一个登录要写 Realm、Provider、FilterChain、UserDetailsService 等成套代码 静态 API:StpUtil.login(id) 即完成会话登录;无需实现任何接口、无需配置文件 官方首页「你只需要:StpUtil.login(10001)」
传统 HttpSession 难以分布式、水平扩展差、前后端分离(APP/小程序无 Cookie)适配差 以账号为主体的 Session 模型(Account-Session)+ Token 主体(Token-Session),天然可放 Redis 官方 Session 章节、v1.12 文档「独创 Id-Session 模式」
多端登录、同端互斥、踢人下线、账号封禁等运营级能力缺失,需业务自研 内置踢人、顶人、封禁(分类/阶梯)、二级认证、临时身份切换、模拟他人 官方功能一览
单点登录与 OAuth2 往往要引入 CAS/Keycloak 等重型中间件 内置 SSO 三模式 + OAuth2.0(含 OIDC)模块 官方功能一览、v1.21/v1.23/v1.39 更新日志
微服务下网关鉴权、内部 RPC 调用「裸奔」 网关过滤器(Servlet/Reactor 双栈)+ Same-Token + Dubbo/gRPC 上下文插件 v1.16、v1.24、v1.31 更新日志

官方链接

类型 地址 说明
官网 / 在线文档(主) https://sa-token.cc 文档首页自述「最新开发文档永远在 sa-token.cc」
官网(备用域名) https://sa-token.com 首页显示 v1.46.0,含开源案例库
GitHub https://github.com/dromara/Sa-Token 默认分支 dev
Gitee https://gitee.com/dromara/sa-token 国内镜像与交流主阵地
所属组织 Dromara 开源社区 仓库 owner 即 dromara
开源协议 Apache-2.0 v1.5.1 曾为 MIT,v1.8.0 起改为 Apache-2.0(更新日志可查)

开发者团队与治理

  • 由个人开发者 click33(山东、济南) 主导发起、并长期维护,2020-02-03 提交首行代码(仓库 createdAt: 2020-02-03T10:34:29Z)。
  • 官方自述「不是 SpringSecurity 的封装,也不是 Shiro 套壳,而是【从 0 自研】,核心包零依赖」;v1.16.0 更新日志「核心包脱离 ServletAPI,彻底零依赖」可与该说法互证 —— 已查证。

1.2 发展历程

数据来源:Sa-Token 官方「更新日志」章节逐版本原文 + GitHub 仓库元数据。

时间 版本 里程碑意义
2020-02-03 首个 commit 项目启动
2020-02-04 v1.0.0 第一个发布版本
2020-03-07 v1.2.0 引入注解式鉴权(@SaCheckPermission 雏形)
2020-12-24 v1.7.0 改为 Maven 多模块 + spring-boot-starter 自动装配
2021-01-02 v1.8.0 Token-Session、Redis starter、Jackson 序列化、协议改 Apache-2.0
2021-01-09 v1.10.0 会话查询全量 API
2021-04-12 v1.16.0 核心包零依赖 + ThreadLocal 上下文 + WebFlux/Reactor 支持 + 网关鉴权方案(架构定型的关键版本)
2021-07-02 v1.21.0 SSO 三模式、二级认证、独立 Redis 插件
2021-07-19 v1.23.0 OAuth2.0 模块正式发布
2021-11-05 v1.28.0 sa-token-jwt、sa-token-dubbo 插件,插件开发指南
2022-05-09 v1.30.0 WebSocket 鉴权、jfinal/jboot 集成
2022-09-08 v1.31.0 SaInterceptor 综合拦截器、@SaIgnore、账号封禁(分类/阶梯)
2023-01-11 v1.34.0 Spring Boot 3.x 集成包、Redisson 插件
2024-08-28 v1.39.0 注解鉴权底层重构、OAuth2 模块整体重构(OIDC、scope 分级、grant_type 扩展)、Shiro/SpringSecurity 迁移示例
2025-02-01 v1.40.0 防火墙策略(path 黑名单、非法字符校验)、SpEL 表达式鉴权、Freemarker 集成
2025-03-21 v1.41.0 SPI 插件体系、SaTokenDao 序列化/存储解耦、SaLoginParameter(大量不向下兼容项)
2025-04-11 v1.42.0 API Key 模块、TOTP、Mock 上下文(异步场景)
2025-05-17 v1.43.0 SSO 消息推送机制、单设备注销、@SaCheckOr append
2025-06-07 v1.44.0 SSO 修复批次、OAuth2 DataLoader 扩展
2026-03-08 v1.45.0 Spring Boot 4 starter、Reactor+SB4 starter、Jackson3 / snack4 插件、重复登录处理策略
2026-11 v1.46.0 官方 sa-token.com 首页标注版本;RuoYi-Cloud-Plus 6.1.0 发行说明「Sa-Token 从 1.45.0 升级至 1.46.0」

取证说明(严谨性提醒):sa-token.cc 文档首页显示 v1.45.0,sa-token.com 首页显示 v1.46.0,二者不一致;当前(2026-11-11)第三方最新证据是若依 6.1.0 发行说明里的 1.46.0。因此本文以 1.45.0 的 API 语义为准描述行为(1.46.0 未见公开更新日志),实际选版建议以 Maven Central 最新坐标为最终依据。

1.3 主要功能(必读)

官方功能一览归纳为 五大核心模块 + 若干实用插件:

flowchart LR subgraph CORE["Sa-Token 核心能力"] A1["登录认证<br/>单端/多端/同端互斥/七天免登录"] A2["权限认证<br/>权限码/角色/二级认证"] A3["会话管理<br/>Account-Session / Token-Session / Custom-Session"] A4["SSO 单点登录<br/>同域 / 跨域 / 同Redis / 跨Redis"] A5["OAuth2.0<br/>四种授权模式 + OIDC"] end subgraph OPS["运营与治理能力"] B1["踢人下线 / 顶人下线"] B2["账号封禁<br/>登录封禁/分类封禁/阶梯封禁"] B3["会话查询 / 在线用户统计"] B4["全局侦听器 SaTokenListener"] B5["防火墙 SaFirewallStrategy"] end subgraph MS["微服务能力"] D1["网关鉴权<br/>SaServletFilter / SaReactorFilter"] D2["Same-Token 内部调用鉴权"] D3["Dubbo / gRPC 上下文透传"] D4["API Key / API 参数签名"] end CORE --> OPS CORE --> MS
能力域 具体能力(官方列示,已查证)
登录 单端登录、多端登录、同端互斥(像 QQ 手机/电脑并存但两台手机互斥)、记住我、七天免登录、Token 自动续签
权限 权限码校验、角色校验、权限+角色「双重 OR」(orRole)、通配符权限、二级认证(敏感操作再验证)
会话 三模型 Session、全端共享/单端独享、自定义 Session、会话剩余有效期读写
账号运营 踢人下线、顶人下线、强制注销、封禁(按业务分类/按处罚阶梯)、模拟他人账号、临时身份切换
单点登录 三种 SSO 模式 + 单点注销 + 前后端分离/非 Java 项目 NoSdk 对接
OAuth2 授权码/隐式/密码/客户端凭证四模式、OIDC、openid、自定义 scope 与 grant_type、Refresh-Token 多并存
微服务 网关统一鉴权、内部服务外网隔离、RPC 链鉴权、RPC 登录态传递
生态适配 SpringMVC / WebFlux / Solon / JFinal / Jboot / SSM / Spring Boot 2-3-4、Thymeleaf/Beetl/Freemarker 标签方言
安全增强 JWT 三种集成模式、API Key、API 参数签名(防篡改/防重放)、防火墙、Http Basic/Digest、密码加密工具

1.4 核心优势(必读)

优势 具体表现 佐证
学习与接入成本极低 登录一行、鉴权一行;无必须实现的扩展接口;application.yml 几行即完成配置 官方首页示例
API 语义统一 StpUtil 一个入口覆盖 login/logout/kickout/checkPermission/getSession/switchTo…;返回值与异常均为业务可读语义 官方 API 手册
前后端分离/多端友好 默认读 Token 位置:request > body > header > cookie(v1.4.0 定序),天然适配 APP/小程序 更新日志 v1.4.0
分布式会话开箱可用 只需换 SaTokenDao 实现(Redis/Redisson/Caffeine/Hutool TimedCache),业务代码零改动 官方「持久层扩展」
一站式 鉴权 + SSO + OAuth2 + 网关 + RPC 链鉴权不额外引中间件 官方功能清单一节
中文文档质量高 单页文档覆盖 60+ Demo、每章带「本章小练习」、B 站视频配套 官方文档结构
零依赖内核 核心包不依赖 Servlet API 与第三方库,可移植到 Solon 等非 Spring 容器 v1.16.0 更新日志
扩展点设计合理 SaStrategy 策略化(可重写 token 生成、权限算法等)、SaTokenListener 事件、v1.41 起 SPI 插件体系 更新日志 v1.27 / v1.41
国产脚手架生态强 若依系(RuoYi-Vue-Plus / RuoYi-Cloud-Plus)、Snowy、ContiNew 等大量采用 官方「使用 Sa-Token 的开源项目」页

1.5 主要短板

与 Spring Security 对照才成立的短板,逐条给出可核验的依据或场景。

短板 说明 影响面
无域对象级 ACL Spring Security 自带 Acl/PermissionEvaluator 体系;Sa-Token 只有「权限码字符串 + 通配符」匹配 精细到「某文档/某订单实例」的授权需业务自写
无安全上下文标准 不产出 SecurityContext/Authentication,因此依赖 Spring 生态的组件(如 Spring Data 审计、@WithMockUser、方法级 SpEL 深度整合、Spring Authorization Server)无法直接复用 与 Spring 官方生态耦合度低
缺少官方级安全治理流程 Spring Security 有 CVE 编号体系与 Spring 官方安全公告周期;Sa-Token 的【安全修复】走 Gitee Issue + 版本日志(曾修复路由拦截绕过 v1.37、SSO @ 绕过 v1.38、分号路径 v1.40) 合规审计/等保测评时需要额外自证
不向下兼容版本较多 更新日志中方括号 [不向下兼容] 出现频繁(v1.41 一次性重构 SaLoginModel→SaLoginParameter、TokenSign→SaTerminalInfo) 跨大版本升级有改造成本
无内置用户/角色/菜单模型 框架只给「鉴权原语」,RBAC 元数据要自建(若依 Plus 正是补这一层) 直接上手需先设计权限模型
极小型维护团队 核心作者单一,Bus factor 偏低(对比 Spring 团队的多人轮值) 长期技术选型的组织风险
中文为主,英文资料少 对跨国团队/外籍成员不友好 海外项目慎用
与 Spring Security 同时引入易冲突 双方都注册过滤器/拦截器,鉴权顺序与异常处理会互相覆盖 迁移期必须显式摘除一边

1.6 局限性(必读)

  • 只解决「认证 + 授权」的通用部分:不含【用户管理】、【组织架构】、【数据权限】(若依的 @DataPermission 是【业务层扩展】,不是 Sa-Token 提供)。
  • 【授权模型】是 RBAC 字符串匹配:能表达「用户具备 system:user:add」,不能原生表达「用户是订单#1001 的属主」这类属性/实例级策略(ABAC/ReBAC 需外部引擎,如 Casbin/OpenFGA)。
  • 非 HTTP 上下文需显式处理:定时任务、消息消费、异步线程池中无请求上下文,需 SaTokenContextForThreadLocal 的 Mock 能力(v1.42 起提供 Mock 上下文模块)。
  • 会话默认强依赖外部存储:多实例部署必须接 Redis,否则各节点内存会话互不可见(默认 SaTokenDaoDefaultImpl 是单机内存 Map)。
  • 不自带传输安全:HTTPS、CSRF、XSS、CORS 仍需网关/容器层解决(框架提供全局过滤器便于统一加安全响应头,但不是 WAF)。
  • 生态工具链缺失:无官方 Spring Boot Actuator 端点、无官方测试注解体系(@SaCheckPermission 的单测需自建 Mock 上下文)。

1.7 适用场景(必读)

场景 适配度 原因
中小型业务系统 / 后台管理(单体或微服务) ★★★★★ 登录鉴权是主要诉求,API 成本最低
若依系脚手架二次开发(RuoYi-Vue-Plus / Cloud-Plus) ★★★★★ 已深度集成,等于默认技术栈
前后端分离 + APP/小程序/多端 ★★★★★ Token 多端、同端互斥、踢人下线开箱可用
需要 SSO 的多系统集团内网 ★★★★☆ 三模式 SSO 覆盖,但大规模身份治理仍建议 Keycloak/CAS
微服务网关统一鉴权 ★★★★☆ 双栈过滤器 + 内部调用 Same-Token,成本低于自研
需要对外开放 OAuth2 授权(第三方接入) ★★★☆☆ 有 OAuth2/OIDC 模块,但规范完备度与生态不如 Spring Authorization Server
强合规/强审计的金融级系统 ★★☆☆☆ 缺少官方 CVE 治理与审计报告,需自行补证
需要实例级 ACL、复杂策略(ABAC) ★★☆☆☆ 建议 Spring Security + PermissionEvaluator,或叠加策略引擎
非 Spring 技术栈(Solon/JFinal) ★★★★☆ 官方提供对应插件

1.8 同类竞品(必读)

框架 GitHub Star(2026-11-11 快照) Fork 定位 与 Sa-Token 的关系
Sa-Token 19,114 2,912 一站式 Java 鉴权(登录+权限+SSO+OAuth2+网关) 本体
Spring Security 9,668 6,391 Spring 官方安全框架(认证/授权/防护,生态最完整) 主要竞争对手,深度对比见第 4 章
Apache Shiro 4,465 2,291 通用安全框架(Subject/Session/Realm,弱 Spring 耦合) 【上一代主流选择】,Sa-Token 文档【公开对标】
Pac4j 未取数(本文不评估) — 多协议客户端安全引擎(OIDC/SAML/CAS) 竞品,偏「客户端接入多身份源」
Keycloak / CAS / MaxKey 未取数(本文不评估) — 身份提供方(IdP)/ 单点登录中间件 互补:Sa-Token 做应用侧鉴权,它们做【统一身份源】

热度口径提醒:开源框架不存在权威「市占率」统计。上表用 Star/Fork 作为热度代理指标,Star 高≠企业装机量大(Spring Security 因被 Spring Boot 默认生态捆绑,实际部署量远高于 Star 比例)。Sa-Token 官方自述「GitHub 18,523 Star,是 Spring Security 的 1.97 倍、Shiro 的 4.19 倍(统计日 2026-01-25)」为一方称;按本次实时快照,Sa-Token 约为 Spring Security 的 1.98 倍、Shiro 的 4.28 倍,该倍数结论可复现。

1.9 发展趋势

开源社区活跃度(已查证)

指标 数值 口径
Star 19,114 ungh.cc 快照 2026-11-10
Fork 2,912 同上
最近推送 2026-10-16 pushedAt,距取证日约 26 天,仍在活跃维护
创建时间 2020-02-03 已 6 年 9 个月
Gitee Star 48,627 官方自述(2026-01-25,一方称)
群/文档量 25+ 微信 500 人群、8+ QQ 千人群、月 PV 20 万+ 官方自述(一方称)
发布节奏 2025 年 5 个 minor(1.40→1.44),2026 年至少 1.45/1.46 更新日志

Star 增长阶段(据官方趋势图与版本节奏归纳,非官方数字)

2020-02 ~ 2021-03  冷启动(0 → 约 1k)      :核心架构打磨,零依赖+WebFlux 定型
2021-03 ~ 2021-09  第一次跃升(1k → 约 7k) :SSO/OAuth2 上线,赶上「前后端分离」红利
2021-09 ~ 2024-12  线性爬坡(7k → 13k)     :若依系等国产脚手架大规模采用带动
2025-01 ~ 2026-11  二次加速(13k → 19.1k)  :API Key/TOTP/防火墙/SPI/Spring Boot 4 适配

小结

Sa-Token 的演进方向非常清晰:从「轻量登录鉴权工具」→「一站式认证授权套件」→「具备插件体系与安全防护的框架」,并借国产脚手架生态(若依系、Solon、Dromara 组织)完成扩散;它在「上手成本 + 中文生态 + 国产框架适配」上已形成护城河,但在「企业级治理、合规审计、官方生态背书」上仍与 Spring Security 存在结构性差距。


2 工作原理与架构

2.1 概念术语

术语 类型 职责 关键 API / 位置
StpUtil 静态工具类 面向业务的统一门面:登录、注销、踢人、校验权限、取 Session cn.dev33.satoken.stp.StpUtil
StpLogic 会话逻辑核心 「一个账号体系」的全部规则实现(Token 生成、会话读写、校验) StpLogicDefault;每个 loginType 一个实例
LoginType(账号类型) 逻辑隔离维度 StpUtil= login;StpUserUtil = user;可自定义 多账号体系的基础
SaTokenDao 持久层抽象 Token↔loginId 映射、Session 存取、活跃时间等全部落库操作 默认内存实现;可换 Redis/Redisson/Caffeine
SaTokenContext 上下文抽象 适配不同 Web 栈(Servlet / Reactor / Solon)读写 request/response/存储 SaTokenContextForThreadLocal
SaTokenConfig 全局配置 timeout、active-timeout、token-name、token-style、is-concurrent、is-share 等 sa-token.*
SaSession 会话容器 KV 缓存组件,带 id/createTime/timeout,可存实体(getModel) 三种模型共用同一对象
SaManager 全局管理器 持有 config / dao / context / strategy / StpLogic 集合 / listener 所有扩展的挂载点
SaStrategy 策略接口 可重写 token 生成、权限匹配等内部算法(不侵入框架) v1.27 引入
SaTokenListener 事件侦听 登录、注销、被踢、被顶下线等关键动作的 AOP 钩子 v1.17 引入,v1.31 改为事件发布订阅
SaRouter / SaInterceptor 路由鉴权 链式路径匹配 + 校验函数;拦截器统一入口 SaRouter.match("/user/**", r -> StpUtil.checkPermission("user"))
SaTokenInfo 返回值对象 tokenName / tokenValue / loginId / tokenTimeout / loginType… StpUtil.getTokenInfo()
Token-Style Token 生成风格 uuid(默认)/ simple-uuid / random-32 / random-64 / random-128 / tik sa-token.token-style

2.2 总体架构

flowchart TD subgraph ENTRY["接入层(按技术栈选一个)"] E1["Servlet 拦截器<br/>SaInterceptor"] E2["全局过滤器<br/>SaServletFilter (MVC)"] E3["响应式过滤器<br/>SaReactorFilter (WebFlux)"] E4["Solon / JFinal 插件"] end subgraph CORE["核心层 sa-token-core(零依赖)"] C1["StpUtil 门面"] C2["StpLogic 会话逻辑<br/>(按 loginType 分实例)"] C3["SaTokenContext 上下文抽象"] C4["SaStrategy 策略"] C5["SaManager 全局管理器"] C1 --> C2 --> C5 C3 --> C2 C4 --> C2 end subgraph PERSIST["持久层 SaTokenDao"] P1["默认内存实现<br/>SaTokenDaoDefaultImpl(单机)"] P2["Redis 系列插件<br/>sa-token-redis-jackson 等"] P3["Redisson / Caffeine / Hutool TimedCache"] end subgraph EXT["扩展/插件层(SPI 加载,v1.41 起)"] X1["sa-token-sso"] X2["sa-token-oauth2"] X3["sa-token-jwt / apikey / sign"] X4["sa-token-dubbo / dubbo3 / grpc"] X5["sa-token-quick-login / spring-el"] end ENTRY --> C1 C2 --> PERSIST C5 --> EXT EXT --> C2 classDef core fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px class C1,C2,C3,C4,C5 core

关键设计取舍:

  1. 门面静态化:StpUtil 全静态方法,避免业务层到处注入 Bean,代价是必须依赖上下文(SaTokenContext)——这也解释了为什么异步线程里必须准备 Mock 上下文。
  2. 一账号体系一 StpLogic:多套账号(User/Admin)通过不同 LoginType 隔离,配置也可单独覆盖(v1.35 起支持为 StpLogic 单独配置 SaTokenConfig)。
  3. 持久层单点收口:所有落库都走 SaTokenDao,所以「换存储 = 换 Bean」,业务零改动。
  4. SPI 插件体系(v1.41):插件不再靠 @Autowired 硬绑,而是按 SPI 注册,解决了「引入插件就启动失败」类问题。

2.3 登录认证运行原理

sequenceDiagram autonumber participant U as 客户端 participant C as Controller participant S as StpLogic participant D as SaTokenDao_Redis[Redis 存储] U->>C: POST /login {username, password} C->>C: 校验账号密码 + 组装用户模型 C->>S: StpUtil.login(10001, new SaLoginParameter()...) S->>S: 生成 token(token-style 决定算法) S->>D: 写入 token→loginId 映射 S->>D: 创建 Account-Session(账号级) S->>D: 创建 Token-Session(令牌级) S-->>C: tokenValue(默认同时写 Cookie / 响应头) C-->>U: 返回 token(前后端分离场景仅回 token) U->>C: GET /user/list Authorization: <token> C->>S: StpUtil.checkLogin() S->>D: 读 token→loginId S->>D: 校验 active-timeout(最近活跃时间) S-->>C: 登录有效,可继续执行业务

要点(均已查证):

  • Token 生成:默认 UUID;tik、random-32/64/128 等风格可配;v1.35 起引入「循环生成保证唯一」算法。
  • Token 读取优先级:request 参数 > body > header > cookie(v1.4.0 更新日志明确)。
  • 会话有效期双轨:timeout(Token 有效期,可 -1 永不过期)+ active-timeout(最低活跃频率,超时则冻结而非删除,v1.35 从「临时有效期」重命名而来)。
  • 自动续签:autoRenew 开关 + 两种过期策略组合。
  • 未登录异常分场景:NotLoginException 有 5+ 种场景值(未提供 token / token 无效 / 已过期 / 被顶下线 / 被踢下线,v1.5.1 起细化,v1.35 追加 -6/-7)。
  • 重复登录策略:v1.45 新增,is-concurrent=false 时可选「踢人下线」或「拦截本次登录」。

2.4 权限校验运行原理

权限/角色校验的本质是「把 loginId 交给你实现的查询接口,再拿返回值做匹配」:

flowchart LR A["请求进入<br/>@SaCheckPermission('user:add')"] --> B["注解拦截器/AOP<br/>取 loginId"] B --> C{"SaTokenDao 命中缓存?"} C -- 是 --> D["返回权限列表"] C -- 否 --> E["调用 StpInterface 实现<br/>getPermissionList(loginId, loginType)"] E --> F["业务查库/查缓存<br/>(若依 Plus 走 Dubbo RPC)"] F --> D D --> G["匹配权限码<br/>支持 * 通配符"] G -- 命中 --> H["放行"] G -- 未命中 --> I["抛 NotPermissionException"]
校验入口 写法 适用
注解鉴权 @SaCheckPermission("system:user:add")、@SaCheckRole("admin")、@SaCheckOr(...) 方法/类粒度,最常用
代码鉴权 StpUtil.checkPermission(...) / hasPermission(...) 复杂分支逻辑
路由拦截鉴权 SaRouter.match("/user/**", r -> StpUtil.checkPermission("user")) 按模块批量授权,适配 RESTful
SpEL 表达式 @SaCheckPermission + sa-token-spring-el 插件 动态参数参与鉴权(v1.40)

重要机制:hasXxx 系列自 v1.38 起只返回布尔、不再抛异常;checkXxx 才抛异常 —— 二者语义分离,是迁移时最易踩的点。

2.5 Session 三模型与持久层

模型 绑定对象 生命周期 典型用途 API
Account-Session 账号(loginId) 与账号登录态一致,多端共享 存用户档案、权限集合(多端一致) StpUtil.getSession()、getSessionByLoginId(id)
Token-Session 单个 Token 与该 Token 同生共死 存本次登录的设备/IP/客户端信息(多端隔离) StpUtil.getTokenSession()、getTokenSessionByToken(t)
Custom-Session 任意业务 key 由业务控制 为任意实体(如商品、工单)挂缓存 SaSessionCustomUtil.getSessionById("goods-10001")

持久层行为:

  • 默认 SaTokenDaoDefaultImpl 用内存 Map + 定时清理脚本,只能单机;多实例必须换 Redis 实现。
  • 键名以 tokenName(默认 satoken)为前缀,按用途分域存储「token→loginId 映射 / 各 Session / 最近活跃时间」,因此多服务共用同一 Redis 时务必约定一致的 token-name,否则鉴权互不可见(这是若依多租户/多服务部署的高频事故点)。
  • v1.41 起序列化与存储解耦:sa-token-redis-jackson、-fastjson2、-snack4、-jdk-serializer 等插件负责序列化;存实体类时 Redis 里出现 无法反序列化的类型 报错,需注册类型白名单(官方 Session 章节有明确提示)。

2.6 多账号体系与 LoginType 隔离

flowchart LR subgraph T1["loginType = 'login'(StpUtil)"] A1["后台管理员体系"] A2["权限码:system:*"] end subgraph T2["loginType = 'user'(StpUserUtil)"] B1["C 端会员体系"] B2["权限码:member:*"] end subgraph T3["loginType = 自定义(new StpLogic('app'))"] C1["APP / 小程序专属体系"] end A1 -.->|隔离| X["同一 Redis,不同 key 域"] B1 -.->|隔离| X C1 -.->|隔离| X

规则:不同 loginType 的会话、Token、Session 互不可见(v1.28 单测覆盖「多账号模式数据不互通」);运行时不可更改 LoginType(官方文档明确警告)。这是「一个系统多套账号体系(如 User 表 + Admin 表)」的标准解法。

2.7 微服务场景的三层鉴权

层 问题 Sa-Token 方案
入口层(网关) 每个微服务都写鉴权代码、重复校验 网关注册 SaServletFilter(MVC)或 SaReactorFilter(WebFlux),SaRouter.match("/**").notMatch(白名单).check(() -> StpUtil.checkLogin())
内部调用层 内网接口裸奔、被绕过网关直连 Same-Token(原 Id-Token):服务间调用携带一次性/短期内部令牌,由 SaSameUtil 校验
RPC 链路层 登录态在 Dubbo/gRPC 调用中丢失 sa-token-dubbo / sa-token-dubbo3 / sa-token-grpc 插件把 token 放进 RPC 隐式参数透传

2.8 可扩展点

扩展点 能改什么 典型用途
SaTokenDao 替换 存储介质 Redis/Redisson、多级缓存、分库分表
SaStrategy 重写 token 生成、权限匹配、会话创建等算法 定制 Token 规则、对接外部权限引擎
SaTokenListener 登录/注销/踢人事件钩子 审计日志、在线用户统计、风控埋点
StpInterface 实现 权限/角色数据源 接数据库、接缓存、接 RPC(若依 Plus 正是这一层)
SaTokenContext 自定义 上下文读写策略 异步/非 Web 场景、跨线程传递
SPI 插件 新增协议与集成 OAuth2、SSO、API Key、签名校验

3 使用指南

3.1 依赖选型

运行环境 Starter 坐标 版本 备注
Spring Boot 2.x cn.dev33:sa-token-spring-boot-starter 1.45.0 JDK 8 可用
Spring Boot 3.x cn.dev33:sa-token-spring-boot3-starter 1.45.0 JDK 17
Spring Boot 4.x cn.dev33:sa-token-spring-boot4-starter 1.45.0 v1.45 新增
WebFlux / Reactor cn.dev33:sa-token-reactor-spring-boot-starter(SB4 对应 ...-boot4-starter) 1.45.0 网关/响应式栈
Solon cn.dev33:sa-token-solon-plugin 1.45.0 非 Spring 容器
Redis 存储 cn.dev33:sa-token-redis-jackson(或 -fastjson2/-snack4) 1.45.0 需同时引 spring-boot-starter-data-redis
Redisson cn.dev33:sa-token-redisson-jackson 1.45.0 若依 Plus 用同类方案
JWT 集成 cn.dev33:sa-token-jwt 1.45.0 三种模式(简单/无状态/混合)
BOM 对齐 cn.dev33:sa-token-bom 1.45.0 多模块项目建议引入

统一版本号可用 sa-token-dependencies / sa-token-bom;v1.45 还重构了 sa-token-dependencies 的模块依赖关系(更新日志)。

3.2 最小可运行接入

① 依赖

<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-spring-boot3-starter</artifactId>
    <version>1.45.0</version>
</dependency>
<!-- 分布式会话(生产必备) -->
<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-redis-jackson</artifactId>
    <version>1.45.0</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>

② 配置(application.yml)

sa-token:
  # token 名称(同时作为 header / cookie 名)
  # token-name: Authorization
  token-name: satoken
  # 有效期,单位秒;-1 代表永不过期
  timeout: 2592000
  # 最低活跃频率,单位秒;超过该时长无操作则冻结;-1 不限制(不检测)
  active-timeout: -1
  # 是否允许同一账号并发登录
  is-concurrent: true
  # 多端登录时是否共用一个 token
  is-share: false
  # token 风格:uuid / simple-uuid / random-32 / random-64 / random-128 / tik
  token-style: uuid
  # 是否输出操作日志
  is-log: false

③ 注册拦截器(Servlet/MVC)

@Configuration
public class SaTokenConfigure implements WebMvcConfigurer {

    // 注册 Sa-Token 拦截器,打开注解鉴权能力,并统一做登录校验
    // 注意:注解鉴权依赖此拦截器(或 AOP 模块),漏注册会导致 @SaCheckPermission 静默失效
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new SaInterceptor(handle -> StpUtil.checkLogin()))
                .addPathPatterns("/**")
                .excludePathPatterns("/user/doLogin", "/error", "/favicon.ico");
    }
}

④ 登录 / 注销 / 鉴权

@RestController
@RequestMapping("/user")
public class UserController {

    // 会话登录:唯一必填参数是「登录人的账号 id」
    @PostMapping("/doLogin")
    public SaResult doLogin(String username, String password) {
        if (!"admin".equals(username) || !"123456".equals(password)) {
            return SaResult.error("账号或密码错误");
        }
        // 记住我 7 天 + 指定设备类型(同端互斥场景需要)
        StpUtil.login(10001, new SaLoginParameter()
                .setTimeout(60 * 60 * 24 * 7)
                .setDeviceType("PC"));
        // 返回 token 信息(前后端分离时前端存到 header)
        return SaResult.data(StpUtil.getTokenInfo());
    }

    // 权限校验:具备 user:add 才能进入
    @SaCheckPermission("user:add")
    @PostMapping("/add")
    public SaResult add() {
        return SaResult.ok("新增成功");
    }

    // 仅需登录,不需权限
    @GetMapping("/info")
    public SaResult info() {
        return SaResult.data(StpUtil.getLoginIdAsLong());
    }

    // 注销当前会话
    @PostMapping("/doLogout")
    public SaResult doLogout() {
        StpUtil.logout();
        return SaResult.ok();
    }
}

⑤ 全局异常处理(网关/服务层都要有)

@RestControllerAdvice
public class SaTokenExceptionHandler {

    // 未登录:401
    @ExceptionHandler(NotLoginException.class)
    public SaResult handleNotLogin(NotLoginException e) {
        return SaResult.error("未登录或登录已失效:" + e.getType()).setCode(401);
    }

    // 无权限:403(v1.28 起用 getPermission(),不再是 getCode())
    @ExceptionHandler(NotPermissionException.class)
    public SaResult handleNotPermission(NotPermissionException e) {
        return SaResult.error("缺少权限:" + e.getPermission()).setCode(403);
    }

    // 无角色:403
    @ExceptionHandler(NotRoleException.class)
    public SaResult handleNotRole(NotRoleException e) {
        return SaResult.error("缺少角色:" + e.getRole()).setCode(403);
    }
}

⑥ 权限数据源(必须自己实现一个)

@Component
public class StpInterfaceImpl implements StpInterface {

    // 返回该账号拥有的权限码集合(登录后框架会缓存,不必每次查库)
    @Override
    public List<String> getPermissionList(Object loginId, String loginType) {
        return List.of("user:add", "user:list", "user:*:export"); // 支持 * 通配
    }

    // 返回该账号拥有的角色标识集合
    @Override
    public List<String> getRoleList(Object loginId, String loginType) {
        return List.of("admin");
    }
}

3.3 鉴权风格x3

风格 代码 优点 风险
注解 @SaCheckPermission("user:add") 与业务代码同处,【可读性】最好;支持类级、orRole、SaMode.AND/OR 忘注册拦截器/AOP 会静默不生效(最大坑)
路由拦截 SaRouter.match("/user/**", r -> StpUtil.checkPermission("user")) 集中式、可批量;适合模块级粗粒度 路径匹配写错会漏放或误拦(v1.36/v1.37 曾修复匹配绕过问题)
代码块 if (!StpUtil.hasPermission("x")) throw ... 完全自由,可做复杂分支 分散、易漏;规范靠人守

推荐组合:拦截器只做 checkLogin(统一登录门槛)→ 【业务方法】用【注解】做【细粒度权限】 → 【少数动态逻辑】用【代码块】。

3.4 集成 Redis 与序列化

spring:
  data:
    redis:
      host: 127.0.0.1
      port: 6379
      database: 0
      password: ''

要点:

  • 引入 sa-token-redis-jackson 后框架会自动替换 SaTokenDao 为 Redis 实现(无需写代码)。
  • Spring Boot 3.x 需注意:Redis 连接池依赖(commons-pool2)与会话序列化兼容,官方文档与 QA 章节专门列出「SpringBoot3.x 版本配置 Redis 注意事项」。
  • 若权限缓存要与业务缓存物理隔离(避免大 key 与淘汰互相影响),可用 sa-token-alone-redis 插件指定独立 Redis。
  • 存自定义实体到 Session,必须注册 JSON 类型白名单,否则读回报「无法反序列化的类型」。

3.5 关键操作速查

需求 API 备注
判断是否登录 StpUtil.isLogin() 不抛异常
强制登录校验 StpUtil.checkLogin() 抛 NotLoginException
踢人下线(按账号) StpUtil.kickout(10077) 让该账号全部会话失效
顶人下线(按 Token) StpUtil.replaced(token) / 登录时 is-concurrent=false 单端替换
封禁账号 StpUtil.disable(10001, 600) / 分类封禁 / 阶梯封禁 单位秒
会话查询 StpUtil.searchTokenValue(...)、getTerminalListByLoginId(id) v1.41 新增按账号查终端列表
二级认证(敏感操作再验证) StpUtil.checkSafe()、openSafe(...) 密码/短信二次确认
临时身份切换 StpUtil.switchTo(10044, () -> {...}) 代码段内切换,出段自动还原
模拟他人 StpUtil.getSessionByLoginId(id) 等 运营后台常用
Token 续期 StpUtil.renewTimeout(100) 指定新的有效期
读取扩展参数 StpUtil.getExtra("key") 登录时 setExtra 写入(若依 Plus 靠它存 userId/clientid)
自定义权限规则 SpringEl 插件 @SaCheckPermission("...") + SpEL 需引 sa-token-spring-el

3.6 网关鉴权(Reactive / MVC 两版)

Spring Cloud Gateway(WebFlux/Reactive 栈):

@Configuration
public class SaGatewayConfig {

    @Bean
    public SaReactorFilter getSaReactorFilter() {
        return new SaReactorFilter()
                .addInclude("/**")
                .addExclude("/favicon.ico", "/actuator/**")
                .setAuth(obj -> SaRouter.match("/**")
                        .notMatch("/auth/login", "/auth/code")
                        .check(r -> StpUtil.checkLogin()))
                .setError(e -> SaResult.error("认证失败:" + e.getMessage()).setCode(401));
    }
}

Spring Cloud Gateway Server WebMVC(Servlet 栈,v1.45 生态下越来越多项目采用):

@Configuration
public class AuthFilter {

    @Bean
    public SaServletFilter authSaServletFilter() {
        return new SaServletFilter()
                .addInclude("/**")
                .addExclude("/favicon.ico", "/actuator/**")
                .setAuth(obj -> SaRouter.match("/**")
                        .notMatch("/auth/login")
                        .check(() -> StpUtil.checkLogin()))
                .setError(e -> SaResult.error("认证失败").setCode(401));
    }
}

两版的差别只在过滤器基类(SaReactorFilter vs SaServletFilter),鉴权 DSL 完全一致。这也是本次取证发现的一个关键事实:RuoYi-Cloud-Plus 6.X 已删除 WebFlux 网关版本、统一改为 MVC 网关,因此其 AuthFilter 使用的是 SaServletFilter(详见 5.4)。

3.7 安装部署(Windows / Linux)

Sa-Token 是纯 JAR 依赖,无独立进程、无中间件安装,所谓「安装部署」实为「引入依赖 + 准备 JDK 与 Redis」。

环节 Windows(10/11 + PowerShell) Linux(Rocky/Ubuntu + Bash)
JDK 需 JDK 17(SB3/SB4 栈)或 JDK 8(SB2 栈) 同左;java -version 核验
Maven 依赖 IDEA 右侧 Maven 面板 Reload,或 mvn -U clean package -DskipTests mvn -U clean package -DskipTests
Redis(分布式会话) Docker:docker run -d --name redis -p 6379:6379 redis:7;或 WSL2 安装 sudo dnf install redis -y && sudo systemctl enable --now redis
启动应用 java -jar .\ruoyi-auth.jar --spring.profiles.active=prod nohup java -jar ./ruoyi-auth.jar --spring.profiles.active=prod > app.log 2>&1 &
验证登录 curl -X POST http://localhost:8080/auth/login -H "Content-Type: application/json" -d '{"username":"admin","password":"admin123"}' 同左(curl 原生可用)
验证鉴权 不带 Token 访问受保护接口,应返回 401;带 Token 应返回 200 同左
容器化 建议基础镜像 eclipse-temurin:17-jre,ENTRYPOINT ["java","-jar","/app/app.jar"] 同左

Windows 专属提醒:PowerShell 下 curl 是 Invoke-WebRequest 的别名,POST JSON 容易因引号转义失败;建议用 curl.exe 显式调用或改用 Invoke-RestMethod -Method Post -Body ($obj | ConvertTo-Json)。

3.8 高频踩坑清单

现象 根因 处置
@SaCheckPermission 完全不生效、任何用户都能进 未注册 SaInterceptor,注解鉴权无入口 补 WebMvcConfigurer#addInterceptors(或引 sa-token-spring-aop)
多实例部署后「登录成功但另一个节点 401」 默认 SaTokenDao 是【内存实现】;或各服务 token-name 不一致 接 Redis 且统一 token-name
引入 Redis 插件后启动失败 / 反序列化报错 【序列化插件】与【实体类】不匹配;未注册 JSON 类型白名单;SB3 缺【连接池依赖】 统一用 -jackson 系插件、注册白名单、补 commons-pool2
异步线程/定时任务里调用 StpUtil 报「上下文尚未初始化」 无请求上下文 用 Mock 上下文(v1.42+)或显式传 token 调用 ...ByToken 变体
与 Spring Security 同时引入,401/403 行为混乱 两套【过滤器/异常处理】互相覆盖 迁移期显式 exclude 或先摘除一边
SSO 回调被 @ 或通配符绕过 【历史漏洞】(v1.38 已修:禁止 allow-url 中 * 出现在中间、禁止 @) 升级到 ≥1.38,并规范 allow-url 配置
网关放行了不该放行的路径 【路由匹配/白名单写错】(v1.36/v1.37 曾修复匹配绕过) 升级版本 + 白名单最小化 + 加「未匹配默认拒绝」用例

4 深度对比:Sa-Token vs Spring Security

4.1 设计哲学对比

维度 Sa-Token Spring Security
出身 个人主导的国产开源项目(Dromara) Spring 官方项目(spring-projects)
第一性目标 「让鉴权简单优雅」,API 最少化 「提供声明式安全访问控制的完整解决方案」,能力最全 + 可组合
抽象粒度 面向会话/Token(StpLogic 为核心) 面向过滤器链 + 认证/授权对象模型(Authentication/AuthorizationManager)
配置方式 application.yml 少量键 + 静态 API Java DSL(HttpSecurity)+ 大量可插拔组件
默认假设 前后端分离、Token 为主、Redis 存会话 Servlet 会话/Cookie 为主,Token 需显式配置(OAuth2 Resource Server / 自定义过滤器)
扩展方式 重写 SaStrategy / 换 SaTokenDao / 实现 StpInterface / SPI 插件 实现 UserDetailsService、AuthenticationProvider、AccessDecisionVoter/AuthorizationManager、自定义 Filter
生态归属 国产脚手架生态(若依系、Solon) Spring 全家桶(Boot 自动配置、OAuth2、Data、Security Test)
文档 中文单页文档 + 60+ Demo 英文 Reference(分 Servlet/Reactive 两套)+ Javadoc

4.2 架构对比

Sa-Token 的处理链(短链路)

flowchart LR R["HTTP 请求"] --> F["SaInterceptor / SaServletFilter"] F --> L["StpUtil.checkLogin()"] L --> G["StpLogic"] G --> D["SaTokenDao(Redis)"] G --> P["StpInterface(权限查询)"] D --> OK["放行 → Controller"] P --> OK G --> ERR["NotLoginException / NotPermissionException"]

Spring Security 的处理链(长链路,Servlet 栈简化版)

flowchart LR R["HTTP 请求"] --> FP["FilterChainProxy"] FP --> F1["SecurityContextHolderFilter"] F1 --> F2["UsernamePasswordAuthenticationFilter / BearerTokenAuthenticationFilter"] F2 --> F3["AuthorizationFilter"] F3 --> AM["AuthorizationManager<br/>(RequestMatcher + 决策)"] F3 -->|通过| CT["DispatcherServlet → Controller"] AM -->|拒绝| AH["AuthenticationEntryPoint / AccessDeniedHandler"] F3 --> MS["方法级:@PreAuthorize → AuthorizationManagerBeforeMethodInvocation"] F2 --> AMgr["AuthenticationManager → AuthenticationProvider → UserDetailsService"]

结构差异的三条主线:

  1. 链长度:Sa-Token 默认 1 个拦截器 + 1 次 DAO 读取即可完成「登录校验」;Spring Security 走完整过滤器链(默认 10+ 个 Filter),每个 Filter 各司其职。
  2. 状态承载:Sa-Token 的登录态在 SaTokenDao(外部存储);Spring Security 的登录态在 SecurityContext(线程本地)+ Session/Token。前者天然跨实例,后者需 Spring Session 或改为无状态 JWT。
  3. 授权决策位置:Sa-Token 在方法/路由层用「权限码字符串」决策;Spring Security 在请求匹配器(URL)与方法调用(@PreAuthorize SpEL)两层决策,且可用 AuthorizationManager 自定义任意逻辑。

4.3 功能矩阵(逐项)

# 能力项 Sa-Token Spring Security 差异结论
1 表单登录 自写 Controller + StpUtil.login 内置 formLogin() Sa 更自由,SS 更省事
2 Token 会话 开箱即用(token-name、多端、互斥) 需自研或引 OAuth2 Resource Server Sa 胜
3 JWT sa-token-jwt 三模式 JwtDecoder + oauth2ResourceServer(jwt) 平手
4 分布式会话 换 SaTokenDao 即完成 需 Spring Session + Redis Sa 胜(成本更低)
5 多端登录/同端互斥 内置 deviceType 维度 需自研 Sa 胜
6 踢人下线/顶人下线 kickout/replaced 一行 需自研(会话注册表 + 事件) Sa 胜
7 账号封禁(分类/阶梯) 内置 需自研 Sa 胜
8 二级认证(敏感操作再验证) 内置 checkSafe 无(需自研,常见做法是 @PreAuthorize + 自定义) Sa 胜
9 权限码校验 @SaCheckPermission(含 orRole、SaMode) @PreAuthorize("hasAuthority('x')") 平手(SS 的 SpEL 更强)
10 角色校验 @SaCheckRole hasRole('x') 平手
11 域对象 ACL ❌ 无 ✅ Acl + PermissionEvaluator SS 胜
12 表达式/动态鉴权 SpEL 插件(v1.40) 原生 SpEL,支持任意 Bean 调用 SS 胜
13 URL 级授权 SaRouter 匹配 requestMatchers(...).hasAuthority(...) 平手(SS 更标准化)
14 CSRF 防护 无内置(文档给「如何防 CSRF」QA) 内置 csrf(),默认开启 SS 胜
15 安全响应头 全局过滤器可手写 内置 headers()(HSTS/X-Frame-Options 等) SS 胜
16 会话固定攻击防护 无(Token 重生即可,不涉及) 内置 sessionFixation() SS 场景专属
17 密码编码 仅提供加密工具(BCrypt 已 @Deprecated) PasswordEncoder(BCrypt/Delegating/Argon2) SS 胜
18 SSO 单点登录 内置三模式 需 Spring Authorization Server / CAS Sa 胜
19 OAuth2 授权服务器 内置(四模式 + OIDC) 需 Spring Authorization Server(独立项目) Sa 更省事,SS 更规范
20 微服务网关鉴权 双栈过滤器一行接入 需 spring-security-oauth2-resource-server 或自研 Sa 胜
21 RPC 链鉴权 Same-Token + Dubbo/gRPC 插件 无(需 Spring Security 上下文传播 + 自研) Sa 胜
22 多账号体系隔离 LoginType 原生 多 SecurityFilterChain + 多 AuthenticationManager Sa 胜(更轻)
23 方法级安全 注解 + AOP 注解 + AOP + @EnableMethodSecurity 平手
24 测试支持 需自建 Mock 上下文 @WithMockUser、SecurityMockMvc SS 胜
25 异步/响应式 Mock 上下文 + Reactor 支持 ReactiveSecurityContextHolder + 上下文传播 平手
26 官方生态集成 低(不产出 Authentication) 高(Spring Boot 自动配置、Data 审计等) SS 胜
27 中文文档/示例 ✅ 强 英文为主 Sa 胜
28 学习曲线 1~2 天上手 1~3 周理解模型 Sa 胜

4.4 代码级对比(同一需求两种写法)

例 1:登录(颁发凭证)

Sa-Token

StpUtil.login(10001);                     // 1 行:生成 token + 建会话 + 写 Cookie/头
return SaResult.data(StpUtil.getTokenInfo());

Spring Security(表单登录 + 自定义成功响应)

@Bean
SecurityFilterChain chain(HttpSecurity http) throws Exception {
    http.authorizeHttpRequests(a -> a.anyRequest().authenticated())
        .formLogin(f -> f.loginPage("/login")
            .successHandler((req, res, auth) -> {          // 还要自己写成功响应
                res.setContentType("application/json");
                res.getWriter().write("{\"user\":\"" + auth.getName() + "\"}");
            }))
        .csrf(AbstractHttpConfigurer::disable);
    return http.build();
}

// 另需:UserDetailsService 实现 + PasswordEncoder Bean + UserDetails 模型

例 2:接口鉴权

Sa-Token

@SaCheckPermission("system:user:add")
@PostMapping("/add")
public R<Void> add(@RequestBody SysUser user) { ... }

Spring Security

@PreAuthorize("hasAuthority('system:user:add')")   // 需 @EnableMethodSecurity
@PostMapping("/add")
public R<Void> add(@RequestBody SysUser user) { ... }

这一项二者几乎等价;差异在权限来源:Sa-Token 由 StpInterface 提供,Spring Security 由 UserDetails.getAuthorities() 提供。

例 3:取当前登录用户

Sa-Token

Long userId = StpUtil.getLoginIdAsLong();
SysUser u = (SysUser) StpUtil.getSession().get("user");     // 会话里直接取,且多端共享

Spring Security

Authentication auth = SecurityContextHolder.getContext().getAuthentication();
String username = auth.getName();
// 业务实体通常要再查库或从 UserDetails 扩展字段取;跨线程需显式传播上下文

例 4:踢人下线 / 在线用户管理

Sa-Token

StpUtil.kickout(10077);                                   // 一行
List<String> tokens = StpUtil.searchTokenValue("", 0, 100, true); // 会话检索

Spring Security

// 需自建方案:SessionRegistry + HttpSessionEventPublisher + ConcurrentSessionFilter
@Bean
SessionRegistry sessionRegistry() { return new SessionRegistryImpl(); }

// 踢人:找到该用户的 SessionInformation → expireNow()

例 5:多端登录互斥(手机 A / 手机 B 互斥,PC 可并存)

Sa-Token

StpUtil.login(userId, new SaLoginParameter().setDeviceType("PHONE"));  // 框架按 device 维度互斥

Spring Security:无对应内置能力,需自研「设备维度会话表 + 登录时清理同设备会话」。

例 6:对外开放 OAuth2 授权

Sa-Token:引 sa-token-oauth2,配置 SaOAuth2ServerConfig + SaClientModel,内置 /oauth2/authorize、/oauth2/token 端点。

Spring Security:引独立项目 spring-authorization-server,配置 RegisteredClientRepository、AuthorizationServerSettings、OAuth2AuthorizationService(或用 Keycloak 等外部 IdP)。

行数量级对比(估算,仅表述工作量差异,非精确统计)

需求 Sa-Token 代码量 Spring Security 代码量
完成一次 Token 登录 1~5 行 30~80 行(含 UserDetailsService/Encoder/Filter 配置)
接口权限校验 1 行注解 1 行注解 + 十余行全局配置
踢人下线 1 行 50~100 行(SessionRegistry 体系)
多端互斥 参数一行 自研,100+ 行
OAuth2 授权服务器 配置类 + 客户端模型 独立依赖 + 3~5 个 Bean + 表结构

4.5 性能与开销

说明:两者均无官方公开 benchmark;以下为基于架构的定性判断,标注「定性」以示口径。

指标 Sa-Token Spring Security 说明
每请求过滤器/拦截器数量 1(拦截器或过滤器) 10+(FilterChainProxy 内部链) 定性
每次鉴权的存储访问 1~2 次 SaTokenDao 读(token→loginId、活跃时间) 0 次(Session 在内存)或 1 次(Spring Session/Redis) 定性:Sa-Token 把成本压在 Redis,SS 压在内存
水平扩展性 天然(外部存储) 需 Spring Session/无状态 JWT —
内存占用 低(无 SecurityContext/会话对象图) 中(SecurityContext + UserDetails + Filter 实例) 定性
大并发瓶颈点 Redis QPS / 网络往返 JVM 过滤器链 CPU + 会话内存 定性
可观测性埋点 SaTokenListener ApplicationListener<AuthenticationSuccessEvent> 等 平手

结论(不含夸张):单机吞吐上二者差距通常不是业务瓶颈(真正的瓶颈是 DB/Redis/GC);Sa-Token 的优势是「扩展性成本」低,Spring Security 的优势是「单机少一次外部 IO」。

4.6 生态、治理与安全记录

维度 Sa-Token Spring Security
维护主体 个人主导 + 社区(Dromara) Spring 官方团队(多人轮值)
版本发布 年均 1~5 个 minor,频繁不向下兼容 严格 semver + 长期支持线(6.x),破坏性变更集中在 major
安全公告 通过版本日志 + Gitee Issue(如 v1.37 修路由拦截绕过、v1.38 修 SSO @ 绕过、v1.40 修分号 path 校验) 官方 CVE + Security Advisories 页面,有编号与 CVSS
等保/合规友好度 需自行整理证据 审计材料、社区案例更充分
生态项目 若依系、Snowy、ContiNew、Solon 生态 Spring Boot / Cloud / Data / Authorization Server 全套
国际化 弱(中文为主) 强

治理风险提示(需要人判断的部分):Sa-Token 曾出现路由匹配绕过类漏洞(v1.36/v1.37 连续修复),说明「自研匹配算法」是此类轻量框架的固有风险点;实践上应(a)锁定 ≥1.37 版本,(b)对白名单做最小化并有单测覆盖,(c)网关层再叠一层显式拒绝策略。

4.7 量化选型打分

口径说明:10 分制,主观打分(依据 = 前文事实与代码量对比);权重按两种典型场景分别设定,权重变了结论会变,这正是下表的意义。

场景 A:企业内网业务系统 / 微服务脚手架二次开发(权重偏「上手 + 微服务 + 国产生态」)

维度 权重 Sa-Token Spring Security 加权差
上手与接入成本 15 9.0 5.0 +60
登录/会话能力 15 9.0 7.0 +30
授权粒度与表达力 15 6.5 9.5 -45
微服务/网关/RPC 10 9.0 6.0 +30
SSO / OAuth2 10 7.0 9.0 -20
生态与官方背书 10 6.0 9.5 -35
中文文档与示例 5 9.5 6.0 +17.5
安全治理与合规 10 6.5 9.0 -25
性能与资源开销 5 9.0 6.5 +12.5
与若依类脚手架适配 5 9.0 4.0 +25
加权总分(满分 100) 100 79.0 74.0 +5.0

场景 B:金融/强合规、对外开放授权、复杂实例级授权(权重偏「安全 + 授权 + 生态」)

维度 权重 Sa-Token Spring Security 加权差
上手与接入成本 8 9.0 5.0 +32
登录/会话能力 12 9.0 7.0 +24
授权粒度与表达力 18 6.5 9.5 -54
微服务/网关/RPC 8 9.0 6.0 +24
SSO / OAuth2 8 7.0 9.0 -16
生态与官方背书 14 6.0 9.5 -49
中文文档与示例 4 9.5 6.0 +14
安全治理与合规 20 6.5 9.0 -50
性能与资源开销 4 9.0 6.5 +10
与若依类脚手架适配 4 9.0 4.0 +20
加权总分(满分 100) 100 74.9 79.4 -4.5

读法:同一组事实、不同权重,结论从「Sa-Token +5.0」变为「Spring Security +4.5」。所以「谁更好」不成立,只有「在你的权重下谁更好」。

4.8 选型结论与迁移路径

选型建议(按实际约束)

你的约束 建议 理由
使用若依系脚手架(Vue-Plus / Cloud-Plus) Sa-Token 已是默认技术栈,逆势替换等于重写鉴权层
单体/微服务后台、20 人天内要上线 Sa-Token 接入 1 天,Spring Security 需 1~2 周理解模型
需要 SSO / 多端 / 踢人 / 封禁等运营能力 Sa-Token 内置能力,Spring Security 全要自研
需要实例级 ACL、ABAC 策略、字段级数据权限深度治理 Spring Security(+ Casbin/OPA) Sa-Token 只有权限码字符串
对外开放 OAuth2、要被第三方 IdP 接入 Spring Security + Spring Authorization Server 或 Keycloak 规范完备度、互操作测试更成熟
金融/等保三级以上、需 CVE 编号可追溯 Spring Security 官方安全治理体系
团队无 Java 安全经验、以中文文档为主 Sa-Token 文档与社区支持成本最低

从 Spring Security 迁移到 Sa-Token(若依原版/自研项目改造)

flowchart TD S1["1 盘点现有鉴权面<br/>登录/权限注解/URL 规则/会话存储"] --> S2["2 定义权限码规范<br/>module:entity:action"] S2 --> S3["3 实现 StpInterface<br/>权限与角色查询(接原 UserDetails 数据源)"] S3 --> S4["4 改写登录入口<br/>AuthenticationManager → StpUtil.login"] S4 --> S5["5 替换注解<br/>@PreAuthorize → @SaCheckPermission"] S5 --> S6["6 替换 URL 规则<br/>requestMatchers → SaRouter.match"] S6 --> S7["7 摘除 Spring Security 过滤器链<br/>(关键:否则双重鉴权)"] S7 --> S8["8 会话落 Redis + 统一 token-name"] S8 --> S9["9 回归验证:401/403 语义、多端、踢人、白名单"]

迁移红线:

  1. 必须显式移除 spring-boot-starter-security 及 SecurityFilterChain,否则 401/403 与 AccessDeniedHandler 会与 Sa-Token 争抢响应。
  2. 权限码语义要一次改对:Spring Security 的 ROLE_ADMIN 前缀体系与 Sa-Token 的裸角色标识不同,需统一映射。
  3. 若原项目用 SecurityContext 传递业务用户对象,必须改为「Session/Token-Extra 存用户」,否则到处都是空指针。

反向迁移(Sa-Token → Spring Security)的触发信号

  • 要做实例级授权(订单/文档/项目维度的 owner 判断);
  • 要被企业统一身份平台(Keycloak/Azure AD)接管;
  • 要通过等保/ISO 27001 审计且要求框架级安全公告留痕;
  • 团队规模扩张到需要标准化安全抽象(而不是静态工具类)。

5 若依中如何使用 Sa-Token

5.1 先澄清:两套「若依云」不是一回事

这是本次调研最重要的一个事实澄清 —— 问题里「RuoYi-Cloud 使用 Sa-Token」的说法,对原版若依云不成立。

项目 仓库 鉴权技术栈(源码实证) 结论
RuoYi-Cloud(原版,yangzongzhuan) yangzongzhuan/RuoYi-Cloud,master = 3.6.8 ruoyi-auth 依赖 ruoyi-common-security;后者 pom 仅依赖 spring-webmvc + ruoyi-api-system + ruoyi-common-redis,没有任何 Spring Security / Sa-Token 依赖。TokenService 用 JwtUtils 生成 JWT + Redis 存 login_tokens:<uuid> → LoginUser,配合 PreAuthorizeAspect / InnerAuthAspect 做方法级与内部调用校验 不用 Sa-Token,也不用 Spring Security(自研 JWT + Redis 令牌体系)。文档站仍把 Spring Security 写在「核心技术」里,属历史叙述/早期版本遗留
RuoYi-Cloud-Plus(Dromara 社区版) dromara/RuoYi-Cloud-Plus,默认分支 6.X(另有 2.X) ruoyi-common-satoken 实现 StpInterface;ruoyi-gateway 用 SaServletFilter;LoginHelper 封装 StpUtil;PlusSaTokenDao 替换持久层 深度使用 Sa-Token,且是其鉴权骨架
RuoYi-Vue(单体)/ RuoYi-Vue-Plus 原版用 Spring Security;Plus 用 Sa-Token — 规律同上:原版不用 Sa-Token,Plus 用

若你手上的项目是原版 RuoYi-Cloud 3.6.8:里面没有 Sa-Token 代码,第 5.2~5.8 讲的是「若依 Plus 怎么用」,第 5.9 给出「在原版里引入 Sa-Token 的改造清单」。

版本细节(已查证):RuoYi-Cloud-Plus 6.1.0 发行说明(2026-11-05)显示「Sa-Token 从 1.45.0 升级至 1.46.0」「删除 Gateway WebFlux 版本,统一使用 MVC Gateway」;仓库 Star 1,327(GitHub 快照),主要活跃阵地为 Gitee。

5.2 RuoYi-Cloud-Plus 的鉴权模块地图

flowchart TD FE["前端 Vue3<br/>v-has-permi 按钮控制"] --> GW["ruoyi-gateway [8080]<br/>AuthFilter(SaServletFilter)"] GW -->|"白名单 security.ignore.whites 放行"| AUTH["ruoyi-auth [9210]<br/>登录/登出/刷新"] AUTH -->|"LoginHelper.login()"| STP["StpUtil"] STP --> DAO["PlusSaTokenDao<br/>Redisson → Redis"] GW -->|"已登录请求转发"| SYS["ruoyi-system [9201]<br/>@SaCheckPermission"] SYS -->|"取不到权限时 RPC"| PERM["PermissionService(Dubbo)"] SYS --> LOGINUSER["Token-Session 中的 LoginUser"] STP --> LOGINUSER subgraph COMMON["ruoyi-common-satoken(公共模块)"] L["LoginHelper<br/>登录/取用户/取扩展字段"] I["SaPermissionImpl<br/>实现 StpInterface"] C["SaToken 配置(Nacos)"] end COMMON --> STP
模块 关键类(源码实证) 职责
ruoyi-gateway AuthFilter、IgnoreWhiteProperties 统一登录校验、客户端 ID 校验、客户端 IP/路径白名单、actuator Basic 认证
ruoyi-auth AuthController → LoginHelper.login(...) 多方式登录(密码/短信/社交/小程序)、下发 Token
ruoyi-common-satoken LoginHelper、SaPermissionImpl、SaTokenConfig 登录封装、权限数据源、全局配置
ruoyi-common-redis PlusSaTokenDao 用 Redisson 替换默认 SaTokenDao,实现分布式会话
ruoyi-system 等业务模块 @SaCheckPermission(...) 接口级权限校验
前端 v-has-permi / v-has-roles 按钮显隐(官方文档明确:界面控制不能替代后端鉴权)

5.3 登录链路:AuthController → LoginHelper → StpUtil

核心代码(LoginHelper,6.X 原文节选)

public static void login(LoginUser loginUser, SaLoginParameter model) {
    model = ObjectUtil.defaultIfNull(model, new SaLoginParameter());
    fillRequestContext(loginUser, model);            // 补 IP、归属地、浏览器、OS、设备类型
    StpUtil.login(loginUser.getLoginId(),
        model.setExtra(USER_KEY, loginUser.getUserId())
             .setExtra(USER_NAME_KEY, loginUser.getUsername())
             .setExtra(DEPT_KEY, loginUser.getDeptId())
             .setExtra(DEPT_NAME_KEY, loginUser.getDeptName())
             .setExtra(DEPT_CATEGORY_KEY, loginUser.getDeptCategory()));
    StpUtil.getTokenSession().set(LOGIN_USER_KEY, loginUser);  // 用户模型放 Token-Session
}

设计解读(三点,均有源码支撑)

  1. loginId 不是纯 userId:6.X 的 LoginUser 引入 LOGIN_ID_SEPARATOR,loginId 形如「用户类型 + 分隔符 + userId」,从而在一个 Sa-Token 实例内支持多用户体系(SaPermissionImpl 里专门有 normalizeLoginId 兼容历史冒号格式)。
  2. 用户模型存 Token-Session,不放 Account-Session:这样多端登录各自持有独立的 LoginUser 快照(含 IP、设备、登录时间),踢掉一端不影响另一端;也解释了为什么 LoginHelper.getLoginUser(token) 能按 token 取用户。
  3. 高频字段走 Extra,完整对象走 Session:getUserId() 读的是 StpUtil.getExtra(USER_KEY)(存在 Token 上,读取不触发 Session 反序列化),比每次都 getTokenSession().get("loginUser") 更轻。

登录后的角色/权限/token 关系

数据 存哪 谁写入 谁读取
token ↔ loginId SaTokenDao(Redis) StpUtil.login 每次请求 checkLogin
LoginUser(含 menuPermission/rolePermission) Token-Session LoginHelper.login LoginHelper.getLoginUser()
userId/deptId/userName… Token Extra LoginHelper.login LoginHelper.getUserId() 等
权限码/角色码集合 由 SaPermissionImpl 提供(框架按需缓存) StpInterface @SaCheckPermission

5.4 网关统一鉴权:AuthFilter

源码(6.X ruoyi-gateway/.../filter/AuthFilter.java,节选)

@Configuration
public class AuthFilter {

    @Bean
    public SaServletFilter authSaServletFilter() {
        return new SaServletFilter()
            .addInclude("/**")
            .addExclude("/favicon.ico", "/actuator", "/actuator/**", "/error")
            .setAuth(obj -> SaRouter.match("/**")
                .notMatch(ignoreWhite.getWhites())          // Nacos: security.ignore.whites
                .check(() -> {
                    HttpServletRequest request = ServletUtils.getRequest();
                    StpUtil.checkLogin();                    // ① 统一登录校验
                    String headerCid = request.getHeader(LoginHelper.CLIENT_KEY);
                    String paramCid  = ServletUtils.getParameter(LoginHelper.CLIENT_KEY);
                    Object extra = StpUtil.getExtra(LoginHelper.CLIENT_KEY);
                    String clientId = extra == null ? null : extra.toString();
                    if (!StringUtils.equalsAny(clientId, headerCid, paramCid)) {   // ② 客户端 ID 与 Token 绑定校验
                        throw NotLoginException.newInstance(StpUtil.getLoginType(),
                            "-100", "客户端ID与Token不匹配", StpUtil.getTokenValue());
                    }
                    validateClientAccessRules(request);       // ③ 客户端级路径/来源 IP 白名单
                }))
            .setError(e -> {
                HttpServletResponse response = ServletUtils.getResponse();
                response.setContentType(SaTokenConsts.CONTENT_TYPE_APPLICATION_JSON);
                if (e instanceof NotLoginException) {
                    return SaResult.error(e.getMessage()).setCode(HttpStatus.UNAUTHORIZED);
                }
                return SaResult.error("认证失败,无法访问系统资源").setCode(HttpStatus.UNAUTHORIZED);
            });
    }
}

白名单配置类(原文)

@Data
@Configuration
@RefreshScope
@ConfigurationProperties(prefix = "security.ignore")
public class IgnoreWhiteProperties {
    /** 放行白名单配置,网关不校验此处的白名单 */
    private List<String> whites = new ArrayList<>();
}

关键取舍与理由

设计 做法 为什么这么做
网关只做登录校验,不做权限校验 网关只 checkLogin();权限码校验下沉到各业务服务 网关无法感知每个接口的权限码(权限随菜单动态变化);避免每次路由改动都要改网关
白名单走 Nacos 动态刷新 @RefreshScope + security.ignore.whites 新增开放接口无需重启网关
客户端 ID 强绑定 Token Extra 里的 clientid 必须等于请求头/参数里的 防止 Token 被复制到别的客户端复用(多端安全)
客户端级细粒度访问控制 clientAccessPath(路径规则)+ clientIpWhitelist(IP 规则)存在 Token Extra 上 让「第三方接入客户端」各自拥有独立可见范围
异常统一转 JSON setError 里 setCode(401) 网关层不能让 NotLoginException 直接冒泡成 HTML 错误页
actuator 单独 Basic 认证 第二个 SaServletFilter 拦 /actuator,用 SaHttpBasicUtil.check(user:pass) 暴露监控端点的同时不破坏主干鉴权

版本差异(已查证):6.X 用 SaServletFilter(MVC 网关,jakarta.servlet);官方发行说明「删除 Gateway WebFlux 版本,统一使用 MVC Gateway」。若你用的是 5.X/2.X 分支或自行搭 WebFlux 网关,则应换成 SaReactorFilter,鉴权 DSL 不变。

5.5 权限数据源:SaPermissionImpl 实现 StpInterface

源码(6.X 原文节选,逻辑已简化注释)

public class SaPermissionImpl implements StpInterface {

    @Override
    public List<String> getPermissionList(Object loginId, String loginType) {
        return resolvePermissionList(loginId, LoginUser::getMenuPermission,
                                     PermissionService::getMenuPermission);
    }

    @Override
    public List<String> getRoleList(Object loginId, String loginType) {
        return resolvePermissionList(loginId, LoginUser::getRolePermission,
                                     PermissionService::getRolePermission);
    }

    private List<String> resolvePermissionList(Object loginId,
                                               Function<LoginUser, Collection<String>> local,
                                               BiFunction<PermissionService, Long, Collection<String>> remote) {
        LoginUser loginUser = LoginHelper.getLoginUser();
        if (ObjectUtil.isNull(loginUser) || !loginUser.getLoginId().equals(normalizeLoginId(loginId))) {
            // 本地会话取不到(如跨服务、非本请求的 loginId)→ 走 Dubbo 远程兜底
            PermissionService permissionService = getPermissionService();
            if (ObjectUtil.isNotNull(permissionService)) {
                return new ArrayList<>(remote.apply(permissionService, resolveUserId(loginId)));
            }
            throw new ServiceException("PermissionService 实现类不存在");
        }
        Collection<String> permissionList = local.apply(loginUser);
        return CollUtil.isNotEmpty(permissionList) ? new ArrayList<>(permissionList) : new ArrayList<>();
    }
}

这套实现的三个工程要点

  1. 本地优先、远程兜底:命中了当前请求的 LoginUser 就直接返回内存里的 menuPermission/rolePermission(零 DB 访问);未命中(例如 RPC 场景或 loginId 不匹配)才走 PermissionService(Dubbo)查库。
  2. 权限在「登录时」算好、随会话走:这是若依的既定策略 —— 用户菜单/角色变更需重新登录或强制刷新会话才能生效,避免每次接口调用都查权限表。
  3. 超管旁路:LoginHelper.isSuperAdmin() 判定 SystemConstants.SUPER_ADMIN_USER_ID,业务里常用「超管跳过权限码校验」,Sa-Token 层不感知,属业务约定。

5.6 业务层注解鉴权与权限标识规范

Controller 典型用法(与官方文档一致)

// 单权限
@SaCheckPermission("system:user:list")
@GetMapping("/list")
public TableDataInfo<SysUserVo> list(SysUserBo bo, PageQuery pageQuery) { ... }

// 需要「新增 或 修改」任一权限即可
@SaCheckPermission(value = {"system:user:add", "system:user:edit"}, mode = SaMode.OR)
@PostMapping
public R<Void> add(@Validated @RequestBody SysUserBo bo) { ... }

// 只要 admin 角色即可(与权限码二选一)
@SaCheckPermission(value = "system:user:resetPwd", orRole = "admin")
@PostMapping("/resetPwd")
public R<Void> resetPwd(@RequestBody SysUserBo bo) { ... }

权限标识规范(若依系约定)

层级 命名 示例
模块 业务模块名 system、workflow、resource
实体 表/资源名 user、role、menu、oss
动作 list / query / add / edit / remove / export / import / resetPwd system:user:export
通配 * 可出现在任一段 system:user:*(慎用,会放大权限面)

前后端一致性:前端 v-has-permi="['system:user:add']" 必须与后端 @SaCheckPermission 完全一致;官方文档明确「前端按钮显隐只是界面控制,不能替代后端接口鉴权」。

5.7 存储替换与配置要点

事项 若依 Plus 的做法 你要注意什么
持久层 ruoyi-common-redis 提供 PlusSaTokenDao(基于 Redisson)并通过 SaManager.setSaTokenDao(...) 替换默认实现 自研时同理:只需替换 Bean,业务代码零改动
配置位置 sa-token 配置集中在 Nacos(ruoyi-auth/ruoyi-gateway 的 application.yml + config_info 表) 多服务必须共用同一套 token-name、同一 Redis,否则「登录成功但业务服务 401」
Token 传递 前端请求头 Authorization(token-name 常配为 Authorization,并按需开启前缀模式) 若开 token-prefix: Bearer,必须前后端一致,否则报「token 无效」
会话模型 LoginUser 存 Token-Session;userId/clientid 等存 Extra 大对象不要塞 Extra(会写进 Token 记录,放大 Redis 体积)
内部调用 InnerAuth(注解 + Same-Token 思路)保护 /inner/** 接口 网关白名单不要放 /inner/**,只允许内网直连

上表中「token-name 常配为 Authorization」为若依系通行约定;具体值与 token-prefix、is-read-cookie 等请以你项目的 Nacos 配置为准(本文未取到该实例的完整配置原文,避免臆造)。

5.8 原版若依云 vs Plus 的鉴权差异对照

维度 RuoYi-Cloud 3.6.8(原版) RuoYi-Cloud-Plus 6.X
鉴权框架 自研:JwtUtils(JWT)+ RedisService 存 login_tokens:<uuid> Sa-Token 1.46.0(StpUtil/StpLogic)
令牌形态 JWT(内含 userkey=uuid、userId、username),用户数据只在 Redis 不透明 Token(默认 UUID 风格),用户数据在 Token-Session
权限载体 LoginUser.permissions(由 SysLoginService 登录时装配) SaPermissionImpl 实现 StpInterface,本地优先 + Dubbo 兜底
方法级校验 自研 PreAuthorizeAspect + 自定义注解 @SaCheckPermission / @SaCheckRole(框架原生)
网关鉴权 AuthFilter(GlobalFilter)手写 JWT 解析 + Redis 校验 SaServletFilter + SaRouter.notMatch(白名单)
多端/踢人/封禁 需自研(原版仅支持单一会话语义) 框架内置(kickout、deviceType 互斥、disable)
内部调用鉴权 InnerAuth + SecurityConstants.INNER 头 InnerAuth + Same-Token 思路(同源)
会话续期 verifyToken:剩余 < 120 分钟则 refreshToken Sa-Token autoRenew + active-timeout + renewTimeout
技术栈 Spring Boot 2/3/4 多分支、Spring Security 仅出现在历史文档中 Spring Boot 3.4.x、Spring Cloud 2024、Dubbo 3.3.x
扩展成本 新增「多端互斥/封禁」需自己加表、加代码 改配置或调一行 API

这段对照的实践价值:如果你在做「原版若依云 → 某一 Sa-Token 版本」的迁移评估,重点是 登录入口 + 权限查询 + 网关过滤器 三处;其余业务代码(@PreAuthorize 风格的注解)可以批量替换注解,但权限码数据(sys_menu.perms)不用动——因为它本来就是字符串,天然兼容 Sa-Token。

5.9 若要在原版 RuoYi-Cloud 中引入 Sa-Token

目标:保留原版的模块划分(gateway/auth/system),把鉴权内核从「自研 JWT + Redis + AOP」换成 Sa-Token。

步骤 动作 关键代码/配置
1 ruoyi-common-security 引 sa-token-spring-boot3-starter + sa-token-redis-jackson 移除 JwtUtils 相关 token 生成逻辑(保留 SecurityUtils 门面,内部改调 StpUtil)
2 新建 StpInterface 实现,权限来源复用 LoginUser.getPermissions() getPermissionList 返回 LoginHelper.getLoginUser().getPermissions()
3 ruoyi-auth 的 TokenController#login 改为 StpUtil.login(userId, new SaLoginParameter().setExtra("userkey", uuid)),并把 LoginUser 存 Token-Session 直接照搬 RuoYi-Cloud-Plus 的 LoginHelper 写法
4 网关 AuthFilter 从「手写 JWT 解析」改为 SaServletFilter(或 WebFlux 用 SaReactorFilter) 参照 5.4 源码
5 注销/刷新接口改 StpUtil.logout() / renewTimeout() 原 delLoginUser 逻辑作废
6 全局异常处理增加 NotLoginException/NotPermissionException 分支 保持返回体 R/AjaxResult 风格不变
7 灰度:先双写(原 token + Sa-Token token),再全量切,最后删旧代码 网关按 header 判断走哪套校验

必须提前想清楚的风险:原版 TokenService 的 JWT 是无状态可解析的(网关可离线验签),改成 Sa-Token 的不透明 Token 后,所有校验都需要回查 Redis——Redis 一旦抖动,全站鉴权不可用。若这是不可接受的,可改用 sa-token-jwt 的「无状态模式」保留离线解析能力。


F 附件

F.1 附:调研取证与口径说明

项 说明
源码取证方式 全部 Java 片段取自 GitHub raw.githubusercontent.com 原文(6.X / master 分支),非博客转述;片段做了去注释与格式压缩,逻辑未改
仓库统计时点 2026-11-11 实时快照(ungh.cc),与官方文中「统计日 2026-01-25」的数字不同属正常
版本口径 官方两站点版本号不一致(sa-token.cc = 1.45.0,sa-token.com = 1.46.0);本文按 1.45.0 语义描述,1.46.0 仅引用第三方发行说明
未取到/未核实项 ① RuoYi-Cloud-Plus 实例的完整 sa-token.* Nacos 配置原文;② Sa-Token 与 Spring Security 的官方 benchmark;③ 各框架真实「市占率」(无权威来源)。相关结论已标注「定性」「待补充」或改用可复现代理指标
打分口径 10 分制主观打分,权重在 4.7 两张表中显式列出;权重改变会改变排序,请按自身场景重算

Z FAQ

Q: Sa-Token 是不是 Spring Security 的封装?

不是。官方明确「从 0 自研,核心包零依赖」,v1.16.0「核心包脱离 ServletAPI,彻底零依赖」的更新日志可证。它不复用 Spring Security 的任何过滤器、认证对象或上下文(这也是它不被 SecurityContext 生态识别的原因)。

Q: 为什么我加了 @SaCheckPermission 却完全不生效?

最常见原因是没有注册 SaInterceptor(或没引 sa-token-spring-aop)。注解鉴权依赖拦截器/AOP 作为入口,缺失时注解不会被执行,且不会报错——属静默失效,必须单测覆盖。

Q: 多实例部署后「A 节点登录,B 节点 401」怎么排查?

按三步:① 是否接了 Redis(默认内存 Dao 无法跨实例);② 各服务 token-name/token-prefix 是否一致(不一致则 key 域不同,互相看不见);③ 是否有人改过 is-share/is-concurrent 导致 Token 被覆盖。

Q: hasPermission 和 checkPermission 该用哪个?

has* 只返回布尔、不抛异常;check* 校验失败抛 NotPermissionException(v1.38 起明确分离)。做 if 分支用 has*,做「不通过就拦截」用 check*,后者交给全局异常处理器统一转 403。

Q: Sa-Token 能和 Spring Security 共存吗?

技术上可以(各自独立),实践中不建议:两者都注册过滤器、都接管 401/403 输出,容易互相覆盖。若必须共存(迁移期),要让其中一个只针对特定路径生效(addInclude/requestMatchers 精确限定),并明确「谁负责抛 401、谁负责 403」。

Q: 为什么 SaSession 里取不到 HttpSession 存的值?

SaSession 与 HttpSession 没有任何关系,框架不接管 HttpSession。官方明确建议:使用 Sa-Token 后一律用 SaSession,不要再用 HttpSession。

Q: Redis 里存了自定义实体,读回报「无法反序列化的类型」怎么办?

需将实体类注册到 JSON 全局类型白名单(官方 Session 章节专门给了链接);或改用能携带类名的序列化插件(如 sa-token-redis-jackson/-snack4),并避免在 Session 里存匿名/内部类。

Q: 网关已经 checkLogin 了,业务服务还要不要再鉴权?

要。网关只解决「是否登录」,接口级权限码随菜单动态变化,只有业务服务知道自己暴露了哪个权限码。若依 Plus 的取舍正是「网关管登录、服务管权限」。

Q: Sa-Token 的 OAuth2 能替代 Spring Authorization Server 吗?

看场景。若只是「自家几个系统之间发/验 token」,Sa-Token 的 OAuth2 模块够用且更省事;若要对接第三方、要求严格遵循 OIDC 一致性测试套件、需要成熟的 client 注册与密钥轮换治理,Spring Authorization Server 或 Keycloak 更稳妥。

Q: 升级 Sa-Token 大版本要注意什么?

先读更新日志里带 [不向下兼容] 的条目(v1.35、v1.41 是重灾区:SaLoginModel→SaLoginParameter、TokenSign→SaTerminalInfo、is-share 默认值变更)。升级策略:① 锁定 sa-token-bom 统一版本;② 全量跑登录/多端/踢人/权限的回归用例;③ 灰度一个服务观察 Redis 键结构变化(新旧键名不兼容会表现为「看不见对方会话」)。

Q: 若依 Plus 里权限改了为什么不立即生效?

因为权限在登录时装配进 LoginUser 并随 Token-Session 走(5.5)。要么让用户重新登录,要么在角色/菜单变更后主动刷新该用户的会话(如 StpUtil.getSessionByLoginId(id).update() / 强制 kickout)。

Q: 生产环境该用哪个 Token 风格?

默认 uuid(36 字符、可读性好、碰撞概率低);追求短小用 random-32;追求紧凑可读用 tik。不建议自行改写生成算法(v1.32 曾出现特定风格下的 Token 重复问题,官方已在后续版本修复)。


Y 推荐文献

  • Sa-Token
  • Spring Security
  • Apache Shiro


  • 《Spring Security in Action》(Second Edition) - Laurentiu Spilca(Manning) - #(实体书)
  • 《Spring Boot 编程思想》- 小马哥(实体书) - #(书中对安全与自动装配的分析对理解 SS 架构有帮助)
  • 《RBAC 与权限系统设计》相关实践文献(可结合 Casbin/OPA 官方文档阅读) - #(实体书/合集)

X 参考文献

官方文档与站点

仓库与源码(一手实证)

项目动态与二手参考

posted @ 2026-11-11 11:59  千千寰宇  阅读(48)  评论(0)    收藏  举报