项目用了Redis做缓存，启动时连不上Redis报错。这节讲Redis连接失败的排查方法，覆盖配置、端口、密码三个维度。
一、常见报错信息
Spring Data Redis报错
TEXT
Caused by: org.springframework.data.redis.RedisConnectionFailureException:
Unable to connect to Redis
Lettuce报错
TEXT
io.lettuce.core.RedisConnectionException:
Unable to connect to localhost:6379
Jedis报错
TEXT
redis.clients.jedis.exceptions.JedisConnectionException:
Could not get a resource from the pool
超时报错
TEXT
io.lettuce.core.RedisCommandTimeoutException:
Command timed out after 3s
二、排查维度1：Redis服务是否启动
Windows检查
Shell
# 检查Redis服务
sc query Redis
# 或在服务管理器查看
# Win+R → services.msc → 找Redis
如果服务没启动：
Shell
# 启动Redis服务
redis-server.exe --service-start
# 或手动启动（如果没有注册为服务）
cd D:\Java\Redis
redis-server.exe
Docker检查
Shell
# 查看Redis容器
docker ps | findstr redis
# 如果没运行，启动它
docker start my-redis
# 如果容器不存在，创建一个
docker run -d --name my-redis -p 6379:6379 redis:7.2
验证Redis是否正常
Shell
# 命令行连接测试
redis-cli ping
# 返回 PONG 说明正常
# 如果有密码
redis-cli -a 你的密码 ping
三、排查维度2：端口是否正确
检查Redis监听端口
Shell
netstat -ano | findstr 6379
输出包含LISTENING说明Redis在监听6379端口。
检查配置文件端口
TEXT
# redis.windows.conf 或 redis.conf
port 6379
确认配置文件里的端口和SpringBoot配置文件里的一致。
端口被占用
如果6379被其他程序占用：
Shell
# 查看占用进程
netstat -ano | findstr 6379
# 杀掉进程或换端口
远程Redis端口检查
如果Redis在远程服务器：
Shell
# 测试端口是否可达
telnet 远程IP 6379
# 或用nc命令
nc -zv 远程IP 6379
连不上说明防火墙阻止或网络不通。
四、排查维度3：密码是否正确
没密码但配置了密码
报错：
TEXT
NOAUTH Authentication required
原因： Redis没设密码，但SpringBoot配置文件里写了password。
解决： 去掉配置文件里的password：
YAML
spring:
redis:
host: 127.0.0.1
port: 6379
# password: Redis@123456 ← 注释掉或删掉
有密码但没配置
报错：
TEXT
NOAUTH Authentication required
原因： Redis设了密码，但SpringBoot配置文件里没写password。
解决： 加上密码配置：
YAML
spring:
redis:
host: 127.0.0.1
port: 6379
password: 你的Redis密码
密码错误
报错：
TEXT
WRONGPASS invalid username-or-password pair
解决： 确认密码正确，注意大小写和特殊字符。
密码有特殊字符
如果密码包含@、#、:等特殊字符，在yml里可能需要特殊处理：
YAML
# 方法1：用引号包起来
spring:
redis:
password: "Redis@123456"
# 方法2：用单引号
spring:
redis:
password: 'Redis@123456'
Redis 6+的用户名
Redis 6+支持ACL用户，如果有用户名：
YAML
spring:
redis:
username: default
password: 你的密码
Spring Boot 3.x的配置变化
Spring Boot 3.x改了Redis配置前缀：
YAML
# Spring Boot 2.x
spring:
redis:
host: 127.0.0.1
port: 6379
password: xxx
# Spring Boot 3.x（data.redis）
spring:
data:
redis:
host: 127.0.0.1
port: 6379
password: xxx
如果你项目是SpringBoot 3.x，用spring.data.redis，否则用spring.redis。
五、排查维度4：网络和防火墙
Redis只允许本地连接
检查Redis配置文件的bind：
TEXT
# 只允许本地连接（默认）
bind 127.0.0.1
# 允许所有IP连接
bind 0.0.0.0
# 或注释掉bind行
# bind 127.0.0.1
改完重启Redis。
protected-mode
TEXT
# 保护模式开启时，如果没设密码且bind了所有IP，Redis只允许本地连接
protected-mode yes
# 如果需要远程无密码连接（不推荐），关闭保护模式
protected-mode no
防火墙放行
Shell
# Windows防火墙放行6379
netsh advfirewall firewall add rule name="Redis 6379" dir=in action=allow protocol=TCP localport=6379
Docker端口映射
Shell
# 确认Docker容器端口映射正确
docker ps
# 输出应该有 0.0.0.0:6379->6379/tcp
# 如果没有端口映射，重新创建容器
docker run -d --name my-redis -p 6379:6379 redis:7.2
六、排查维度5：连接池配置
连接池满了
报错：
TEXT
Could not get a resource from the pool
原因： 连接池里的连接都被占用了，新的请求获取不到连接。
排查：
Shell
# 查看Redis当前连接数
redis-cli info clients
# 输出：
# connected_clients:50
# blocked_clients:0
如果连接数很高，可能是连接泄漏（获取了连接但没释放）。
解决：
- 检查代码有没有正确关闭连接
- 增大连接池大小：
YAML
spring:
redis:
lettuce:
pool:
max-active: 50 # 最大连接数
max-idle: 20 # 最大空闲连接
min-idle: 5 # 最小空闲连接
max-wait: 3000ms # 获取连接最大等待时间
连接超时
报错：
TEXT
Command timed out after 3s
原因： Redis响应太慢，或网络延迟高。
解决： 增加超时时间：
YAML
spring:
redis:
timeout: 5000ms # 连接超时
lettuce:
pool:
max-wait: 5000ms # 获取连接超时
七、排查维度6：SSL/TLS连接
如果Redis配了SSL：
YAML
spring:
redis:
ssl:
enabled: true
host: 127.0.0.1
port: 6379
如果Redis没配SSL但SpringBoot配了SSL，连接会失败。
确认SSL配置和Redis实际配置一致。
八、常见问题汇总
问题1：SpringBoot 2.x连接Redis 6/7
可能需要指定Lettuce的版本：
XML
<dependency>
<groupId>io.lettuce</groupId>
<artifactId>lettuce-core</artifactId>
<version>6.2.6.RELEASE</version>
</dependency>
问题2：Jedis vs Lettuce
SpringBoot默认用Lettuce。如果要换成Jedis：
XML
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-redis</artifactId>
<exclusions>
<exclusion>
<groupId>io.lettuce</groupId>
<artifactId>lettuce-core</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>redis.clients</groupId>
<artifactId>jedis</artifactId>
</dependency>
注意Jedis和Lettuce的连接池配置不同：
YAML
# Jedis
spring:
redis:
jedis:
pool:
max-active: 8
# Lettuce
spring:
redis:
lettuce:
pool:
max-active: 8
问题3：Redis Cluster连接
如果用的是Redis集群：
YAML
spring:
redis:
cluster:
nodes:
- 127.0.0.1:7000
- 127.0.0.1:7001
- 127.0.0.1:7002
max-redirects: 3
password: xxx
问题4：Redis Sentinel连接
哨兵模式：
YAML
spring:
redis:
sentinel:
master: mymaster
nodes:
- 127.0.0.1:26379
- 127.0.0.1:26380
password: xxx
问题5：时区问题
Redis存取时间戳时区不对：
YAML
spring:
redis:
timeout: 3000ms
jackson:
time-zone: Asia/Shanghai
九、调试Redis连接
1. 用Redis Desktop Manager连接
下载Another Redis Desktop Manager，用图形化工具连接Redis，确认地址、端口、密码正确。
2. 用IDEA连接
装Redis插件 → 连接 → 测试。
3. 命令行连接
Shell
# 无密码
redis-cli
# 有密码
redis-cli -a 密码
# 指定host和port
redis-cli -h 127.0.0.1 -p 6379 -a 密码
# 测试连接
127.0.0.1:6379> ping
PONG
# 查看Redis信息
127.0.0.1:6379> info
4. Spring Boot Actuator
如果项目开启了Actuator，可以查看Redis健康状态：
TEXT
http://localhost:8080/actuator/health
JSON
{
"status": "UP",
"components": {
"redis": {
"status": "UP"
}
}
}
十、完整排查流程
TEXT
Redis连接失败
│
├─ Redis服务启动了吗？ → sc query Redis / docker ps
│ ├─ 没启动 → 启动
│ └─ 启动了 ↓
│
├─ redis-cli能连上吗？ → redis-cli ping
│ ├─ 连不上 → 服务有问题，看Redis日志
│ └─ 能连上 ↓
│
├─ 配置文件地址对吗？ → host/port确认
│ ├─ 不对 → 改配置
│ └─ 对 ↓
│
├─ 密码对吗？ → 有密码vs没密码
│ ├─ 不对 → 改密码配置
│ └─ 对 ↓
│
├─ 端口监听了吗？ → netstat -ano | findstr 6379
│ ├─ 没有 → bind配置问题
│ └─ 有 ↓
│
├─ bind允许你的IP吗？ → bind 0.0.0.0
│ ├─ 不允许 → 改bind
│ └─ 允许 ↓
│
├─ 防火墙放行了吗？ → 添加放行规则
│ ├─ 没有 → 添加
│ └─ 有 ↓
│
└─ SpringBoot配置前缀对吗？ → spring.redis vs spring.data.redis
小结
| 排查维度 | 检查内容 |
|---|---|
| 服务启动 | sc query Redis |
| 端口 | netstat + 配置文件port |
| 密码 | 有无密码、密码正确性 |
| 网络 | bind、protected-mode、防火墙 |
| 连接池 | max-active、max-wait |
| 配置版本 | spring.redis vs spring.data.redis |
先redis-cli ping测Redis本身，再查SpringBoot配置，90%的问题能定位到。