Como Migrar o Mosquitto para um Broker MQTT na Nuvem Sem Downtime

Quando você vai migrar o Mosquitto para MQTT na nuvem, a parte arriscada não é o novo broker, e sim o momento em que os dispositivos trocam de lado. Este tutorial traz um runbook sem downtime: inventarie o que roda hoje no seu Mosquitto, mapeie as credenciais para o broker na nuvem, rode os dois brokers lado a lado com uma bridge do Mosquitto, mova os clients em ondas e desative tudo com um plano de rollback pronto. Os exemplos usam a ConnectMQ como destino, mas o método funciona com qualquer broker compatível com o padrão.

Por Que as Equipes Migram do Mosquitto

O Mosquitto é um broker excelente e leve, e continua sendo a escolha certa para muitas implantações de borda e de laboratório. As equipes normalmente levam o broker central para um broker MQTT gerenciado na nuvem por razões operacionais, e não por deficiências técnicas: renovação de certificados, patches de sistema operacional, backups, monitoramento e plantão acabam caindo em alguém que tem outro trabalho. Dispositivos remotos também precisam de um endpoint acessível, o que significa regras de firewall e exposição pública de um servidor que você mesmo mantém. Se ainda está decidindo, compare antes os prós e contras em broker MQTT auto-hospedado vs gerenciado e alternativa ao Mosquitto na nuvem.

Passo 1: Inventarie Clients, Topics e Recursos

Não dá para migrar o que você não listou. Colete quatro coisas do broker atual.

Configuração. Leia o mosquitto.conf e os arquivos em conf.d. Anote listeners e portas, allow_anonymous, password_file, acl_file, configurações de persistência, max_inflight_messages, limites de tamanho de mensagem e bridges existentes.

Clients. O Mosquitto registra no log cada conexão com o seu client ID. Extraia os IDs únicos e os endereços de origem do log:

grep "New client connected" /var/log/mosquitto/mosquitto.log \
  | sed -E 's/.*from ([0-9a-fA-F.:]+):[0-9]+ as ([^ ]+).*/\2 \1/' \
  | sort -u > clients.txt
wc -l clients.txt

Topics. Assine tudo por um período representativo e registre os nomes de topics únicos, incluindo os retidos:

timeout 600 mosquitto_sub -h localhost -p 1883 -u admin -P 'ADMIN_PASSWORD' \
  -i inventory-$RANDOM -t '#' -F '%t %r' | sort -u > topics.txt

O campo %r imprime 1 para retained messages, que você vai precisar recriar no novo broker.

Uso de recursos. Verifique se os clients usam MQTT 5, QoS 2, sessões persistentes, payloads grandes, assinaturas com curinga ou ACLs por topic. Cada um vira um requisito para o destino.

Passo 2: Mapeie Recursos e Credenciais

Compare seu inventário com o broker de destino antes de mexer em qualquer dispositivo:

Duas linhas merecem atenção. Primeiro, client IDs: no Mosquitto, qualquer client normalmente pode escolher qualquer ID, enquanto a ConnectMQ vincula cada client ID às credenciais emitidas. Planeje um conjunto de credenciais por dispositivo ou serviço e atualize firmware ou configuração para que cada dispositivo use o client ID emitido. Segundo, ACLs: se a sua configuração do Mosquitto depende de ACLs de topic granulares para separar partes não confiáveis, redesenhe essa fronteira com brokers separados ou um backend que intermedeie o acesso antes de migrar.

Depois, crie o destino: cadastre-se em app.connectmq.com, escolha um plano dimensionado para o seu pico de conexões, crie um broker e emita credenciais para a bridge e para a primeira onda de clients.

Passo 3: Rode em Paralelo com uma Bridge do Mosquitto

A bridge é o que torna possível uma migração sem downtime. O Mosquitto se conecta ao broker na nuvem como um client MQTT comum e encaminha topics selecionados em cada direção, para que dispositivos em qualquer um dos brokers vejam os mesmos dados durante a transição. Adicione um arquivo como /etc/mosquitto/conf.d/bridge-connectmq.conf:

connection connectmq
address broker.connectmq.com:8883
bridge_protocol_version mqttv311
remote_clientid YOUR_CLIENT_ID
remote_username YOUR_USERNAME
remote_password YOUR_PASSWORD
bridge_capath /etc/ssl/certs
bridge_insecure false
try_private false
notifications false
cleansession true
restart_timeout 5 60

# Telemetria produzida por dispositivos locais sobe para a nuvem
topic factory1/+/+/telemetry out 1
topic factory1/+/+/status out 1
# Comandos emitidos por aplicações na nuvem descem para os dispositivos locais
topic factory1/+/+/cmd in 1

Reinicie o Mosquitto com sudo systemctl restart mosquitto e verifique no log se a bridge conectou com sucesso. Algumas configurações importam:

• try_private false: a flag de bridge privada é uma extensão específica do Mosquitto; desative-a quando o lado remoto for outro broker.
• notifications false: impede que o Mosquitto publique topics de estado da bridge no remoto, que você não precisa lá.
• Topics direcionais: use out e in em vez de both sempre que possível. Fazer bridge bidirecional dos mesmos topics entre dois brokers pode criar loops de mensagens.
• restart_timeout: aplica backoff às tentativas de reconexão se o lado da nuvem ficar brevemente inacessível.

Verifique a bridge assinando no lado da nuvem com as suas próprias credenciais, ou observando o explorador de topics ao vivo no portal enquanto um dispositivo local publica.

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u YOUR_USERNAME -P YOUR_PASSWORD -i YOUR_CLIENT_ID \
  -t 'factory1/#' -v

Use aqui um conjunto de credenciais diferente do da bridge, porque cada client ID só pode manter uma conexão.

Passo 4: Mova os Clients em Ondas

Com a bridge rodando, cada client pode migrar de forma independente. Mova primeiro os consumidores, depois os produtores:

1. Consumidores de backend (bancos de dados, Node-RED, dashboards): aponte-os para o broker na nuvem. Graças à bridge, eles continuam recebendo a telemetria local.
2. Um grupo piloto de dispositivos: alguns dispositivos de sites e versões de firmware diferentes, por exemplo de uma planta em Joinville e outra em Manaus. Mude o host, a porta para 8883, o TLS e as credenciais, e acompanhe-os por alguns dias.
3. Dispositivos restantes em lotes: por site ou por linha de produto, com um checkpoint após cada lote.
4. Produtores de comandos: quando os dispositivos estiverem no broker na nuvem, mova as aplicações que enviam comandos.

Para cada lote, confirme o estado de conexão em $SYS/broker/connection/{clientId}/state, verifique se os topics esperados aparecem no explorador e recrie as retained messages que o seu inventário apontou. Como a ConnectMQ não garante o estado retido entre restarts, faça os dispositivos republicarem o status e a configuração retidos sempre que se conectarem, o que é uma boa prática em qualquer broker.

Fique de olho nos limites do seu plano durante as ondas. Se uma onda levar as conexões além da cota, clients MQTT 5 recebem o reason code 0x97; clients 3.1.1 são recusados. Faça o upgrade do plano antes da onda, e não durante.

Passo 5: Faça a Virada e Depois Desative

Quando o broker local não tiver mais clients diretos além da bridge, a migração está funcionalmente concluída. Mantenha a bridge e o broker antigo rodando por um período de observação combinado, como caminho de rollback. Fazer rollback de um dispositivo é simplesmente uma mudança de configuração de volta ao host antigo, e a bridge mantém os dois lados sincronizados nesse meio-tempo.

Depois, desative em ordem: remova a configuração da bridge, pare o Mosquitto, feche as portas do firewall, revogue as credenciais antigas e arquive os arquivos de configuração. Se alguns sites precisam de MQTT local para lógica de borda que deve funcionar offline, mantenha lá uma instância do Mosquitto de forma permanente e faça a bridge para cima; esse design híbrido é comum e perfeitamente válido.

Checklist de Migração

1. Configuração, lista de clients e lista de topics exportadas do Mosquitto.
2. Lacunas de recursos (ACLs, QoS 2, tamanho de mensagem, persistência) resolvidas.
3. Broker de destino criado em um plano com conexões suficientes.
4. Um conjunto de credenciais emitido por dispositivo ou serviço.
5. Bridge rodando com topics direcionais; dados verificados dos dois lados.
6. Consumidores migrados e verificados.
7. Dispositivos migrados em ondas com checkpoints.
8. Estado retido republicado na conexão.
9. Caminho de rollback mantido durante o período de observação.
10. Broker antigo desativado e credenciais revogadas.

O guia MQTT do protótipo à produção cobre etapas de hardening que você pode querer incluir no mesmo projeto.

Migre para a ConnectMQ

Crie um broker gratuito em app.connectmq.com no plano Serverless, sem cartão de crédito, e monte a bridge contra ele para testar o runbook completo antes de se comprometer. A ConnectMQ oferece um broker MQTT gerenciado com TLS, WebSockets, credenciais emitidas e um portal com explorador de topics ao vivo. Para contexto sobre modelos de implantação, leia o guia de broker MQTT na nuvem e use o servidor MQTT público para experimentos rápidos e não sensíveis, nunca para dados de produção.

Perguntas frequentes

Posso migrar o Mosquitto para MQTT na nuvem sem mudar o firmware dos dispositivos?

Só se host, porta, configurações de TLS, credenciais e client ID puderem ser configurados sem atualização de firmware. Dispositivos com endereço de broker fixo no código podem ficar em um Mosquitto local que faz bridge com a nuvem.

A bridge deve usar QoS 1 ou QoS 0?

QoS 1 é a escolha usual para fazer bridge de telemetria e comandos, porque protege as mensagens no link da bridge. Use QoS 0 apenas para dados de alta taxa em que perdas ocasionais são aceitáveis.

As retained messages migram automaticamente?

As retained messages que já estão no Mosquitto não são copiadas em bloco. A bridge encaminha as novas publicações; faça os dispositivos republicarem o status retido ao conectar e verifique os topics retidos no lado da nuvem.

Por quanto tempo devo manter o broker Mosquitto antigo?

Mantenha-o, com a bridge rodando, até que todos os clients estejam estáveis no novo broker por um período combinado. Isso dá um caminho de rollback instantâneo a um custo muito baixo.