Docker로 Redis 클러스터 구축하기

Redis 클러스터를 Docker를 활용해 구성하는 과정을 실제 발생한 문제 해결을 바탕으로 정리했습니다.
Windows + Docker Desktop 환경 기준입니다.

---

🧱 기본 구조

• Redis Master: 3개
• Redis Replica: 3개 (총 6개 노드)
• 포트: 17500~17505, 클러스터 버스 포트는 27500~27505

---

1. Docker Network 생성

docker network create <사용자명>-network

---

2. docker-compose.yml 작성

각 컨테이너가 외부에서 접근 가능하도록 설정하고, 클러스터 구성에 필요한 포트를 열어줍니다.

# 예시 - redis-master-1
  redis-master-1:
    image: redis:7.4
    command: >
      sh -c "redis-server --cluster-enabled yes --cluster-config-file nodes.conf --appendonly yes
      --protected-mode no --requirepass <비밀번호> --masterauth <비밀번호> --bind 0.0.0.0 --cluster-node-timeout 30000
      --port 6379 --cluster-announce-ip <호스트주소> --cluster-announce-port 17500 --cluster-announce-bus-port 27500"
    container_name: redis-master-1
    ports:
      - "17500:6379"
      - "27500:27500"
    networks:
      - <사용자명>-network
    environment:
      - REDISCLI_AUTH=<비밀번호>
    volumes:
      - redis-master-1-data:/data

나머지 노드들도 포트만 다르게 설정해서 6개 작성합니다.

---

docker-compose.yml 구성 해석

각 Redis 인스턴스는 독립된 서비스로 정의되며, 주요 설정은 다음과 같습니다:

• image: redis:7.4 : Redis 7.4 버전을 사용합니다.
• command : Redis 인스턴스를 클러스터 모드로 실행하며, 다음 설정들을 포함합니다:
  • --cluster-enabled yes : 클러스터 모드를 활성화
  • --cluster-config-file nodes.conf : 클러스터 정보 저장 파일
  • --appendonly yes : AOF(Append Only File) 사용 설정
  • --requirepass 및 --masterauth : 비밀번호 인증 설정
  • --cluster-announce-ip : 클러스터 통신용으로 외부에서 접속 가능한 IP를 지정
  • --cluster-announce-port, --cluster-announce-bus-port : 각각 Redis 포트와 클러스터 내부 통신을 위한 bus 포트를 설정
• ports : 호스트와 컨테이너 포트를 매핑하여 외부 접속을 허용합니다.
• volumes : Redis 데이터를 지속적으로 보존하기 위한 볼륨 설정입니다.
• networks : 모든 Redis 인스턴스가 동일한 사용자 정의 네트워크(<네트워크이름>)에 연결되도록 설정합니다.
• environment : 컨테이너 내부에서 redis-cli 사용 시 인증에 필요한 비밀번호 환경변수 설정 (REDISCLI_AUTH)

서비스별 포트 예시

서비스 이름	Redis 포트	Cluster Bus 포트
redis-master-1	17500	27500
redis-master-2	17502	27502
redis-master-3	17504	27504
redis-slave-1	17501	27501
redis-slave-2	17503	27503
redis-slave-3	17505	27505

위 포트 번호는 포트 충돌을 방지하기 위해 직접 지정한 것입니다.

3. 컨테이너 실행

docker-compose up -d

포트 충돌이 나면 netstat -ano | findstr :포트번호 와 taskkill /PID <pid> /F 로 해결

---

4. Redis 클러스터 생성

docker exec -it redis-master-1 redis-cli -a <비밀번호>   --cluster create   172.18.0.2:6379   172.18.0.3:6379   172.18.0.4:6379   172.18.0.5:6379   172.18.0.6:6379   172.18.0.7:6379   --cluster-replicas 1   --cluster-yes

IP는 docker inspect로 컨테이너별 IP를 확인 후 입력

---

5. 클러스터 연결 오류 해결

문제: 클러스터 노드 간 연결 실패

Error condition on socket for SYNC: Connection refused

해결: cluster-announce-ip와 포트 설정 확인, 방화벽 또는 포트 점유 프로세스 확인

---

문제: <호스트주소> 해석 안 됨

Failed to resolve '<호스트주소>'

해결: WSL 환경에서는 로컬 IP (192.168.x.x)로 대체하거나 hosts 파일 수정

---

6. 클러스터 해제 명령어

redis-cli -a <비밀번호> -c -p 17500
> CLUSTER RESET HARD

---

✅ 마무리 팁

• 클러스터용 포트와 버스포트를 명확히 구분하고 방화벽 예외로 등록
• 클러스터가 완성된 후에는 redis-cli -c -a <비밀번호> -p 17500로 클러스터 상태 점검 가능
• 문제 발생 시 docker logs <컨테이너명> 로그 확인

---