1. 引言
你是不是也遇到过这种情况：Spring Boot 项目里明明写了 Redis 配置，启动时却报Connection refused: localhost/127.0.0.1:6379，翻遍博客也没找到能直接照做的答案？
别慌，这个报错 90% 是环境或配置问题，跟代码关系不大。本文用 5 个排查步骤，从现象、原因到解决，带你一步步定位并修复，全程附可复制代码，照着做就能跑通。
2. 报错现象
先看最常见的报错长什么样。启动 Spring Boot 项目时，控制台输出类似：
org.springframework.data.redis.RedisConnectionFailureException: Unable to connect to Redis; nested exception is io.lettuce.core.RedisConnectionException: Unable to connect to localhost/127.0.0.1:6379 Caused by: java.net.ConnectException: Connection refused: localhost/127.0.0.1:6379关键信息就一句话：程序连不上localhost:6379这个地址。下面按步骤排查。
3. 5 个排查步骤
3.1 第一步：确认 Redis 服务是否启动
Connection refused最常见的原因就是 Redis 服务根本没跑起来。
在命令行执行：
redis-cliping- 返回
PONG：服务正常，跳到第 2 步； - 报
Could not connect to Redis at 127.0.0.1:6379: Connection refused：服务未启动，执行启动命令：
# macOS / Linuxredis-server# Windows（若用 WSL 或 Docker 则按对应方式）redis-server.exe启动后再执行redis-cli ping，确认返回PONG。
3.2 第二步：核对连接地址与端口
服务启动了还连不上？检查 Spring Boot 配置里的地址和端口是否与 Redis 实际监听一致。
# application.ymlspring:data:redis:host:localhostport:6379# 有密码就填，没有就删掉这行password:yourpassword用下面命令查看 Redis 实际监听端口：
redis-cli-p6379info server|greptcp_port如果端口不一致（比如 Redis 跑在 6380），把配置改成对应端口即可。
3.3 第三步：检查 Redis 是否绑定在 127.0.0.1
Redis 默认只监听本机回环地址。如果项目部署在 Docker 或远程服务器，需要确认绑定地址。
查看 Redis 配置：
redis-cli config getbind- 输出
127.0.0.1：只允许本机访问，远程连不上； - 需要远程访问时，修改
redis.conf：
bind 0.0.0.0 protected-mode no注意：生产环境开放远程访问务必设置强密码，否则极易被攻击。
3.4 第四步：确认密码是否匹配
配置了密码但没填，或密码填错，也会导致连接失败（报错通常是NOAUTH Authentication required）。
在application.yml中补上密码：
spring:data:redis:password:yourpassword命令行验证密码是否正确：
redis-cli-ayourpasswordping返回PONG即密码正确。
3.5 第五步：检查防火墙与网络
本地都正常、但部署到服务器后连不上，多半是防火墙或安全组拦截了 6379 端口。
# 查看端口是否被监听netstat-tlnp|grep6379# 放行端口（CentOS / Ubuntu 示例）sudofirewall-cmd --add-port=6379/tcp--permanentsudofirewall-cmd--reload云服务器（阿里云、腾讯云等）还需在控制台安全组中放行 6379 入方向规则。
4. 完整可运行示例
下面是一个最小可运行的 Spring Boot + Redis 示例，验证连接是否正常。
importorg.springframework.beans.factory.annotation.Autowired;importorg.springframework.data.redis.core.StringRedisTemplate;importorg.springframework.web.bind.annotation.GetMapping;importorg.springframework.web.bind.annotation.RestController;@RestControllerpublicclassRedisController{@AutowiredprivateStringRedisTemplateredisTemplate;@GetMapping("/redis/test")publicStringtest(){redisTemplate.opsForValue().set("hello","world");return"写入成功，读取值："+redisTemplate.opsForValue().get("hello");}}启动项目后访问http://localhost:8080/redis/test，看到写入成功，读取值：world即表示连接正常。
5. 排查思路小结
| 步骤 | 检查项 | 常见原因 | 解决方式 |
|---|---|---|---|
| 1 | 服务是否启动 | Redis 未运行 | redis-server启动 |
| 2 | 地址与端口 | 配置与监听不一致 | 修改application.yml |
| 3 | 绑定地址 | 仅监听 127.0.0.1 | 修改bind配置 |
| 4 | 密码 | 未填或填错 | 补全password |
| 5 | 防火墙/安全组 | 6379 被拦截 | 放行端口 |
6. 总结
Connection refused并不可怕，按「服务 → 地址端口 → 绑定 → 密码 → 防火墙」的顺序排查，绝大多数问题都能在 5 分钟内定位。
你最近还遇到过哪些 Redis 连接相关的坑？欢迎在评论区留言，下一篇可以继续拆解NOAUTH、超时等高频问题。
)
