Uma migração do HiveMQ Cloud Serverless é, em grande parte, um projeto de reconfiguração: o protocolo MQTT continua o mesmo, mas cada cliente precisa de um novo hostname, de novas credenciais e possivelmente de um novo client ID, e todo estado que vivia no cluster antigo precisa ser reconstruído. Este guia percorre o procedimento completo em seis passos, usando um broker privado da ConnectMQ como destino. Os mesmos passos valem para qualquer broker MQTT baseado no padrão.
Se você ainda não leu o contexto, comece pelo fim do HiveMQ Cloud Serverless para conhecer as datas e o que o HiveMQ exclui depois de 31 de dezembro de 2026.
Passo 1: Faça o inventário de tudo o que se conecta
Não dá para migrar o que você não listou. Abra o console do HiveMQ Cloud, anote o hostname do cluster e todas as credenciais de acesso e monte uma tabela com uma linha por tipo de cliente:
| Campo | Exemplo | Por que importa |
|---|---|---|
| Tipo de cliente | Sensor de temperatura ESP32 | Define como você vai reconfigurá-lo |
| Quantidade | 140 | Determina o dimensionamento do plano |
| Padrão de client ID | sensor-<mac> |
Precisa se adequar às regras de client ID do novo broker |
| Credencial usada | devices-rw |
Vira uma nova credencial no novo broker |
| Publica em | site1/+/temp |
Estrutura de topics a verificar após a migração |
| Assina | site1/+/cmd |
Estrutura de topics a verificar após a migração |
| QoS, retained, clean start | QoS 1, status retido | Recursos a confirmar no plano de destino |
| Transporte | MQTT sobre TLS, porta 8883 | Porta e configurações de TLS a alterar |
| Forma de atualização | OTA, arquivo de configuração, manual | Esforço e prazo necessários |
Não se esqueça dos clientes silenciosos: um fluxo do Node-RED em um Raspberry Pi esquecido, uma entrada do Grafana ou do Telegraf, um app móvel com hostname fixo no código ou um parceiro que assina um único topic. O checklist de migração do HiveMQ traz uma versão imprimível deste inventário.
Passo 2: Mapeie os recursos para o novo broker
Compare o seu inventário com o plano de destino antes de mudar qualquer coisa:
| O que você usa no HiveMQ Serverless | O que verificar no destino | ConnectMQ |
|---|---|---|
| MQTT 3.1.1 / 5.0 | As mesmas versões | Ambas suportadas |
| TLS na 8883, WebSocket seguro | Portas e caminho | 1883, 8883 (TLS), 8083 (WS), 8084 (WSS, caminho /mqtt) |
| Credenciais criadas no console | Como as credenciais são emitidas | Usuário, senha e client ID gerados no portal |
| Qualquer client ID | Regras de client ID | Client ID vinculado às credenciais; variantes com _suffix permitidas |
| Permissões de topic por credencial | Modelo de controle de acesso | ACLs por topic não são oferecidas; use brokers ou credenciais separados por fronteira de confiança |
| QoS 2 | Suporte no plano | Serverless (Paid) e superiores |
| Retained messages | Suporte e durabilidade | Suportadas; os clientes devem republicar o estado ao conectar |
| Número de clientes simultâneos | Limites do plano | 25 no Serverless Free, até 1.000 no Serverless Paid, Dedicated acima disso |
Duas linhas exigem uma decisão.
Client IDs. O HiveMQ Cloud deixa cada cliente escolher o próprio client ID. A ConnectMQ vincula o client ID às credenciais emitidas: um cliente pode usar exatamente o client ID emitido ou uma variante com sufixo, como YOUR_CLIENT_ID_sensor140. Planeje dar a cada dispositivo um sufixo derivado do número de série ou do endereço MAC. Veja boas práticas de client ID MQTT para conhecer padrões.
Permissões. Se você usava permissões de topic do HiveMQ para separar partes que não confiam entre si (por exemplo, clientes que não podem ver os dados uns dos outros), não tente reproduzir isso em um único broker. Use um broker por cliente ou fronteira de confiança, ou coloque um backend no meio.
Passo 3: Crie o broker de destino
- Cadastre-se em app.connectmq.com. O plano Serverless gratuito não exige cartão de crédito, o que é ideal para testes.
- Escolha um plano dimensionado pelo seu pico de conexões, com folga. Use o Serverless (Paid) para frotas em produção de até 1.000 conexões ou o Dedicated para cargas maiores ou sensíveis à latência. Os nossos guias de alternativa serverless e de alternativa gerenciada na nuvem ajudam na escolha.
- Crie o broker e copie o usuário, a senha e o client ID gerados.
- Desta vez, torne o endereço do broker configurável. Guarde hostname, porta, credenciais e client ID em um arquivo de configuração, em um serviço de provisionamento ou em configurações atualizáveis via OTA, e não no firmware compilado. Um simples alias de DNS no seu próprio domínio não basta para o TLS, porque o certificado do broker é emitido para o hostname do provedor, e os clientes que verificam o hostname o rejeitariam.
Passo 4: Teste com um cliente real
Antes de mover clientes de produção, comprove o básico com as mesmas bibliotecas que os seus dispositivos usam. Com os clientes mosquitto sobre TLS:
# Terminal 1: assinar
mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
-u YOUR_USERNAME -P YOUR_PASSWORD -i YOUR_CLIENT_ID_test1 \
-t 'site1/#' -v
# Terminal 2: publicar
mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
-u YOUR_USERNAME -P YOUR_PASSWORD -i YOUR_CLIENT_ID_test2 \
-t 'site1/room1/temp' -m '{"temp":21.7}' -q 1
Depois, teste os detalhes que importam para a sua frota: níveis de QoS, retained messages, mensagens Last Will, sessões persistentes se você as usa, tamanhos de mensagem próximos ao seu maior payload e a latência a partir da rede que os seus dispositivos realmente usam. O explorador de topics ao vivo do portal da ConnectMQ mostra cada mensagem assim que ela chega, o que é a forma mais rápida de confirmar as estruturas de topics. Exemplos de código para ESP32, Python, Node.js e Node-RED estão em Reconfigurar clientes MQTT depois do HiveMQ.
Passo 5: Rode em paralelo e migre em ondas
A migração mais segura mantém os dois brokers no ar e retransmite o tráfego entre eles, para que um dispositivo no broker antigo e uma aplicação no broker novo continuem vendo as mensagens um do outro. Um pequeno processo de relay assina em um broker e republica no outro. Mostramos um script de relay completo e a ordem das ondas em Migração do HiveMQ sem interrupção.
A ordem recomendada é:
- Consumidores primeiro. Mova bancos de dados, motores de regras, fluxos do Node-RED e dashboards para o novo broker. Graças ao relay, eles continuam recebendo dados dos dispositivos que ainda estão no cluster antigo.
- Um grupo piloto de dispositivos. Alguns de sites e versões de firmware diferentes. Acompanhe-os por alguns dias.
- O restante da frota em lotes, com um ponto de verificação depois de cada lote.
- Produtores de comandos por último, quando os dispositivos que eles controlam já tiverem migrado.
Durante cada onda, acompanhe o número de conexões em relação ao seu plano. Se você exceder a cota, os clientes MQTT 5 recebem o reason code 0x97 (quota exceeded). Faça o upgrade antes de uma onda, e não durante.
Passo 6: Faça a virada e limpe o ambiente
Quando o cluster do HiveMQ não mostrar mais nenhuma conexão de cliente além do relay:
- Pare o relay.
- Confirme que todos os topics esperados estão ativos no novo broker e que o estado retido foi republicado.
- Exporte o que quiser guardar do cluster antigo, como uma lista de credenciais para os seus registros.
- Exclua o cluster Serverless, lembrando que o HiveMQ não consegue recriá-lo.
- Remova o hostname antigo dos padrões de firmware, da documentação, dos runbooks e dos cofres de segredos.
Procure terminar bem antes de 31 de dezembro de 2026. Uma folga de várias semanas deixa espaço para dispositivos que ficam online raramente, como equipamentos sazonais ou sensores que acordam uma vez por dia.
Armadilhas comuns
- Colisões de client ID. Dois dispositivos com o mesmo client ID vão desconectar um ao outro repetidamente em qualquer broker. Derive os sufixos de identificadores de hardware únicos.
- Certificados de CA fixos no código. Dispositivos que fixam um bundle de CA específico podem rejeitar o certificado de um novo broker. A ConnectMQ usa um certificado Let's Encrypt; garanta que a raiz ISRG Root X1 esteja no trust store do dispositivo. Veja configuração de TLS no MQTT.
- Supor que o estado retido é migrado. Não é. Faça os dispositivos publicarem o estado atual com a flag retain logo após a conexão.
- Esquecer a lógica de reconexão. Um dispositivo sem backoff adequado pode inundar um novo broker durante uma onda. Revise antes o keep alive do MQTT e as configurações de reconexão do seu cliente.
Perguntas frequentes
Quanto tempo leva uma migração do HiveMQ Serverless?
Para algumas poucas aplicações, um dia. Para frotas de dispositivos em campo que precisam de atualização de firmware, planeje semanas: desenvolver e testar o novo firmware, fazer o rollout em etapas e esperar pelos dispositivos que se conectam raramente. Comece agora para que o prazo final não seja o seu dia de teste.
Posso migrar sem atualizar o firmware dos dispositivos?
Somente se o hostname, as credenciais e o client ID puderem ser configurados sem mudar o firmware, por exemplo por meio de um arquivo de configuração ou de um serviço de provisionamento. Se estiverem compilados no código, você precisa de uma atualização over-the-air.
Preciso mudar a minha estrutura de topics?
Não. Topics são apenas strings, e a ConnectMQ suporta os wildcards padrão e as profundidades de topic típicas de projetos IoT. Mantenha a sua estrutura atual para que dashboards e regras continuem funcionando.
Com qual plano da ConnectMQ devo começar?
Comece com o plano Serverless gratuito para testar. Em produção, escolha o Serverless (Paid) para até 1.000 conexões ou o broker MQTT gerenciado na nuvem da ConnectMQ (Dedicated) quando precisar de um cluster isolado.
