Redisson 配置实战：从单节点到集群的完整调优路径

Redisson 配置实战：从单节点到集群的完整调优路径

【免费下载链接】redissonRedisson: Valkey & Redis Java Client and Real-Time Data Platform. Sync/Async/RxJava/Reactive API. Over 50 Valkey and Redis based Java objects and services: Set, Multimap, SortedSet, Map, List, Queue, Deque, Semaphore, Lock, AtomicLong, Map Reduce, Bloom filter, Spring, Tomcat, Scheduler, JCache API, Hibernate, RPC, local cache..项目地址: https://gitcode.com/GitHub_Trending/re/redisson

服务刚迁完新机房，Redis 连接全线超时。翻遍文档才发现问题不在网络，而在 Redisson 配置：旧 YAML 写的是单节点块，新机房跑的主从架构，客户端根本没去发现主节点。配置方式选错，参数再漂亮也是白搭。下面按部署形态拆开讲，怎么配、配多少、出了问题往哪查。

先选模式：单节点、哨兵还是集群？

这一步只解决一个问题：你的部署形态对应 Redisson 配置里的哪一块。三种形态在配置上互斥，写错块就是"能连上也白搭"。

如果你只是本地开发或数据量小、没有高可用要求，选单节点。如果你有主从复制但还没到集群规模，选哨兵。如果数据量或写入量单主扛不住，选集群。

单机环境：最短可用配置到逐项调参

先把最小配置跑通，再谈调参。下面的 YAML 只有两行有效内容，Redisson.create之后getBucket能读写就通了：

singleServerConfig: address: "127.0.0.1:6379"

跑通之后，参数分两组看。

连接参数：控制"连不上时等多久、试几次"。

池化参数：控制"同一时刻能有多少条连接"。单节点场景只有普通池和订阅池（pub/sub 专用连接）两池。

singleServerConfig: address: "127.0.0.1:6379" password: "yourpassword" connectionPoolSize: 32 connectionMinimumIdleSize: 16 subscriptionConnectionPoolSize: 50

connectionPoolSize默认 64，connectionMinimumIdleSize默认 24；如果并发低于 32，可以按 并发数 × 2 收敛。等价 Java 写法三行：

Config config = new Config(); config.useSingleServer().setAddress("127.0.0.1:6379").setPassword("yourpassword"); RedissonClient client = Redisson.create(config);

哨兵模式：masterName 填错会怎样

哨兵配置的坑基本集中在三个字段：sentinelAddresses、masterName、scanInterval。完整写法如下：

sentinelServersConfig: masterName: "mymaster" sentinelAddresses: - "127.0.0.1:26379" - "127.0.0.1:26380" password: "yourpassword" scanInterval: 2000 failedSlaveReconnectionInterval: 3000

masterName填错会怎样？哨兵只按这个名字索引主从节点，名字不对，客户端问每个哨兵都得到空答案，于是进入"连不上主 → 重试 → 再问哨兵"的死循环，日志刷满连接失败，业务侧全部超时。白话讲：masterName不是 IP 也不是端口，是哨兵进程里给这个主从组起的名，在任一哨兵上执行SENTINEL masters第一个字段就是它。

另外两个易错点：sentinelAddresses建议至少给 2 个，挂一个还能问；scanInterval（默认 1000 ms）控制多久重新向哨兵拉一次主从拓扑，主从切换后的恢复速度直接取决于它，频繁切换的测试环境可以调小到 2000 以内。

集群模式：读写分离与连接池分开设

集群模式本节改用 Java 流式 API 写，和上面 YAML 对照着看。这段配置的关键不是节点列表，而是读写怎么走、池子怎么分：

Config config = new Config(); config.useClusterServers() .addNodeAddress("127.0.0.1:7000", "127.0.0.1:7001", "127.0.0.1:7002") .setReadMode(ReadMode.SLAVE) .setSubscriptionMode(SubscriptionMode.SLAVE) .setMasterConnectionPoolSize(16) .setSlaveConnectionPoolSize(32) .setMasterConnectionMinimumIdleSize(8) .setSlaveConnectionMinimumIdleSize(16) .setScanInterval(5000); RedissonClient client = Redisson.create(config);

四个概念拆开讲：

• readMode：SLAVE（默认）读请求走从节点，由负载均衡策略选一个；MASTER全部打主；MASTER_SLAVE主从混合。读多写少的业务保持默认，主节点压力会明显降下来。
• subscriptionMode：决定 pub/sub 订阅建在哪个节点上。集群里订阅连接是独占的，放从节点（SLAVE）可以保护主节点的连接数，只有主从延迟敏感的场景才用MASTER。
• 主从分池的理由：集群下每个主、每个从各自有独立连接池，masterConnectionPoolSize默认 64、slaveConnectionPoolSize默认 64，都是按节点算的，不是全局数。读走从节点时，从池要按"读并发 ÷ 从节点数"放大，主池按写并发收敛即可——一个值管两池的写法在集群下会失真。
• scanInterval（默认 5000 ms）：多久重新发现一次拓扑，扩缩容后多久生效看它。

Spring Boot 落地：starter 到自定义 Bean 的三档粒度

Spring Boot 集成按"你愿意写多少代码"分三档，由浅入深。

第一档：什么都不配。引完redisson-spring-boot-starter后，starter 会用spring.data.redis.*的 host/port/password 自动构建一个单节点配置，应用直接起。

第二档：指定 redisson.yml 路径。这是最常用的一档，把完整配置交给 YAML，只留一个指针：

spring: redis: redisson: file: classpath:redisson-config.yml

redisson-config.yml里就写上一节各形态的块。starter 的RedissonProperties还支持spring.redis.redisson.config，直接内联整段 YAML 字符串，适合配置中心下发。

第三档：手写@Bean。需要按环境动态算参数时用，注意加@ConditionalOnMissingBean之类的守卫，避免和 starter 自动装配打架：

@Bean(destroyMethod = "shutdown") @ConditionalOnMissingBean public RedissonClient redissonClient() { Config config = new Config(); config.useSentinelServers() .setMasterName("mymaster") .addSentinelAddress("26379 节点的地址"); return Redisson.create(config); }

三档里参数含义和前面完全一致，这里不重复。

调优三板斧：线程池、序列化、连接池

调参不靠拍脑袋，靠"默认值 + 计算公式"。下面三张表覆盖了 90% 的调优动作。

线程池（Config层，所有形态通用）：

序列化：

连接池：

一句话补充：timeout别为了掩盖慢查询无限调大，先查慢命令再动它。

排错手册：三类高频故障的排查动线 🔍

排错按"看日志 → 定参数 → 动手改"走，不走弯路。

连接超时：先找日志里Connection attempt to ... timed out这一行，它区分了是建连阶段还是命令阶段超时。再确认connectTimeout（建连）和timeout（命令）分别卡在哪一端，同时用redis-cli -h 目标 -p 端口 ping验证网络可达性。最后改：跨机房或公网场景把connectTimeout放宽到 10000 以上，同时把retryAttempts（默认 4）配合retryInterval让重试真正兜住瞬时抖动；如果日志反复出现"连旧 IP 失败"，检查 DNS 监控参数dnsMonitoringInterval（默认 5000 ms）。

序列化不兼容：症状是写成功、读报 codec 解析异常或类型转换错，且只有"新客户端读老 key"时出现。先确认当前codec配置和当初写入端的 codec 是否一致——老版本 Redisson 默认 Kryo，换过客户端语言或升级过 codec 策略时最容易踩。最后改：短期把codec切到JsonJacksonCodec平滑过渡（它按 key 自描述编码），长期统一团队 codec 规范。

集群节点发现失败：日志特征是启动时Connection attempt to cluster master node持续失败，或运行期出现 slot 覆盖不全的告警。先确认nodeAddresses里至少有一个能连通的节点——Redisson 从任一节点自动发现完整拓扑，其他地址只是加速起点，给满 6 个地址不保证更快，给进已下线的节点反而拖慢启动。再确认checkSlotsCoverage（默认 true，拓扑不完整会抛错）与scanInterval是否符合预期：缩容场景下可把scanInterval调小加速感知。

开发 / 测试 / 生产：三套配置各差在哪

生产环境额外注意：多可用区部署时客户端可能拿到内网地址，用natMapper做地址映射；哨兵/集群的池化参数要按节点数换算，别拿单节点的直觉套。

配置方式跟着部署形态走，调参跟着监控指标走。想深挖字段含义，从 Config.java 入手最准，文档入口见 docs/configuration.md。

【免费下载链接】redissonRedisson: Valkey & Redis Java Client and Real-Time Data Platform. Sync/Async/RxJava/Reactive API. Over 50 Valkey and Redis based Java objects and services: Set, Multimap, SortedSet, Map, List, Queue, Deque, Semaphore, Lock, AtomicLong, Map Reduce, Bloom filter, Spring, Tomcat, Scheduler, JCache API, Hibernate, RPC, local cache..项目地址: https://gitcode.com/GitHub_Trending/re/redisson