Gateway em Nuvem (WireGuard + MikroTik)
Este documento descreve a arquitetura em que o serviço de gateway deixa de rodar em um hardware na unidade do cliente e passa a rodar no servidor SaaS, alcançando os leitores faciais da rede local por um túnel WireGuard cujo cliente é o MikroTik do cliente.
É um documento de arquitetura e de operação, destinado ao time interno. A versão voltada a integradores e ao comercial está em Gateway em Nuvem (portal público).
Arquitetura em adoção gradual. O Gateway físico continua sendo um produto ativo e suportado. A escolha entre os dois modelos é do cliente, e a migração está sendo feita caso a caso, priorizando as unidades com histórico de falha no hardware local.
1. O problema que essa arquitetura resolve
O Accelero é SaaS e fala MQTT com os equipamentos. O broker fica na nuvem e quem inicia a conexão é sempre o equipamento, de dentro para fora. Isso é o que permite operar sem IP público no cliente, sem redirecionamento de porta e sem expor nada da rede da unidade.
O problema é que leitores faciais não falam MQTT. Eles expõem uma API HTTP/HTTPS na rede local e nada mais. Para o Accelero alcançá-los, sempre foi necessário um componente na mesma rede que traduzisse MQTT (nuvem) para HTTP (local): o Gateway de Comunicação.
Do ponto de vista de segurança, o desenho sempre foi bom: o gateway autentica no broker com credenciais próprias, o broker é o único ponto exposto na internet, e os leitores permanecem acessíveis somente na rede local. Isso não mudou. O que mudou foi onde esse componente roda.
Esse componente foi entregue historicamente como hardware na unidade, uma Orange Pi (ou mini PC) com a distro Iongrade e os containers do gateway. Esse modelo carrega custos e riscos que não são do software:
| Problema | Efeito prático |
|---|---|
| Custo de aquisição | Uma Orange Pi ou mini PC por unidade, com preço em alta recente. |
| Custo de energia e espaço | Equipamento ligado 24×7 no rack do cliente. |
| Falha de hardware | Cartão SD ou eMMC corrompido, fonte queimada, capacitor com defeito, superaquecimento. |
| Falha física | Equipamento desligado da tomada, cabo de rede removido, mudança de rack. |
| Manutenção remota difícil | Acesso depende de SSH reverso e do serviço inotify estar no ar no host. |
| Deslocamento | Boa parte dos incidentes exige visita técnica presencial. |
O modo de falha mais frequente é a corrupção do sistema de arquivos, e as causas são conhecidas: cartão SD como mídia de boot, queda de energia, desligamento incorreto, cartão de baixa qualidade e desgaste por excesso de escrita. Cartão SD degrada com o uso, pode entrar em modo somente leitura e chega a produzir corrupção silenciosa, comportamento documentado pelo próprio projeto Armbian.
Há ainda a diferença de natureza dos equipamentos: uma Orange Pi roda uma distro Linux de propósito geral, com sistema de arquivos, pacotes, atualizações e Docker. Um MikroTik roda RouterOS, um sistema dedicado a rede, com menos variáveis e menos manutenção operacional. Para o papel de borda, o MikroTik é o equipamento mais previsível, além de ser mais barato que uma Orange Pi nos preços praticados atualmente.
A arquitetura em nuvem remove o computador da unidade, mantendo apenas um dispositivo de rede que na maioria dos projetos já existe: o MikroTik.
2. Visão geral da arquitetura
O serviço de gateway (o mesmo código, os mesmos containers) passa a rodar no servidor SaaS. A rede local do cliente é alcançada por um túnel WireGuard cifrado, estabelecido de dentro para fora pelo MikroTik.
Pontos que definem o desenho:
- O MikroTik não é o ponto de integração. Ele é o ponto de conectividade segura e roteamento. Toda a lógica de integração (normalização de mensagens,
PendencyHandlerpor dispositivo,StatsFetcher, keepalive) continua no serviço de gateway, agora na nuvem. Ver Arquitetura básica de serviços. - O túnel é iniciado pelo MikroTik. O cliente não precisa de IP público fixo nem de redirecionamento de porta. Funciona atrás de NAT e de CGNAT, desde que o MikroTik consiga sair por UDP até o endpoint WireGuard da nuvem.
- Os leitores permanecem em IP privado. Nenhuma porta de facial é publicada na internet. O acesso ocorre exclusivamente pelo túnel, com firewall restringindo endereços e serviços.
- Para o Accelero, nada muda. O gateway continua se identificando pelos mesmos tópicos MQTT
{FACILITY}/{MODELO}/{SERIAL}/#, continua enviando keepalive e continua aparecendo na tela de gateways. A aplicação não sabe (nem precisa saber) se o gateway roda em Orange Pi ou na VPS.
2.1 O que o MikroTik substitui, e o que não substitui
Esta distinção é a razão de o desenho final ser esse, e vale ser dita explicitamente em qualquer apresentação técnica.
O gateway sempre exerceu três papéis distintos:
- terminar a comunicação segura com a nuvem (transporte);
- traduzir MQTT para HTTP e orquestrar a entrega (integração);
- falar com os leitores por API REST na rede local (execução).
O MikroTik substitui apenas o papel 1. Ele é um excelente equipamento de borda e de transporte seguro, mas não é um middleware de integração: não tem fila de mensagens, não trata indisponibilidade de leitor, não faz retentativa, não transforma payload, não guarda buffer offline nem produz log de aplicação. RouterOS tem automação e fetch, mas isso não o transforma em substituto de um serviço de integração.
Por isso o gateway não foi eliminado, foi realocado. Os papéis 2 e 3 continuam existindo, com o mesmo código, agora rodando na VPS: Listener, PendencyHandler por dispositivo, GarbageCollector, StatsFetcher, keepalive. Ver Arquitetura básica de serviços.
A alternativa que foi descartada era "MikroTik com túnel e a nuvem chamando REST direto no leitor". Ela elimina o gateway de verdade, mas empurra fila, retentativa e tratamento de erro para dentro da aplicação, e acopla o Accelero à API de cada fabricante. O desenho adotado mantém o desacoplamento e troca só o lugar onde o componente roda.
3. Sentido da comunicação (leia esta seção antes de projetar o firewall)
Esta é a parte que mais gera erro de projeto. O tráfego não é unidirecional, e o sentido depende do modo de operação do equipamento.
3.1 Gerenciamento de cadastro (nuvem para facial)
O serviço de gateway inicia requisições HTTP/HTTPS contra o IP do leitor, pelo túnel, para enviar pessoas, fotos, templates faciais, cartões e comandos.
Gateway (nuvem) ---> HTTP ---> Leitor facial (LAN do cliente)
Aqui basta que a nuvem alcance a LAN.
3.2 Validação online / Modo Direct (facial para nuvem)
No Modo Direct, a cada leitura o próprio equipamento consulta o servidor para saber se libera a passagem. Quem inicia a requisição é o leitor facial, e o destino é o serviço de gateway.
Leitor facial (LAN do cliente) ---> HTTP ---> Gateway (nuvem)
Em Modo Direct, o leitor precisa alcançar o gateway pelo túnel. Isso exige três coisas que costumam ser esquecidas:
- O leitor deve ser configurado apontando para o endereço do gateway dentro da VPN, não para um IP público nem para o IP antigo da Orange Pi.
- A rede local precisa ter rota de volta para a faixa da VPN, com o MikroTik como próximo salto. Se o leitor usa o MikroTik como gateway padrão, isso já está resolvido; se ele aponta para outro roteador, é preciso rota estática.
- O firewall do túnel precisa permitir esse sentido, e não apenas nuvem para LAN.
Sem isso, o cadastro sincroniza normalmente e só a liberação de acesso falha, o que costuma ser diagnosticado errado como problema no leitor.
Também dependem do sentido leitor para nuvem os eventos assíncronos (notificações de acesso, callbacks de reconhecimento, imagens de LPR), conforme o fabricante.
4. WireGuard: por que esse protocolo, e onde ele roda
Por que WireGuard e não OpenVPN
A própria MikroTik descreve o WireGuard como mais simples, mais rápido e mais performático que o OpenVPN, e a implementação de OpenVPN no RouterOS tem particularidades e limitações documentadas pelo fabricante. Para um appliance pequeno mantendo um túnel permanente, o WireGuard leva vantagem em três pontos que importam aqui:
- configuração menor e menos sujeita a erro: um par de chaves, um endpoint e uma lista de
AllowedIPs, sem PKI, certificados e renovação; - reconexão praticamente instantânea, sem renegociação custosa, o que importa em link com oscilação;
- menor consumo de CPU no MikroTik, relevante nos modelos de entrada usados na borda.
OpenVPN só deve ser considerado se houver exigência específica de compatibilidade com um parque já existente.
Onde o WireGuard roda
Decisão adotada: WireGuard no host da VPS, com os containers de gateway usando a conectividade do host.
O WireGuard depende de suporte no kernel Linux. Um container não substitui o kernel do host: ele apenas empacota ferramentas e configuração. Rodar o WireGuard dentro de container é possível, mas exige NET_ADMIN (às vezes SYS_MODULE), sysctl net.ipv4.conf.all.src_valid_mark=1, eventualmente montar /lib/modules, e deixa roteamento e NAT bem mais sensíveis de depurar.
Como o túnel é infraestrutura compartilhada da VPS e não um detalhe de um cliente, o desenho no host é mais previsível:
- uma única tabela de rotas e um único ponto de firewall para auditar;
- containers de cliente sem privilégio de rede elevado;
- reinício de container do gateway não derruba o túnel;
- debug com as ferramentas normais do host (
wg show,ip route,tcpdump).
Registrar no chamado o motivo, e revisar: cap_add: NET_ADMIN, sysctl net.ipv4.conf.all.src_valid_mark=1, montagem de /lib/modules, e as regras de NAT/rota, que deixam de ser herdadas do host.
5. Isolamento multi-cliente
Cada cliente tem seu próprio container de gateway na VPS, e cada unidade tem seu próprio peer WireGuard. O isolamento se apoia em quatro camadas:
| Camada | Regra |
|---|---|
| Identidade | Par de chaves WireGuard exclusivo por unidade. Chave privada nunca é reaproveitada entre clientes. |
| Endereçamento | Faixa de IP de VPN exclusiva por unidade. |
| Roteamento | AllowedIPs do peer restrito às redes daquela unidade, e apenas a elas. |
| Firewall | Regras que permitem tráfego somente entre o container de gateway do cliente e os equipamentos autorizados daquela unidade. |
Com o WireGuard no host, existe uma única tabela de rotas para todos os peers. Redes de cliente usam quase sempre as mesmas faixas (192.168.0.0/24, 192.168.1.0/24, 192.168.88.0/24 no padrão MikroTik). Dois clientes com a mesma faixa geram rota ambígua, e o tráfego pode ser entregue à unidade errada.
Tratativas, em ordem de preferência:
- NAT 1:1 no MikroTik (
dst-nat/netmap), publicando a LAN real do cliente sob uma faixa única atribuída pela Iongrade dentro da VPN. O gateway na nuvem passa a enxergar sempre endereços únicos, independentemente do que o cliente usa internamente. É a única tratativa que escala sem depender do cliente. - Padronizar uma faixa exclusiva por unidade na rede de controle de acesso, quando for possível redesenhar a rede do cliente.
Sem uma das duas, a arquitetura funciona nos primeiros clientes e passa a falhar de forma intermitente conforme o parque cresce.
Manter um registro central (planilha ou CDB) com: facility, cliente, faixa de VPN atribuída, faixa real da LAN, mapeamento NAT quando houver, chave pública do peer, IPs dos equipamentos.
Definir e registrar aqui o plano de endereçamento oficial da VPN (bloco reservado, tamanho da sub-rede por unidade) e onde fica o registro central de peers.
6. Parâmetros que evitam a maior parte dos chamados
MTU
WireGuard adiciona cabeçalho ao pacote. Com MTU mal ajustado, conexões TCP abrem normalmente e travam ao transferir payload grande, que é exatamente o caso do envio de fotos e templates faciais. O sintoma clássico é "o gateway está online, o keepalive chega, mas o cadastro de foto nunca conclui".
Ajustar MTU na interface WireGuard dos dois lados (valor de partida usual: 1420) e reduzir se o link do cliente for PPPoE.
Persistent keepalive
O MikroTik deve usar persistent-keepalive (usual: 25s). Sem isso, o mapeamento NAT da operadora expira em links residenciais e com CGNAT, e o túnel só "volta" quando o cliente gera tráfego, o que atrasa comandos vindos da nuvem.
Latência e banda
O que antes era tráfego de LAN passa a atravessar a internet do cliente. Isso é aceitável na operação normal, mas pesa em carga inicial e recadastramento em massa: cada foto vai para cada leitor. Um cadastro de milhares de pessoas em vários leitores é um volume relevante de download no cliente e de upload na VPS.
Programar cargas grandes fora do horário de pico e validar a banda de subida do cliente antes de migrar unidades com parque grande.
7. Provisionamento de uma nova unidade
- Reservar a faixa de VPN da unidade no registro central e definir o mapeamento NAT, se houver colisão com a LAN real.
- Gerar o par de chaves WireGuard do peer e cadastrar o peer no servidor da VPS, com
AllowedIPsrestrito às redes da unidade. - Configurar o MikroTik: interface WireGuard, chave privada, chave pública do servidor, endpoint,
persistent-keepalive, MTU, e as regras de firewall e NAT. - Validar a conectividade antes de subir o gateway:
pingda VPS para o IP de VPN do MikroTik e para o IP de cada leitor, pelo túnel. - Subir o container do gateway do cliente, com facility, serial e
MQTT_HOSTcorretos. - Cadastrar o gateway no Accelero (ou confirmar o cadastro existente, em migração) e conferir data, hora e versão sendo atualizadas na tela de gateways.
- Validar o keepalive no broker.
- Testar os dois sentidos: enviar um cadastro com foto para um leitor (nuvem para LAN) e, em Modo Direct, fazer uma leitura real no equipamento (LAN para nuvem).
- Registrar a unidade como "gateway em nuvem" no controle interno.
Documentar aqui o procedimento e os scripts reais de provisionamento (cadastro de peer no host, template de configuração do MikroTik, subida do container), equivalentes ao que existe em Gateways: instalação e upgrade para o modelo físico.
8. Migração de uma unidade do Gateway físico para o gateway em nuvem
- Levantar os IPs, usuários e senhas de todos os equipamentos administrados pelo gateway físico.
- Confirmar que existe MikroTik na unidade e que ele tem versão de RouterOS com suporte a WireGuard.
- Provisionar o túnel e validar o alcance a todos os equipamentos (passos 1 a 4 da seção anterior).
- Subir o gateway em nuvem mantendo o mesmo facility. Definir se o serial será preservado ou se será cadastrado um novo gateway no Accelero.
- Desligar o gateway físico e só então colocar o gateway em nuvem em produção. Dois gateways com o mesmo serial assinando os mesmos tópicos MQTT causa comportamento imprevisível no tratamento de pendências.
- Em Modo Direct, reconfigurar cada leitor para apontar ao novo endereço do gateway na VPN. Este passo é obrigatório e não tem como ser feito de forma remota antes do túnel existir.
- Acompanhar keepalive, envio de cadastro e liberação de acesso por alguns dias antes de retirar o hardware da unidade.
O passo 6 é o que mais atrasa migração. Levantar antes quantos equipamentos operam em Modo Direct na unidade.
9. Operação e diagnóstico
Roteiro de diagnóstico, do mais externo para o mais interno:
| Sintoma | Onde olhar |
|---|---|
| Gateway offline no Accelero | Container do gateway está no ar? Broker recebendo keepalive daquele serial? |
| Túnel caído | wg show no host: existe handshake recente para aquele peer? MikroTik com internet? |
| Túnel de pé, leitor inalcançável | ping e teste de porta da VPS para o IP do leitor. Rota e AllowedIPs corretos? Firewall do túnel? |
| Leitor responde, cadastro de foto não conclui | MTU. Testar com pacote grande e sem fragmentação. |
| Cadastro sincroniza, acesso não libera (Modo Direct) | Sentido LAN para nuvem: endereço configurado no leitor, rota de volta, firewall. Ver seção 3.2. |
| Túnel cai e volta sozinho | persistent-keepalive ausente, ou link do cliente com CGNAT instável. |
| Comportamento errático nas pendências | Verificar se o gateway físico antigo continua ligado com o mesmo serial. |
Acesso remoto ficou mais simples. O gateway em nuvem roda na infraestrutura da Iongrade, então não depende de SSH reverso nem do inotify do host do cliente. O acesso ao container é direto, como em qualquer serviço da VPS.
10. Pontos de falha: o que muda e o que não muda
Esta arquitetura reduz a quantidade de componentes em campo, mas não elimina pontos de falha. A comparação honesta é:
| Componente | Gateway físico | Gateway em nuvem |
|---|---|---|
| Computador na unidade | Sim (ponto de falha) | Não |
| Roteador na unidade | Sim | Sim (MikroTik, agora crítico) |
| Internet do cliente | Sim | Sim |
| Túnel VPN | Não | Sim (novo ponto de falha) |
| Servidor SaaS | Sim | Sim (agora também hospeda o gateway) |
| Manutenção presencial | Frequente | Rara |
O que de fato melhora: os pontos de falha que sobram são componentes que a Iongrade consegue monitorar e corrigir remotamente, ou equipamento de rede padronizado com ciclo de vida conhecido. O que piora: o MikroTik passa a ser infraestrutura crítica de controle de acesso, e não mais apenas o roteador da unidade.
Comportamento em queda de link
Com o link do cliente fora do ar:
- Gerenciamento de cadastro: os leitores continuam liberando acesso normalmente com a base já sincronizada. Cadastros novos ficam pendentes e são aplicados quando o túnel volta.
- Validação online / Modo Direct: a liberação para, porque a decisão é do servidor. Isso já era verdade no gateway físico, já que o gateway local também dependia do MQTT com a nuvem para decidir.
Ou seja, quanto à dependência de internet, os dois modelos são equivalentes. Essa é uma objeção comum em reunião comercial e a resposta é essa.
Duas diferenças finas que valem conhecer
Elas não mudam a escolha, mas explicam comportamento em campo:
- Pendências em voo. No gateway físico, uma pendência já recebida por MQTT fica gravada em disco dentro da unidade e é entregue ao leitor mesmo se a internet cair logo em seguida. No gateway em nuvem, a pendência fica na fila na VPS e só é entregue quando o túnel voltar. Nos dois casos nada se perde, mas a janela de entrega é diferente.
- Falso offline de equipamento. O
StatsFetcherdo gateway físico continua enxergando os leitores pela LAN mesmo sem internet, então distingue "leitor com defeito" de "unidade sem link". No gateway em nuvem, a queda do túnel faz todos os leitores da unidade aparecerem offline de uma vez, o que na prática é um bom indicador: leitor isolado offline aponta para o equipamento, unidade inteira offline aponta para o túnel ou para o link.
11. Segurança
- Tráfego cifrado fim a fim entre a nuvem e a rede da unidade, incluindo fotos e templates biométricos, que são dado pessoal sensível. Ver LGPD e segurança.
- Nenhuma porta exposta na unidade. Não há redirecionamento de porta, não há IP público de leitor, não há serviço de facial acessível pela internet. Isso é uma melhoria de segurança relevante frente à prática (comum no mercado) de publicar a porta do facial para alcançá-lo de fora.
- Superfície mínima no túnel:
AllowedIPse firewall restringem o alcance aos IPs e serviços necessários, e não à LAN inteira do cliente. - Segregação entre clientes conforme a seção 5. Um cliente não alcança rede nem equipamento de outro.
- Gestão de chaves: chave por unidade, revogação removendo o peer, rotação registrada no controle interno.
Definir a política de rotação de chaves e o procedimento de revogação (desativação de contrato, troca de MikroTik, suspeita de comprometimento).
12. Quando não usar o gateway em nuvem
- Accelero on-premises sem internet: o gateway precisa estar na mesma rede do servidor. Modelo físico.
- Unidade sem MikroTik e sem previsão de instalar um: avaliar custo do MikroTik contra o custo do Gateway físico.
- Link muito instável ou de banda baixa, especialmente com parque grande de leitores e recadastramento frequente.
- Exigência contratual de que nenhum tráfego de controle de acesso atravesse a internet.
13. Unidades que permanecem no modelo físico: como reduzir risco
A migração é gradual e boa parte do parque vai continuar com Gateway físico por bastante tempo. Como a maioria dos incidentes vem da mídia de boot e da alimentação, vale endurecer a borda nas unidades que ficam:
- Boot em eMMC ou SSD em vez de cartão SD, sempre que o hardware permitir. É a medida de maior efeito.
- Cartão de qualidade e de procedência conhecida quando o SD for inevitável, evitando os modelos mais baratos.
- Reduzir escrita em disco: log com rotação agressiva, evitar log de debug permanente, limpar pendências antigas (o
GarbageCollectorjá faz isso, confirmar que está ativo). - Alimentação: fonte adequada e, em unidade crítica, nobreak. Boa parte da corrupção vem de desligamento abrupto.
- Watchdog e restart automático dos containers, para que uma falha de processo não vire chamado.
Priorizar essas medidas justamente nas unidades que não vão migrar tão cedo, por não terem MikroTik ou por serem on-premises.
Próximos passos
- Gateway em Nuvem (portal público): versão para integradores.
- Arquitetura básica de serviços: o que roda dentro do container de gateway.
- Gateways: instalação e upgrade: procedimento do modelo físico.
- SSH Reverso: acesso remoto no modelo físico.