[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 主要功能(必读)
官方功能一览归纳为 五大核心模块 + 若干实用插件:
| 能力域 | 具体能力(官方列示,已查证) |
|---|---|
| 登录 | 单端登录、多端登录、同端互斥(像 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 总体架构
关键设计取舍:
- 门面静态化:
StpUtil全静态方法,避免业务层到处注入 Bean,代价是必须依赖上下文(SaTokenContext)——这也解释了为什么异步线程里必须准备 Mock 上下文。 - 一账号体系一
StpLogic:多套账号(User/Admin)通过不同LoginType隔离,配置也可单独覆盖(v1.35 起支持为StpLogic单独配置SaTokenConfig)。 - 持久层单点收口:所有落库都走
SaTokenDao,所以「换存储 = 换 Bean」,业务零改动。 - SPI 插件体系(v1.41):插件不再靠
@Autowired硬绑,而是按 SPI 注册,解决了「引入插件就启动失败」类问题。
2.3 登录认证运行原理
要点(均已查证):
- 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 交给你实现的查询接口,再拿返回值做匹配」:
| 校验入口 | 写法 | 适用 |
|---|---|---|
| 注解鉴权 | @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 隔离
规则:不同 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));
}
}
两版的差别只在过滤器基类(
SaReactorFiltervsSaServletFilter),鉴权 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 的处理链(短链路)
Spring Security 的处理链(长链路,Servlet 栈简化版)
结构差异的三条主线:
- 链长度:Sa-Token 默认 1 个拦截器 + 1 次 DAO 读取即可完成「登录校验」;Spring Security 走完整过滤器链(默认 10+ 个 Filter),每个 Filter 各司其职。
- 状态承载:Sa-Token 的登录态在
SaTokenDao(外部存储);Spring Security 的登录态在SecurityContext(线程本地)+ Session/Token。前者天然跨实例,后者需Spring Session或改为无状态 JWT。 - 授权决策位置:Sa-Token 在方法/路由层用「权限码字符串」决策;Spring Security 在请求匹配器(URL)与方法调用(
@PreAuthorizeSpEL)两层决策,且可用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(若依原版/自研项目改造)
迁移红线:
- 必须显式移除
spring-boot-starter-security及SecurityFilterChain,否则 401/403 与AccessDeniedHandler会与 Sa-Token 争抢响应。 - 权限码语义要一次改对:Spring Security 的
ROLE_ADMIN前缀体系与 Sa-Token 的裸角色标识不同,需统一映射。 - 若原项目用
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 的鉴权模块地图
| 模块 | 关键类(源码实证) | 职责 |
|---|---|---|
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
}
设计解读(三点,均有源码支撑)
loginId不是纯 userId:6.X 的LoginUser引入LOGIN_ID_SEPARATOR,loginId形如「用户类型 + 分隔符 + userId」,从而在一个 Sa-Token 实例内支持多用户体系(SaPermissionImpl里专门有normalizeLoginId兼容历史冒号格式)。- 用户模型存
Token-Session,不放Account-Session:这样多端登录各自持有独立的 LoginUser 快照(含 IP、设备、登录时间),踢掉一端不影响另一端;也解释了为什么LoginHelper.getLoginUser(token)能按 token 取用户。 - 高频字段走
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<>();
}
}
这套实现的三个工程要点
- 本地优先、远程兜底:命中了当前请求的
LoginUser就直接返回内存里的menuPermission/rolePermission(零 DB 访问);未命中(例如 RPC 场景或 loginId 不匹配)才走PermissionService(Dubbo)查库。 - 权限在「登录时」算好、随会话走:这是若依的既定策略 —— 用户菜单/角色变更需重新登录或强制刷新会话才能生效,避免每次接口调用都查权限表。
- 超管旁路:
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 参考文献
官方文档与站点
- Sa-Token 首页 / 产品介绍 - sa-token.cc
- Sa-Token 更新日志 - sa-token.cc
- Sa-Token Session 会话 - sa-token.cc
- Sa-Token 官网(v1.46.0 首页与生态列表)- sa-token.com
- RuoYi-Cloud-Plus 权限控制 - plus-doc.dromara.org
- RuoYi-Cloud 认证中心 - doc.ruoyi.vip
- RuoYi-Cloud 项目介绍(模块结构)- doc.ruoyi.vip
- Spring Security Reference - docs.spring.io
仓库与源码(一手实证)
-
dromara/Sa-Token 仓库元数据(Star 19,114 / Fork 2,912 / pushedAt 2026-10-16)- ungh.cc
-
dromara/RuoYi-Cloud-Plus 仓库元数据(Star 1,327 / 默认分支 6.X)- ungh.cc
-
spring-projects/spring-security 仓库元数据(Star 9,668 / Fork 6,391)- ungh.cc
-
RuoYi-Cloud-Plus 6.X:ruoyi-gateway AuthFilter.java(SaServletFilter 源码)- GitHub raw
-
RuoYi-Cloud-Plus 6.X:IgnoreWhiteProperties.java(security.ignore.whites)- GitHub raw
-
RuoYi-Cloud-Plus 6.X:SaPermissionImpl.java(StpInterface 实现)- GitHub raw
-
RuoYi-Cloud 3.6.8:TokenService.java(JWT + Redis 令牌实现)- GitHub raw
-
RuoYi-Cloud 3.6.8:ruoyi-common-security/pom.xml(无 Spring Security 依赖的实证)- GitHub raw
项目动态与二手参考
本文链接: https://www.cnblogs.com/johnnyzen
关于博文:评论和私信会在第一时间回复,或直接私信我。
版权声明:本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!
日常交流:大数据与软件开发-QQ交流群: 774386015 【入群二维码】参见左下角。您的支持、鼓励是博主技术写作的重要动力!

浙公网安备 33010602011771号