Redis 与缓存 / 系统课时
排查 Redis 无法连接
排查 Redis 无法连接
Redis 无法连接时,应先区分“服务根本没有监听”“网络到不了”和“已经连到 Redis 但认证失败”。按进程、监听地址、网络、认证和客户端参数逐层检查,可以避免在防火墙、密码和 Redis 配置之间反复试错。
学习目标
- 根据错误现象快速判断故障位于服务端、网络层还是认证阶段
- 检查 Redis 进程、监听地址、端口和网络可达性
- 验证 ACL、密码、TLS 与客户端连接参数是否一致
从本机确认进程和监听端口
如果报错是 Connection refused,优先确认 Redis 进程是否存在以及目标端口是否真的在监听。下面以 Linux 为例,<PORT> 应替换为 Redis 实际端口。
pgrep -a redis-server
ss -lntp | grep ':<PORT>'
redis-cli -h 127.0.0.1 -p <PORT> PING预期输出
<PID> redis-server 127.0.0.1:<PORT>
LISTEN 0 <VALUE> 127.0.0.1:<PORT> 0.0.0.0:* users:(("redis-server",pid=<PID>,fd=<VALUE>))
PONG如果 pgrep 没有结果,应先恢复 Redis 进程;进程存在但 ss 查不到目标端口时,应检查实际配置文件、启动参数和启动日志。本机 PING 能返回 PONG,说明 Redis 服务自身至少能够接受本地 TCP 请求。
检查 bind、端口和访问路径
本机能连接但远程不能连接时,重点检查 Redis 实际监听的地址。若只监听 127.0.0.1,远程客户端即使网络畅通也无法直接访问。不要为了省事把 Redis 无条件暴露到公网,应通过内网、防火墙和访问控制共同限制来源。
可以在已能本地连接的机器上读取相关配置。实际可查询项会受到 Redis 版本和权限限制。
redis-cli -h 127.0.0.1 -p <PORT> CONFIG GET bind
redis-cli -h 127.0.0.1 -p <PORT> CONFIG GET port
redis-cli -h 127.0.0.1 -p <PORT> CONFIG GET protected-mode预期输出
bind
127.0.0.1
port
<PORT>
protected-mode
yes如果实际 bind、端口与客户端目标不一致,应修正配置并按部署方式安全重启或滚动变更。protected-mode 是额外的安全保护,不应通过关闭它来替代正确的网络隔离和认证配置。

再判断网络是否真正可达
远程连接超时通常意味着 TCP 路径没有建立,而不是密码错误。可以从应用所在主机直接测试目标 Redis 地址和端口。以下命令使用 Bash 的 TCP 能力,只判断端口是否可建立连接。
timeout 3 bash -c '</dev/tcp/<HOST>/<PORT>' && echo CONNECTED || echo FAILED预期输出
CONNECTED返回 FAILED 时,应沿客户端到 Redis 的实际路径检查主机防火墙、云安全组、Kubernetes NetworkPolicy、容器端口映射、路由和 DNS。TCP 尚未建立时,修改 Redis 密码不会解决问题。
区分认证失败与 TLS 不匹配
如果 TCP 已经可以建立,但 redis-cli 返回 NOAUTH 或 WRONGPASS,故障已经进入 Redis 协议层。启用了 ACL 的环境需要同时确认用户名和密码;建议通过环境变量传递密码,避免直接把密码写进命令参数和 Shell 历史。
export REDISCLI_AUTH='<PASSWORD>'
redis-cli -h <HOST> -p <PORT> --user <USER> PING
unset REDISCLI_AUTH预期输出
PONG如果服务端使用 TLS,客户端也必须使用对应的 TLS 端口和证书参数。明文客户端连接 TLS 端口,或 TLS 客户端连接普通端口,都可能表现为握手失败、连接被关闭或协议错误。
export REDISCLI_AUTH='<PASSWORD>'
redis-cli --tls --cacert <CA_PATH> -h <HOST> -p <TLS_PORT> --user <USER> PING
unset REDISCLI_AUTH预期输出
PONG<CA_PATH> 与 <TLS_PORT> 必须来自实际部署配置。生产环境还应校验证书信任链和主机名,不要通过跳过证书验证来长期绕过配置错误。
用最终连接参数完成验收
完成服务、网络和认证检查后,应回到应用真实使用的参数重新验证,包括主机名、端口、ACL 用户、密码来源、TLS 开关和连接超时。命令行测试成功而应用仍失败时,问题通常已经缩小到应用配置、环境变量覆盖或连接池初始化阶段。
export REDISCLI_AUTH='<PASSWORD>'
redis-cli -h <HOST> -p <PORT> --user <USER> PING
unset REDISCLI_AUTH预期输出
PONG最终以应用所在运行环境能够稳定得到 PONG 为准。按照“进程与监听 → TCP 网络 → 认证与 TLS → 客户端参数”的顺序检查,可以让每一步都明确排除一层故障,而不是依赖反复修改配置碰运气。