Redis에서 connection refused가 나오면 먼저 물어야 할 것은 “Redis가 죽었나?”보다 “어떤 host, port, access rule이 이 연결을 거절하고 있나?”입니다. 많은 incident가 Redis 장애처럼 보이지만 실제로는 잘못된 target, loopback-only listener, container networking 실수인 경우가 많습니다.
이 글은 가장 빠른 점검 순서부터 갑니다. Redis가 실제로 listening 중인지, 클라이언트가 올바른 주소를 보고 있는지, bind와 protected mode 때문에 원격 접근이 막힌 것은 아닌지부터 확인합니다.
connection refused는 보통 무엇을 뜻하나
TCP 관점에서 connection refused는 그 host와 port에서 연결을 받아줄 listener가 없거나, 현재 위치에서 그 listener에 도달하지 못한다는 뜻에 가깝습니다.
Redis에서는 보통 아래 같은 원인으로 좁혀집니다.
- Redis 프로세스가 실행 중이 아님
- Redis가 기대한 인터페이스에 listen하지 않음
- 클라이언트가 잘못된 host나 port를 사용
- container나 VM 네트워크가 다른 곳을 가리킴
그래서 첫 점검은 네트워크 경계 가까이에서 하는 편이 좋습니다.
Redis가 실제로 listening 중인지 확인하세요
가장 기본적인 확인은 아래입니다.
redis-cli -h 127.0.0.1 -p 6379 PING서버 로컬에서는 되는데 애플리케이션 위치에서는 안 된다면 Redis 프로세스 자체보다 reachability, bind address, firewall 쪽 문제일 가능성이 큽니다.
bind와 protected mode를 보세요
Redis 보안 문서는 loopback에만 bind하면 로컬 클라이언트만 접근할 수 있다고 설명합니다. protected mode도 적절한 인증이나 네트워크 보호 없이 노출된 인스턴스 접근을 제한합니다.
흔한 패턴은 이렇습니다.
- Redis는 로컬에서 잘 된다
- 앱이 Docker, 다른 VM, 다른 node로 옮겨간다
- 같은 host와 port를 계속 쓴다
- Redis가 여전히 loopback에만 열려 있어 connection refused가 난다
앱이 같은 머신에서만 붙는다면 여기부터 의심해야 합니다.
환경 변수 이름보다 실제 target을 보세요
Redis incident 중 적지 않은 비율은 단순한 주소 실수입니다.
- container 안의
localhost는 container 자신을 가리킴 - 앱은 내부 port를 보는데 host는 다른 port를 노출함
- connection string이 여전히 dev 인스턴스를 가리킴
- staging이나 preview의 DNS가 local과 다름
Redis 설정을 바꾸기 전에 앱이 실제로 어떤 host와 port로 붙는지 로그로 먼저 확인하세요.
흔한 원인
1. Redis가 기대 포트에서 떠 있지 않다
앱은 6379를 보지만 서비스는 꺼져 있거나 다른 포트로 옮겨졌습니다.
2. Redis가 loopback에만 열려 있다
로컬 shell에서는 되지만 원격 앱에서는 안 됩니다.
3. container networking이 잘못됐다
앱이 service name 대신 localhost를 보고 있습니다.
4. protected mode나 주변 네트워크 정책이 막는다
의도적으로 위험한 원격 접근 패턴을 거절하는 상황일 수 있습니다.
실전 점검 순서
- 서버 로컬에서
PING확인 - 앱이 실제로 보는 host와 port 확인
- 앱과 같은 네트워크 문맥에서 재현
- bind와 protected mode 확인
- container, VM, firewall, cloud network rule 확인
이 순서가 Redis 설정을 무작정 건드리는 것보다 훨씬 빨리 원인에 닿게 해줍니다.
첫 분기에 좋은 shortcut
앱에서 connection refused가 날 때는 아래처럼 먼저 갈라보세요.
- 로컬
PING도 안 된다: Redis 프로세스나 listener부터 - 로컬
PING는 되는데 앱만 안 된다: target host와 network context부터 - host는 맞는데 원격 path만 실패: bind, protected mode, firewall부터
- containerized app이
localhost를 쓴다: service discovery나 port mapping부터
이 분기만으로도 Redis 설정을 잘못된 방향으로 바꾸는 실수를 줄일 수 있습니다.
증상별 진입 힌트
- 앱이 Redis에 아예 연결되지 못하고
connection refused를 받으면 여기서 시작하면 됩니다. - 연결은 되는데 command가 느리면 latency 가이드가 더 맞습니다.
바로 확인할 명령
redis-cli -h <host> -p 6379 ping
netstat -ano | findstr 6379
redis-cli INFO server이 명령으로 Redis listener 유무, host와 port 도달 여부, 서버 기동 상태를 먼저 확인할 수 있습니다.
listener가 없는지, bind address가 잘못됐는지, 앱이 Redis가 실제 있는 host와 다른 곳을 보고 있는지 보세요.
FAQ
Q. 서버에서 redis-cli는 되는데 앱은 왜 connection refused일까요?
앱이 다른 네트워크 문맥에서 돌거나, 다른 host를 보거나, 원격 노출되지 않은 listener를 치고 있을 수 있습니다.
Q. localhost는 항상 안전한가요?
클라이언트가 같은 머신이나 같은 network namespace 안에 있을 때만 그렇습니다.
Q. protected mode를 꺼서라도 연결해야 하나요?
주변 네트워크 경계와 보안 영향을 이해하지 못했다면 권장하지 않습니다.
Read Next
- 로컬에서는 되는데 전체 workload에서는 불안정하다면 Redis Memory Usage High를 보세요.
- listener는 reachable하지만 key 동작이 이상하다면 Redis Keys Not Expiring를 보세요.
Related Posts
Sources:
- https://redis.io/docs/latest/operate/oss_and_stack/management/security/
- https://redis.io/docs/latest/commands/ping/
심사 대기 중에는 광고 대신 관련 가이드를 먼저 보여줍니다.
먼저 읽어볼 가이드
검색 유입이 많은 핵심 글부터 이어서 보세요.
- 미들웨어 트러블슈팅 가이드: Redis vs RabbitMQ vs Kafka 개발자를 위한 미들웨어 트러블슈팅 허브 글입니다. Redis, RabbitMQ, Kafka 중 어떤 증상부터 먼저 봐야 하는지와 어떤 문제 패턴이 각 시스템에 가까운지 정리합니다.
- Kubernetes CrashLoopBackOff: 먼저 볼 것들 startup failure, probe, config, resource limit 관점에서 CrashLoopBackOff를 어떻게 나눠서 봐야 하는지 정리한 가이드입니다.
- Kafka consumer lag가 계속 늘 때: 트러블슈팅 가이드 Kafka consumer lag가 계속 늘어날 때 무엇부터 봐야 하는지 정리합니다. poll 주기, 처리 속도, rebalance, consumer 설정까지 실전 기준으로 다룹니다.
- Kafka Rebalancing Too Often 가이드 Kafka consumer group에서 rebalance가 너무 자주 일어날 때 membership flapping, poll timing, protocol, assignment churn을 어떤 순서로 봐야 하는지 설명하는 실전 가이드입니다.
- Docker container가 계속 재시작될 때: 먼저 확인할 것들 exit code, command failure, environment mistake, health check 관점에서 Docker restart loop를 푸는 실전 가이드입니다.
심사 대기 중에는 광고 대신 관련 가이드를 먼저 보여줍니다.