Apache RocketMQ Docker 컨테이너 배포 가이드

개요

Apache RocketMQ는 Apache Software Foundation에서 개발 및 유지 관리하는 분산 메시지 미들웨어입니다. 높은 처리량, 낮은 지연 시간, 높은 신뢰성 등의 특징을 가지며 분산 시스템에서 비동기 통신, 트래픽 피크 완화, 시스템 결합 분리 등의 시나리오에 널리 사용됩니다. 컨테이너화 기술의 보급으로 Docker를 사용하여 RocketMQ를 배포하면 환경 구성이 크게 간소화되고 배포 일관성과 운영 효율성이 향상됩니다.

이 문서에서는 Docker 컨테이너 방식으로 Apache RocketMQ를 배포하는 방법을 자세히 설명합니다. 환경 준비, 이미지 가져오기, 컨테이너 배포, 기능 테스트, 프로덕션 환경 최적화 및 문제 해결 등 사용자에게 완전한 컨테이너 배포 방안을 제공합니다.

환경 준비

Docker 환경 설치

RocketMQ 컨테이너를 배포하기 전에 대상 서버에 Docker 환경이 설치되어 있어야 합니다. 다음 원클릭 설치 스크립트를 사용하여 Docker 및 관련 구성 요소를 빠르게 배포하는 것이 좋습니다.

bash <(wget -qO- https://xuanyuan.cloud/docker.sh)

실행 완료 후 docker --version 명령어로 설치 성공 여부를 확인할 수 있으며, Docker version x.x.x, build xxxxxxx 형태의 출력이 나오면 정상적으로 설치된 것입니다.

이미지 준비

ROCKETMQ 이미지 가져오기

다음 명령어를 사용하여 轩辕(Xuanyuan) 미러 가속 주소에서 최신 버전의 ROCKETMQ 이미지를 가져옵니다.

docker pull xxx.xuanyuan.run/apache/rocketmq:latest

가져오기가 완료되면 다음 명령어로 이미지가 성공적으로 다운로드되었는지 확인할 수 있습니다.

docker images | grep apache/rocketmq

출력에 apache/rocketmq와 latest 태그 레코드가 포함되어 있으면 이미지 준비가 완료된 것입니다.

컨테이너 배포

기본 배포 명령

RocketMQ는 일반적으로 NameServer와 Broker 두 가지 핵심 구성 요소로 구성됩니다. 아래는 기본 컨테이너 배포 명령입니다.

NameServer 컨테이너 시작

docker run -d \
  --name rocketmq-nameserver \
  --publish 9876:9876 \
  --volume /data/rocketmq/nameserver/logs:/root/logs \
  --env "MAX_HEAP_SIZE=512m" \
  --env "HEAP_NEWSIZE=128m" \
  xxx.xuanyuan.run/apache/rocketmq:latest \
  sh mqnamesrv

매개변수 설명:

-d: 컨테이너를 백그라운드로 실행합니다.
--name: 컨테이너 이름을 rocketmq-nameserver로 지정합니다.
--publish 9876:9876: NameServer 기본 포트를 매핑합니다. 실제 포트는 轩辕(Xuanyuan) 이미지 문서(ROCKETMQ)에서 확인해야 합니다.
--volume: 로그 디렉터리를 호스트에 마운트하여 데이터를 영속화합니다.
--env: JVM 메모리 매개변수를 설정합니다. 서버 구성에 따라 조정할 수 있습니다.

Broker 컨테이너 시작

docker run -d \
  --name rocketmq-broker \
  --publish 10911:10911 \
  --publish 10909:10909 \
  --volume /data/rocketmq/broker/logs:/root/logs \
  --volume /data/rocketmq/broker/store:/root/store \
  --env "NAMESRV_ADDR=nameserver-ip:9876" \
  --env "MAX_HEAP_SIZE=1024m" \
  --env "HEAP_NEWSIZE=256m" \
  xxx.xuanyuan.run/apache/rocketmq:latest \
  sh mqbroker -c /opt/rocketmq/conf/broker.conf

매개변수 설명:

NAMESRV_ADDR: 실제 NameServer의 IP 주소와 포트로 교체해야 합니다.
포트 매핑: 轩辕(Xuanyuan) 이미지 문서(ROCKETMQ)를 통해 Broker의 통신 포트를 확인합니다. 예를 들어 10911은 기본 리스닝 포트, 10909는 VIP 채널 포트입니다.
마운트 디렉터리: 저장 디렉터리 마운트를 추가하여 메시지 데이터가 영속화되도록 합니다.

컨테이너 상태 확인

배포가 완료된 후 다음 명령어로 컨테이너 실행 상태를 확인합니다.

# 모든 RocketMQ 관련 컨테이너 확인
docker ps --filter "name=rocketmq-"

# 컨테이너 로그 확인 (Broker 예시)
docker logs -f rocketmq-broker

로그에 The broker[broker-a, xxx.xxx.xxx.xxx:10911] boot success. serializeType=JSON과 같은 정보가 나타나면 Broker가 성공적으로 시작된 것입니다.

기능 테스트

기본 연결 테스트

Broker 컨테이너 진입:

docker exec -it rocketmq-broker sh

NameServer 주소 설정:

export NAMESRV_ADDR=nameserver-ip:9876

테스트 메시지 전송:

sh tools.sh org.apache.rocketmq.example.quickstart.Producer

출력에 SendResult [sendStatus=SEND_OK, msgId=...과 같은 정보가 나타나면 메시지 전송이 성공한 것입니다.

테스트 메시지 수신:

sh tools.sh org.apache.rocketmq.example.quickstart.Consumer

출력에 ConsumeMessageThread_%d Receive New Messages: [MessageExt...과 같은 정보가 나타나면 메시지 수신이 성공한 것입니다.

외부 접근 테스트

호스트 또는 접근 가능한 다른 서버에서 RocketMQ 클라이언트 도구를 사용하여 배포된 서비스에 연결하고 외부 네트워크 연결을 확인합니다. 호스트 방화벽에서 관련 포트(예: 9876, 10911)가 개방되어 있어야 합니다.

프로덕션 환경 권장 사항

데이터 영속화

디렉터리 마운트: 프로덕션 환경에서는 로그 및 저장 디렉터리를 반드시 마운트하여 컨테이너 재시작으로 인한 데이터 손실을 방지해야 합니다.

--volume /data/rocketmq/nameserver/logs:/root/logs \
--volume /data/rocketmq/nameserver/store:/root/store \  # NameServer에 영속화 요구가 있는 경우
--volume /data/rocketmq/broker/logs:/root/logs \
--volume /data/rocketmq/broker/store:/root/store \

저장 최적화: SSD와 같은 고성능 스토리지를 Broker의 store 디렉터리에 사용하여 메시지 읽기/쓰기 성능을 향상시키는 것이 좋습니다.

리소스 구성

JVM 매개변수 조정: 서버 구성에 따라 JVM 메모리를 합리적으로 설정하여 OOM 또는 리소스 낭비를 방지합니다.

--env "MAX_HEAP_SIZE=4g" \  # 최대 힙 메모리, 물리 메모리의 50% 권장
--env "HEAP_NEWSIZE=1g" \   # New 세대 메모리, 최대 힙 메모리의 25% 권장

컨테이너 리소스 제한: --memory와 --cpus 옵션을 사용하여 컨테이너의 리소스 사용을 제한하고 리소스 경합을 방지합니다.

--memory=8g --cpus=4 \

고가용성 구성

다중 노드 배포: 단일 장애점을 방지하기 위해 NameServer 노드를 최소 3개 이상 배포합니다.
Broker 클러스터: 메시지 신뢰성을 보장하기 위해 마스터-슬레이브 아키텍처 또는 Dledger 모드로 Broker 클러스터를 구축합니다.
네트워크 분리: Docker 네트워크를 통해 서로 다른 환경(개발/테스트/프로덕션)을 분리하고 기본 브리지 네트워크 대신 사용자 정의 네트워크를 사용합니다.

docker network create rocketmq-network
docker run -d --name rocketmq-nameserver --network rocketmq-network ...

보안 강화

컨테이너 권한: root 사용자로 컨테이너를 실행하지 말고 --user 옵션으로 비특권 사용자를 지정합니다.

--user 1000:1000 \

구성 파일 마운트: 사용자 정의 broker.conf 파일을 마운트하여 접근 제어, TLS 등 보안 기능을 활성화합니다.

--volume /data/rocketmq/conf/broker.conf:/opt/rocketmq/conf/broker.conf \

로그 로테이션: 호스트에서 로그 로테이션 정책을 구성하여 로그 파일이 너무 커져 디스크 공간을 차지하지 않도록 합니다.

문제 해결

컨테이너가 시작되지 않는 경우

시작 로그 확인:

docker logs --tail=100 rocketmq-broker  # 최근 100줄 로그 확인

포트 점유 확인:

netstat -tulpn | grep 9876  # NameServer 포트가 점유되었는지 확인

리소스 제한 확인: 리소스 부족으로 컨테이너가 시스템에 의해 종료된 경우 dmesg | grep -i 'out of memory' 명령으로 시스템 OOM 로그를 확인할 수 있습니다.

메시지 전송/수신 실패

NameServer 연결 확인: Broker에 설정된 NAMESRV_ADDR가 올바른지 확인하고 telnet nameserver-ip 9876으로 네트워크 연결을 테스트합니다.
Broker 상태 확인: RocketMQ 콘솔 또는 명령줄 도구로 Broker 상태를 확인합니다.

sh mqadmin clusterList -n nameserver-ip:9876

권한 구성 확인: ACL을 활성화한 경우 생산자/소비자의 accessKey와 secretKey가 올바른지 확인합니다.

데이터 일관성 문제

저장 디렉터리 권한: 호스트 마운트 디렉터리의 권한이 올바른지 확인하고 컨테이너 내부 사용자가 읽기/쓰기가 가능한지 확인합니다.

ls -ld /data/rocketmq/broker/store  # 권한이 755 또는 컨테이너 사용자가 접근 가능해야 함

디스크 공간 확인: 디스크 공간이 부족하면 메시지 쓰기에 실패할 수 있으므로 df -h로 디스크 사용량을 확인합니다.

참고 자료

轩辕(Xuanyuan) 이미지 문서(ROCKETMQ)
ROCKETMQ 이미지 태그 목록
Docker 공식 문서: Docker Run Reference

태그: Apache RocketMQ docker 컨테이너 NameServer Broker

8월 15일 07:16에 게시됨

괴물 클럽