이벤트와 큐: Valkey, NATS, RabbitMQ.
애플리케이션 서비스 간 백그라운드 작업, 이벤트, 메시지: Valkey, NATS, RabbitMQ 중 무엇을 선택할지, 연결 변수, Laravel·Node.js·Python 예시, 리소스, 백업, 제한을 안내합니다.
사이트가 이메일 발송, 이미지 크기 조정, 주문 결제 같은 작업을 워커에 넘기거나, 한 서비스가 다른 서비스에 어떤 일이 일어났다고 알릴 때 메시지는 큐나 메시지 브로커를 거칩니다. 프로젝트에는 세 가지를 각각 서비스로 추가할 수 있습니다: 개요 → 서비스 → 서비스 추가.
| 서비스 | 이럴 때 선택 |
|---|---|
| Valkey | 간단한 작업 큐(Laravel 큐와 Horizon, BullMQ, Celery, RQ)와 Streams 이벤트 — 이미 캐시와 세션에 사용 중일 때 |
| NATS | 서비스 간 가벼운 메시징: 이벤트, 요청과 응답, JetStream을 이용한 영속 스트림 |
| RabbitMQ | 전통적인 메시지 브로커: exchange를 통한 라우팅, 확인 응답, 재시도와 dead-lettering, quorum 큐 |
잘 모르겠다면 백그라운드 작업에는 Valkey로 시작하세요. 대부분의 프레임워크가 기본으로 지원합니다. 메시지를 여러 큐 사이에서 라우팅해야 하고 하나도 잃으면 안 될 때는 RabbitMQ를, 서비스끼리 작은 메시지를 많이 주고받거나 서로 응답을 요청할 때는 NATS를 선택하세요.
Valkey: 작업 큐와 Streams
Valkey는 Redis 호환 저장소로, 데이터베이스와 같은 관리형 서비스입니다. 애플리케이션의 첫 번째 Valkey는 모든 코드 서비스에 REDIS_URL, REDIS_HOST, REDIS_PORT, REDIS_PASSWORD를 제공하며, 모든 Valkey는 자체 RIVERVO_<NAME>_URL도 제공합니다.
Valkey로 메시지를 보내는 방법은 세 가지입니다.
- 작업 큐 —
redis드라이버를 쓰는 Laravel 큐와 Horizon, BullMQ, Celery, RQ. 라이브러리가 작업을 Valkey에 보관하고, 워커가 하나씩 가져가 실패한 작업을 재시도합니다. - 컨슈머 그룹이 있는 Streams —
XADD로 스트림에 이벤트를 추가하고, 그룹의 컨슈머가XREADGROUP으로 읽고XACK로 확인합니다. 이벤트는 저장되므로 멈췄던 컨슈머는 중단한 곳부터 이어서 읽고, 확인되지 않은 이벤트는 다시 가져갈 수 있으며, 새 그룹은 스트림을 처음부터 읽을 수 있습니다. - Pub/Sub —
PUBLISH와SUBSCRIBE는 그 순간 연결된 구독자에게만 메시지를 전달합니다. 메시지는 저장되지 않아 재시작 중이거나 아직 연결되지 않은 구독자는 받지 못합니다. Pub/Sub는 메시지를 잃어도 문제없는 곳(예: “새로고침” 신호)에만 쓰고, 그 밖에는 Streams나 큐를 쓰세요.
Valkey는 다른 데이터베이스와 마찬가지로 매일 백업되며, 접속을 허용하면 외부에서도 연결할 수 있습니다. 데이터베이스를 참고하세요.
NATS
NATS는 가볍고 빠른 메시징 시스템으로, JetStream이 켜져 있습니다.
- 발행과 구독 — 서비스가
orders.created같은 subject에 발행하면 해당 subject의 모든 구독자가 메시지를 받습니다. JetStream 없이는 위의 Pub/Sub처럼 보내고 끝나는 방식입니다. - 요청과 응답 — 한 서비스가 묻고 다른 서비스가 답합니다. 여러 인스턴스가 queue group으로 응답하면 NATS가 요청을 나누어 보냅니다.
- JetStream — 영속 스트림: 메시지는 서비스 디스크에 저장되고, 컨슈머는 읽은 위치를 기억하며, 모든 메시지는 확인될 때까지 최소 한 번 전달됩니다.
- JetStream 기반 키-값 저장소와 오브젝트 저장소 — 서비스 간 작은 공유 설정, 잠금, 파일용.
변수. 애플리케이션의 첫 번째 NATS는 모든 코드 서비스에 다음을 제공합니다.
NATS_URL=nats://<user>:<password>@<service name>:4222
모든 NATS 서비스는 같은 형식의 주소가 담긴 RIVERVO_<NAME>_URL도 제공합니다. NAME은 서비스 이름을 대문자로 쓰고 대시를 _로 바꾼 것입니다. 이름이 events인 서비스는 RIVERVO_EVENTS_URL을 제공합니다.
JetStream은 스트림을 서비스 디스크에 보관합니다. 메모리에 보관하는 스트림은 서비스 메모리의 약 4분의 1까지 사용할 수 있습니다.
RabbitMQ
RabbitMQ 4.1은 전통적인 메시지 브로커입니다. 프로듀서는 exchange에 발행하고, exchange는 라우팅 키에 따라 메시지를 큐로 보내며, 컨슈머는 각 메시지를 **확인(ack)**합니다. 거부되거나 만료된 메시지는 dead-letter exchange로 보낼 수 있습니다. 재시작 후에도 메시지가 남아야 하는 큐에는 quorum 큐(인수 x-queue-type: quorum)를 쓰고 메시지를 persistent로 발행하세요.
변수. 애플리케이션의 첫 번째 RabbitMQ는 모든 코드 서비스에 다음을 제공합니다.
| 변수 | 값 |
|---|---|
AMQP_URL | amqp://<user>:<password>@<service name>:5672/%2f |
RABBITMQ_HOST | 서비스 이름 |
RABBITMQ_PORT | 5672 |
RABBITMQ_USER, RABBITMQ_PASSWORD | 사용자와 비밀번호 |
RABBITMQ_VHOST | / |
AMQP_URL 끝의 %2f는 기본 가상 호스트 /를 연결 주소 형식에 맞게 쓴 것입니다. 모든 RabbitMQ 서비스는 같은 형식의 주소가 담긴 자체 RIVERVO_<NAME>_URL도 제공합니다.
관리 API. 관리용 HTTP API는 애플리케이션 사설 네트워크 안의 15672 포트에서 수신합니다. 애플리케이션의 서비스는 같은 사용자와 비밀번호로 http://<service name>:15672에 접속합니다. 예:
curl -u "$RABBITMQ_USER:$RABBITMQ_PASSWORD" "http://$RABBITMQ_HOST:15672/api/queues"인터넷에 공개된 관리 페이지는 없습니다. 관리 패널의 서비스 페이지에 큐 목록이 읽기 전용으로 간단히 표시됩니다: 대기 중인 메시지, 미확인 메시지, 컨슈머 수.
내부 전용
NATS와 RabbitMQ에는 공개 주소가 없으며, 애플리케이션 밖(내 컴퓨터, 다른 서버, 다른 애플리케이션)에서는 접속할 수 없습니다. PostgreSQL, MySQL, Valkey와 달리 외부 접속은 제공되지 않습니다. 메시지를 발행하고 소비하는 서비스는 같은 애플리케이션의 서비스로 실행됩니다: 웹 서비스, 백그라운드 워커, 예약 작업.
같은 종류의 두 번째 서비스
애플리케이션의 첫 번째 Valkey, NATS, RabbitMQ만 일반적인 이름(REDIS_*, NATS_URL, AMQP_URL, RABBITMQ_*)을 받습니다. 같은 종류의 다음 서비스는 자체 RIVERVO_<NAME>_URL만 추가합니다. 코드에서 이 변수를 읽거나, 변수 탭에서 일반적인 이름에 그 값을 설정하세요. 변수는 다음 배포 때 서비스에 적용됩니다. 환경 변수를 참고하세요.
Laravel
Valkey. 변수 탭에서 설정하세요.
QUEUE_CONNECTION=redisphp artisan queue:work(Horizon을 쓴다면 php artisan horizon)를 백그라운드 워커로 실행하세요. Laravel을 참고하세요.
RabbitMQ. Laravel에는 RabbitMQ 드라이버가 기본으로 없으며, Rivervo는 QUEUE_CONNECTION을 자동으로 변경하지 않습니다. Laravel 큐에 RabbitMQ를 쓰려면:
- 패키지를 설치하세요:
composer require vladimir-yuldashev/laravel-queue-rabbitmq. - 패키지 README에 나온 버전별 방법대로
config/queue.php에rabbitmq연결을 추가하세요. 애플리케이션에 이미 있는RABBITMQ_HOST,RABBITMQ_PORT,RABBITMQ_USER,RABBITMQ_PASSWORD,RABBITMQ_VHOST를 읽습니다.
'rabbitmq' => [
'driver' => 'rabbitmq',
'hosts' => [
[
'host' => env('RABBITMQ_HOST', '127.0.0.1'),
'port' => env('RABBITMQ_PORT', 5672),
'user' => env('RABBITMQ_USER', 'guest'),
'password' => env('RABBITMQ_PASSWORD', 'guest'),
'vhost' => env('RABBITMQ_VHOST', '/'),
],
],
],- 변수 탭에서
QUEUE_CONNECTION=rabbitmq를 설정하고 배포하세요. 워커는 그대로php artisan queue:work입니다.
NATS. Laravel에는 공식 NATS 큐 드라이버가 없습니다. 직접 작성하는 코드에서 PHP용 NATS 클라이언트(예: basis-company/nats)를 사용하고, NATS_URL의 호스트, 포트, 사용자, 비밀번호를 넘겨 주세요. 이를 기반으로 개발하기 전에 클라이언트가 필요한 기능(JetStream, 키-값)을 지원하는지 확인하세요.
Node.js
BullMQ (Valkey)
import { Queue, Worker } from 'bullmq'
import IORedis from 'ioredis'
const connection = new IORedis(process.env.REDIS_URL, { maxRetriesPerRequest: null })
// 웹 서비스에서
const emails = new Queue('emails', { connection })
await emails.add('welcome', { userId: 42 }, { attempts: 3 })
// 백그라운드 워커에서
new Worker('emails', async (job) => {
await sendWelcome(job.data.userId)
}, { connection })BullMQ 워커가 쓰는 연결에는 maxRetriesPerRequest: null이 필요합니다.
Valkey Streams
import IORedis from 'ioredis'
const redis = new IORedis(process.env.REDIS_URL)
// 프로듀서
await redis.xadd('orders', '*', 'id', '42')
// 그룹 “billing”의 컨슈머
await redis.xgroup('CREATE', 'orders', 'billing', '0', 'MKSTREAM').catch((err) => {
if (!String(err).includes('BUSYGROUP')) throw err // 그룹이 이미 있음
})
const me = process.env.HOSTNAME ?? 'worker'
for (;;) {
const res = await redis.xreadgroup('GROUP', 'billing', me, 'COUNT', 10, 'BLOCK', 5000, 'STREAMS', 'orders', '>')
for (const [, entries] of res ?? []) {
for (const [id, fields] of entries) {
await handleOrder(fields)
await redis.xack('orders', 'billing', id)
}
}
}읽었지만 확인하지 않은 항목은 그룹에 대기 상태로 남으며, XAUTOCLAIM으로 다른 컨슈머에 넘길 수 있습니다.
NATS (nats.js)
import { connect, JSONCodec, AckPolicy } from 'nats'
const nc = await connect({ servers: process.env.NATS_URL })
const jc = JSONCodec()
// 한 번만: subject orders.*용 스트림과 영속 컨슈머
const jsm = await nc.jetstreamManager()
await jsm.streams.add({ name: 'ORDERS', subjects: ['orders.>'] })
await jsm.consumers.add('ORDERS', { durable_name: 'billing', ack_policy: AckPolicy.Explicit })
// 프로듀서
const js = nc.jetstream()
await js.publish('orders.created', jc.encode({ id: 42 }))
// 컨슈머
const consumer = await js.consumers.get('ORDERS', 'billing')
for await (const m of await consumer.consume()) {
await handleOrder(jc.decode(m.data))
m.ack()
}요청과 응답: 한 서비스는 nc.subscribe('prices.get', { queue: 'prices', callback: (err, msg) => msg.respond(jc.encode(price)) })로 응답하고, 다른 서비스는 await nc.request('prices.get', jc.encode({ sku: 'A1' }), { timeout: 2000 })로 요청합니다.
RabbitMQ (amqplib)
import amqp from 'amqplib'
const conn = await amqp.connect(process.env.AMQP_URL)
const ch = await conn.createChannel()
await ch.assertQueue('emails', { durable: true, arguments: { 'x-queue-type': 'quorum' } })
// 프로듀서
ch.sendToQueue('emails', Buffer.from(JSON.stringify({ userId: 42 })), { persistent: true })
// 컨슈머: 미확인 메시지는 한 번에 최대 10개
await ch.prefetch(10)
await ch.consume('emails', async (msg) => {
try {
await sendWelcome(JSON.parse(msg.content.toString()).userId)
ch.ack(msg)
} catch {
ch.nack(msg, false, false) // 큐에 dead-letter exchange가 있으면 그쪽으로
}
})큐를 선언하는 모든 서비스는 같은 인수로 선언해야 합니다.
Python
Celery (Valkey 또는 RabbitMQ)
import os
from celery import Celery
app = Celery("tasks", broker=os.environ["REDIS_URL"]) # 또는 os.environ["AMQP_URL"]
@app.task(acks_late=True)
def send_welcome(user_id):
...celery -A tasks worker --loglevel=info를 백그라운드 워커로 실행하세요. Celery는 amqp:// 주소를 그대로 받습니다. RabbitMQ를 쓸 때 최신 Celery 버전은 quorum 큐를 선언할 수 있습니다(task_default_queue_type = "quorum"). 사용 중인 버전의 Celery 문서를 참고하세요.
RQ (Valkey)
import os
from redis import Redis
from rq import Queue
queue = Queue("emails", connection=Redis.from_url(os.environ["REDIS_URL"]))
queue.enqueue(send_welcome, 42)워커: rq worker emails --url "$REDIS_URL".
NATS (nats-py)
import asyncio, json, os
import nats
from nats.errors import TimeoutError
async def main():
nc = await nats.connect(os.environ["NATS_URL"])
js = nc.jetstream()
await js.add_stream(name="ORDERS", subjects=["orders.>"])
await js.publish("orders.created", json.dumps({"id": 42}).encode())
sub = await js.pull_subscribe("orders.>", durable="billing")
while True:
try:
msgs = await sub.fetch(10, timeout=5)
except TimeoutError:
continue
for msg in msgs:
await handle_order(json.loads(msg.data))
await msg.ack()
asyncio.run(main())RabbitMQ (pika)
import json, os
import pika
conn = pika.BlockingConnection(pika.URLParameters(os.environ["AMQP_URL"]))
ch = conn.channel()
ch.queue_declare(queue="emails", durable=True, arguments={"x-queue-type": "quorum"})
# 프로듀서
ch.basic_publish(exchange="", routing_key="emails",
body=json.dumps({"user_id": 42}),
properties=pika.BasicProperties(delivery_mode=2))
# 컨슈머
def on_message(ch, method, properties, body):
send_welcome(json.loads(body)["user_id"])
ch.basic_ack(delivery_tag=method.delivery_tag)
ch.basic_qos(prefetch_count=10)
ch.basic_consume(queue="emails", on_message_callback=on_message)
ch.start_consuming()중복 전달
워커가 메시지를 확인하기 전에 멈추면(배포, 재시작, 복원 중) 큐와 브로커는 메시지를 다시 전달합니다. 같은 메시지를 두 번 처리해도 문제가 없도록 컨슈머를 작성하세요. 처리한 모든 메시지의 ID를 보관하거나, 동작 자체를 반복 가능하게 만드세요(예: “결제 추가” 대신 “상태를 결제 완료로 설정”).
리소스와 요금
| 서비스 | 시작 사양 | 최소 메모리 |
|---|---|---|
| NATS | 메모리 256MB · CPU 1코어 · 디스크 5GB | 256MB |
| RabbitMQ | 메모리 1GB · CPU 1코어 · 디스크 10GB | 512MB |
각 서비스는 다른 서비스와 마찬가지로 메모리, CPU, 디스크에 따라 요금이 정해집니다. 프로젝트 서비스를 참고하세요. 리소스는 나중에 서비스의 설정에서 변경할 수 있습니다.
백업과 복원
NATS와 RabbitMQ는 다른 서비스와 마찬가지로 매일 백업되며, 최근 7일분과 4주분을 보관합니다.
- 백업은 서비스가 실행되는 동안 데이터 파일을 복사합니다. RabbitMQ는 같은 백업에 정의(사용자, 가상 호스트, 큐, exchange, 바인딩, 정책) 내보내기도 포함됩니다.
- 특정 시점으로 복원은 불가능합니다. 이는 PostgreSQL과 MySQL에서만 가능하며, 매일 사본 중 하나로 복원합니다.
- 복원하면 서비스가 잠시 멈추고 파일을 되돌린 뒤 다시 시작됩니다. 백업 시점 전후에 도착했거나 확인된 메시지는 누락되거나 다시 전달될 수 있습니다. 컨슈머를 반복 처리에 안전하게 만들어야 하는 또 하나의 이유입니다.
- RabbitMQ의 경우 복사된 파일로 시작할 수 없으면 정의만으로 서비스가 시작됩니다. 큐, exchange, 사용자는 있지만 백업의 메시지는 사라집니다.
유지 보수와 이전
NATS와 RabbitMQ에는 설정할 유지 보수 시간이 없습니다. 다른 서버로 자동 이전되지 않으며, 이전이 필요해지면 고객 지원팀이 고객님과 일정을 조율합니다.