Sa-Token v1.46.0 版本特性深度解析从注销前侦听器到 JSON 反序列化安全加固【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架让鉴权变得简单、优雅—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token本篇文章以 Sa-Token 仓库根目录下的 update-log.md 更新日志为主体骨架结合 sa-token-core、sa-token-plugin 等模块的源码实现系统梳理 v1.46.0 及同期版本的核心技术演进注销前侦听器、JSON 多态反序列化白名单、HTTP 请求扩展插件、Redis/Redisson 数据访问层增强、SSO 安全加固等。读完本文你将理解这些特性的设计动机、底层调用链与迁移配置要点可直接用于生产环境升级评估。一、更新日志概览与版本脉络update-log.md是 Sa-Token 仓库的版本变更总账记录了从 v1.45.0 发布到 v1.46.0 之间每一个功能迭代、安全修复与文档优化节点。从内容结构上看日志主要分为三大类核心框架特性如注销前侦听器、JSON 安全策略、配置项新增等落点在sa-token-core插件与集成增强如 HTTP 请求插件、alone-redisson 独立连接、Redis 序列化改进等落点在sa-token-plugin与sa-token-starter工程与生态维护博客系统、多语言支持、文档站点、示例工程等。其中v1.46.02026-08-18 起是信息密度最高的版本本文将以该版本为核心展开同时覆盖 v1.45.0 的关键能力。二、注销前侦听器doBeforeLogout / doBeforeKickout / doBeforeReplaced2.1 功能定位v1.46.0 新增了三个注销前侦听器事件用于在账号注销、被顶下线、被踢下线真正生效之前同步触发一次回调。这是对既有全局侦听器体系的重要补充。在 SaTokenListener.java 中三个新方法均为default 方法默认空实现因此对老用户完全兼容无需强制改造// 注销前 default void doBeforeLogout(String loginType, Object loginId, String tokenValue, SaLogoutParameter logoutParameter) {} // 被踢下线前 default void doBeforeKickout(String loginType, Object loginId, String tokenValue, SaLogoutParameter logoutParameter) {} // 被顶下线前 default void doBeforeReplaced(String loginType, Object loginId, String tokenValue, SaLogoutParameter logoutParameter) {}与之对应原本的doLogout/doKickout/doReplaced仍然保留作为注销后事件继续生效。2.2 底层触发机制从源码调用链看三个前事件统一由 StpLogic.java 中的私有方法_fireBeforeLogoutEvent负责分发根据SaLogoutParameter.getMode()决定触发哪个事件private void _fireBeforeLogoutEvent(Object loginId, String tokenValue, SaLogoutParameter logoutParameter) { if(logoutParameter.getMode() SaLogoutMode.LOGOUT) { SaTokenEventCenter.doBeforeLogout(loginType, loginId, tokenValue, logoutParameter); } if(logoutParameter.getMode() SaLogoutMode.KICKOUT) { SaTokenEventCenter.doBeforeKickout(loginType, loginId, tokenValue, logoutParameter); } if(logoutParameter.getMode() SaLogoutMode.REPLACED) { SaTokenEventCenter.doBeforeReplaced(loginType, loginId, tokenValue, logoutParameter); } }事件最终通过 SaTokenEventCenter.java 广播给所有注册的SaTokenListener实现。SaLogoutParameter携带了登录类型、登录账号、token 值与注销模式回调中可据此区分场景如注销时做资源清理、被踢时推送通知、被顶时记录审计日志。2.3 使用建议需要在会话销毁前执行清理操作如解绑设备、下线通知、操作日志时优先使用这三个前事件默认方法的设计意味着只需在你自己的SaTokenListener实现中重写所需方法即可其余方法保持空实现避免样板代码。三、JSON 安全加固SaJsonStrategy 类型白名单3.1 背景Jackson DefaultTyping 反序列化风险v1.46.0 修复了一个高危安全漏洞JacksonDefaultTyping多态反序列化存在 RCE 风险。原因在于启用默认类型后序列化字符串中会携带类型信息如class攻击者若可篡改数据源就能利用类型标记实例化 classpath 上的任意类触发反序列化攻击链。修复方案是引入SaJsonStrategy全局类型白名单核心类见 SaJsonStrategy.java只有白名单内的类型才允许参与多态反序列化。3.2 白名单构成getSaJsonAllowTypeList()每次调用都会现场合并四类来源并返回快照去重后保持注册顺序JDK 内置允许类型getJdkAllowTypeList集合结构锚点Map/Collection基本类型包装类Number/Boolean/Character旧版日期Date/Calendar以及java.time全家桶LocalDateTime、Instant、ZonedDateTime等、BigDecimal/BigInteger、UUID、Enum等常见值类型SPI 文件声明loadSpiAllowTypeList读取META-INF/satoken/sa-json-type.list中的类名列表空行与#开头的注释行会被忽略便于各插件声明自己的允许类型SaJsonType标记接口所有实现了该标记接口的类均被允许用户自定义注册registerAllowType(Class)在初始化前手动注册。3.3 关键约束与警告从SaJsonStrategy源码可以看出两个必须注意的约束注册时机isInit()为true即getSaJsonAllowTypeList()已被调用过之后registerAllowType(Class)会抛出SaTokenException。因此自定义类型注册必须在 JSON 插件初始化之前完成——比如在main方法或 Spring 启动前调用强烈不建议注册Object.class注册Object.class等同于放开全部类型限制。源码会向System.err输出郑重安全警告明确提示class/type等类型标记可被用来实例化 classpath 上任意类型生产环境强烈不建议这么做。3.4 Jackson 插件的落地方式在 SaJsonTemplateForJackson.java 的构造器中插件通过buildAllowTypeValidator()依据SaJsonStrategy.instance.getSaJsonAllowTypeList()构建PolymorphicTypeValidator再配合activateDefaultTyping启用默认类型——即序列化时嵌入类型信息class属性反序列化时仅接受白名单内的类型。同一批安全更新还包含Snack3 序列化不再写入类型信息对齐 fastjson 的安全策略JSON 反序列化容错优化参考sa-token-serializer-features等模块提升不同数据源下的健壮性。四、HTTP 请求扩展插件SaHttpTemplate 的统一抽象4.1 新增两个实现v1.46.0 新增了sa-token-rest-client与sa-token-rest-template两个 HTTP 请求插件分别基于 Spring 6.1 的RestClient与经典RestTemplate实现统一接口SaHttpTemplate接口定义见 SaHttpTemplate.java配套文档见 plugin/http-extend.md。以 SaHttpTemplateForRestClient.java 为例内部持有RestClient.create()实现get(url)与postByFormData(url, params)两个方法其中 POST 以application/x-www-form-urlencoded提交表单数据并统一通过SaManager.log输出 debug 级别的请求/响应日志便于排查 SSO 等远程交互链路public class SaHttpTemplateForRestClient implements SaHttpTemplate { private final RestClient restClient RestClient.create(); Override public String get(String url) { SaManager.log.debug(发起请求GET{}, url); String res restClient.get().uri(url).retrieve().body(String.class); SaManager.log.debug(返回结果{}, res); return res; } // postByFormData(url, params)以表单格式 POST 并返回字符串结果 }4.2 使用场景该抽象主要服务于SSO 客户端与认证服务器的 HTTP 通信为后续扩展更多底层 HTTP 客户端如 OkHttp、Forest 等提供统一插槽方便接入方按自身技术栈替换实现。五、Redis / Redisson 数据层增强v1.46.0 对 Redis 数据访问层做了多项修复与增强直接影响使用 Redis 存储会话的稳定性。5.1 TTL 保持SET KEEPTTLsa-token-redis-template及 jdk-serializer 版本修复了update key 时 TTL 偏移的问题issues #I80P5O、#ICWJOQ。根因是旧的更新操作会重置过期时间导致 Token 被意外续命。修复后SaTokenDaoForRedisTemplate.java 的 update 方法使用RedisSET KEEPTTLExpiration.keepTtl()原子保留原 TTL前提是Redis 版本 6.0对于Redis 6.0 以下版本文档补充了替代方案将 update 方法替换为毫秒级 TTL 写回写法。相关说明同步到了 more/common-questions.md 与 up/integ-redis.md低版本用户按文档替换即可规避报错。5.2 searchData 由 KEYS 改为 SCANredis-template 的searchData从KEYS命令改为SCAN游标方式ScanOptionsconnection.scan既避免阻塞主线程也兼容低版本 Spring Data Redis参考 issue #702。源码中wrapKey也被抽为可重写方法开发者可以自定义键前缀策略。5.3 Redisson Dao 增强SaTokenDaoForRedisson.java 的改进点支持指定 Codec提供SaTokenDaoForRedisson(RedissonClient, Codec)构造器默认使用StringCodec.INSTANCE与业务方 RedissonClient 的全局 Codec 隔离避免序列化器互相干扰update 使用setAndKeepTTL基于RBucket.setAndKeepTTL()原子保留原过期时间同样要求 Redis 6.0低版本有毫秒写法替代同时补充了按配置决定是否启用 Redis的示例参考 issue #I9I4ZG方便多环境切换。5.4 sa-token-alone-redisson 独立连接插件v1.46.0 新增sa-token-alone-redisson插件文档见 plugin/alone-redisson.md示例工程见sa-token-demo-alone-redisson等目录与既有sa-token-alone-redis插件形成互补用于让权限缓存与业务数据缓存使用独立的 Redis 连接。从 SaAloneRedissonRegister.java 的源码结构看其核心逻辑是读取独立连接配置SaAloneRedissonProperties基于独立的RedissonClient构建new SaTokenDaoForRedisson(aloneClient)并注册为SaTokenDaoBean从而覆盖业务 RedissonClient 对应的 Dao实现权限数据与业务数据的连接级隔离。测试用例位于sa-token-plugin/sa-token-alone-redisson/src/test/下含纯单测与 Spring 环境单测两个场景。六、Session 类型安全集合读取v1.46.0 为 Session 数据读取新增了类型安全集合 APIgetList/getSet/getMap定义在 SaGetValueInterface.java接口被SaSession继承使用default T ListT getList(String key, ClassT elementClass) { ... } default T SetT getSet(String key, ClassT elementClass) { ... } default K, V MapK, V getMap(String key, ClassK keyClass, ClassV valueClass) { ... }调用时传入元素/键值的具体 Class读取时自动完成反序列化与泛型转换避免手工List?强转带来的ClassCastException。对应的SaSetValueInterface还提供了带兜底函数的三参重载如getList(key, elementClass, fun)当值为 null 时执行fun获取默认值并写入配合 JSON 白名单机制可安全存取带类型信息的复杂对象。七、SSO 单点登录安全与功能增强v1.46.0 对 SSO 模块做了集中加固指定账号单点注销SSO 客户端新增指定账号单点注销 API可精确注销某个账号而非全部会话StpInterface.isDisabled补充loginType参数方法签名从isDisabled(loginId, service)演进为isDisabled(loginId, service, loginType)见 StpInterface.java使账号封禁判断可以按登录类型区分StpLogic.isDisableLevel 内部即通过SaManager.getStpInterface().isDisabled(loginId, service, loginType)完成查询buildServerAuthUrl健壮性增强识别 URL 编码后的back参数back为空时跳过追加并强化重定向编码/解码防止参数被截断或二次编码错乱NoSdk 模式签名校验强化demo 的签名校验补充时间窗与nonce 防重放配合SsoSignUtil该工具在 v1.45.0 的 NoSdk 补全中引入文档见 sso/sso-nosdk.md提升无 SDK 集成场景的抗重放能力安全漏洞修复OAuth2/SSO 的redirect参数绕过 allow-url 校验漏洞已修复重定向目标必须通过域名白名单校验。八、安全与健壮性多项底层增强v1.46.0 还包含一批跨模块的安全与健壮性改进allowLoginIdColon配置项默认false禁止 loginId 包含冒号:。该校验位于 StpLogic.checkLoginArgs// 3、账号 id 不能包含冒号:除非配置 allowLoginIdColontrue if( ! Boolean.TRUE.equals(getConfigOrGlobal().getAllowLoginIdColon()) id.toString().contains(:)) { throw new SaTokenException(loginId 不能包含冒号:).setCode(SaErrorCode.CODE_11018); }配置项定义在 SaTokenConfig.java默认值false。之所以限制冒号是因为 token 解析与 Session 存储中冒号通常作为分隔符允许冒号可能引入歧义确有特殊账号需要包含冒号时可显式配置allowLoginIdColontrue放开有校验与告警机制兜底需自行评估风险。随机字符串/数字改用 CSPRNGtoken 随机串生成从普通随机源切换为SecureRandom降低 token 被预测的概率JWT extraData 禁止包含保留字段防止扩展数据覆盖 JWT 标准声明见sa-token-jwt插件SaRequest/SaResponse/SaStorage创建策略通过SaStrategy中的SaCreateSaRequestFunction/SaCreateSaResponseFunction/SaCreateSaStorageFunctionSaStrategy.java允许自定义请求/响应/存储对象的创建方式便于适配非标准 Web 容器参考 issue #841Context Filter 注册 REQUESTASYNC修复 SSE/Flux 流式返回场景下上下文未初始化的缺陷issues #IC4XFE、#ICB9OJgetSaTokenConfig策略SaStrategy新增getSaTokenConfig函数默认为 null启用后接管SaManager.getConfig()的返回值支持从外部如配置中心动态提供配置来源isLastingCookie为 null 时getCookieTimeout不再 NPE修复 Cookie 超时计算空指针WebFlux/Gateway 兼容修复 Boot3 WebFlux/Gateway 下setStatus的NoSuchMethodErrorreactor starter 结构调整issues #IIAW1A、#916、#IHRIBYisUrl支持 IPv6 方括号地址并拒绝裸 IPv6sa-token-dependencies不再锁定 Reactor 版本避免与 Spring Cloud Gateway 冲突issue #622。九、如何获取与验证这些特性9.1 版本与依赖框架版本号已升级至1.46.0可通过 Maven 中央仓库引入javadoc/sources/gpg 仅在发布 Maven 中央时启用BOM 模块补齐了sa-token-caffeine与sa-token-loveqq-boot-starter统一依赖版本管理可参考 sa-token-bom/pom.xml 与 sa-token-dependencies/pom.xml。9.2 示例工程对照更新日志中多次提到的特性都有对应示例与测试可对照学习HTTP 插件sa-token-plugin/sa-token-rest-client、sa-token-plugin/sa-token-rest-template源码及测试SSO 增强sa-token-plugin/sa-token-sso源码配合 sso/sso-apidoc.md 与 sso/sso-nosdk.md 文档Redisson 独立连接sa-token-plugin/sa-token-alone-redisson及sa-token-demo-alone-redisson/sa-token-demo-alone-redisson-sb4示例Redis 数据层sa-token-plugin/sa-token-redis-template下的SaTokenDaoForRedisTemplateSearchDataTest等测试验证了 SCAN 搜索行为JSON 安全sa-token-plugin/sa-token-jackson/sa-token-jackson3/sa-token-snack3/sa-token-fastjson插件源码与测试以及 plugin/custom-serializer.md 文档。9.3 升级注意事项速查清单关注点说明Redis 版本update 方法依赖SET KEEPTTLRedis 6.0可无缝使用低版本需替换为毫秒 TTL 写法见 common-questions.md / integ-redis.mdJSON 白名单自定义反序列化类型需在 JSON 插件初始化前通过SaJsonStrategy.registerAllowType注册切勿注册Object.class放开限制loginId 冒号默认禁止:特殊账号需显式开启allowLoginIdColonSSO 回调back参数现在支持 URL 编码形式重定向会统一编解码老链路如有手工编码需对齐新行为WebFluxBoot3 请使用新版 reactor starter 结构setStatus不再冲突十、总结Sa-Token v1.46.0 是一次安全加固 集成扩展并重的版本一方面通过 JSON 类型白名单、CSPRNG 随机源、redirect 校验等手段系统性收紧了框架的安全边界另一方面通过注销前侦听器、类型安全集合 API、HTTP 请求抽象、Redisson 独立连接等能力扩展了框架在多会话管理、分布式存储与异构集成场景下的可用性。对于升级用户而言重点关注 Redis 版本兼容与 JSON 白名单注册时机两个前置条件即可平滑迁移。本文对应的完整变更记录可在仓库根目录的 update-log.md 中持续跟踪。【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架让鉴权变得简单、优雅—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Sa-Token v1.46.0 版本特性深度解析：从注销前侦听器到 JSON 反序列化安全加固
Sa-Token v1.46.0 版本特性深度解析从注销前侦听器到 JSON 反序列化安全加固【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架让鉴权变得简单、优雅—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token本篇文章以 Sa-Token 仓库根目录下的 update-log.md 更新日志为主体骨架结合 sa-token-core、sa-token-plugin 等模块的源码实现系统梳理 v1.46.0 及同期版本的核心技术演进注销前侦听器、JSON 多态反序列化白名单、HTTP 请求扩展插件、Redis/Redisson 数据访问层增强、SSO 安全加固等。读完本文你将理解这些特性的设计动机、底层调用链与迁移配置要点可直接用于生产环境升级评估。一、更新日志概览与版本脉络update-log.md是 Sa-Token 仓库的版本变更总账记录了从 v1.45.0 发布到 v1.46.0 之间每一个功能迭代、安全修复与文档优化节点。从内容结构上看日志主要分为三大类核心框架特性如注销前侦听器、JSON 安全策略、配置项新增等落点在sa-token-core插件与集成增强如 HTTP 请求插件、alone-redisson 独立连接、Redis 序列化改进等落点在sa-token-plugin与sa-token-starter工程与生态维护博客系统、多语言支持、文档站点、示例工程等。其中v1.46.02026-08-18 起是信息密度最高的版本本文将以该版本为核心展开同时覆盖 v1.45.0 的关键能力。二、注销前侦听器doBeforeLogout / doBeforeKickout / doBeforeReplaced2.1 功能定位v1.46.0 新增了三个注销前侦听器事件用于在账号注销、被顶下线、被踢下线真正生效之前同步触发一次回调。这是对既有全局侦听器体系的重要补充。在 SaTokenListener.java 中三个新方法均为default 方法默认空实现因此对老用户完全兼容无需强制改造// 注销前 default void doBeforeLogout(String loginType, Object loginId, String tokenValue, SaLogoutParameter logoutParameter) {} // 被踢下线前 default void doBeforeKickout(String loginType, Object loginId, String tokenValue, SaLogoutParameter logoutParameter) {} // 被顶下线前 default void doBeforeReplaced(String loginType, Object loginId, String tokenValue, SaLogoutParameter logoutParameter) {}与之对应原本的doLogout/doKickout/doReplaced仍然保留作为注销后事件继续生效。2.2 底层触发机制从源码调用链看三个前事件统一由 StpLogic.java 中的私有方法_fireBeforeLogoutEvent负责分发根据SaLogoutParameter.getMode()决定触发哪个事件private void _fireBeforeLogoutEvent(Object loginId, String tokenValue, SaLogoutParameter logoutParameter) { if(logoutParameter.getMode() SaLogoutMode.LOGOUT) { SaTokenEventCenter.doBeforeLogout(loginType, loginId, tokenValue, logoutParameter); } if(logoutParameter.getMode() SaLogoutMode.KICKOUT) { SaTokenEventCenter.doBeforeKickout(loginType, loginId, tokenValue, logoutParameter); } if(logoutParameter.getMode() SaLogoutMode.REPLACED) { SaTokenEventCenter.doBeforeReplaced(loginType, loginId, tokenValue, logoutParameter); } }事件最终通过 SaTokenEventCenter.java 广播给所有注册的SaTokenListener实现。SaLogoutParameter携带了登录类型、登录账号、token 值与注销模式回调中可据此区分场景如注销时做资源清理、被踢时推送通知、被顶时记录审计日志。2.3 使用建议需要在会话销毁前执行清理操作如解绑设备、下线通知、操作日志时优先使用这三个前事件默认方法的设计意味着只需在你自己的SaTokenListener实现中重写所需方法即可其余方法保持空实现避免样板代码。三、JSON 安全加固SaJsonStrategy 类型白名单3.1 背景Jackson DefaultTyping 反序列化风险v1.46.0 修复了一个高危安全漏洞JacksonDefaultTyping多态反序列化存在 RCE 风险。原因在于启用默认类型后序列化字符串中会携带类型信息如class攻击者若可篡改数据源就能利用类型标记实例化 classpath 上的任意类触发反序列化攻击链。修复方案是引入SaJsonStrategy全局类型白名单核心类见 SaJsonStrategy.java只有白名单内的类型才允许参与多态反序列化。3.2 白名单构成getSaJsonAllowTypeList()每次调用都会现场合并四类来源并返回快照去重后保持注册顺序JDK 内置允许类型getJdkAllowTypeList集合结构锚点Map/Collection基本类型包装类Number/Boolean/Character旧版日期Date/Calendar以及java.time全家桶LocalDateTime、Instant、ZonedDateTime等、BigDecimal/BigInteger、UUID、Enum等常见值类型SPI 文件声明loadSpiAllowTypeList读取META-INF/satoken/sa-json-type.list中的类名列表空行与#开头的注释行会被忽略便于各插件声明自己的允许类型SaJsonType标记接口所有实现了该标记接口的类均被允许用户自定义注册registerAllowType(Class)在初始化前手动注册。3.3 关键约束与警告从SaJsonStrategy源码可以看出两个必须注意的约束注册时机isInit()为true即getSaJsonAllowTypeList()已被调用过之后registerAllowType(Class)会抛出SaTokenException。因此自定义类型注册必须在 JSON 插件初始化之前完成——比如在main方法或 Spring 启动前调用强烈不建议注册Object.class注册Object.class等同于放开全部类型限制。源码会向System.err输出郑重安全警告明确提示class/type等类型标记可被用来实例化 classpath 上任意类型生产环境强烈不建议这么做。3.4 Jackson 插件的落地方式在 SaJsonTemplateForJackson.java 的构造器中插件通过buildAllowTypeValidator()依据SaJsonStrategy.instance.getSaJsonAllowTypeList()构建PolymorphicTypeValidator再配合activateDefaultTyping启用默认类型——即序列化时嵌入类型信息class属性反序列化时仅接受白名单内的类型。同一批安全更新还包含Snack3 序列化不再写入类型信息对齐 fastjson 的安全策略JSON 反序列化容错优化参考sa-token-serializer-features等模块提升不同数据源下的健壮性。四、HTTP 请求扩展插件SaHttpTemplate 的统一抽象4.1 新增两个实现v1.46.0 新增了sa-token-rest-client与sa-token-rest-template两个 HTTP 请求插件分别基于 Spring 6.1 的RestClient与经典RestTemplate实现统一接口SaHttpTemplate接口定义见 SaHttpTemplate.java配套文档见 plugin/http-extend.md。以 SaHttpTemplateForRestClient.java 为例内部持有RestClient.create()实现get(url)与postByFormData(url, params)两个方法其中 POST 以application/x-www-form-urlencoded提交表单数据并统一通过SaManager.log输出 debug 级别的请求/响应日志便于排查 SSO 等远程交互链路public class SaHttpTemplateForRestClient implements SaHttpTemplate { private final RestClient restClient RestClient.create(); Override public String get(String url) { SaManager.log.debug(发起请求GET{}, url); String res restClient.get().uri(url).retrieve().body(String.class); SaManager.log.debug(返回结果{}, res); return res; } // postByFormData(url, params)以表单格式 POST 并返回字符串结果 }4.2 使用场景该抽象主要服务于SSO 客户端与认证服务器的 HTTP 通信为后续扩展更多底层 HTTP 客户端如 OkHttp、Forest 等提供统一插槽方便接入方按自身技术栈替换实现。五、Redis / Redisson 数据层增强v1.46.0 对 Redis 数据访问层做了多项修复与增强直接影响使用 Redis 存储会话的稳定性。5.1 TTL 保持SET KEEPTTLsa-token-redis-template及 jdk-serializer 版本修复了update key 时 TTL 偏移的问题issues #I80P5O、#ICWJOQ。根因是旧的更新操作会重置过期时间导致 Token 被意外续命。修复后SaTokenDaoForRedisTemplate.java 的 update 方法使用RedisSET KEEPTTLExpiration.keepTtl()原子保留原 TTL前提是Redis 版本 6.0对于Redis 6.0 以下版本文档补充了替代方案将 update 方法替换为毫秒级 TTL 写回写法。相关说明同步到了 more/common-questions.md 与 up/integ-redis.md低版本用户按文档替换即可规避报错。5.2 searchData 由 KEYS 改为 SCANredis-template 的searchData从KEYS命令改为SCAN游标方式ScanOptionsconnection.scan既避免阻塞主线程也兼容低版本 Spring Data Redis参考 issue #702。源码中wrapKey也被抽为可重写方法开发者可以自定义键前缀策略。5.3 Redisson Dao 增强SaTokenDaoForRedisson.java 的改进点支持指定 Codec提供SaTokenDaoForRedisson(RedissonClient, Codec)构造器默认使用StringCodec.INSTANCE与业务方 RedissonClient 的全局 Codec 隔离避免序列化器互相干扰update 使用setAndKeepTTL基于RBucket.setAndKeepTTL()原子保留原过期时间同样要求 Redis 6.0低版本有毫秒写法替代同时补充了按配置决定是否启用 Redis的示例参考 issue #I9I4ZG方便多环境切换。5.4 sa-token-alone-redisson 独立连接插件v1.46.0 新增sa-token-alone-redisson插件文档见 plugin/alone-redisson.md示例工程见sa-token-demo-alone-redisson等目录与既有sa-token-alone-redis插件形成互补用于让权限缓存与业务数据缓存使用独立的 Redis 连接。从 SaAloneRedissonRegister.java 的源码结构看其核心逻辑是读取独立连接配置SaAloneRedissonProperties基于独立的RedissonClient构建new SaTokenDaoForRedisson(aloneClient)并注册为SaTokenDaoBean从而覆盖业务 RedissonClient 对应的 Dao实现权限数据与业务数据的连接级隔离。测试用例位于sa-token-plugin/sa-token-alone-redisson/src/test/下含纯单测与 Spring 环境单测两个场景。六、Session 类型安全集合读取v1.46.0 为 Session 数据读取新增了类型安全集合 APIgetList/getSet/getMap定义在 SaGetValueInterface.java接口被SaSession继承使用default T ListT getList(String key, ClassT elementClass) { ... } default T SetT getSet(String key, ClassT elementClass) { ... } default K, V MapK, V getMap(String key, ClassK keyClass, ClassV valueClass) { ... }调用时传入元素/键值的具体 Class读取时自动完成反序列化与泛型转换避免手工List?强转带来的ClassCastException。对应的SaSetValueInterface还提供了带兜底函数的三参重载如getList(key, elementClass, fun)当值为 null 时执行fun获取默认值并写入配合 JSON 白名单机制可安全存取带类型信息的复杂对象。七、SSO 单点登录安全与功能增强v1.46.0 对 SSO 模块做了集中加固指定账号单点注销SSO 客户端新增指定账号单点注销 API可精确注销某个账号而非全部会话StpInterface.isDisabled补充loginType参数方法签名从isDisabled(loginId, service)演进为isDisabled(loginId, service, loginType)见 StpInterface.java使账号封禁判断可以按登录类型区分StpLogic.isDisableLevel 内部即通过SaManager.getStpInterface().isDisabled(loginId, service, loginType)完成查询buildServerAuthUrl健壮性增强识别 URL 编码后的back参数back为空时跳过追加并强化重定向编码/解码防止参数被截断或二次编码错乱NoSdk 模式签名校验强化demo 的签名校验补充时间窗与nonce 防重放配合SsoSignUtil该工具在 v1.45.0 的 NoSdk 补全中引入文档见 sso/sso-nosdk.md提升无 SDK 集成场景的抗重放能力安全漏洞修复OAuth2/SSO 的redirect参数绕过 allow-url 校验漏洞已修复重定向目标必须通过域名白名单校验。八、安全与健壮性多项底层增强v1.46.0 还包含一批跨模块的安全与健壮性改进allowLoginIdColon配置项默认false禁止 loginId 包含冒号:。该校验位于 StpLogic.checkLoginArgs// 3、账号 id 不能包含冒号:除非配置 allowLoginIdColontrue if( ! Boolean.TRUE.equals(getConfigOrGlobal().getAllowLoginIdColon()) id.toString().contains(:)) { throw new SaTokenException(loginId 不能包含冒号:).setCode(SaErrorCode.CODE_11018); }配置项定义在 SaTokenConfig.java默认值false。之所以限制冒号是因为 token 解析与 Session 存储中冒号通常作为分隔符允许冒号可能引入歧义确有特殊账号需要包含冒号时可显式配置allowLoginIdColontrue放开有校验与告警机制兜底需自行评估风险。随机字符串/数字改用 CSPRNGtoken 随机串生成从普通随机源切换为SecureRandom降低 token 被预测的概率JWT extraData 禁止包含保留字段防止扩展数据覆盖 JWT 标准声明见sa-token-jwt插件SaRequest/SaResponse/SaStorage创建策略通过SaStrategy中的SaCreateSaRequestFunction/SaCreateSaResponseFunction/SaCreateSaStorageFunctionSaStrategy.java允许自定义请求/响应/存储对象的创建方式便于适配非标准 Web 容器参考 issue #841Context Filter 注册 REQUESTASYNC修复 SSE/Flux 流式返回场景下上下文未初始化的缺陷issues #IC4XFE、#ICB9OJgetSaTokenConfig策略SaStrategy新增getSaTokenConfig函数默认为 null启用后接管SaManager.getConfig()的返回值支持从外部如配置中心动态提供配置来源isLastingCookie为 null 时getCookieTimeout不再 NPE修复 Cookie 超时计算空指针WebFlux/Gateway 兼容修复 Boot3 WebFlux/Gateway 下setStatus的NoSuchMethodErrorreactor starter 结构调整issues #IIAW1A、#916、#IHRIBYisUrl支持 IPv6 方括号地址并拒绝裸 IPv6sa-token-dependencies不再锁定 Reactor 版本避免与 Spring Cloud Gateway 冲突issue #622。九、如何获取与验证这些特性9.1 版本与依赖框架版本号已升级至1.46.0可通过 Maven 中央仓库引入javadoc/sources/gpg 仅在发布 Maven 中央时启用BOM 模块补齐了sa-token-caffeine与sa-token-loveqq-boot-starter统一依赖版本管理可参考 sa-token-bom/pom.xml 与 sa-token-dependencies/pom.xml。9.2 示例工程对照更新日志中多次提到的特性都有对应示例与测试可对照学习HTTP 插件sa-token-plugin/sa-token-rest-client、sa-token-plugin/sa-token-rest-template源码及测试SSO 增强sa-token-plugin/sa-token-sso源码配合 sso/sso-apidoc.md 与 sso/sso-nosdk.md 文档Redisson 独立连接sa-token-plugin/sa-token-alone-redisson及sa-token-demo-alone-redisson/sa-token-demo-alone-redisson-sb4示例Redis 数据层sa-token-plugin/sa-token-redis-template下的SaTokenDaoForRedisTemplateSearchDataTest等测试验证了 SCAN 搜索行为JSON 安全sa-token-plugin/sa-token-jackson/sa-token-jackson3/sa-token-snack3/sa-token-fastjson插件源码与测试以及 plugin/custom-serializer.md 文档。9.3 升级注意事项速查清单关注点说明Redis 版本update 方法依赖SET KEEPTTLRedis 6.0可无缝使用低版本需替换为毫秒 TTL 写法见 common-questions.md / integ-redis.mdJSON 白名单自定义反序列化类型需在 JSON 插件初始化前通过SaJsonStrategy.registerAllowType注册切勿注册Object.class放开限制loginId 冒号默认禁止:特殊账号需显式开启allowLoginIdColonSSO 回调back参数现在支持 URL 编码形式重定向会统一编解码老链路如有手工编码需对齐新行为WebFluxBoot3 请使用新版 reactor starter 结构setStatus不再冲突十、总结Sa-Token v1.46.0 是一次安全加固 集成扩展并重的版本一方面通过 JSON 类型白名单、CSPRNG 随机源、redirect 校验等手段系统性收紧了框架的安全边界另一方面通过注销前侦听器、类型安全集合 API、HTTP 请求抽象、Redisson 独立连接等能力扩展了框架在多会话管理、分布式存储与异构集成场景下的可用性。对于升级用户而言重点关注 Redis 版本兼容与 JSON 白名单注册时机两个前置条件即可平滑迁移。本文对应的完整变更记录可在仓库根目录的 update-log.md 中持续跟踪。【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架让鉴权变得简单、优雅—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考