Um proxy reverso no Apache com WebSockets e SSL recebe conexões HTTPS e WSS, termina o TLS e encaminha as requisições ao servidor de automação. Para manter HTTP e WebSocket funcionando juntos, configure o upgrade de protocolo, os cabeçalhos de origem e o acesso restrito ao backend:
- Confirme a versão do Apache e mantenha a aplicação acessível apenas pelo proxy.
- Habilite os módulos de proxy, SSL e controle de cabeçalhos.
- Emita um certificado válido para o domínio da automação.
- Configure o VirtualHost HTTPS com encaminhamento HTTP e suporte a WebSocket.
- Valide o certificado, o handshake WebSocket, os webhooks e a renovação do certificado.
Pré-requisitos
A terminação TLS centraliza o certificado no Apache, mas não substitui a autenticação do servidor de automação. O procedimento abaixo usa Ubuntu 24.04 LTS, Apache 2.4.47 ou superior e uma aplicação já instalada. A configuração principal encaminha tanto as páginas HTTP quanto as conexões WebSocket pela mesma regra, sem depender de um caminho específico como /ws/.
- Acesso SSH com permissão para executar comandos com
sudo. - Domínio apontado para o servidor. Substitua
seudominio.com.brpelo domínio real em todos os arquivos e comandos. - Portas TCP 80 e 443 acessíveis para validação do certificado, redirecionamento e acesso HTTPS.
- Aplicação atendendo por HTTP em
127.0.0.1:5678. A porta é um exemplo: use a porta real do seu serviço. - Conhecimento do endpoint WebSocket, da URL pública e da configuração de proxies confiáveis da aplicação.
- Ausência de outro VirtualHost com o mesmo
ServerNamee a mesma porta. - Backup dos arquivos existentes antes de alterar um site que já recebe tráfego.
O cenário usa um domínio dedicado à automação e publica a aplicação na raiz. Publicar em um subdiretório exige suporte da aplicação a prefixos de URL, inclusive nos arquivos estáticos, redirecionamentos e WebSockets. Para revisar o papel desse intermediário, consulte O que é Servidor Proxy Reverso e Como Configurá-lo.
1. Prepare os módulos e isole a porta da aplicação
O encaminhamento HTTP depende de mod_proxy e mod_proxy_http. No Apache 2.4.47 ou superior, o segundo módulo também consegue negociar o upgrade para WebSocket quando a regra permite esse protocolo. Isso evita encaminhar todas as requisições para um destino ws://, o que não serve como substituto genérico para as páginas e APIs HTTP.
-
Instale os componentes usados neste procedimento:
sudo apt update sudo apt install apache2 certbot curl sudo a2enmod proxy proxy_http ssl headers rewrite apache2 -vVerifique a versão apresentada pelo último comando. Esta configuração exige Apache 2.4.47 ou superior; não copie a opção de upgrade para uma instalação mais antiga sem conferir a compatibilidade.
-
Confira os módulos carregados:
sudo apache2ctl -M | grep -E 'proxy_module|proxy_http_module|ssl_module|headers_module|rewrite_module'As linhas relevantes devem incluir estes módulos; a ordem pode variar:
headers_module (shared) proxy_module (shared) proxy_http_module (shared) rewrite_module (shared) ssl_module (shared) -
Na configuração da aplicação, altere o endereço de escuta para
127.0.0.1, mantendo a porta interna correta. Reinicie apenas o serviço da aplicação pelo mecanismo que ela utiliza e confira o resultado:sudo ss -ltnp 'sport = :5678' curl --connect-timeout 5 -I http://127.0.0.1:5678/
Na listagem do ss, o endereço local deve ser 127.0.0.1:5678, não 0.0.0.0:5678 nem [::]:5678. A resposta do curl depende da aplicação: um redirecionamento para login pode ser válido. Se o endpoint não aceitar HEAD, teste com GET usando curl -i.
Quando o backend estiver em outra máquina, use firewall para aceitar conexões somente do Apache e proteja o transporte conforme a confiança na rede. Não publique a porta interna apenas para contornar uma falha de conectividade.
2. Emita o certificado e prepare a renovação
O certificado SSL do domínio precisa existir antes de ativar o VirtualHost da porta 443. Aqui, a emissão usa o desafio HTTP-01 com um diretório público exclusivo para os arquivos de validação. Essa separação permite renovar o certificado sem encaminhar o desafio ao servidor de automação.
Atenção: os arquivos abaixo são novos exemplos de configuração. Se esses nomes já existirem, faça backup e revise o conteúdo antes de substituí-los. Em um domínio em produção, execute a mudança em uma janela controlada.
-
Crie a raiz usada na validação:
sudo install -d -m 755 /var/www/acme/.well-known/acme-challenge sudo nano /etc/apache2/sites-available/automacao-http.confSalve o seguinte VirtualHost HTTP:
<VirtualHost *:80> ServerName seudominio.com.br DocumentRoot /var/www/acme <Directory /var/www/acme> Options -Indexes AllowOverride None Require all granted </Directory> ErrorLog /var/log/apache2/automacao-http-error.log CustomLog /var/log/apache2/automacao-http-access.log combined </VirtualHost> -
Ative o site e valide a sintaxe antes de recarregar:
sudo a2ensite automacao-http.conf sudo apache2ctl configtestA indicação de sucesso é:
Syntax OKsudo systemctl reload apache2 -
Solicite o certificado e responda às perguntas de cadastro e aceitação dos termos:
sudo certbot certonly --webroot -w /var/www/acme -d seudominio.com.br
Se houver registro AAAA, ele também deve alcançar este servidor corretamente. Um endereço IPv6 incorreto pode prejudicar a validação mesmo quando o acesso por IPv4 funciona. Não avance enquanto a emissão não terminar com sucesso.
Os próximos exemplos consideram os arquivos /etc/letsencrypt/live/seudominio.com.br/fullchain.pem e /etc/letsencrypt/live/seudominio.com.br/privkey.pem. Confirme os caminhos informados pelo Certbot: certificados anteriores podem gerar nomes de diretório diferentes. Preserve as permissões gerenciadas pela ferramenta e não torne a chave privada legível para todos os usuários.
3. Configure o VirtualHost HTTPS e o upgrade WebSocket
O túnel WebSocket será negociado na mesma rota usada pelas requisições HTTP. A opção upgrade=websocket permite ao Apache encaminhar a solicitação de upgrade ao backend; a aplicação ainda precisa aceitar o handshake. Uma requisição HTTP comum continua sendo tratada como HTTP.
-
Crie o arquivo do site seguro:
sudo nano /etc/apache2/sites-available/automacao-ssl.confUse a configuração abaixo, ajustando domínio, certificado e porta interna:
<VirtualHost *:443> ServerName seudominio.com.br SSLEngine On SSLCertificateFile /etc/letsencrypt/live/seudominio.com.br/fullchain.pem SSLCertificateKeyFile /etc/letsencrypt/live/seudominio.com.br/privkey.pem SSLProtocol -all +TLSv1.2 +TLSv1.3 RewriteEngine On RewriteCond %{HTTP_HOST} !^seudominio\.com\.br(?::443)?$ [NC] RewriteRule ^ - [R=400,L] ProxyRequests Off ProxyPreserveHost On ProxyAddHeaders On RequestHeader unset Forwarded RequestHeader unset X-Forwarded-For RequestHeader unset X-Forwarded-Host RequestHeader set X-Forwarded-Proto "https" RequestHeader set X-Forwarded-Port "443" ProxyPass "/" "http://127.0.0.1:5678/" upgrade=websocket connectiontimeout=5 timeout=300 ProxyPassReverse "/" "http://127.0.0.1:5678/" ErrorLog /var/log/apache2/automacao-ssl-error.log CustomLog /var/log/apache2/automacao-ssl-access.log combined </VirtualHost> -
Ative o VirtualHost e só aplique a mudança se a validação for bem-sucedida:
sudo a2ensite automacao-ssl.conf sudo apache2ctl configtest sudo systemctl reload apache2
ProxyRequests Off desabilita o proxy direto; não impede o funcionamento do proxy reverso. ProxyPassReverse ajusta determinados cabeçalhos de redirecionamento enviados pelo backend, mas não reescreve URLs dentro de HTML, JavaScript ou mensagens WebSocket. Por isso, a URL pública da aplicação também precisa estar correta.
O valor connectiontimeout=5 limita a espera para estabelecer conexão com o backend. Já timeout=300 é um exemplo de tempo de espera de comunicação, não uma garantia de duração da sessão nem um limite total para a execução de uma automação. Ajuste conforme os intervalos de heartbeat e o comportamento do serviço.
Não é necessário carregar mod_proxy_wstunnel para esta regra moderna com destino HTTP. Ele é relevante em configurações que usam destinos explícitos ws:// ou wss://. Se adotar regras separadas, coloque a rota específica antes da regra genérica /; caso contrário, a primeira correspondência pode capturar o pedido antes da regra WebSocket.
4. Ajuste a URL pública e proteja os cabeçalhos
Os cabeçalhos encaminhados permitem que a aplicação reconheça o protocolo e o endereço usados pelo visitante. No exemplo, o Apache recebe HTTPS, mas conversa com o backend por HTTP local. Sem informar essa diferença corretamente, a aplicação pode gerar URLs inseguras, recusar cookies ou redirecionar repetidamente para HTTPS.
-
Defina na aplicação a URL pública
https://seudominio.com.br. Se houver um campo separado para webhooks, configure a mesma origem HTTPS, com o caminho exigido pelo serviço. -
Autorize como proxy confiável apenas o endereço pelo qual o Apache acessa a aplicação. Neste cenário local, essa origem é
127.0.0.1. Os nomes dessas opções variam conforme o servidor de automação. -
Reinicie ou recarregue a aplicação conforme a documentação dela. Confirme que links, callbacks e conexões do navegador passaram a usar HTTPS e WSS.
-
No VirtualHost HTTP criado anteriormente, adicione esta diretiva antes de
</VirtualHost>:RedirectMatch 301 "^/(?!\.well-known/acme-challenge/)(.*)$" "https://seudominio.com.br/$1"Ela redireciona as demais rotas para HTTPS e deixa o caminho de validação acessível por HTTP. Depois, valide e aplique:
sudo apache2ctl configtest sudo systemctl reload apache2
A configuração remove valores de Forwarded, X-Forwarded-For e X-Forwarded-Host recebidos do cliente antes do encaminhamento. O módulo de proxy adiciona seus próprios cabeçalhos e o protocolo externo é definido explicitamente. Com ProxyPreserveHost On, o cabeçalho Host recebido do cliente é repassado ao backend; por isso, o VirtualHost HTTPS valida o valor de Host antes de encaminhar a requisição — a regra RewriteCond adicionada rejeita com 400 qualquer host diferente do domínio esperado, impedindo que um atacante injete um host arbitrário para influenciar URLs e redirecionamentos gerados pela aplicação. Isso pressupõe acesso direto dos clientes ao Apache; se existir outro proxy antes dele, será necessário definir uma cadeia de confiança específica.
Mantenha a autenticação da aplicação e a validação de origem dos WebSockets. Para painéis privados, restrições de acesso podem ser apropriadas, mas não bloqueie indiscriminadamente os endpoints de webhooks que precisam receber chamadas externas. Nunca use upgrade=ANY como atalho para corrigir um handshake recusado.
5. Valide HTTPS, WSS e a renovação automática
O handshake WebSocket precisa ser testado no endpoint real da aplicação, não apenas na página inicial. Primeiro confirme o acesso HTTPS e o redirecionamento; depois verifique a conexão persistente no navegador e execute uma operação da automação que dependa dela.
-
Confira o redirecionamento HTTP e a resposta HTTPS:
curl -I http://seudominio.com.br/ curl -I https://seudominio.com.br/Na primeira resposta, espere um status 301 e o cabeçalho
Locationapontando para HTTPS. Na segunda, o status depende da aplicação: pode ser uma página disponível ou um redirecionamento de autenticação. Não use-k, pois essa opção esconderia falhas na validação do certificado. -
Abra as ferramentas de desenvolvimento do navegador, acesse a aba de rede e filtre por WS. Faça login e execute a ação que abre a conexão. Confirme a URL
wss://, a troca de mensagens e a ausência de reconexões repetidas. -
Para inspecionar um handshake por HTTP/1.1, adapte o caminho de exemplo abaixo ao endpoint real:
curl --http1.1 -i -N --max-time 5 \ -H "Connection: Upgrade" \ -H "Upgrade: websocket" \ -H "Sec-WebSocket-Version: 13" \ -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \ -H "Origin: https://seudominio.com.br" \ https://seudominio.com.br/ws/Se esse endpoint aceitar o pedido sem credenciais ou subprotocolo adicional, a linha de status esperada será:
HTTP/1.1 101 Switching ProtocolsEsse comando inspeciona o handshake, mas não substitui um cliente WebSocket completo. O encerramento pelo limite de cinco segundos pode ocorrer mesmo após um upgrade bem-sucedido. Aplicações autenticadas podem exigir cookies, tokens ou subprotocolos; nesses casos, valide pelo cliente oficial ou pelo navegador.
-
Configure um gancho para recarregar o Apache após renovações bem-sucedidas:
sudo install -d -m 755 /etc/letsencrypt/renewal-hooks/deploy sudo nano /etc/letsencrypt/renewal-hooks/deploy/reload-apacheSalve o conteúdo:
#!/bin/sh /usr/sbin/apache2ctl configtest && /usr/bin/systemctl reload apache2sudo chmod 750 /etc/letsencrypt/renewal-hooks/deploy/reload-apache sudo systemctl enable --now certbot.timer sudo systemctl list-timers --all certbot.timer sudo certbot renew --dry-run
O teste de renovação verifica o fluxo de emissão, mas não executa os ganchos de deploy por padrão. Confira separadamente a sintaxe e a recarga. Para testar a exceção HTTP, crie um arquivo temporário:
printf 'validacao-acme\n' | sudo tee /var/www/acme/.well-known/acme-challenge/teste-proxy
curl http://seudominio.com.br/.well-known/acme-challenge/teste-proxy
A resposta deve conter validacao-acme, sem redirecionamento para a aplicação. Remova depois apenas esse arquivo de teste. Por fim, valide um webhook externo, a sessão autenticada e uma atualização em tempo real: carregar a tela inicial não comprova todo o funcionamento.
Problemas comuns e como resolver
Os logs do VirtualHost ajudam a separar falhas de transporte, recusas da aplicação e problemas de certificado. Durante o diagnóstico, acompanhe também os registros do backend e reproduza uma única operação por vez:
sudo tail -f /var/log/apache2/automacao-ssl-error.log /var/log/apache2/automacao-ssl-access.log
Sintoma: erro 502 ou 503 ao abrir a automação
Causa: o Apache pode não conseguir conectar à porta interna, o serviço pode estar parado ou o protocolo do destino pode estar incorreto.
Solução: repita o acesso local com curl e confira a escuta com ss. Compare endereço, porta e protocolo com o ProxyPass. Não aumente o timeout antes de confirmar que a aplicação responde diretamente.
Sintoma: a página abre, mas as atualizações em tempo real falham
Causa: endpoint WebSocket incorreto, regra específica depois da regra genérica, URL ws:// em uma página HTTPS ou recusa de autenticação e origem.
Solução: inspecione a requisição WS no navegador. Confirme WSS, caminho, parâmetros e credenciais. Respostas 401 ou 403 indicam recusa que deve ser investigada na aplicação; não remova a autenticação para obter o status 101.
Sintoma: redirecionamentos HTTPS se repetem
Causa: a aplicação interpreta o HTTP interno como protocolo público ou não confia no cabeçalho enviado pelo Apache.
Solução: confira a URL pública, o valor de X-Forwarded-Proto e a lista de proxies autorizados. Use curl -I para examinar o destino de cada redirecionamento sem seguir indefinidamente a cadeia.
Sintoma: o WebSocket cai quando fica sem mensagens
Causa: um timeout de inatividade pode ser atingido no Apache, na aplicação ou em outro componente do caminho.
Solução: compare os horários das quedas com os limites configurados. Ajuste o timeout da rota e o heartbeat suportado pelo cliente e pelo servidor. Evite simplesmente elevar todos os limites: conexões abandonadas também consomem recursos.
Sintoma: o certificado funciona hoje, mas a renovação falha
Causa: o desafio HTTP pode ter sido enviado ao backend, bloqueado por autenticação ou direcionado a outro endereço pelo DNS.
Solução: teste novamente o caminho de validação, confira os registros A e AAAA e execute certbot renew --dry-run. Mantenha a exceção HTTP e acompanhe os erros do agendamento antes do vencimento.
Perguntas frequentes
Quais módulos do Apache são necessários para proxy reverso com WebSockets e SSL?
Uma configuração com backend HTTP normalmente utiliza mod_proxy, mod_proxy_http e mod_ssl; mod_headers permite controlar cabeçalhos encaminhados à aplicação. No Apache 2.4.47 ou superior, mod_proxy_http pode tratar o upgrade para WebSocket com a configuração adequada. O mod_proxy_wstunnel é uma alternativa para configurações que encaminham explicitamente conexões para destinos ws:// ou wss://.
Como configurar WebSockets no Apache sem interromper as requisições HTTP?
Configure o encaminhamento HTTP ao backend e habilite o upgrade WebSocket na regra apropriada, conforme a versão do Apache e o endpoint da aplicação. Quando houver regras separadas, coloque a rota específica de WebSocket antes da regra genérica. Valide a conexão no navegador: um handshake WebSocket bem-sucedido sobre HTTP/1.1 retorna o status 101 Switching Protocols.
O certificado SSL precisa ser instalado também no servidor de automação?
Quando Apache e aplicação estão no mesmo servidor e o backend atende apenas pela interface de loopback, é possível terminar o TLS no Apache e usar HTTP nesse trecho local. Se a comunicação atravessar uma rede não confiável, utilize HTTPS também até o backend, com validação do certificado e do nome do servidor. O navegador deve acessar a aplicação por HTTPS e os WebSockets por WSS.
Como impedir acesso direto à porta do backend de automação?
Se o backend estiver no mesmo servidor do Apache, configure a aplicação para escutar somente em 127.0.0.1 ou em um socket Unix, quando houver suporte. Se estiver em outro servidor, restrinja a porta por firewall para aceitar apenas a origem do proxy. Mantenha ProxyRequests Off no Apache e preserve a autenticação da aplicação, pois o proxy reverso não substitui o controle de acesso.
Por que a aplicação entra em loop de redirecionamento HTTPS atrás do Apache?
O loop pode ocorrer quando o Apache recebe HTTPS, mas a aplicação interpreta a conexão HTTP interna como se fosse o acesso original do usuário. Configure a URL pública HTTPS na aplicação e encaminhe a informação de protocolo por um cabeçalho como X-Forwarded-Proto, definido pelo proxy. A aplicação deve confiar nesses cabeçalhos somente quando recebidos de proxies autorizados.
Conclusão
A publicação segura do servidor de automação depende da combinação entre TLS válido, negociação WebSocket e confiança limitada no proxy. O Apache pode encaminhar HTTP e WebSocket pela mesma regra, enquanto a aplicação permanece responsável pela autenticação, pelos endpoints e pelas permissões dos usuários.
- Revise a exposição: confirme que apenas o Apache recebe o tráfego público e que a porta interna permanece restrita ao endereço previsto.
- Valide o fluxo completo: teste login, webhooks e mensagens em tempo real, além do certificado e do redirecionamento HTTPS.
- Mantenha a configuração: acompanhe logs, teste a renovação e execute a validação de sintaxe antes de cada recarga do Apache.
Leia também
- O que é Servidor Proxy Reverso e Como Configurá-lo
- Checklist: configurar proxy reverso WordPress com SSL e IP restrito
- Otimizar Apache contra ataques DDoS e sobrecarga no Ubuntu 22.04
Precisa de ajuda com proxy reverso Apache?
Uma infraestrutura com acesso administrativo permite ajustar certificados, isolamento do backend e conexões persistentes conforme as necessidades da automação. Conheça as opções da AviraHost e avalie os recursos adequados ao seu ambiente.