企业官网建设流程全解析

Sa-Token 是一款开源、免费的轻量级 Java 权限认证框架，主要解决：登录认证、权限认证、单点登录、OAuth2.0、微服务网关鉴权等一系列权限相关问题。🔐

目前最新版本v1.46.0已推送至Maven中央仓库🎉，大家可以通过如下方式引入：

<!-- Sa-Token 权限认证 --><dependency><groupId>cn.dev33</groupId><artifactId>sa-token-spring-boot4-starter</artifactId><version>1.46.0</version></dependency>

Spring Boot 3.x 请改用sa-token-spring-boot3-starter，Spring Boot 2.x 请改用sa-token-spring-boot-starter。

该版本包含大量 ⛏️️️新增特性、⛏️底层重构、⛏️️️代码优化 等，下面容我列举几条比较重要的更新内容供大家参阅：

📦 更新点1：新增sa-token-fory-json插件，JSON 方案再添一位

这是官方规划里「JSON 模块集成 Apache Fory」的落地，把 Fory JSON 接到SaJsonTemplate上。

此前 Session / Redis 序列化主要是 Jackson（Boot 默认，JSON 里会写@class）和 Fastjson2 / Snack（默认不写类型信息）。相对 Jackson：Fory 官方文档给出的吞吐更高，且默认不写类型信息，避开多态反序列化那条面；相对 Fastjson2：用法接近，适合已经在用 Apache Fory、或不想再绑 Fastjson 栈的项目。引入后 SPI 自动注入，不用自己包一层。

<!-- Sa-Token 整合 Apache Fory JSON --><dependency><groupId>cn.dev33</groupId><artifactId>sa-token-fory-json</artifactId><version>1.46.0</version></dependency>

JSON 插件全家桶现在是：Jackson、Jackson3、Fastjson、Fastjson2、Fory JSON、Snack3、Snack4。Boot 2/3 默认仍是 Jackson，Boot 4 默认 Jackson3，用得顺不必为了换而换。

在线文档：JSON 序列化扩展 🔗

🌐 更新点2：新增sa-token-rest-client/sa-token-rest-template插件

SSO 模式三的 ticket 校验、单点注销、消息推送都要发 HTTP。此前只有 Forest、OkHttps 两套第三方客户端。Spring 项目本来就有spring-web，再为 SSO 拉一套 HTTP 库，依赖和 API 都多一层。

本版按官方规划补上 Spring 官方客户端：sa-token-rest-template、sa-token-rest-client。相对 Forest / OkHttps：不引入第三方 HTTP 栈，跟 Spring 一条线。RestClient相对RestTemplate：它是 Spring Framework 6.1+ / Boot 3.2+ 的官方继任者，Boot 4 里RestTemplate已标记 deprecated，新项目优先 RestClient。Boot 2 或 Boot 3.0–3.1 没有RestClient，继续用 RestTemplate 或 Forest。

<!-- Spring Boot 3.2+ / 4 优先 RestClient --><dependency><groupId>cn.dev33</groupId><artifactId>sa-token-rest-client</artifactId><version>1.46.0</version></dependency>

同一 classpath 只放一个 HTTP 插件。没配任何处理器会报错误码 30010。本版还加了 SSO Client 的 Spring Boot 4 示例。

在线文档：HTTP 请求扩展 🔗

🗄️ 更新点3：新增sa-token-alone-redisson插件，权限缓存和业务缓存拆开

来自 GitHub #710、Gitee #ICE2V0：alone-redis 要能配独立 Redisson。

升级有什么用：现在redisson集成也可以做到权限缓存和业务缓存分离了，会话数据和业务 Redis 不再挤在同一个 Client 上，key 冲突、误删、codec 打架都能避开。Boot 4 另有sa-token-alone-redis-by-spring-boot4。

<dependency><groupId>cn.dev33</groupId><artifactId>sa-token-alone-redisson</artifactId><version>1.46.0</version></dependency>

引入后不必再引sa-token-redisson/sa-token-redisson-spring-boot-starter。

sa-token:alone-redisson:config:singleServerConfig:address:"redis://127.0.0.1:6379"database:2

config与file二选一。示例覆盖单机、集群、Boot 3/4。

Boot 4 注意：Redisson 3.45 的 starter 仍引用已移除的RedisAutoConfiguration，不要引redisson-spring-boot-starter，自己注册 Bean。SaTokenDaoForRedisson默认StringCodec，并可用setAndKeepTTL原子保留 TTL。fix: #791

在线文档：独立 Redisson 插件 🔗

🔧 更新点4：RedisTemplate 检索改 SCAN、update 保 TTL、key 可加前缀

这几条都是社区老工单：

• searchData用 KEYS 会堵 Redis：#702
• update 后续期 TTL 偏移：#I80P5O、#ICWJOQ
• 多项目共用 Redis 要加前缀：#956

升级有什么用：在线用户查询不再KEYS *；改 Session 不会把过期时间抹成「再活一整段 timeout」；多系统共 Redis 可以wrapKey隔离开。

publicclassMySaTokenDaoextendsSaTokenDaoForRedisTemplate{@OverridepublicStringwrapKey(Stringkey){return"my-app:"+key;}}

KEEPTTL 需要 Redis >= 6.0。

🔔 更新点5：注销前侦听器，会话清掉之前还能读现场

来自 sa-token 小助手用户「潮汐」的建议：侦听器触发时设备信息往往已经没了，审计不好记。

升级有什么用：踢人、顶人、主动注销前，还能读到 Token-Session、设备列表，写日志、发通知不用自己抢时序。

@OverridepublicvoiddoBeforeLogout(StringloginType,ObjectloginId,StringtokenValue,SaLogoutParameterlogoutParameter){SaSessionsession=SaManager.getStpLogic(loginType).getSessionByLoginId(loginId,false);SaTerminalInfoterminal=session==null?null:session.getTerminal(tokenValue);// 记注销日志}

对应钩子：doBeforeLogout/doBeforeKickout/doBeforeReplaced。不要用StpUtil读当前请求上下文，用参数里的loginId、tokenValue去查。

在线文档：全局侦听器 🔗

📋 更新点6：Session 新增getList/getSet/getMap

本版主动补齐。以前从 Session 取集合，要么get完再强转，要么自己处理 Redis 回来的裸 List。现在把元素类型写在参数上，主要是为了让代码写得更优雅，调用更友善。

// 以前@SuppressWarnings("unchecked")List<SysUser>users=(List<SysUser>)session.get("users");// 现在List<SysUser>users=session.getList("users",SysUser.class);Set<String>roles=session.getSet("roles",String.class);Map<String,Long>scoreMap=session.getMap("scoreMap",String.class,Long.class);// 缺 key 时给默认集合session.getList("users",SysUser.class,ArrayList::new);

OAuth2 索引、SSO Client 列表、ApiKey 索引也切到这套 API，业务侧同一套写法。

在线文档：Session 会话 🔗

🚪 更新点7：SSO 客户端支持按账号单点注销

社区提案：子系统删用户时，希望一行 API 通知认证中心把该账号全端打下线。

升级有什么用：后台封号、离职回收，不必再自己拼 SSO 推送报文。

// sso-serverSaSsoServerUtil.ssoLogout(loginId);// sso-client（本地 loginId，框架按策略转成认证中心 id）SaSsoClientUtil.ssoLogout(loginId);

在线文档：Sa-Token SSO 单点注销 🔗

🧩 更新点8：SaRequest/SaResponse/SaStorage可策略创建

来自 GitHub #841：旧版靠继承SaTokenContextForSpring改上下文，v1.42 重构后那套父类没了。

升级有什么用：Nginx 改 URI、自定义 Request 包装，改策略函数即可，不用再继承已删除的上下文类。

SaStrategy新增createSaRequest/createSaResponse/createSaStorage。getSaTokenConfig也可接管配置来源，方便从数据库读 Sa-Token 配置。

⚠️ 更新点9：两处不向下兼容，升级先看

1）allowLoginIdColon默认 false。官方一直强调 loginId 不要带冒号（持久化 key 用:分段）。本版源码直接拒登。存量项目如果 loginId 里真有冒号：

sa-token:allow-login-id-colon:true

2）StpInterface.isDisabled增加loginType参数。自己实现了封禁查询的，要改方法签名。

另外：JWTextraData禁止写入loginType、loginId、deviceType、eff、rnStr等保留字段，撞名会直接抛错。

🛡️ 更新点10：修复 OAuth2 / SSOredirect绕过allow-url漏洞

来自社区用户提交的漏洞报告：OAuth2 调用/oauth2/doConfirm时，redirect_uri校验可被绕过；本版审查后确认 SSO 的redirect存在同类问题。

触发条件为（需同时满足）：

1. 项目搭了SSO 认证中心或OAuth2 授权服务器；
2. 请求里可以由前端（或攻击者）传入redirect/redirect_uri；
3. allow-url配了不安全通配（如http://domain*，*出现在域名部分，前面不是/或:）。

普通登录鉴权、没用 SSO/OAuth2 的项目，与这条无关。allow-url: "*"等于主动放开白名单，也不在本条讨论范围。

会造成：ticket 或授权码被下发到第三方站点。

新版本：SSO 与 OAuth2 两侧同时拒绝@、%40、%2540；*只能出现在最后一位，且前一位必须是/或:；isUrl支持 IPv6 方括号地址。生产环境请把allow-url配成明确地址。用了 SSO/OAuth2 的，建议升到 v1.46.0。

sa-token:sso-server:clients:sso-client1:allow-url:http://sa-sso-client1.com:9003/*

感谢这位社区用户提交的漏洞报告。

🔐 更新点11：修复 Jackson 多态反序列化漏洞，新增类型白名单

这是本版对 JSON 反序列化路径的主动审查：使用 Jackson / Jackson3 把SaSession写入 Redis 时，JSON 里会带@class类型标记；旧版本未限制严格限制反序列化类型白名单，可能会在反序列化时触发 classpath 上的任意类。

触发条件为（需同时满足）：使用SaJsonTemplate去反序列化业务中未严格审查的 json 字符串。

fastjson/fastjson2/fory-json/snack3默认不写类型标记，一般不走这条面。不去使用SaJsonTemplate去反序列化业务中未严格审查的 json 字符串。本版起sa-token-snack3也不再写入类型信息。

会造成：攻击者提交恶意 json 字符串，可能触发多态反序列化 RCE。

新版本：增加SaJsonStrategy全局类型白名单，只允许白名单内类型参与这类反序列化。JDK 常见值类型、框架已实现SaJsonType的 Model 默认在名单里；你的业务实体默认不在。用了 Jackson 且 Session 里存了自定义对象的，升级后可能看到：

无法反序列化的类型：com.pj.model.SysUser，请先将其注册到 JSON 全局类型白名单

推荐让实体实现SaJsonType：

publicclassSysUserimplementsSaJsonType{// ...}

也可以在SpringApplication.run之前调用SaJsonStrategy.instance.registerAllowType(SysUser.class)，或在META-INF/satoken/sa-json-type.list按行写完整类名。JSON 插件初始化后再注册会失败。不要登记Object.class。用了 Jackson + SaJsonTemplate 反序列化业务 json 字符串的，建议升到 v1.46.0，并先把业务类型登记进白名单。

在线文档：JSON 序列化扩展 🔗

📡 更新点12：修复 SSE / Flux 上下文未初始化，以及 Boot3 WebFluxsetStatus

这两条都是社区报错工单：SSE 来自 Gitee #IC4XFE、#ICB9OJ；setStatus来自 #IIAW1A、GitHub #916。

SSE / Flux

在之前的版本中，SpringMVC 接口如果返回SseEmitter、Flux等异步、流式结果，随后再调StpUtil/SaHolder会报：

cn.dev33.satoken.exception.SaTokenContextException: SaTokenContext 上下文尚未初始化

这是因为 Context Filter 只注册了REQUEST。流式返回会再走一遍ASYNCdispatch，过滤器没挂上，ThreadLocal 上下文是空的。普通@RequestMapping一问一答不受影响。

新版本把 Filter 注册为REQUEST+ASYNC，二次 dispatch 也会初始化上下文，一般不用再手改 Filter。

Boot3+ WebFlux / GatewaysetStatus

在之前的版本中，Boot3+ 的 WebFlux 或 Gateway 里调用：

SaHolder.getResponse().setStatus(401);

会报：

java.lang.NoSuchMethodError: 'org.springframework.http.server.reactive.ServerHttpResponse setStatusCode(org.springframework.http.HttpStatus)'

这是因为 Boot2 的ServerHttpResponse.setStatusCode吃HttpStatus，Boot3 改成了HttpStatusCode，旧 Reactor starter 字节码对不上。WebMVC 用户与这条无关。

新版本拆了 Boot2 / Boot3+ 的 Reactor 实现，Boot3+ 走HttpStatusCode.valueOf(sc)，不再报错。sa-token-dependencies也不再锁死 Reactor 版本，避免跟 Spring Cloud Gateway 打架。fix: #622

📚 更新点13：文档站启用 .com 顶级域名，博客、多语言、安全策略

域名从sa-token.cc迁到 sa-token.com，请即使修改书签。独立博客上线；文档站暗色主题 5 种 IDE 风格；translate.js 多语言；README 有英/日/韩/俄/繁中。

随机数改用SecureRandom。新增SECURITY.md：安全问题走 GitHub Private Vulnerability Reporting 或邮件，不要开公开 Issue。

文档版本选择器改为动态加载。Solon 插件由 PathAnalyzer 换成 PathMatcher。

感谢 @Ran 补充SECURITY.md（fix #932、#877）；感谢 @noear 适配 Solon PathMatcher（fix #IJTNJK）。

📜 完整更新日志

除了以上提到的几点以外，还有更多更新点无法逐一详细介绍，下面是 v1.46.0 版本的完整更新日志：

• core：
  • 新增：侦听器新增注销前钩子doBeforeLogout/doBeforeKickout/doBeforeReplaced。[重要]
  • 新增：StpInterface.isDisabled补充loginType参数。[不向下兼容]
  • 新增：新增allowLoginIdColon配置，默认禁止 loginId 包含冒号。[不向下兼容]
  • 修复：Jackson DefaultTyping 多态反序列化 RCE，新增SaJsonStrategy全局类型白名单。[重要][漏洞修复]
  • 新增：getSaTokenConfig策略支持自定义配置来源，方便从数据库中读取配置。
  • 新增：新增SaRequest/SaResponse/SaStorage创建策略。 fix: #841
  • 新增：Session 新增getList/getSet/getMap类型安全集合读取。
  • 修改：随机字符串/数字改用 CSPRNG（SecureRandom）生成。
  • 修复：isLastingCookie为 null 时getCookieTimeout不再 NPE。
  • 修复：isUrl支持 IPv6 方括号地址并拒绝裸 IPv6。
  • 修复：JSON 反序列化容错优化。 fix: #ICOTM8
• 插件：
  • 新增：新增sa-token-fory-jsonJSON 序列化插件。[重要]
  • 新增：新增 HTTP 请求扩展插件sa-token-rest-client/sa-token-rest-template。[重要]
  • 新增：新增sa-token-alone-redisson独立连接插件及 Spring Boot 3/4 示例。[重要]fix: #710、#ICE2V0
  • 新增：新增sa-token-alone-redis-by-spring-boot4插件及示例，实现 Spring Boot 4 下权限缓存与业务缓存分离。[重要]
  • 新增：SaTokenDaoForRedisson支持指定 Codec（默认StringCodec），update 方法改用setAndKeepTTL原子保留原过期时间。[重要]fix: #791
  • 修复：sa-token-redis-template及 jdk-serializer 在 update key 时 TTL 偏移的问题。[重要]fix: #I80P5O、#ICWJOQ
  • 修复：redis-templatesearchData由 KEYS 改为 SCAN。[重要]fix: #702
  • 新增：RedisTemplate Dao 支持重写wrapKey自定义键前缀。 fix: #956
  • 修复：sa-token-redis-template-jdk-serializerKEEPTTL 泛型编译错误。
  • 修复：Snack3 序列化不再写入类型信息，对齐 fastjson 安全策略。[漏洞修复]
  • 修复：集成 JWT 时extraData禁止包含保留字段。[不向下兼容]
  • 优化：升级 fastjson / fastjson2 至 2.0.64。
  • 优化：sa-token-dependencies不再锁定 Reactor 版本，避免与 Spring Cloud Gateway 冲突。 fix: #622
• starter：
  • 修复：Context Filter 注册 REQUEST+ASYNC，修复 SSE/Flux 流式返回上下文未初始化。[重要]fix: #IC4XFE、#ICB9OJ
  • 修复：Boot3+ WebFlux/GatewaysetStatusNoSuchMethodError。 fix: #IIAW1A、#916、#IHRIBY
  • 新增：新增 SSO Client Spring Boot 4 示例。
  • 新增：新增sa-token-demo-first-run首次运行引导示例。
  • 修复：demo-ssm 适配 v1.42.0+ 上下文机制。
• Solon：
  • 优化：sa-token-solon-plugin由 PathAnalyzer 适配改为 PathMatcher，优化 Config 示例。 merge: pr 364 fix: #IJTNJK
  • 优化：升级依赖 noear-redisx 至 1.8.5、noear-snack4 至 4.0.59。
• SSO：
  • 修复：OAuth2/SSOredirect参数绕过allow-url校验的安全漏洞。[重要][漏洞修复]
  • 新增：SSO 客户端新增指定账号单点注销 API。
  • 补全：补全最新版 SSO NoSdk 模式实现，新增SsoSignUtil。
  • 修复：buildServerAuthUrl识别 URL 编码后的 back 参数，back 为空时跳过追加，并增强重定向编码/解码健壮性。 fix: #842
  • 修复：getClient统一通过getClients查找以支持子类覆盖。
  • 修复：NoSdk demo 签名校验补充时间窗与 nonce 防重放。[漏洞修复]
  • 修复：订正 SSO-Client 接收消息推送地址的路由说明。
• OAuth2：
  • 修复：redirect参数绕过allow-url校验的安全漏洞。[重要][漏洞修复]
  • 修改：expiresTime为 -1 时按永久有效存储 Token。
  • 重构：doConfirm确认授权流程统一校验。
  • 重构：SaOAuth2Dao改用带 Class 参数的getObject反序列化。 fix: #IK5GYU
  • 修复：OAuth2 demo 拒绝授权时回传 state。
  • 新增：OAuth2 章节补充数据互通后的 token 过期策略说明。
• 文档：
  • 修改：全仓库域名 sa-token.cc 统一迁移至 sa-token.com。[重要]
  • 新增：上线独立博客系统，收录原创文章。[重要]
  • 新增：文档站点多语言切换（基于 translate.js）。[重要]
  • 新增：README 多语言版本（英文、日文、韩文、俄文、繁体中文）与切换入口。[重要]
  • 新增：新增SECURITY.md安全策略及联系邮箱。[重要]merge: pr 933 fix: #932、#877
  • 新增：文档站点暗色主题切换，支持 5 种 IDE 风格。
  • 新增：文档版本选择器改为动态加载（all-version-common.js）。 merge: pr 928 fix: #900
  • 新增：新增源码运行指南文档。
  • 新增：新增「Sa-Token 集成 Demos 示例大全下载」文档。
  • 新增：导航栏增加安全推荐与案例下拉菜单。
  • 优化：文档站点整体优化（侧边栏、首页、捐赠页、导航交互、API 手册等）。
  • 同步：同步公众号文章列表、博客列表、赞助者名单、企业登记案例。
  • 补充：补充 SSE/Flux 流式返回常见问题；补充按配置决定是否启用 Redis 的示例。 fix: #I9I4ZG
  • 修复：订正 API 手册、SSO/OAuth2/WebFlux/Dubbo 等文档错漏。
• 其它：
  • 新增：新增乐之者java B站视频教程链接。[重要]
  • 优化：统一日志文案用词，「帐号」改为「账号」。
  • 优化：统一 token 续期相关注释措辞。
  • 修复：修正 ConcurrentHashMap 的错误 import 路径。 merge: pr 359

更新日志在线文档直达链接：https://sa-token.com/doc.html#/more/update-log

🌟 其它

代码仓库地址：https://gitee.com/dromara/sa-token

框架功能结构图：