🚨 Spring Boot + Redis 연결 오류: RedisConnectionFailureException: Unable to connect to Redis

1. 문제 상황

Spring Boot 프로젝트 실행 시, 아래와 같은 에러 로그 발생:

org.springframework.data.redis.RedisConnectionFailureException: Unable to connect to Redis
...
Caused by: io.netty.channel.AbstractChannel$AnnotatedConnectException: Connection refused: localhost/127.0.0.1:6379​

• Spring Boot 애플리케이션에서 Redis에 연결을 시도했지만 실패
• localhost:6379 포트에서 연결 거부(Connection refused) 발생

---

2. 원인 분석

에러 메시지를 보면, Redis 서버가 실행 중이거나 접근 가능한 상태가 아님을 의미함.

확인 결과:

• Docker로 Redis를 띄웠으나
• 컨테이너 내부 포트(6379/tcp)만 열려 있고, 로컬 호스트와 포트 매핑이 되어 있지 않았음

즉, 애플리케이션은 localhost:6379로 연결을 시도했지만 실제로는 외부에서 해당 포트가 열려 있지 않아 연결 실패가 발생.

---

3. 해결 방법

잘못된 실행 (포트 매핑 없음)

docker run -d redis

 

→ 이 경우 docker ps 출력에서 PORTS에 6379/tcp만 표시되고, 로컬 호스트와 연결되지 않음.

올바른 실행 (포트 매핑 추가)

컨테이너를 내리고, -p 옵션으로 호스트와 컨테이너 포트를 매핑:

 

docker rm -f compassionate_nash docker run -d --name redis-container -p 6379:6379 redis

결과 확인

• docker ps에서 PORTS에 0.0.0.0:6379->6379/tcp 표시됨
• redis-cli -h localhost -p 6379 ping → PONG 정상 응답
• Spring Boot 실행 시 오류 사라짐

---

4. 정리

• Connection refused 에러는 대체로 Redis 서버가 실행 중이지 않거나 포트 매핑이 잘못된 경우 발생
• Docker 사용 시 반드시 -p 6379:6379 옵션을 통해 로컬과 포트를 연결해야 함
• 이후 application.yml에서 spring.data.redis.host=localhost로 설정하면 정상적으로 연결 가능