Começar

Eventos e filas: Valkey, NATS e RabbitMQ.

Tarefas em segundo plano, eventos e mensagens entre os serviços de uma aplicação: quando escolher Valkey, NATS ou RabbitMQ, as variáveis de ligação, exemplos para Laravel, Node.js e Python, recursos, cópias de segurança e limites.

11 MIN DE LEITURA

Quando um site passa trabalho a um worker — enviar um email, redimensionar uma imagem, cobrar uma encomenda — ou um serviço avisa os outros de que algo aconteceu, a mensagem passa por uma fila ou por um message broker. Um projeto pode ter três, cada um adicionado como serviço: Visão geral → Serviços → Adicionar um serviço.

ServiçoEscolha-o para
Valkeyfilas de tarefas simples (filas do Laravel e Horizon, BullMQ, Celery, RQ) e eventos em Streams — quando já o usa para cache e sessões
NATSmensagens leves entre serviços: eventos, pedido e resposta, e streams duráveis com JetStream
RabbitMQum message broker clássico: encaminhamento através de exchanges, confirmações, novas tentativas e dead-lettering, quorum queues

Se não tiver a certeza, comece pelo Valkey para as tarefas em segundo plano: a maioria das frameworks suporta-o de origem. Escolha o RabbitMQ quando as mensagens tiverem de ser encaminhadas entre muitas filas e nenhuma se puder perder, e o NATS quando os serviços trocam muitas mensagens pequenas ou pedem respostas uns aos outros.

Valkey: filas de tarefas e Streams

O Valkey é um armazenamento compatível com Redis — o mesmo serviço gerido que em Bases de dados. O primeiro Valkey da aplicação dá a cada serviço de código REDIS_URL, REDIS_HOST, REDIS_PORT e REDIS_PASSWORD; cada Valkey fornece ainda a sua própria RIVERVO_<NAME>_URL.

Três formas de enviar mensagens através dele:

  • Filas de tarefas — filas do Laravel com o driver redis e Horizon, BullMQ, Celery, RQ. A biblioteca guarda as tarefas no Valkey; um worker vai buscá-las uma a uma e repete as que falham.
  • Streams com grupos de consumidores — XADD acrescenta um evento a um stream, os consumidores de um grupo leem-no com XREADGROUP e confirmam-no com XACK. Os eventos ficam guardados: um consumidor que tenha parado continua onde ficou, um evento não confirmado pode ser recolhido de novo e um grupo novo pode ler o stream desde o início.
  • Pub/Sub — PUBLISH e SUBSCRIBE entregam uma mensagem apenas aos subscritores ligados nesse momento. A mensagem não fica guardada: um subscritor que esteja a reiniciar ou ainda não ligado perde-a. Use o Pub/Sub só onde uma mensagem perdida não faça mal (por exemplo, um sinal de «atualizar») e Streams ou uma fila para tudo o resto.

O Valkey tem cópia de segurança diária, como as outras bases de dados; também pode ser acedido a partir do exterior se abrir o acesso. Consulte Bases de dados.

NATS

O NATS é um sistema de mensagens leve e rápido, com o JetStream ativado:

  • Publicação e subscrição — um serviço publica num assunto como orders.created e cada subscritor desse assunto recebe a mensagem. Sem JetStream, é «envia e esquece», como o Pub/Sub acima.
  • Pedido e resposta — um serviço pergunta, outro responde. Quando várias instâncias respondem como queue group, o NATS distribui os pedidos entre elas.
  • JetStream — streams duráveis: as mensagens ficam guardadas no disco do serviço, um consumidor lembra-se do que já leu e cada mensagem é entregue pelo menos uma vez até ser confirmada.
  • Armazenamento chave-valor e de objetos assente no JetStream — para pequenas definições partilhadas, bloqueios ou ficheiros entre serviços.

Variáveis. O primeiro NATS da aplicação dá a cada serviço de código:

NATS_URL=nats://<user>:<password>@<service name>:4222

Cada serviço NATS fornece ainda RIVERVO_<NAME>_URL com um endereço da mesma forma — NAME é o nome do serviço em maiúsculas, com os hífenes trocados por _: um serviço chamado events dá RIVERVO_EVENTS_URL.

O JetStream guarda os streams no disco do serviço; os streams mantidos em memória podem usar cerca de um quarto da memória do serviço.

RabbitMQ

O RabbitMQ 4.1 é um message broker clássico: os produtores publicam em exchanges, as exchanges encaminham as mensagens para filas por routing keys, os consumidores confirmam cada mensagem e uma mensagem rejeitada ou expirada pode ir para uma exchange de dead-letter. Para filas cujas mensagens tenham de sobreviver a um reinício, use quorum queues (o argumento x-queue-type: quorum) e publique as mensagens como persistentes.

Variáveis. O primeiro RabbitMQ da aplicação dá a cada serviço de código:

VariávelValor
AMQP_URLamqp://<user>:<password>@<service name>:5672/%2f
RABBITMQ_HOSTo nome do serviço
RABBITMQ_PORT5672
RABBITMQ_USER, RABBITMQ_PASSWORDo utilizador e a palavra-passe
RABBITMQ_VHOST/

O %2f no fim de AMQP_URL é o virtual host predefinido /, escrito da forma que os endereços de ligação exigem. Cada serviço RabbitMQ fornece ainda a sua própria RIVERVO_<NAME>_URL com um endereço da mesma forma.

API de gestão. A API HTTP de gestão escuta na porta 15672 dentro da rede privada da aplicação: os serviços da aplicação chegam a ela em http://<service name>:15672 com o mesmo utilizador e palavra-passe, por exemplo:

curl -u "$RABBITMQ_USER:$RABBITMQ_PASSWORD" "http://$RABBITMQ_HOST:15672/api/queues"

Não há página de gestão na internet. A página do serviço no painel mostra uma lista curta, só de leitura, das suas filas: mensagens prontas, não confirmadas e consumidores.

Apenas interno

O NATS e o RabbitMQ não têm endereço público e não podem ser acedidos de fora da aplicação — a partir do seu computador, de outro servidor ou de outra aplicação. Ao contrário do PostgreSQL, do MySQL e do Valkey, não há acesso a partir do exterior para eles. Os serviços que publicam e consomem mensagens funcionam como serviços da mesma aplicação: serviços web, workers em segundo plano e tarefas agendadas.

Segundo serviço do mesmo tipo

Só o primeiro Valkey, NATS e RabbitMQ da aplicação recebem os nomes habituais (REDIS_*, NATS_URL, AMQP_URL e RABBITMQ_*). O seguinte do mesmo tipo acrescenta apenas a sua própria RIVERVO_<NAME>_URL; leia essa variável no seu código ou defina os nomes habituais com os valores dela no separador Variáveis. As variáveis chegam a um serviço no deploy seguinte — consulte Variáveis de ambiente.

Laravel

Valkey. Defina no separador Variáveis:

QUEUE_CONNECTION=redis

Execute php artisan queue:work — ou php artisan horizon com o Horizon — como worker em segundo plano. Consulte Laravel.

RabbitMQ. O Laravel não tem um driver de RabbitMQ incluído e a Rivervo não altera QUEUE_CONNECTION por si. Para usar o RabbitMQ nas filas do Laravel:

  1. Instale o pacote: composer require vladimir-yuldashev/laravel-queue-rabbitmq.
  2. Adicione a ligação rabbitmq ao config/queue.php, como o README do pacote indica para a sua versão. Lê RABBITMQ_HOST, RABBITMQ_PORT, RABBITMQ_USER, RABBITMQ_PASSWORD e RABBITMQ_VHOST, que a aplicação já tem:
'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', '/'),
        ],
    ],
],
  1. Defina QUEUE_CONNECTION=rabbitmq no separador Variáveis e faça o deploy. O worker continua a ser php artisan queue:work.

NATS. Não existe um driver de filas oficial do Laravel para o NATS. Use um cliente NATS para PHP no seu próprio código — por exemplo, basis-company/nats — e passe-lhe o anfitrião, a porta, o utilizador e a palavra-passe de NATS_URL. Confirme que o cliente suporta as funcionalidades de que precisa (JetStream, chave-valor) antes de construir sobre ele.

Node.js

BullMQ (Valkey)

import { Queue, Worker } from 'bullmq'
import IORedis from 'ioredis'
 
const connection = new IORedis(process.env.REDIS_URL, { maxRetriesPerRequest: null })
 
// in the web service
const emails = new Queue('emails', { connection })
await emails.add('welcome', { userId: 42 }, { attempts: 3 })
 
// in the background worker
new Worker('emails', async (job) => {
  await sendWelcome(job.data.userId)
}, { connection })

O BullMQ exige maxRetriesPerRequest: null na ligação usada pelos seus workers.

Valkey Streams

import IORedis from 'ioredis'
 
const redis = new IORedis(process.env.REDIS_URL)
 
// producer
await redis.xadd('orders', '*', 'id', '42')
 
// consumer of the group «billing»
await redis.xgroup('CREATE', 'orders', 'billing', '0', 'MKSTREAM').catch((err) => {
  if (!String(err).includes('BUSYGROUP')) throw err // the group already exists
})
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)
    }
  }
}

Uma entrada lida mas não confirmada fica pendente no grupo; XAUTOCLAIM passa-a a outro consumidor.

NATS (nats.js)

import { connect, JSONCodec, AckPolicy } from 'nats'
 
const nc = await connect({ servers: process.env.NATS_URL })
const jc = JSONCodec()
 
// once: a stream for the subjects orders.* and a durable consumer
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 })
 
// producer
const js = nc.jetstream()
await js.publish('orders.created', jc.encode({ id: 42 }))
 
// consumer
const consumer = await js.consumers.get('ORDERS', 'billing')
for await (const m of await consumer.consume()) {
  await handleOrder(jc.decode(m.data))
  m.ack()
}

Pedido e resposta: um serviço responde com nc.subscribe('prices.get', { queue: 'prices', callback: (err, msg) => msg.respond(jc.encode(price)) }), outro pergunta com 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' } })
 
// producer
ch.sendToQueue('emails', Buffer.from(JSON.stringify({ userId: 42 })), { persistent: true })
 
// consumer: at most 10 unacknowledged messages at a time
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) // to the dead-letter exchange, if the queue has one
  }
})

Todos os serviços que declaram a fila têm de a declarar com os mesmos argumentos.

Python

Celery (Valkey ou RabbitMQ)

import os
from celery import Celery
 
app = Celery("tasks", broker=os.environ["REDIS_URL"])  # or os.environ["AMQP_URL"]
 
@app.task(acks_late=True)
def send_welcome(user_id):
    ...

Execute celery -A tasks worker --loglevel=info como worker em segundo plano. O Celery aceita endereços amqp:// tal como estão. Com o RabbitMQ, as versões recentes do Celery podem declarar quorum queues (task_default_queue_type = "quorum") — consulte a documentação do Celery para a sua versão.

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)

O worker: 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"})
 
# producer
ch.basic_publish(exchange="", routing_key="emails",
                 body=json.dumps({"user_id": 42}),
                 properties=pika.BasicProperties(delivery_mode=2))
 
# consumer
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()

Entregue mais do que uma vez

As filas e os brokers voltam a entregar uma mensagem quando um worker para antes de a confirmar — durante um deploy, um reinício ou um restauro. Escreva os consumidores de forma que tratar a mesma mensagem duas vezes não cause problemas: guarde o ID de cada mensagem processada ou torne a própria ação repetível (por exemplo, «definir o estado como pago» em vez de «adicionar um pagamento»).

Recursos e preço

ServiçoComeça comMemória mínima
NATS256 MB de memória · 1 núcleo de CPU · 5 GB de disco256 MB
RabbitMQ1 GB de memória · 1 núcleo de CPU · 10 GB de disco512 MB

O preço de cada um depende da memória, da CPU e do disco, como em qualquer serviço — consulte Serviços de um projeto. Os recursos podem ser alterados mais tarde em Definições do serviço.

Cópias de segurança e restauro

O NATS e o RabbitMQ têm cópia de segurança diária; guardamos os últimos 7 dias e 4 semanas, como nos outros serviços.

  • A cópia de segurança copia os ficheiros de dados do serviço enquanto este funciona. No RabbitMQ, a mesma cópia inclui também uma exportação das definições: utilizadores, virtual hosts, filas, exchanges, bindings e políticas.
  • Não há restauro para um momento exato — isso existe só para o PostgreSQL e o MySQL. Restaura uma das cópias diárias.
  • Um restauro para o serviço por pouco tempo, repõe os ficheiros e volta a arrancá-lo. As mensagens que chegaram ou foram confirmadas por volta da hora da cópia podem faltar ou ser entregues de novo — mais uma razão para tornar os consumidores seguros para repetição.
  • No RabbitMQ, se os ficheiros copiados não conseguirem arrancar, o serviço arranca só com as definições: as filas, as exchanges e os utilizadores estão lá, mas as mensagens da cópia perdem-se.

Manutenção e mudanças de servidor

O NATS e o RabbitMQ não têm hora de manutenção para definir. Não são mudados automaticamente para outro servidor; se algum dia for necessário, o suporte combina isso consigo.

Ainda com dúvidas?

Fale connosco por chat — a AI responde de imediato e um engenheiro entra quando for preciso, a qualquer hora.

Contactar o suporte