redis cluster 必须使用 redis-cluster 驱动，laravel 的 redis 驱动不支持集群协议；需配置 clusters 节点列表、禁用 redis.default、使用 predis ≥1.1；cache::tags() 和 scan 不可用；cache:clear 仅清单节点，需用 redis-cli --cluster flushall 清全集群。
Redis Cluster 驱动必须用 redis-cluster，不是 redis
Laravel 的 redis 驱动根本不支持 Redis Cluster 协议，硬设 'driver' => 'redis' 并指向集群节点列表，会直接报 Connection refused 或卡在 MOVED 重定向上。只有显式使用 redis-cluster 驱动才能让客户端（Predis 或 phpredis）启用集群模式分片逻辑。
实操建议：
- 确保
config/cache.php中'default' => 'redis-cluster'，且'stores.redis-cluster.driver'是'redis-cluster' -
config/database.php的redis.clusters必须定义，不能留空；redis.default要注释或删除，否则 Laravel 会优先加载它并忽略 clusters - 集群节点必须用数组形式列出，例如：
'clusters' => ['cache' => [['host' => '10.0.1.10', 'port' => 6379], ['host' => '10.0.1.11', 'port' => 6379]]]，不能写成单个host字符串 - 别指望
REDIS_URL=redis://...能自动解析集群 —— 它只适用于单点，集群必须手动配置节点列表
redis-cluster 驱动不支持 Cache::tags() 和 SCAN 命令
这是由 Redis Cluster 架构决定的：键被哈希到不同 slot，而 Cache::tags() 依赖服务端批量操作（如 KEYS + DEL），SCAN 类命令在跨节点时无法保证一致性。Laravel 会静默禁用这些功能，调用 Cache::tags('user')->put(...) 不报错但实际不生效。
常见错误现象：
- 缓存打标后无法通过
Cache::tags('user')->flush()清除，只能靠Cache::forget()逐个删 -
Cache::store('redis-cluster')->get('xxx')正常，但Cache::store('redis-cluster')->getMultiple(['a','b'])报错或返回空数组 - 用
redis-cli --cluster call手动执行KEYS会提示(error) CROSSSLOT Keys in request don't hash to the same slot
替代方案：业务层自己维护 tag → key 映射表，或改用单节点 Redis + Sentinel 模式保功能。
集群连接必须用 Predis，phpredis 不行
Laravel 10+ 默认倾向 phpredis，但它对 Redis Cluster 的支持极弱 —— 即使启用了 redis.so 扩展，redis-cluster 驱动仍会 fallback 到 Predis。强行指定 'client' => 'phpredis' 会导致 Class 'RedisCluster' not found 或连接后立即断开。
实操建议：
- 运行
composer require predis/predis，确保依赖存在 - 在
config/database.php的redis配置块中显式设'client' => 'predis' - Predis 版本需 ≥ 1.1，低于此版本不支持 RESP3 和部分集群重试策略
- 验证方式：在
php artisan tinker中执行app('cache')->getStore()->getConnection()->getCluster()->getNodes()，应返回节点列表而非异常
集群模式下 cache:clear 不清整个集群
php artisan cache:clear 默认只清理当前应用配置的 connection 对应的数据库（database 值），而 Redis Cluster 没有“DB”概念 —— 所有键按 slot 分布在多个主节点上。cache:clear 实际只向其中一个节点发 FLUSHDB，其余节点的键完全不动。
容易踩的坑：
- 执行
cache:clear后仍读到旧缓存，误以为命令失效 - 线上紧急清缓存时漏掉节点，导致数据不一致持续数小时
- 没意识到
cache:forget也受限于单节点，删键前得先算出 key 对应的 slot（CLUSTER KEYSLOT your:key）再连对应节点
真正清集群要用 redis-cli --cluster flushall，或在部署脚本里遍历所有主节点执行 redis-cli -h {host} -p {port} FLUSHALL。别省这一步。
