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.1Redis 默认只监听本机回环地址。如果项目部署在 Docker 或远程服务器需要确认绑定地址。查看 Redis 配置redis-cli config getbind输出127.0.0.1只允许本机访问远程连不上需要远程访问时修改redis.confbind 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-port6379/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.yml3绑定地址仅监听 127.0.0.1修改bind配置4密码未填或填错补全password5防火墙/安全组6379 被拦截放行端口6. 总结Connection refused并不可怕按「服务 → 地址端口 → 绑定 → 密码 → 防火墙」的顺序排查绝大多数问题都能在 5 分钟内定位。你最近还遇到过哪些 Redis 连接相关的坑欢迎在评论区留言下一篇可以继续拆解NOAUTH、超时等高频问题。