Tutoriais de VPS
RabbitMQ na VPS: TLS, permissões mínimas e recuperação de mensagens
Implante RabbitMQ com Compose, AMQPS privado e Caddy HTTPS. Corrija permissões de certificados, valide hostnames, configure usuários e entrega confiável e recupere definitions e mensagens com backups adequados.

Colocar pagamentos, pedidos, e-mail e tarefas de IA na mesma requisição HTTP faz o serviço depender de todos os componentes. O RabbitMQ separa produtores e consumidores: o aplicativo publica mensagens, workers processam no próprio ritmo e confirmações, tentativas e filas de mensagens rejeitadas tratam falhas.
O guia usa Ubuntu 24.04, Docker Compose e Caddy. O exemplo conferido em 15 de setembro de 2026 fixava RabbitMQ 4.3.5. A versão oficial mais recente consultada em 16 de novembro é 4.4.0. O Compose 4.3.5 permanece como exemplo específico; para instalação nova, revise a versão atual e fixe sua imagem management. Instâncias existentes precisam seguir o caminho de atualização suportado.
RabbitMQ é um broker, não um banco nem um painel de agendamento:
- Requisições publicam; workers processam e-mail, imagens e relatórios.
- Exchanges e filas separam pedidos, estoque e pagamentos.
- Acknowledgments, publisher confirms e dead-letter exchanges tratam falhas.
- Consumidores concorrentes dividem o trabalho da mesma fila e permitem escalar.
- Há clientes AMQP 0-9-1, AMQP 1.0, MQTT, STOMP e Stream, com os plugins correspondentes.
- UI, API HTTP e Prometheus mostram conexões, acúmulo, vazão e alarmes.
Para executar um script a cada minuto, cron ou systemd timer são mais simples. Para eventos retidos e reprodução de logs, considere Kafka. RabbitMQ atende tarefas de negócio, roteamento flexível e confirmação pelo aplicativo.
| Arquitetura | Vantagem | Limitação | Uso |
|---|---|---|---|
| Um nó | Implantação e diagnóstico simples, menor custo | Falha da VPS ou disco interrompe o serviço | Desenvolvimento e tarefas com recuperação tolerável |
| Vários contêineres na mesma VPS | Permite testar configurações | Compartilha host, disco e rede | Laboratório, sem HA real |
| Três nós independentes com quorum queues | Tolera um membro indisponível mantendo maioria | Mais custo e operação | Serviços críticos |
Use grupos ímpares para replicação por quorum, normalmente 3 ou 5. Dois membros não oferecem tolerância útil a uma falha individual com maioria. Confira os membros de cada fila: três brokers não garantem três réplicas em todas as filas.
Aqui é preparado um nó recuperável com nome estável. Para infraestrutura crítica, use domínios de falha independentes em vez de acrescentar contêineres ao mesmo host.
A capacidade depende de conexões, canais, filas, tamanho das mensagens, tempo de acúmulo, confirmações e latência do disco.
| Carga | VPS sugerida | Condição |
|---|---|---|
| Desenvolvimento | 2 vCPU, 2GB RAM, SSD de 30GB | Sem acúmulo importante; admite parada |
| Produção pequena, mensagens curtas | 2–4 vCPU, 4GB RAM, NVMe de 60GB | Folga para broker, cache e monitoramento |
| Muitas conexões ou acúmulo prolongado | 4 vCPU, pelo menos 8GB RAM, NVMe dedicado | Medir mensagens, latência dos confirms e disco |
| Porta | Função | Exposição |
|---|---|---|
5671/TCP | AMQP TLS | Loopback; IP privado para clientes remotos |
5672/TCP | AMQP sem criptografia | Desativado |
15672/TCP | Administração UI/API | 127.0.0.1 atrás do Caddy |
15692/TCP | Prometheus | 127.0.0.1 |
4369/TCP | epmd | Sem publicação |
25672/TCP | Comunicação entre nós | Sem publicação aqui; rede privada no cluster |
Não publique 5672, 15672, 4369 ou 25672 na internet. O Docker pode contornar algumas regras do firewall do host. Para AMQP remoto, combine binding privado, regras de origem do provedor e TLS; veja proteção de bancos e middleware.
Instale antes Docker Engine e Compose v2 pelas instruções oficiais para Ubuntu. Este bloco instala Caddy e ferramentas e verifica o Docker:
sudo apt update
sudo apt full-upgrade -y
sudo apt install -y ca-certificates curl openssl caddy
docker --version
docker compose version
sudo systemctl enable --now caddy
Planeje atualizações, reinicializações, limites de logs, saúde e recuperação com a lista de Compose para produção.
sudo install -d -m 0750 -o "$USER" -g "$USER" /opt/rabbitmq
cd /opt/rabbitmq
install -d -m 0750 data tls
install -d -m 0700 pki backups
umask 077
Crie .env. Mantenha AMQPS no loopback; clientes remotos devem usar uma interface WireGuard ou privada:
{
printf 'RABBITMQ_ADMIN_USER=opsadmin\n'
printf 'RABBITMQ_ADMIN_PASS=%s\n' "$(openssl rand -hex 32)"
printf 'RABBITMQ_DEFAULT_VHOST=production\n'
printf 'RABBITMQ_BIND_IP=127.0.0.1\n'
} > .env
chmod 600 .env
O comando sobrescreve o arquivo de ambiente, portanto só serve para instância nova. Não coloque .env nem strings de conexão em Git, logs ou chamados. Os valores do usuário padrão só inicializam um diretório vazio; editar .env depois não altera contas existentes.
Gere uma CA interna e certificado para mq.example.com:
cd /opt/rabbitmq/pki
openssl genrsa -out ca.key 4096
openssl req -x509 -new -sha256 -days 3650 \
-key ca.key \
-subj '/CN=RabbitMQ Internal CA' \
-out ca.crt
openssl genrsa -out server.key 4096
openssl req -new -sha256 \
-key server.key \
-subj '/CN=mq.example.com' \
-out server.csr
printf '%s\n' \
'subjectAltName=DNS:mq.example.com' \
'extendedKeyUsage=serverAuth' > server.ext
openssl x509 -req -sha256 -days 825 \
-in server.csr \
-CA ca.crt \
-CAkey ca.key \
-CAcreateserial \
-extfile server.ext \
-out server.crt
install -m 0644 ca.crt server.crt /opt/rabbitmq/tls/
install -m 0600 server.key /opt/rabbitmq/tls/
Guarde ca.key offline ou criptografada, sem montar no broker nem distribuir aos clientes. Estes confiam em ca.crt. Troque o hostname do exemplo no subject e no SAN. Uma CA empresarial também serve, com SAN correspondente. Acompanhe validade e renovação.
Crie /opt/rabbitmq/rabbitmq.conf:
listeners.tcp = none
listeners.ssl.default = 5671
ssl_options.cacertfile = /etc/rabbitmq/tls/ca.crt
ssl_options.certfile = /etc/rabbitmq/tls/server.crt
ssl_options.keyfile = /etc/rabbitmq/tls/server.key
ssl_options.verify = verify_peer
ssl_options.fail_if_no_peer_cert = false
management.tcp.ip = 0.0.0.0
management.tcp.port = 15672
prometheus.tcp.ip = 0.0.0.0
prometheus.tcp.port = 15692
vm_memory_high_watermark.relative = 0.5
disk_free_limit.absolute = 2GB
AMQP sem criptografia fica desativado; 5671 usa TLS. verify_peer verifica o certificado de cliente quando apresentado; fail_if_no_peer_cert=false permite clientes TLS sem certificado com usuário e senha. Para exigir mTLS, emita certificados de cliente e altere para true após testar compatibilidade.
O limite de alarme padrão documentado fica perto de 60% da memória detectada; aqui é 50%. Confira quanto o broker detecta no contêiner. O limite de 2GB do contêiner é separado da RAM da VPS, e o alarme não é um teto rígido. Ajuste disk_free_limit ao disco e ao acúmulo; 2GB livres são apenas um ponto inicial.
Crie /opt/rabbitmq/enabled_plugins para administração e Prometheus:
[rabbitmq_management,rabbitmq_prometheus].
Crie /opt/rabbitmq/compose.yml:
services:
rabbitmq:
image: rabbitmq:4.3.5-management
container_name: rabbitmq
hostname: rabbitmq-1
restart: unless-stopped
environment:
RABBITMQ_DEFAULT_USER: ${RABBITMQ_ADMIN_USER}
RABBITMQ_DEFAULT_PASS: ${RABBITMQ_ADMIN_PASS}
RABBITMQ_DEFAULT_VHOST: ${RABBITMQ_DEFAULT_VHOST}
ports:
- "${RABBITMQ_BIND_IP:-127.0.0.1}:5671:5671"
- "127.0.0.1:15672:15672"
- "127.0.0.1:15692:15692"
volumes:
- ./data:/var/lib/rabbitmq
- ./rabbitmq.conf:/etc/rabbitmq/rabbitmq.conf:ro
- ./enabled_plugins:/etc/rabbitmq/enabled_plugins:ro
- ./tls:/etc/rabbitmq/tls:ro
healthcheck:
test: ["CMD", "rabbitmq-diagnostics", "-q", "ping"]
interval: 30s
timeout: 10s
retries: 5
start_period: 40s
mem_limit: 2g
cpus: 2.0
ulimits:
nofile:
soft: 65536
hard: 65536
logging:
driver: json-file
options:
max-size: "10m"
max-file: "5"
Preserve hostname: rabbitmq-1: a identidade importa na restauração, sobretudo com quorum queues e streams. Evite tags latest.
Para uma instalação nova da versão 4.4.0 consultada, adicione este compose.override.yml depois de ler suas notas. Não aplique sem conferir uma atualização de 4.3:
services:
rabbitmq:
image: rabbitmq:4.4.0-management
Antes de iniciar, permita que o usuário RabbitMQ da imagem selecionada leia os arquivos montados. A chave privada e a configuração criadas pertencem ao usuário do host e podem ficar ilegíveis quando a imagem reduz privilégios:
cd /opt/rabbitmq
RABBITMQ_SELECTED_IMAGE="$(docker compose config --images)"
RABBITMQ_CONTAINER_UID="$(docker run --rm --entrypoint id "$RABBITMQ_SELECTED_IMAGE" -u rabbitmq)"
RABBITMQ_CONTAINER_GID="$(docker run --rm --entrypoint id "$RABBITMQ_SELECTED_IMAGE" -g rabbitmq)"
sudo chown -R "$RABBITMQ_CONTAINER_UID:$RABBITMQ_CONTAINER_GID" data tls
sudo chmod 750 data tls
sudo chmod 600 tls/server.key
sudo chown "root:$RABBITMQ_CONTAINER_GID" rabbitmq.conf enabled_plugins
sudo chmod 640 rabbitmq.conf enabled_plugins
unset RABBITMQ_SELECTED_IMAGE RABBITMQ_CONTAINER_UID RABBITMQ_CONTAINER_GID
A seleção da imagem pressupõe que o projeto contém somente o broker. Mantenha a chave privada da CA fora das montagens. Valide sem imprimir segredos:
cd /opt/rabbitmq
docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
cd /opt/rabbitmq
docker compose exec rabbitmq rabbitmq-diagnostics -q ping
docker compose exec rabbitmq rabbitmq-diagnostics -q listeners
docker compose exec rabbitmq rabbitmq-diagnostics -q check_local_alarms
docker compose logs --tail=200 rabbitmq
Confira a cadeia do certificado:
openssl s_client \
-connect 127.0.0.1:5671 \
-servername mq.example.com \
-CAfile /opt/rabbitmq/tls/ca.crt \
-verify_return_error </dev/null
Espere Verify return code: 0 (ok). Porém, -servername define SNI sem validar o hostname. Execute também:
openssl s_client -connect 127.0.0.1:5671 -servername mq.example.com \
-verify_hostname mq.example.com -verify_return_error \
-CAfile /opt/rabbitmq/tls/ca.crt </dev/null
Use o hostname real e confira métricas:
curl -fsS http://127.0.0.1:15692/metrics | head
Monitore disponibilidade, conexões, mensagens sem confirmação/prontas, publicação/consumo e alarmes de memória/disco. Veja Prometheus e Grafana.
Use um domínio separado, como mq-admin.example.com, e edite /etc/caddy/Caddyfile:
mq-admin.example.com {
encode zstd gzip
reverse_proxy 127.0.0.1:15672
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains"
X-Content-Type-Options "nosniff"
Referrer-Policy "strict-origin-when-cross-origin"
}
}
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -fsSI https://mq-admin.example.com/
Caddy fornece HTTPS para administração; não encaminha AMQP. Restrinja acesso por VPN, acesso de confiança zero ou IP autorizado, use senhas fortes e aplique patches. Ative HSTS para subdomínios só quando todos suportarem HTTPS. Veja o guia do Caddy.
Não use administrador nos aplicativos. Crie usuários e vhosts separados por serviço ou ambiente. Este usuário acessa production e recursos com prefixo app.:
cd /opt/rabbitmq
APP_USER=worker
APP_PASS="$(openssl rand -hex 32)"
docker compose exec rabbitmq rabbitmqctl add_user "$APP_USER" "$APP_PASS"
docker compose exec rabbitmq rabbitmqctl set_permissions \
-p production "$APP_USER" '^app\.' '^app\.' '^app\.'
install -m 0600 /dev/null app-client.env
printf 'RABBITMQ_USER=%s\nRABBITMQ_PASSWORD=%s\n' \
"$APP_USER" "$APP_PASS" > app-client.env
unset APP_USER APP_PASS
As expressões correspondem a configure, write e read. Os recursos precisam começar com app.. Ajuste ao que o cliente declara, sem conceder .*. O exchange padrão de nome vazio não corresponde ao prefixo; inclua essa possibilidade expressamente só se necessária. Restrições de routing keys exigem permissões de topic separadas.
O usuário do aplicativo não precisa das tags administrator, monitoring ou management. Use amqps://, CA confiável e segredos em configuração restrita. Codifique caracteres reservados da URI; senhas hexadecimais simplificam esse cuidado.
- Marque mensagens como persistent.
- Ative publisher confirms e trate confirmações negativas e timeouts.
- Envie ack após processar; escolha requeue ou dead-letter em falhas.
- Configure prefetch para limitar entregas pendentes por consumidor.
- Defina tentativas, TTL e política dead-letter.
- Use chaves de idempotência para evitar cobranças ou entregas duplicadas.
Persistência e confirmações não eliminam duplicatas. Projete entrega pelo menos uma vez com consumidores idempotentes e teste reconexão e recuperação de acúmulo sob falhas reais.
Definitions preserva usuários, vhosts, permissões, políticas e topologia, sem mensagens pendentes. Exporte no nó ativo:
cd /opt/rabbitmq
BACKUP_DIR="backups/$(date -u +%Y%m%dT%H%M%SZ)"
install -d -m 0700 "$BACKUP_DIR"
docker compose exec rabbitmq rabbitmqctl export_definitions \
/var/lib/rabbitmq/definitions-backup.json
docker compose cp \
rabbitmq:/var/lib/rabbitmq/definitions-backup.json \
"$BACKUP_DIR/definitions.json"
docker compose exec rabbitmq rm -f \
/var/lib/rabbitmq/definitions-backup.json
test -s "$BACKUP_DIR/definitions.json"
chmod 600 "$BACKUP_DIR/definitions.json"
O arquivo contém hashes de senha e é sensível. Em um substituto preparado, copie o arquivo salvo para o diretório de trabalho:
docker compose cp definitions.json \
rabbitmq:/var/lib/rabbitmq/definitions-restore.json
docker compose exec rabbitmq rabbitmqctl import_definitions \
/var/lib/rabbitmq/definitions-restore.json
Importar definitions não recupera mensagens e pode mesclar topologia existente. Use um destino isolado e remova depois o arquivo temporário.
Para mensagens, interrompa produtores e consumidores e pare o nó antes de copiar todo o diretório:
cd /opt/rabbitmq
FULL_BACKUP="backups/rabbitmq-full-$(date -u +%Y%m%dT%H%M%SZ).tar.gz"
docker compose stop rabbitmq
sudo tar -czf "$FULL_BACKUP" \
data .env compose.yml rabbitmq.conf enabled_plugins tls pki
sudo chown "$USER":"$USER" "$FULL_BACKUP"
chmod 600 "$FULL_BACKUP"
docker compose start rabbitmq
test -s "$FULL_BACKUP"
docker compose exec rabbitmq rabbitmq-diagnostics -q ping
Confira o resultado do arquivamento. Criptografe o backup, principalmente porque inclui credenciais e material de CA; controle separadamente a cópia da chave privada. Copie os arquivos para fora do host.
Restaure uma instância parada, isolada e compatível com o mesmo rabbit@rabbitmq-1, dados completos incluindo cookie Erlang e permissões corretas. Restaure configuração/certificados, inicie, confira topologia/acúmulo e conecte clientes de teste. Não inicialize, sobrescreva nem renomeie dados de produção ativos como ensaio.
Confira notas, transições suportadas, feature flags e compatibilidade Erlang. Faça definitions e backup completo com o nó parado. A imagem inclui o runtime, mas ainda exige compatibilidade de migração.
cd /opt/rabbitmq
docker compose exec rabbitmq rabbitmqctl await_startup
docker compose exec rabbitmq rabbitmqctl export_definitions \
/var/lib/rabbitmq/pre-upgrade-definitions.json
# 修改 compose.yml 中固定的镜像补丁版本后再执行
docker compose config --quiet
docker compose pull
docker compose up -d
docker compose exec rabbitmq rabbitmqctl await_startup
docker compose exec rabbitmq rabbitmq-diagnostics -q ping
docker compose exec rabbitmq rabbitmq-diagnostics -q check_local_alarms
docker compose logs --tail=200 rabbitmq
O exemplo deixa outra cópia de definitions dentro dos dados; tire-a do contêiner se quiser preservar. Altere a imagem fixada ou o override antes de baixar. Um nó requer parada.
Em clusters independentes, siga a ordem gradual oficial e verifique réplicas. Valide confirms, ack, redução de acúmulo, API e métricas, além da inicialização. Depois de mudanças irreversíveis, recupere uma cópia anterior compatível em vez de apenas voltar à imagem antiga.
ss -lnt | grep ':5671'
docker compose ps
docker compose exec rabbitmq rabbitmq-diagnostics -q listeners
openssl s_client -connect 127.0.0.1:5671 \
-servername mq.example.com \
-CAfile tls/ca.crt </dev/null
Se funciona localmente, confira RABBITMQ_BIND_IP, rotas privadas, regras do provedor e publicação Docker pelo guia de portas e firewall. Não volte ao 5672 público sem criptografia.
O DNS do cliente precisa corresponder ao SAN e à CA confiável. Corrija DNS privado, SAN, relógio e caminhos da CA; não desative validação.
docker compose exec rabbitmq rabbitmqctl list_users
docker compose exec rabbitmq rabbitmqctl list_vhosts
docker compose exec rabbitmq rabbitmqctl list_permissions -p production
Confira credenciais e as três categorias de permissão. Codifique o vhost: / normalmente aparece como %2F; aqui production usa /production.
docker compose exec rabbitmq rabbitmq-diagnostics -q check_local_alarms
docker stats rabbitmq --no-stream
df -h /opt/rabbitmq/data
du -sh /opt/rabbitmq/data
Os alarmes bloqueiam publicação para proteger o nó. Reduza acúmulo, recupere consumidores, amplie disco e investigue mensagens grandes antes de elevar limites.
Desenvolvimento pode começar com 2 vCPU/2GB; produção pequena costuma exigir 2–4 vCPU, 4GB e NVMe de 60GB. Meça conexões, mensagens, filas, acúmulo e confirms.
Evite: desative AMQP sem criptografia e mantenha administração no loopback atrás de HTTPS. Clientes remotos devem usar rede privada/VPN, TLS 5671 e restrição de origem.
Preserva a definição da fila. Também são necessários mensagens persistentes, confirms e ack corretos; falhas podem deixar entrega incerta ou duplicada.
Sim, sem tolerar falha do host. Tolerar um membro indisponível exige pelo menos três membros independentes e maioria disponível.
Não: preserva contas e topologia. Mensagens exigem backup consistente do nó parado.
Só inicializa armazenamento vazio. Use rabbitmqctl change_password ou API, atualize segredos e verifique reconexão.