🐰
RabbitMQ 치트시트

RabbitMQ 최신 3.13/4.0+ 기준 초보자 완벽 가이드: Docker 1초 설치, AMQP 핵심 멘탈 모델, 4대 Exchange(Direct/Fanout/Topic/Headers), Work Queue & Prefetch 공정 분배, 수동 ACK, 메시지 영속성, DLX(데드 레터 큐), Spring Boot 연동 및 rabbitmqctl 명령어 치트시트
#rabbitmq#amqp#message-broker#queue#exchange#spring-amqp#pika#docker#kafka#backend최종 업데이트: 2026-10-06
RabbitMQ 치트시트 핵심 명령어 및 실전 가이드

## 1. 필수 사전 설치 요건 & 환경 구성 (Prerequisites)

RabbitMQ는 가볍고 신뢰성이 뛰어난 오픈소스 AMQP 메시지 브로커입니다. 초보자도 1분 안에 직접 실습해 볼 수 있도록 가장 빠르고 권장되는 Docker 실행부터 시작합니다.

### 🐳 1. Docker로 1초 만에 실행하기 (가장 추천)
RabbitMQ 웹 관리자 UI(Management Plugin)가 포함된 공식 이미지를 사용하면 별도의 Erlang 설치 없이 즉시 실행할 수 있습니다.

```bash
# RabbitMQ 및 웹 관리 콘솔 컨테이너 백그라운드 실행
docker run -d --name rabbitmq \
  -p 5672:5672 \
  -p 15672:15672 \
  -e RABBITMQ_DEFAULT_USER=guest \
  -e RABBITMQ_DEFAULT_PASS=guest \
  rabbitmq:3-management
```

- **5672 포트**: AMQP 클라이언트 애플리케이션 통신 포트
- **15672 포트**: 브라우저 웹 관리 대시보드 포트
- **접속 확인**: 웹 브라우저에서 `http://localhost:15672` 접속 ➔ 아이디/비밀번호 `guest` / `guest` 입력 후 로그인

---

### 💻 2. 로컬 OS 직접 설치 (Docker 미사용 시)
RabbitMQ는 Erlang 기반이므로 호환되는 **Erlang OTP 26 이상**이 먼저 설치되어 있어야 합니다.

| 운영체제 (OS) | 설치 명령어 / 방법 |
| :--- | :--- |
| **Windows** | 1. [Erlang 다운로드](https://www.erlang.org/patches/otp-26.2) 설치 후 환경변수 등록<br>2. [RabbitMQ 인스톨러](https://github.com/rabbitmq/rabbitmq-server/releases) 실행 (또는 `choco install rabbitmq`) |
| **macOS** | 터미널에서 `brew install rabbitmq` 실행<br>실행: `brew services start rabbitmq` |
| **Linux (Ubuntu/Debian)** | `sudo apt update && sudo apt install -y rabbitmq-server`<br>서비스 기동: `sudo systemctl enable --now rabbitmq-server` |

설치 후 웹 관리자 플러그인 활성화:
```bash
rabbitmq-plugins enable rabbitmq_management
```

---

### 📦 3. 클라이언트 라이브러리 설치
실습할 언어의 RabbitMQ 드라이버 패키지를 설치합니다:

```bash
# Python (표준 pika 라이브러리)
pip install pika

# Node.js
npm install amqplib

# Java / Spring Boot (Gradle)
# implementation 'org.springframework.boot:spring-boot-starter-amqp'
```

---

## 2. RabbitMQ 핵심 개념 & 멘탈 모델 (Mental Model)

AMQP(Advanced Message Queuing Protocol)의 핵심은 **"생산자(Producer)는 큐에 직접 메시지를 넣지 않고, 반드시 익스체인지(Exchange)를 거친다"**는 점입니다.

```text
[AMQP 메시지 전달 파이프라인]
┌───────────┐         Routing Key          ┌──────────┐   Binding Key   ┌───────────┐
│ Producer  ├─────────────────────────────►│ Exchange ├────────────────►│   Queue   │
│ (생산자)   │  "주문 완료 이벤트 전송"       │ (우체국)  │   "라우팅 규칙"  │  (우편함)  │
└───────────┘                              └──────────┘                 └─────┬─────┘
                                                                              │
                                                                       Consume│
                                                                              ▼
                                                                        ┌───────────┐
                                                                        │ Consumer  │
                                                                        │ (소비자)   │
                                                                        └───────────┘
```

### 🔑 4대 핵심 구성요소
1. **Producer (생산자)**: 메시지를 생성하여 Exchange에 발행하는 주체.
2. **Exchange (익스체인지)**: 메시지를 받아 바인딩 규칙(Binding Key)에 따라 적절한 Queue로 라우팅하는 우체국.
3. **Queue (큐)**: 메시지가 소비자에게 소비될 때까지 안전하게 대기하는 메모리/디스크 버퍼.
4. **Consumer (소비자)**: 큐에서 대기 중인 메시지를 가져와 처리하는 애플리케이션.

### 🔀 4대 Exchange 타입 비교
| Exchange 타입 | 라우팅 동작 원리 | 주요 실무 활용 예시 |
| :--- | :--- | :--- |
| **Direct** | 메시지의 `routing_key`와 큐의 `binding_key`가 **정확히 일치**할 때 전달 | 1:1 작업 큐, 특정 단일 서비스 대상 명령 전달 |
| **Fanout** | 라우팅 키를 무시하고 **바인딩된 모든 큐로 무조건 복제 브로드캐스트** | 실시간 알림 전체 공지, 여러 마이크로서비스 동시 수신 |
| **Topic** | 라우팅 키의 **와일드카드 패턴(`*`, `#`)**을 매칭하여 유연하게 전달 | 다중 시스템 로그 수집 (`app.error`, `order.#`) |
| **Headers** | 라우팅 키 대신 **메시지 헤더의 Key-Value 속성**을 비교하여 라우팅 | 복합 메타데이터 조건부 라우팅 |

---

## 3. [초보자 1단계] 헬로월드: 가장 단순한 1:1 메시지 송수신

기본(Default) Direct Exchange를 사용하여 큐로 메시지를 보내고 받는 최소 동작 예제입니다.

### 📤 생산자: `producer.py`
```python
import pika

# 1. RabbitMQ 서버 연결 (기본 포트 5672)
connection = pika.BlockingConnection(pika.ConnectionParameters(host='localhost'))
channel = connection.channel()

# 2. 메시지를 받을 큐 선언 (큐가 없으면 자동 생성)
channel.queue_declare(queue='hello_queue')

# 3. 메시지 발행 (기본 익스체인지 사용: routing_key가 큐 이름이 됨)
message = '반갑습니다! RabbitMQ 첫 메시지입니다.'
channel.basic_publish(
    exchange='',
    routing_key='hello_queue',
    body=message.encode('utf-8')
)

print(f" [V] 전송 완료: '{message}'")

# 4. 연결 종료
connection.close()
```

### 📥 소비자: `consumer.py`
```python
import pika

connection = pika.BlockingConnection(pika.ConnectionParameters(host='localhost'))
channel = connection.channel()

channel.queue_declare(queue='hello_queue')

# 메시지 수신 시 호출될 콜백 함수
def callback(ch, method, properties, body):
    print(f" [OK] 수신된 메시지: {body.decode('utf-8')}")

# 구독 등록 (auto_ack=True: 메시지를 받자마자 큐에서 즉시 자동 삭제)
channel.basic_consume(
    queue='hello_queue',
    on_message_callback=callback,
    auto_ack=True
)

print(' [*] 메시지 대기 중입니다. 종료하려면 CTRL+C를 누르세요.')
channel.start_consuming()
```

---

## 4. [초보자 2단계] 작업 큐 (Work Queues) & 공정한 분배 (Prefetch)

여러 워커(Worker) 프로세스가 하나의 큐를 나누어 처리할 때, 작업량에 따라 공정하게 배분하는 패턴입니다.

```text
[Fair Dispatch: 공정한 일감 분배]
                      ┌───────────────┐ ──► [Worker 1] (느린 작업 처리 중...)
[Producer] ──► [Queue]│ ✉️ ✉️ ✉️ ✉️ ✉️ │
                      └───────────────┘ ──► [Worker 2] (빠른 작업 처리 완료 ➔ 다음 메시지 즉시 수신)
                      (prefetch_count=1: 한 번에 1개씩만 전달)
```

### ⚡ 핵심 설정 2가지
1. **수동 확인 응답 (Manual ACK)**: 작업 도중 프로세스가 비정상 종료되면 메시지가 다른 워커에게 재할당되도록 `basic_ack()`를 수동 호출합니다.
2. **공정 분배 (`basic_qos(prefetch_count=1)`)**: 워커가 현재 작업을 완료하고 ACK를 보내기 전까지는 새 메시지를 보내지 않습니다.

```python
import pika
import time

connection = pika.BlockingConnection(pika.ConnectionParameters('localhost'))
channel = connection.channel()

# 큐 내구성(durable=True): RabbitMQ가 재시작되어도 큐 유지
channel.queue_declare(queue='task_queue', durable=True)

# 🚀 핵심: 공정 배분 (워커당 처리 중인 미승인 메시지 최대 1개로 제한)
channel.basic_qos(prefetch_count=1)

def do_work(ch, method, properties, body):
    msg = body.decode('utf-8')
    print(f" [x] 작업 시작: {msg}")
    
    # 작업 시뮬레이션
    time.sleep(2)
    
    print(f" [x] 작업 완료: {msg}")
    # 🚀 핵심: 작업 성공 완료 후 브로커에 수동 ACK 전송
    ch.basic_ack(delivery_tag=method.delivery_tag)

channel.basic_consume(queue='task_queue', on_message_callback=do_work, auto_ack=False)
channel.start_consuming()
```

---

## 5. [초보자 3단계] 발행/구독 (Publish/Subscribe - Fanout Exchange)

동일한 이벤트를 여러 서비스(예: 이메일 발송 큐, 감사 로그 큐, 통계 큐)로 동시에 복제 배포하는 패턴입니다.

```text
[Fanout 브로드캐스트]
                     ┌──────────────────┐ ──► [Email Queue] ──► [Email Service]
[Producer] ──► [Fanout Exchange]        │
                     └──────────────────┘ ──► [Log Queue]   ──► [Log Service]
                     (모든 바인딩 큐로 무조건 복사)
```

```python
# 1. Fanout 익스체인지 선언
channel.exchange_declare(exchange='logs_fanout', exchange_type='fanout')

# 2. 임시 익명 큐 생성 (exclusive=True: 소비자 종료 시 큐 자동 삭제)
result = channel.queue_declare(queue='', exclusive=True)
queue_name = result.method.queue

# 3. 큐를 Fanout 익스체인지에 바인딩
channel.queue_bind(exchange='logs_fanout', queue=queue_name)

# 4. 발행 시에는 routing_key를 비워두어도 모든 큐로 전달됨
channel.basic_publish(
    exchange='logs_fanout',
    routing_key='',
    body=b'System Alert: Database backup completed!'
)
```

---

## 6. [초보자 4단계] 토픽 기반 라우팅 (Topic Exchange)

메시지 라우팅 키에 점(`.`)으로 구분된 단어를 조합하고, 와일드카드로 원하는 패턴만 선택 구독합니다.

### 🎯 와일드카드 규칙
- `*` (별표): **정확히 1개의 단어** 매칭 (예: `kern.*` ➔ `kern.info`, `kern.crit`)
- `#` (우물정): **0개 이상의 단어** 매칭 (예: `audit.#` ➔ `audit`, `audit.user.login`)

```text
[Topic 라우팅 매칭 예시]
Routing Key: "auth.user.login_failed"
  ├── Binding: "*.user.*"        ➔ 매칭 성공! ✅
  ├── Binding: "auth.#"          ➔ 매칭 성공! ✅
  └── Binding: "payment.*"       ➔ 매칭 실패 ❌
```

```python
# Topic 익스체인지 생성
channel.exchange_declare(exchange='topic_logs', exchange_type='topic')

# 중요 에러 큐: 모든 시스템의 critical 로그만 수신 (*.critical)
channel.queue_bind(exchange='topic_logs', queue='critical_queue', routing_key='*.critical')

# 보안 감사 큐: 보안 모듈의 모든 하위 이벤트 수신 (security.#)
channel.queue_bind(exchange='topic_logs', queue='security_queue', routing_key='security.#')

# 메시지 발행 예시
channel.basic_publish(
    exchange='topic_logs',
    routing_key='security.user.password_reset',
    body=b'User 42 reset password'
)
```

---

## 7. 메시지 신뢰성 & 영속성 보장 (Persistence)

서버 전원이 꺼지거나 재부팅되어도 메시지가 증발하지 않도록 보장하는 3단계 안전장치입니다.

```python
# 1. 큐 영속화 (durable=True)
channel.queue_declare(queue='secure_orders', durable=True)

# 2. 메시지 디스크 영속화 (delivery_mode=2)
channel.basic_publish(
    exchange='',
    routing_key='secure_orders',
    body=b'Order #987654',
    properties=pika.BasicProperties(
        delivery_mode=pika.DeliveryMode.Persistent # 디스크 저장
    )
)

# 3. 퍼블리셔 확인 모드 (Publisher Confirms): 브로커가 디스크 기록 후 ACK 반환 보장
channel.confirm_delivery()
```

---

## 8. 데드 레터 큐 (Dead Letter Exchange - DLX)

메시지 처리에 실패하거나(Rejected), 지정된 유효시간(TTL)이 초과된 메시지를 유실 없이 별도 격리 큐로 이동시켜 재시도하는 패턴입니다.

```python
# 1. 실패 메시지를 보관할 DLX 및 데드 레터 큐 준비
channel.exchange_declare(exchange='dlx_exchange', exchange_type='direct')
channel.queue_declare(queue='dead_letter_queue', durable=True)
channel.queue_bind(exchange='dlx_exchange', queue='dead_letter_queue', routing_key='retry_failed')

# 2. 메인 업무 큐 선언 시 DLX 인자 연결
args = {
    'x-dead-letter-exchange': 'dlx_exchange',
    'x-dead-letter-routing-key': 'retry_failed',
    'x-message-ttl': 60000 # 60초 동안 소비되지 않으면 DLX로 이동
}
channel.queue_declare(queue='main_work_queue', durable=True, arguments=args)
```

---

## 9. 실무 백엔드 연동: Spring Boot (Spring AMQP)

Spring Boot 환경에서 가장 많이 쓰이는 설정 및 리스너 어노테이션 패턴입니다.

### 📄 `application.yml`
```yaml
spring:
  rabbitmq:
    host: localhost
    port: 5672
    username: guest
    password: guest
    listener:
      simple:
        acknowledge-mode: manual # 수동 ACK 모드
        prefetch: 1              # 공정 분배
```

### ☕ `@RabbitListener` 수신 및 발행 코드
```java
@Service
public class OrderMessageService {

    @Autowired
    private RabbitTemplate rabbitTemplate;

    // 메시지 발행 (Direct Exchange)
    public void sendOrder(String orderId) {
        rabbitTemplate.convertAndSend("order.exchange", "order.created", orderId);
    }

    // 메시지 수신 및 수동 ACK 처리
    @RabbitListener(queues = "order.queue")
    public void receiveOrder(String orderId, Channel channel, @Header(AmqpHeaders.DELIVERY_TAG) long tag) throws IOException {
        try {
            System.out.println("주문 처리 진행: " + orderId);
            // 비즈니스 로직 수행...
            
            channel.basicAck(tag, false); // 정상 처리 승인
        } catch (Exception e) {
            // 실패 시 큐 재진입 여부(requeue=false) 지정하여 DLX로 이관
            channel.basicNack(tag, false, false);
        }
    }
}
```

---

## 10. CLI 핵심 관리 명령어 치트시트 (`rabbitmqctl`)

```bash
# 1. 서버 상태 및 노드 헬스체크
rabbitmqctl status
rabbitmqctl ping

# 2. 큐 및 익스체인지 상태 조회
rabbitmqctl list_queues name messages_ready messages_unacknowledged consumers
rabbitmqctl list_exchanges name type
rabbitmqctl list_bindings

# 3. 사용자 계정 및 권한 관리
rabbitmqctl add_user admin SuperSecretPass123!
rabbitmqctl set_user_tags admin administrator
rabbitmqctl set_permissions -p / admin ".*" ".*" ".*"

# 4. 가상 호스트(vhost) 관리
rabbitmqctl add_vhost my_vhost
rabbitmqctl list_vhosts

# 5. 큐 강제 비우기 (주의)
rabbitmqctl purge_queue hello_queue
```

---

## 11. 실무 주의사항 & 프로덕션 체크리스트

| 점검 항목 | 권장 사항 | 이유 |
| :--- | :--- | :--- |
| **Auto-ACK 사용 금지** | 실무에서는 반드시 수동 ACK(`auto_ack=False`) 적용 | 애플리케이션 장애 시 처리 중이던 메시지 유실 방지 |
| **Prefetch 제한 설정** | `prefetch_count=1 ~ 50` 지정 | 특정 워커에게 메시지가 수천 개 쏠리는 병목 현상 차단 |
| **영속성 플래그 동기화** | `durable=True` 및 `delivery_mode=2` 함께 적용 | 둘 중 하나라도 누락되면 서버 재시작 시 데이터 손실 |
| **Unacked 누수 감시** | 웹 콘솔에서 Unacked 수치가 계속 증가하는지 모니터링 | `basic_ack` 호출 누락 시 메모리 고갈 원인 1순위 |
| **Quorum Queue 도입** | 고가용성 클러스터 구축 시 Classic 큐 대신 Raft 기반 Quorum 큐 사용 | 데이터 정합성 보장 및 브로커 장애 시 무중단 복구 |
💬
RabbitMQ 치트시트

의견 및 질문

댓글 수정

댓글 삭제
