Integração e API

Reverse Proxy

Originado dos proxies HTTP usados para intermediar clientes e servidores, o reverse proxy posiciona-se diante dos serviços e representa os backends para quem acessa. NGINX, HAProxy, Caddy e Traefik encaminham HTTP/1.1, HTTP/2, WebSocket, gRPC ou TCP conforme configuração. O requisito mínimo é uma rota de upstream e resolução confiável. A limitação é estrutural: cabeçalhos, timeouts e TLS mal configurados quebram autenticação, streaming e endereços de origem.

🔀 Tipos de Comunicação

Proxy HTTP/HTTPS de aplicação

O reverse proxy aceita HTTP ou HTTPS, analisa host e caminho e encaminha para um upstream. NGINX usa blocos `server` e `location`; Caddy associa sites e `reverse_proxy`; Traefik usa routers, services e middlewares. O proxy pode encerrar TLS na porta 443 e falar HTTP interno, embora TLS fim a fim seja preferível em redes não confiáveis. O Host original, `X-Forwarded-Proto`, `X-Forwarded-For` e `Forwarded` precisam ser definidos. Aplicações devem confiar nesses cabeçalhos somente quando chegam do proxy conhecido. Caso contrário, um cliente pode forjar IP e esquema. Em Home Assistant, Grafana, Node-RED e painéis locais, o proxy fornece um único domínio e certificado. O aplicativo precisa conhecer sua URL externa e base path para gerar links corretos.

STREAM

Proxy de WebSocket, SSE e streaming

Conexões longas exigem configurações próprias. WebSocket começa com HTTP e usa Upgrade; o proxy precisa preservar `Upgrade` e `Connection` ou usar suporte nativo. Server-Sent Events depende de resposta aberta, buffering desativado ou ajustado e timeouts longos. Streams de câmera e downloads grandes também sofrem com buffers e limites. Um timeout padrão de 60 s pode derrubar dashboards. Aumentá-lo para horas sem limites pode consumir conexões. Keepalive e HTTP/2 mudam. O proxy deve diferenciar tráfego comum e streaming por rota. Testes precisam incluir reconexão, perda de rede e múltiplos clientes. Uma interface funcionar em navegação simples não prova que notificações em tempo real permanecem.

Balanceamento entre múltiplos upstreams

Reverse proxies distribuem requisições por round-robin, least connections, hash, pesos ou algoritmos do produto. NGINX usa round-robin por padrão em grupos upstream. Health checks retiram instâncias falhas quando disponíveis. Sessões em memória podem exigir sticky sessions, mas isso reduz flexibilidade; armazenar sessão em backend compartilhado é preferível. Em uma residência, duas instâncias de Home Assistant não funcionam como cluster ativo apenas porque o proxy balanceia; a aplicação precisa suportar consistência. Para APIs stateless, o balanceamento é mais simples. A política deve considerar conexões WebSocket longas, que não redistribuem até reconectar. O proxy não replica banco nem estado.

Proxy TCP/UDP de camada 4

HAProxy, NGINX stream e outros encaminham conexões TCP e datagramas UDP sem interpretar HTTP. Isso serve para MQTT na porta 1883/8883, bancos, syslog ou protocolos específicos. TLS pode ser pass-through ou encerrado. No pass-through, o backend vê a criptografia e o proxy tem menos acesso a políticas de aplicação. SNI permite rotear TLS em alguns cenários sem decriptar. UDP não possui sessão como TCP e exige afinidade e timeouts. Protocolos de descoberta multicast, como mDNS, não são resolvidos por um proxy unicast comum. O projeto deve distinguir proxy de roteamento e gateway de protocolo. Encaminhar porta não traduz semântica.

✅ Vantagens Arquiteturais

⚡

Consolida certificados e exposição externa

Um único proxy pode atender `home.exemplo.com`, `grafana.exemplo.com` e `nodered.exemplo.com` com certificados ACME. Caddy automatiza obtenção e renovação; NGINX e HAProxy usam certificados fornecidos por Certbot ou outro agente. A centralização reduz repetição, mas cria dependência. A chave privada precisa de proteção e backup. Renovação deve ser monitorada. Portas 80/443 e desafios DNS ou HTTP precisam de política. Expor serviços residenciais diretamente à internet aumenta risco. VPN ou acesso remoto oficial pode ser melhor. Quando o proxy é usado, autenticação, MFA, patches, WAF quando necessário e restrição geográfica ou de identidade devem complementar. TLS válido não torna o aplicativo seguro.

⚡

Permite roteamento por domínio e caminho

Vários serviços compartilham um IP. O proxy escolhe por SNI, Host e URL. Isso simplifica DNS e firewall. Roteamento por subdomínio costuma ser mais compatível que por subpath, porque aplicações geram URLs absolutas e cookies. `home.exemplo.com` tende a exigir menos ajustes que `exemplo.com/home`. Quando subpath é necessário, o proxy e a aplicação devem concordar sobre prefixo e reescrita. Cookies `Path`, redirects, WebSocket e assets são testados. Uma regra genérica pode expor endpoint administrativo. Rotas usam princípio do menor privilégio. O arquivo de configuração é versionado.

⚡

Descarrega funções transversais dos backends

Compressão, cache, TLS, cabeçalhos, autenticação externa, rate limiting e logs podem ser aplicados antes do serviço. Isso reduz carga. Cache precisa ser usado apenas em respostas adequadas. Estados de dispositivo e dados pessoais não devem ser cacheados sem chave e política corretas. Compressão de segredos combinada a conteúdo controlado pode criar riscos. Autenticação no proxy, como Authelia, oauth2-proxy ou forward auth do Traefik, acrescenta camada, mas o backend precisa preservar sua autorização quando aplicável. A centralização deve ser simples e auditável. Um reverse proxy não deve virar aplicação de negócio improvisada.

⚡

Melhora manutenção e migração de serviços

O endpoint externo permanece enquanto o backend muda de IP, porta, container ou host. Blue-green e canary podem ser implementados por peso. Durante uma migração de Node-RED de 10.0.10.20:1880 para 10.0.10.30:1880, o DNS do cliente não muda. A troca precisa considerar sessões e conexões persistentes. Health checks não garantem funcionamento funcional; uma página 200 pode esconder banco indisponível. Testes sintéticos ajudam. Configuração de proxy precisa ser validada antes de recarregar. NGINX suporta teste de sintaxe; Caddy e HAProxy possuem validadores. Um erro na borda pode indisponibilizar todos os serviços.

⚡

Cria um ponto comum de logs e métricas de acesso

O proxy registra método, rota, status, bytes, latência e upstream. Essas informações ajudam a detectar scanners, erros 502/504 e serviços lentos. Logs não devem armazenar query strings com tokens, cabeçalhos Authorization ou corpos sensíveis. O IP do cliente depende de topologia. Se existe CDN ou outro proxy, uma cadeia de confiança é necessária. Aceitar `X-Forwarded-For` de qualquer origem permite falsificação. Métricas de conexões, filas e erros são monitoradas. A consequência prática é detectar que uma câmera ou painel está inacessível antes de uma automação depender dele. O log, porém, não substitui o monitoramento do serviço interno.

Exemplo de Código

# NGINX: proxy HTTPS para Home Assistant
location / {
  proxy_pass http://homeassistant:8123;
  proxy_set_header Host $host;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";
  proxy_read_timeout 3600s;
}
# Configure trusted_proxies no Home Assistant e restrinja a origem.

NGINXHTTP/1.0, HTTP/1.1, HTTP/2, gRPC, FastCGI e proxy TCP/UDP via módulo stream, conforme build e configuração. É web server, reverse proxy, cache e load balancer. Sua configuração declarativa é madura e eficiente. Certificados, renovação ACME, autenticação externa e dashboards geralmente dependem de ferramentas adicionais. Em automação local, NGINX Proxy Manager oferece interface gráfica, mas adiciona container, banco e camada própria. O administrador precisa entender o arquivo final e manter backups.

CaddyHTTP/1.1, HTTP/2 e HTTP/3 no frontend, com reverse proxy e automação HTTPS integrada. A configuração Caddyfile pode ser curta: `home.example.com { reverse_proxy 10.0.0.20:8123 }`. O produto obtém e renova certificados por ACME quando DNS e portas permitem. Essa simplicidade reduz trabalho, mas a automação de certificados precisa de monitoramento. Plugins DNS podem exigir builds específicos e tokens protegidos. Em rede interna, uma CA privada pode ser usada, exigindo confiança nos clientes.

Traefik ProxyHTTP, HTTPS, TCP e UDP, com descoberta dinâmica de Docker, Kubernetes, Consul e outras fontes. Labels de containers criam routers, services e middlewares. É adequado quando serviços mudam com frequência. A conveniência de ler o socket Docker traz risco: acesso ao socket equivale a grande privilégio. Usa-se proxy de socket restrito quando possível. Middlewares implementam headers, redirects, rate limits e forward auth. A configuração dinâmica precisa de governança para não publicar um container por engano.

HAProxyProxy e balanceador de camada 4 e 7 para TCP e HTTP, com alto desempenho, health checks, ACLs, TLS e métricas. É comum quando controle fino de balanceamento e conexões é prioritário. A configuração exige cuidado com modos `tcp` e `http`, timeouts e cabeçalhos. Em MQTT, pode balancear conexões TCP, mas persistência de sessão e estado do broker precisam de arquitetura compatível. Em APIs, logs e stick tables permitem controle. Não é um API management completo sem componentes adicionais.