企业官网建设流程全解析

Sa-Token Alone Redisson 插件实战：为权限数据单独配置独立 Redisson 连接，彻底分离业务缓存

【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架，让鉴权变得简单、优雅！—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token

Sa-Token 默认的 Redisson 集成会把权限数据（Token、Session、权限缓存）和业务缓存放在同一个RedissonClient上。当业务量增大、缓存策略需要隔离，或者出于故障隔离、资源管控的考虑时，可以为 Sa-Token 单独再起一个 Redis 连接——这正是sa-token-alone-redisson插件解决的问题。读完本文，你可以独立完成：依赖引入（含 Spring Boot 2/3/4 的差异处理）、config/file两种方式配置独立 Redisson 连接（单机/集群/哨兵）、理解插件如何注册独立的SaTokenDaoBean，并通过示例工程验证权限缓存与业务缓存确实落在不同的 Redis 上。

一、插件定位：默认集成与独立连接的差异

Sa-Token 的 Redisson 生态中有三个相关构件，定位各不相同：

典型业务场景是搭建两套 Redis：一个给业务的RedissonClient（例如database: 0），另一个专门存放 Sa-Token 的权限数据（例如database: 2）。两套连接在序列化、连接池、过期策略上互不干扰，业务侧对 Redisson 的全局 codec、线程池等定制也不会影响权限数据的存取。

二、引入依赖

引入sa-token-alone-redisson即可，无需再引入sa-token-redisson或sa-token-redisson-spring-boot-starter。从 插件 pom 可以看到，本插件已经传递依赖了sa-token-redisson，并内置了 Bean 注册类，引入即完成装配。

<!-- Sa-Token 插件：权限缓存与业务缓存分离（Redisson） --> <dependency> <groupId>cn.dev33</groupId> <artifactId>sa-token-alone-redisson</artifactId> <version>${sa.top.version}</version> </dependency> <!-- 业务 Redis（按需） --> <dependency> <groupId>org.redisson</groupId> <artifactId>redisson-spring-boot-starter</artifactId> <version>${redisson.version}</version> </dependency>

Gradle 方式：

implementation 'cn.dev33:sa-token-alone-redisson:${sa.top.version}' // 业务 Redis（按需） implementation 'org.redisson:redisson-spring-boot-starter:${redisson.version}'

Spring Boot 4 特别注意：当前 Redisson 3.45 的redisson-spring-boot-starter仍引用了已被移除的RedisAutoConfiguration，在 Boot 4 下不要引入该 starter，改为引入redisson核心包并自行注册RedissonClientBean。仓库中 sa-token-demo-alone-redisson-sb4 示例给出了标准写法：

@Configuration public class BusinessRedissonConfig { @Bean(destroyMethod = "shutdown") public RedissonClient redissonClient(@Value("${spring.redis.redisson.config}") String yaml) throws IOException { return Redisson.create(Config.fromYAML(yaml)); } }

注意sa-token-alone-redisson插件本身通过Redisson.create(...)手动创建连接，不依赖任何 Boot 版本的自动装配，因此无需 Boot 4 专用包。

三、配置独立连接（Redisson 原生 yaml）

本插件的配置项与官方spring.redis.redisson.config/spring.redis.redisson.file语法相同，使用 Redisson 原生 yaml：单机用singleServerConfig，集群用clusterServersConfig。

插件侧只有两个配置属性，定义在 SaAloneRedissonProperties 中，前缀为sa-token.alone-redisson：

config与file二选一，同时配置时优先config；两者都未配置时插件启动会抛出SaTokenException。

3.1 单机模式（内嵌 yaml）

sa-token: token-name: satoken timeout: 2592000 # Sa-Token 单独使用的 Redisson 连接 alone-redisson: config: | singleServerConfig: address: "redis://127.0.0.1:6379" database: 2 password: null spring: redis: # 业务使用的 Redisson 连接 redisson: config: | singleServerConfig: address: "redis://127.0.0.1:6379" database: 0 password: null

该示例与仓库中 单机 demo 的 application.yml 完全一致：Sa-Token 权限数据落在database: 2，业务缓存落在database: 0，实现同实例内的逻辑隔离；也可以将address指向完全不同的 Redis 服务器。

3.2 集群模式（内嵌 yaml）

sa-token: alone-redisson: config: | clusterServersConfig: nodeAddresses: - "redis://127.0.0.1:3000" - "redis://127.0.0.1:3001" - "redis://127.0.0.1:3002" password: null

对应仓库中的 集群 demo 配置，其中业务侧仍使用单机 Redis（singleServerConfig），展示了权限缓存走集群、业务缓存走单机的混合部署形态。

注意：Redis Cluster 没有 database 索引，集群配置里不要写database。

3.3 外置文件

# application.yml sa-token: alone-redisson: file: classpath:sa-redisson.yml

src/main/resources/sa-redisson.yml示例（单机）：

singleServerConfig: address: "redis://127.0.0.1:6379" database: 2 password: null

集群则把文件内容换成上面 3.2 节里的clusterServersConfig即可。哨兵模式同样走 Redisson 原生 yaml（sentinelServersConfig），按 Redisson 官方配置文档的格式填写即可。

从源码看，SaAloneRedissonRegister.openFile 对file的解析支持三种写法：classpath:前缀走ClassPathResource，file:前缀走FileSystemResource，无前缀时默认按 classpath 下相对路径解析；文件不存在会抛出未找到 Redisson 配置文件: xxx的明确异常。

3.4 完整示例工程

仓库中提供了四个可直接运行的示例，分别覆盖单机、集群、Spring Boot 3、Spring Boot 4 场景，配置可对照查看：

• 单机：sa-token-demo-alone-redisson
• 集群：sa-token-demo-alone-redisson-cluster
• Spring Boot 3：sa-token-demo-alone-redisson-sb3
• Spring Boot 4：sa-token-demo-alone-redisson-sb4

四、插件实现原理：独立 Client 与 @Primary Dao

整个插件的核心逻辑都在 SaAloneRedissonRegister 这一个配置类中，理解它就能完全掌握插件行为。

4.1 Bean 注册与生命周期

@Configuration @EnableConfigurationProperties(SaAloneRedissonProperties.class) public class SaAloneRedissonRegister implements DisposableBean { private RedissonClient aloneClient; /** * 使用独立连接注册 SaTokenDao，覆盖业务 RedissonClient 对应的 Dao */ @Bean @Primary public SaTokenDao saTokenDaoForAloneRedisson(SaAloneRedissonProperties properties) { this.aloneClient = Redisson.create(buildConfig(properties)); return new SaTokenDaoForRedisson(aloneClient); } @Override public void destroy() { if (aloneClient != null && !aloneClient.isShuttingDown()) { aloneClient.shutdown(); } } }

关键设计有三点：

1. 独立连接：直接调用Redisson.create(buildConfig(properties))创建客户端，不走 Spring 容器中的任何RedissonClientBean，从根源上保证与业务连接物理隔离；
2. @Primary注解：即使业务侧同时存在sa-token-redisson-spring-boot-starter提供的 Dao，本 Bean 也会优先注入，确保 Sa-Token 一定使用独立连接（不过按文档建议，二者只引入其一）；
3. 生命周期管理：实现DisposableBean，容器关闭时主动shutdown()独立客户端，避免连接泄漏。

4.2 配置解析规则

buildConfig静态方法实现了文档中“config 优先于 file”的规则：

public static Config buildConfig(SaAloneRedissonProperties properties) { try { Config config; if (StringUtils.hasText(properties.getConfig())) { config = Config.fromYAML(properties.getConfig()); } else if (StringUtils.hasText(properties.getFile())) { try (InputStream in = openFile(properties.getFile())) { config = Config.fromYAML(in); } } else { throw new SaTokenException("请配置 sa-token.alone-redisson.config 或 sa-token.alone-redisson.file"); } return config; } catch (SaTokenException e) { throw e; } catch (Exception e) { throw new SaTokenException("解析 sa-token.alone-redisson 配置失败", e); } }

解析失败（如 yaml 写错）会在启动阶段以SaTokenException快速暴露，便于尽早发现配置问题。该注册逻辑有对应的单元测试 SaAloneRedissonRegisterTest 和 Spring 环境测试 SaAloneRedissonRegisterSpringTest 验证。

4.3 序列化隔离：SaTokenDaoForRedisson 的 StringCodec

SaTokenDaoForRedisson默认使用StringCodec读写 Redis，这一点在 SaTokenDaoForRedisson 的构造器中体现：

/** * 使用默认 StringCodec */ public SaTokenDaoForRedisson(RedissonClient redissonClient) { this(redissonClient, StringCodec.INSTANCE); }

这意味着 Sa-Token 写入 Redis 的 value 是纯字符串（JSON 文本），与业务RedissonClient的全局 codec（如 Jackson、Kryo 等二进制编码）完全无关——即使业务侧把全局 codec 换成了序列化格式，权限数据依然以可读的字符串形式存储在独立连接的 Redis 中，不会互相污染。自 1.46.0 起还提供了SaTokenDaoForRedisson(redissonClient, codec)双参构造器，允许显式指定 codec。

五、验证效果：权限缓存与业务缓存各归其位

仓库中各 alone-redisson 示例工程的 TestController 提供了标准验证方式：

@RestController @RequestMapping("/test/") public class TestController { @Autowired RedissonClient redissonClient; // 测试 Sa-Token 缓存 --- http://localhost:8084/test/login @RequestMapping("login") public SaResult login(@RequestParam(defaultValue="10001") String id) { StpUtil.login(id); return SaResult.ok(); } // 测试业务缓存 --- http://localhost:8084/test/test @RequestMapping("test") public SaResult test() { redissonClient.getBucket("hello").set("Hello World"); return SaResult.ok(); } }

操作步骤：

1. 启动 Redis 后运行示例工程（单机 demo 端口为8084，集群 demo 为8085，sb3/sb4 demo 分别为8086等，以各自application.yml中server.port为准）；
2. 访问/test/login触发登录，StpUtil.login(id)会经由独立连接在database: 2中写入 Token 与 Session 数据；
3. 访问/test/test，注入的RedissonClient（来自业务侧 starter 或自注册 Bean）把hello键写入database: 0；
4. 分别连接两个 database（或两台 Redis）查看，即可观察到 Sa-Token 数据与业务数据各存其位，互不干扰。

六、注意点清单

• 引入本插件后，无需再引入sa-token-redisson或sa-token-redisson-spring-boot-starter，插件已包含 Dao 实现并完成注册；
• 业务代码注入的RedissonClient来自官方redisson-spring-boot-starter或你自己注册的 Bean，与 Sa-Token 使用的独立连接互不影响。Spring Boot 4 请自行注册 Bean，不要引入 3.45 的 starter；
• SaTokenDaoForRedisson默认使用StringCodec，与业务RedissonClient的全局 codec 无关，权限数据在 Redis 中始终为可读字符串；
• Redis Cluster 没有 database 索引，集群配置里不要写database；
• 哨兵模式走 Redisson 原生 yaml（sentinelServersConfig），格式与单机/集群同理；
• config与file同时配置时优先config，建议只保留一种，避免维护歧义。

小结

sa-token-alone-redisson插件通过“独立RedissonClient+@PrimaryDao 注册”的轻量设计，把 Sa-Token 权限缓存与业务缓存的物理隔离做到了配置化级别：只需一段 Redisson 原生 yaml，即可获得独立连接池、独立 database（或独立服务器）、独立故障域的权限存储，且对业务侧 Redisson 的任意定制完全免疫。仓库中单机、集群、SB3、SB4 四个 demo 工程覆盖了主流部署形态，可直接作为落地参照。

【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架，让鉴权变得简单、优雅！—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token