Pular para o conteúdo

Como configurar proxy reverso no Apache com WebSockets e SSL

Por Equipe Técnica AviraHost · 20 min de leitura · Atualizado em · apache, proxy-reverso, websockets, ssl, automacao, seguranca, AviraHost · 0

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:

  1. Confirme a versão do Apache e mantenha a aplicação acessível apenas pelo proxy.
  2. Habilite os módulos de proxy, SSL e controle de cabeçalhos.
  3. Emita um certificado válido para o domínio da automação.
  4. Configure o VirtualHost HTTPS com encaminhamento HTTP e suporte a WebSocket.
  5. 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.br pelo 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 ServerName e 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.

  1. Instale os componentes usados neste procedimento:

    sudo apt update
    sudo apt install apache2 certbot curl
    sudo a2enmod proxy proxy_http ssl headers rewrite
    apache2 -v

    Verifique 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.

  2. 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)
  3. 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.

  1. 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.conf

    Salve 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>
  2. Ative o site e valide a sintaxe antes de recarregar:

    sudo a2ensite automacao-http.conf
    sudo apache2ctl configtest

    A indicação de sucesso é:

    Syntax OK
    sudo systemctl reload apache2
  3. 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.

  1. Crie o arquivo do site seguro:

    sudo nano /etc/apache2/sites-available/automacao-ssl.conf

    Use 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>
  2. 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.

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  1. 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 Location apontando 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.

  2. 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.

  3. 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 Protocols

    Esse 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.

  4. 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-apache

    Salve o conteúdo:

    #!/bin/sh
    /usr/sbin/apache2ctl configtest && /usr/bin/systemctl reload apache2
    sudo 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

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.

Conhecer as opções de servidor VPS


Esta resposta foi útil?