Redis集群必须使用redis.cluster.RedisCluster类，因其内置集群感知连接池，支持节点发现、槽映射缓存与故障转移；单机ConnectionPool完全无效，会触发MOVED/ASK错误；初始化需传startup_nodes列表，禁用外部connection_pool；关键参数是max_connections_per_node而非max_connections；须关闭health_check_interval=0，显式设置超时并启用retry_on_timeout；必须预热拓扑与连接池，且多key操作需保证同槽位。
Redis集群连接池必须用redis.cluster.RedisCluster，不能复用单机ConnectionPool
单机ConnectionPool对集群完全无效——它只管一个节点，而Redis Cluster有多个分片、自动重定向、MOVED/ASK错误处理等机制。直接套用单机配置会触发redis.exceptions.ResponseError: MOVED或redis.exceptions.ClusterDownError，且连接无法自动路由到正确槽位。
必须使用redis.cluster.RedisCluster类，它内部封装了集群感知的连接池管理逻辑，支持节点发现、槽映射缓存、故障转移重试。初始化时传入的是节点列表（不是单个host/port），例如：RedisCluster(startup_nodes=[{"host": "node1", "port": 6379}, {"host": "node2", "port": 6379}])。
- 不要在
RedisCluster构造中传connection_pool参数——它不接受外部ConnectionPool实例 -
startup_nodes只需提供至少一个可连通的集群节点，客户端会自动获取完整拓扑 - 若集群启用了密码，必须统一设置
password，且所有节点密码一致；否则部分节点认证失败导致NOAUTH
max_connections_per_node才是集群场景的关键参数，不是max_connections
集群模式下没有全局max_connections，而是每个节点独立维护连接池。max_connections_per_node控制单个Redis节点最多持多少空闲+活跃连接。设太小会导致频繁阻塞在get_connection()；设太大则可能压垮单个节点（尤其当集群节点数少、流量倾斜时）。
典型配置参考：16节点集群，QPS峰值3000，平均命令耗时150ms → 单节点理论并发连接需求 ≈ 3000 / 16 × 0.15 ≈ 28，建议从max_connections_per_node=40起步，观察CLIENT LIST中各节点连接数分布。
立即学习“Python免费学习笔记（深入）”；
- 该参数默认为
None（不限制），生产环境必须显式设置，否则系统文件描述符极易耗尽 - 连接数监控应按节点粒度进行，
redis-cli -h nodeX -p 6379 CLIENT LIST | wc -l比看总连接数更有意义 - 不要与单机模式混淆：集群里
max_connections参数会被忽略，强行传入也不会生效
健康检查和超时必须按集群特性调优，health_check_interval要设为0
集群节点可能动态上下线，但RedisCluster的默认健康检查逻辑（基于PING）在集群模式下与CLUSTER NODES状态不同步，开启health_check_interval反而导致误判节点失效、频繁刷新拓扑、引发短暂路由混乱。
官方推荐集群模式关闭主动健康检查，改由拓扑刷新机制兜底：RedisCluster(..., health_check_interval=0, retry_on_timeout=True, socket_connect_timeout=2, socket_timeout=5)。
-
socket_connect_timeout和socket_timeout必须显式设值，否则默认None，超时可能长达数分钟 -
retry_on_timeout=True在集群中特别重要——网络抖动导致的TimeoutError常伴随MOVED重定向，重试能自动完成二次路由 - 集群不支持
decode_responses=True（会报NotImplementedError），所有响应仍是bytes，需手动.decode()
预热和拓扑缓存是高并发冷启动的刚需，别等第一个请求才建连
首次请求触发拓扑发现（CLUSTER SLOTS + CLUSTER NODES）会卡住整个线程，QPS突增时大量请求堆积，形成“启动雪崩”。必须在应用启动阶段主动预热连接池并加载槽映射。
正确做法是调用cluster_slots = client.cluster_slots()（触发拓扑拉取）+ 循环client.get_connection_by_key("preheat:key")建立若干连接，再归还：
from redis.cluster import RedisCluster
client = RedisCluster(startup_nodes=[...], decode_responses=False)
# 预热：强制拉取拓扑并建立连接
try:
client.cluster_slots() # 触发拓扑发现
for _ in range(8): # 预建8个连接
conn = client.get_connection_by_key("warmup")
client.connection_pool.release(conn)
except Exception as e:
# 拓扑不可达时记录告警，但不中断启动
pass
- 预热必须在主线程完成，不能放到异步任务里——否则首个HTTP请求仍会阻塞
- 拓扑缓存默认有效期60秒，高频变更集群（如扩缩容）需调低
topology_refresh_interval（最小10秒） - 预热连接数建议为
max_connections_per_node // 2，避免占用过多初始资源
集群连接池最易被忽略的点是：它不保证跨节点事务一致性，也不自动合并Pipeline结果。所有涉及多key的操作（如MGET跨槽）必须确保keys落在同一节点，否则会直接抛CrossSlotError——这和单机连接池的行为逻辑完全不同。
