Migração do HiveMQ sem Interrupção: Rode Dois Brokers MQTT em Paralelo e Migre os Clientes em Ondas

A forma mais segura de sair do HiveMQ Cloud Serverless sem interromper o serviço é rodar os dois brokers em paralelo por um tempo e retransmitir as mensagens entre eles. Assim, dispositivos e aplicações podem migrar um grupo de cada vez, e um dispositivo que ainda está no HiveMQ continua conversando com uma aplicação que já migrou. Este artigo mostra como construir esse relay, como evitar loops de mensagens e como migrar os clientes em ondas antes do prazo de 31 de dezembro de 2026.

Por que um relay é necessário

Nem o HiveMQ Cloud Serverless nem um broker gerenciado na nuvem como a ConnectMQ fazem bridge com outro broker por você no lado da nuvem. A solução é um pequeno processo de relay que você mesmo executa: ele se conecta aos dois brokers como um cliente MQTT comum, assina topics selecionados de um lado e os republica do outro. Como é apenas um cliente, funciona com qualquer broker baseado no padrão e não precisa de permissões especiais.

 devices (still on HiveMQ) --> HiveMQ Serverless --relay--> ConnectMQ --> moved consumers
 moved command senders     --> ConnectMQ        --relay--> HiveMQ Serverless --> devices

Se você já roda Mosquitto no local, o recurso de bridge dele pode fazer o mesmo trabalho; veja migrar do Mosquitto para um broker MQTT na nuvem e configuração de bridge no Mosquitto.

O problema dos loops e como evitá-lo

Se o relay encaminhar o topic site1/# do HiveMQ para a ConnectMQ e também da ConnectMQ para o HiveMQ, cada mensagem vai ficar indo e voltando para sempre. Evite loops já no projeto:

• Encaminhe em uma só direção por topic. A telemetria flui em um sentido (do antigo para o novo) e os comandos no outro (do novo para o antigo). Não encaminhe o mesmo filtro de topic nas duas direções.
• Use o No Local do MQTT 5 nas assinaturas, para que o relay não receba as próprias publicações no mesmo broker.
• Marque as mensagens retransmitidas com uma user property do MQTT 5, como relayed=1, e descarte as mensagens que já a tiverem.

O script abaixo aplica as três medidas.

Um relay completo em Python

Este relay usa paho-mqtt 2.x e MQTT 5 nos dois lados. Telemetria e status vão do HiveMQ para a ConnectMQ; comandos vão da ConnectMQ para o HiveMQ.

# pip install "paho-mqtt>=2.0"
import os, ssl
import paho.mqtt.client as mqtt
from paho.mqtt.packettypes import PacketTypes
from paho.mqtt.properties import Properties
from paho.mqtt.subscribeoptions import SubscribeOptions

# Filtros de topic por direção (nunca liste o mesmo filtro nas duas)
OLD_TO_NEW = ["site1/+/telemetry", "site1/+/status"]
NEW_TO_OLD = ["site1/+/cmd"]

def make_client(client_id, user, password):
    c = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id=client_id, protocol=mqtt.MQTTv5)
    c.username_pw_set(user, password)
    c.tls_set(cert_reqs=ssl.CERT_REQUIRED)
    c.reconnect_delay_set(min_delay=1, max_delay=60)
    return c

old = make_client("relay-old-1", os.environ["HIVEMQ_USER"], os.environ["HIVEMQ_PASSWORD"])
new = make_client(os.environ["CMQ_CLIENT_ID"] + "_relay", os.environ["CMQ_USER"], os.environ["CMQ_PASSWORD"])

def is_relayed(msg):
    props = getattr(msg, "properties", None)
    return any(k == "relayed" for k, _ in (getattr(props, "UserProperty", None) or []))

def forward(target):
    def on_message(client, userdata, msg):
        if is_relayed(msg):
            return
        props = Properties(PacketTypes.PUBLISH)
        props.UserProperty = [("relayed", "1")]
        target.publish(msg.topic, msg.payload, qos=min(msg.qos, 1), retain=msg.retain, properties=props)
    return on_message

def subscriber(filters):
    def on_connect(client, userdata, flags, reason_code, properties):
        print("connected:", reason_code, "subscribing to", filters)
        opts = SubscribeOptions(qos=1, noLocal=True)
        for f in filters:
            client.subscribe(f, options=opts)
    return on_connect

old.on_connect, old.on_message = subscriber(OLD_TO_NEW), forward(new)
new.on_connect, new.on_message = subscriber(NEW_TO_OLD), forward(old)

old.connect(os.environ["HIVEMQ_HOST"], 8883)
new.connect("broker.connectmq.com", 8883)
new.loop_start()
old.loop_forever()

Execute-o em um host confiável próximo aos dois brokers, por exemplo uma pequena VM na nuvem ou um container, com as credenciais em variáveis de ambiente. O QoS é limitado a 1 para que o relay funcione no plano Serverless gratuito; aumente para 2 no Serverless (Paid) e superiores se os seus fluxos precisarem. As flags retain são preservadas, então as mensagens de status retidas publicadas no HiveMQ também aparecem como retidas na ConnectMQ.

Duas observações práticas:

• O relay conta como uma conexão em cada broker. Inclua-o ao dimensionar o novo plano.
• Monitore-o como produção. Se o relay parar, as mensagens entre clientes migrados e não migrados também param. Execute-o sob o systemd ou com uma política de reinício de container.

O plano de ondas

Migre os clientes em uma ordem que mantenha todos os fluxos de dados funcionando.

Depois de cada onda, verifique:

• O número de conexões no dashboard da ConnectMQ corresponde ao número de clientes migrados.
• Os topics esperados aparecem no explorador de topics ao vivo.
• O estado de conexão de cada cliente em $SYS/broker/connection/{clientId}/state mostra os dispositivos migrados online.
• Nenhum cliente migrado continua se conectando ao HiveMQ (confira no console do HiveMQ).
• O número de conexões fica dentro dos limites do plano; clientes MQTT 5 recebem 0x97 se uma cota for excedida.

Rollback

Enquanto o cluster antigo ainda funciona, cada onda pode ser revertida restaurando as configurações de conexão anteriores. Mantenha as configurações antigas disponíveis no seu sistema de provisionamento até a conclusão da última onda. Esse é o principal motivo para não deixar a migração para os últimos dias de dezembro: depois de 31 de dezembro de 2026, não há mais para onde voltar.

Checklist da virada

1. Todos os dispositivos e aplicações rodam no novo broker.
2. O console do HiveMQ não mostra nenhuma conexão de cliente além do relay.
3. O estado retido está presente no novo broker, republicado pelos dispositivos ou restaurado de uma exportação. Veja exclusão de dados do HiveMQ Serverless.
4. Pare o relay e observe por um dia se algum cliente reaparece no HiveMQ.
5. Exclua o cluster HiveMQ Serverless e remova o hostname antigo da configuração, dos padrões de firmware e da documentação.

Para o processo de ponta a ponta, veja o guia de migração do HiveMQ Serverless. Você pode construir e testar o relay hoje mesmo com um broker gratuito em app.connectmq.com.

Perguntas frequentes

O HiveMQ Cloud consegue fazer bridge direto com a ConnectMQ?

Não no lado da nuvem. Execute um cliente de relay como o script acima, ou um bridge do Mosquitto na sua própria infraestrutura, que se conecta aos dois brokers como um cliente MQTT normal.

Os dispositivos vão perceber a migração?

Os dispositivos que migram veem uma reconexão rápida quando suas configurações mudam. Os que ainda não migraram não percebem mudança alguma, porque o relay mantém os dados deles fluindo para as aplicações já migradas.

O relay adiciona latência?

Ele adiciona um salto extra, normalmente de alguns milissegundos a dezenas de milissegundos, dependendo de onde roda. Coloque-o perto dos dois brokers e remova-o quando a migração terminar.

O relay deve usar QoS 1 ou QoS 2?

QoS 1 é um bom padrão e funciona em todos os planos da ConnectMQ. Garanta que os consumidores tratem uma eventual duplicata, que o QoS 1 permite. Use QoS 2 apenas onde duplicatas forem inaceitáveis e o seu plano o suportar.