Redis가 떠 있는데 캐시가 작동 안 할 때

캐시 컨테이너가 실행 중이지만 접속이 안 되는 문제는 보통 네트워크나 인증이다. 로그를 봐도 "connection refused"만 반복되면, 체계적으로 접근해야 한다.

컨테이너 상태 확인

# Redis 컨테이너가 정말 떠 있는가
docker ps | grep redis

# 최근 로그 확인
docker logs --tail=50 redis-container-name

# Redis 프로세스 상태
docker exec redis-container-name redis-cli ping

마지막 명령에서 PONG이 나오면, Redis 자체는 정상이다. 문제는 앱에서 Redis로 접속하는 경로다.

볼륨 마운트와 환경변수 확인

# 컨테이너 상세 정보
docker inspect redis-container-name | grep -A10 Mounts
docker inspect redis-container-name | grep -A10 Env

볼륨이 제대로 마운트됐는가? 특히 Redis 데이터가 영구 저장소에 있는가? 환경변수에서 REDIS_URL이나 REDIS_PASSWORD가 제대로 설정됐는가?

포트 매핑 확인

docker ps --no-trunc | grep redis

출력 예: 127.0.0.1:6379->6379/tcp

포트 매핑을 보면 알 수 있다.

문제 1: 127.0.0.1:6379->6379/tcp Localhost에만 바인드됨. 같은 호스트의 다른 컨테이너에서는 접속 불가.

해결: 0.0.0.0:6379->6379/tcp로 변경하거나, Docker compose에서 network_mode: host 사용 또는 custom network에 연결.

문제 2: :::6379->6379/tcp IPv6 바인딩. 일부 클라이언트는 IPv6을 지원하지 않음.

네트워크 연결 테스트

# 앱 컨테이너에서 Redis로 접속 시도
docker exec app-container-name nc -zv redis-container-name 6379

# 또는 redis-cli로 직접
docker exec app-container-name redis-cli -h redis-container-name ping

Connection refused or No route to host가 나오면 네트워크 문제다.

Docker Compose 네트워크 설정

Compose 파일에서 컨테이너들이 같은 네트워크에 있는가?

services:
  redis:
    image: redis:latest
    networks:
      - backend

  app:
    image: myapp:latest
    environment:
      REDIS_URL: redis://redis:6379  # 호스트명으로 접속
    networks:
      - backend

networks:
  backend:
    driver: bridge

만약 networks 섹션이 없으면, Compose가 자동으로 default network를 만들지만 의존성 순서가 보장되지 않을 수 있다.

환경변수와 연결 문자열

# 앱 컨테이너의 환경변수 확인
docker exec app-container-name env | grep REDIS

앱이 보는 Redis URL이 맞는가?

REDIS_URL=redis://redis:6379  # 올바름 (Docker 네트워크)
REDIS_URL=redis://localhost:6379  # 틀림 (localhost는 앱 컨테이너 내부)
REDIS_URL=redis://127.0.0.1:6379  # 틀림 (loopback은 앱 컨테이너 내부)

인증 설정 확인

Redis에 비밀번호가 설정되어 있는가?

# Redis 설정 확인
docker exec redis-container-name redis-cli CONFIG GET requirepass

비밀번호가 있다면, 앱의 연결 문자열에도 포함해야 한다:

REDIS_URL=redis://:password@redis:6379

체계적인 확인 순서

1. docker logs로 Redis 로그 확인 (시작 에러 있는가?)
2. redis-cli ping으로 Redis 자체가 응답하는지 확인
3. docker ps로 포트 매핑 확인 (localhost만 바인드된 건 아닌가?)
4. nc 또는 redis-cli로 앱 컨테이너에서 Redis로 접속 시도
5. Docker Compose 네트워크 설정 확인
6. 앱 컨테이너의 REDIS_URL 환경변수 확인
7. Redis 인증 설정과 연결 문자열 일치 여부 확인

Docker 네트워크는 처음에 헷갈리지만, 한 번 이해하면 매번 같은 방식으로 확인할 수 있다. 작은 확인들을 기록해두면 다음 배포 때 훨씬 빠르다.