如何在PHP环境中配置Redis哨兵模式实现高可用_集成Predis库与连接池配置

ThinkPHP 6.x 中必须将 Redis 配置的 host 显式设为 null 才能触发哨兵逻辑；若 host 为 '' 或 'localhost'，则静默降级直连导致协议错误。

ThinkPHP 6.x 中必须禁用 host 才能触发哨兵逻辑

TP 6 默认的 Redis 连接器有个“小脾气”——它优先走直连模式。只要 host 不为 null 或空字符串，它就完全无视 sentinels 和 service 配置，直接尝试连接 host:port。结果可想而知：你明明配好了哨兵，却连上某个哨兵节点，然后卡在协议错误上——因为哨兵返回的是重定向响应，不是标准的 Redis 命令响应，两边对不上话。

正确的做法：显式把 'host' => null 写上去。别信什么“留空就行”，这里的 null 必须是 PHP 的 null，不是空字符串 ''，也不是 'localhost'。区别很大：

• host 设为 '' 或 '127.0.0.1'：静默降级为主机直连，故障时没有任何提示
• port 仍需保留（比如 6379），它会被用作 fallback 主端口，但实际不用于初始连接
• timeout 建议 ≥ 2.5，哨兵协商涉及多次往返，设得太低容易在启动时超时失败

Predis 是更稳妥的选择，但要手动指定驱动类型

phpredis 对哨兵的支持从 v5.3.0+ 才真正可用。很多 CentOS 7 默认装的是 5.2.x，这个版本会直接跳过哨兵逻辑、假装连上了主节点——结果是写入全部丢失且没有任何报错。Predis 没有这个坑，纯 PHP 实现，哨兵兼容性非常稳定。但 TP 不会自动 fallback，必须显式声明才行。

• 执行 composer require predis/predis 安装依赖
• 在 config/cache.php 的 Redis 配置中加 'type' => 'predis'
• Predis 的哨兵配置字段名不同：service 要写成 'replication' => 'sentinel'，并且需要额外传入 'parameters' => ['service' => 'myMaster', 'sentinels' => [...]]
• 别忘了 'scheme' => 'tcp'，否则 Predis 可能误用 unix socket

环境变量无法直接存数组，必须扁平化解析

.env 文件不支持嵌套结构，直接写 REDIS_SENTINELS=[{"host":"x","port":26379}] 会被当作字符串原样读取，env() 返回的是字符串，不是数组。但硬编码在配置里又会导致本地开发无法覆盖，两边不讨好。

正确的方式是把哨兵地址列表压成逗号分隔字符串，在运行时解析：

• .env 中写：REDIS_SENTINELS=10.0.1.10:26379,10.0.1.11:26379,10.0.1.12:26379
• 配置文件里用：array_map(fn($s) => ['host' => explode(':', $s)[0], 'port' => (int)explode(':', $s)[1]], explode(',', env('REDIS_SENTINELS', '')))
• 注意空值防御：如果 env('REDIS_SENTINELS') 为空，explode(',', '') 会返回 ['']，需要加 array_filter 清空这些空项

连接池启动失败常因哨兵响应慢，别只盯 timeout

TP 启动时会预热连接池，如果此时哨兵集群还没就绪，或者网络延迟较高，RedisSentinel::getMasterAddrByName() 就可能超时，整个应用启动失败。这不一定是配置写错了，而是时序问题。

• 检查哨兵是否真在监听：用 redis-cli -h 10.0.1.10 -p 26379 ping 确认每个哨兵可达
• 确认 service（即 master name）与哨兵配置中 sentinel monitor 的第一个参数完全一致——大小写敏感，不能有空格
• 如果用 phpredis，运行 php --ri redis 查版本；5.3.0 以下必须切 Predis，没有商量余地
• 连接池初始化失败时，TP 日志里通常只报 Connection refused 或空异常，得开 redis.log 或抓包看真实请求流向

哨兵配置最容易被忽略的点在于：它不是“填完就能用”的功能，而是一整套协同机制——客户端、哨兵节点、主从拓扑三者必须严格对齐。任意一环的名称、端口、版本不匹配，都会表现为“连得上但执行命令失败”这类静默异常，排查起来相当头疼。