Coloque documentos do ONLYOFFICE atrás do HAProxy sem interromper a edição.

Execute o ONLYOFFICE Docs por trás do HAProxy, encerrando o HTTPS no proxy, encaminhando o host e o esquema originais e permitindo conexões WebSocket de longa duração. Comece com um servidor de documentos funcionando corretamente; adicione mais servidores de backend somente quando sua implementação do ONLYOFFICE estiver configurada para operação com vários nós, e não apenas porque o HAProxy pode distribuir as requisições.

O HAProxy consegue balancear a carga de dois servidores de documentos independentes?

O HAProxy pode distribuir requisições HTTP entre nós, mas isso não transforma duas instalações independentes do ONLYOFFICE em um cluster de edição coordenado. Uma sessão de edição mantém conexões e estado da aplicação persistentes. O exemplo oficial do ONLYOFFICE com comportamento ativo-ativo utiliza verificações de integridade no backend e um cookie de persistência; esses são mecanismos de roteamento, não substitutos para os serviços compartilhados e a arquitetura de nível de aplicação que sua edição exige.

Para uma instalação convencional em um único servidor, use apenas docs1no backend abaixo. Para dois nós, primeiro confirme a arquitetura do cluster, a edição suportada, as dependências compartilhadas, a compatibilidade de versão e a configuração JWT com a documentação de implantação do ONLYOFFICE ou com o suporte do fornecedor. Os endereços de exemplo — 10.0.10.21e 10.0.10.22— são IPs privados ilustrativos, não hosts descobertos.

O que precisa estar funcionando antes de você editar o HAProxy?

O nome público docs.example.comdeve ser resolvido para o seu endpoint HAProxy. O HAProxy precisa das portas TCP 80 e 443 para entrada e acesso à rede privada de cada Servidor de Documentos na porta 80. Seu aplicativo de gerenciamento de documentos também deve ser capaz de acessar o endereço público do Docs, enquanto o ONLYOFFICE deve ser capaz de buscar documentos e enviar callbacks para o aplicativo. Mantenha o tráfego HTTP do backend privado; criptografe o salto do backend separadamente se ele atravessar uma rede não confiável.

1. Verifique cada servidor de documentos a partir do host proxy. Execute o comando `ipconfig` curl -i http://10.0.10.21/healthchecke, se presente, verifique se o endpoint está funcionando corretamente curl -i http://10.0.10.22/healthcheck. Um endpoint operacional normal retorna HTTP 200 com um corpo de trueerro. Investigue o roteamento, os firewalls ou a integridade do servidor antes de configurar o balanceamento de carga caso algum deles apresente falhas.
2. Confirme um segredo JWT fixo. O Servidor de Documentos e seu conector devem concordar com o segredo do token. Para instalações Docker, a ONLYOFFICE documenta a JWT_SECRETvariável de ambiente; desde a versão 7.2 da documentação, confiar em um segredo gerado automaticamente pode causar falhas de integração após a recriação ou reinicialização. Em implantações com vários nós, alinhe os segredos entre os nós de acordo com a arquitetura do fornecedor.

Essas verificações seguem as orientações de instalação do Docker e as instruções de configuração do JWT fornecidas pelo fornecedor . Não desative o JWT apenas para contornar um erro de proxy.

Como configurar o HTTPS e encaminhar os cabeçalhos corretos?

Passo 1: Prepare o certificado

Obtenha um certificado confiável que cubra o diretório docs.example.com. Neste exemplo do Linux, o HAProxy lê um arquivo PEM contendo a cadeia de certificados seguida pela chave privada. Se os certificados já existirem em outro local, substitua esses caminhos. Restrinja o acesso ao arquivo PEM combinado e configure-o para ser reconstruído quando o certificado for renovado.

sudo install -d -m 700 /etc/haproxy/certs
sudo sh -c 'umask 077; cat /etc/letsencrypt/live/docs.example.com/fullchain.pem /etc/letsencrypt/live/docs.example.com/privkey.pem > /etc/haproxy/certs/docs.example.com.pem'

Passo 2: Adicione o frontend e o backend

Faça backup da sua configuração existente /etc/haproxy/haproxy.cfge adapte as seções a seguir, em vez de substituir cegamente as configurações de registro ou serviço específicas da distribuição. Esta é uma configuração ilustrativa para versões modernas do HAProxy. Ela aceita apenas HTTP para redirecionamento, encerra o HTTPS na porta 443, encaminha o host e o esquema públicos e monitora o endpoint de integridade do aplicativo.

global
    log /dev/log local0

defaults
    mode http
    log global
    option httplog
    option forwardfor
    timeout connect 5s
    timeout client 60s
    timeout server 60s
    timeout tunnel 1h

frontend docs_http
    bind :80
    http-request redirect scheme https code 301

frontend docs_https
    bind :443 ssl crt /etc/haproxy/certs/docs.example.com.pem
    http-request set-header X-Forwarded-Proto https
    http-request set-header X-Forwarded-Host %[req.hdr(Host)]
    default_backend docs_nodes

backend docs_nodes
    option http-server-close
    balance roundrobin
    cookie SERVERID insert indirect nocache
    option httpchk GET /healthcheck
    http-check expect string true
    server docs1 10.0.10.21:80 check cookie docs1
    server docs2 10.0.10.22:80 check cookie docs2

Remova a docs2linha a menos que o segundo nó esteja realmente pronto. O cookie de persistência ajuda as solicitações HTTP subsequentes a retornarem ao nó selecionado. O HAProxy lida com uma atualização do WebSocket HTTP sem uma reescrita de URL especial; timeout tunnel 1hpermite que conexões atualizadas ociosas permaneçam abertas por mais tempo do que solicitações comuns. A documentação do WebSocket do HAProxy explica esse comportamento.

X-Forwarded-ProtoA configuração httpscorreta aqui é porque este frontend encerra o HTTPS público. Não confie em um esquema de encaminhamento arbitrário fornecido pelo cliente ou em um host na borda da rede voltada para a Internet. A documentação do proxy ONLYOFFICE exige especificamente que X-Forwarded-Protoo X-Forwarded-Hostcontexto da URL externa seja mantido.

Como devo recarregar e testar o balanceador de carga?

Etapa 3: Valide antes de alternar o tráfego

Verifique a sintaxe antes de recarregar. Um código de saída diferente de zero significa que você deve resolver o erro de configuração ou certificado relatado antes de prosseguir.

sudo haproxy -c -f /etc/haproxy/haproxy.cfg
sudo systemctl reload haproxy
curl -i https://docs.example.com/healthcheck

A resposta pública da verificação de integridade deve exibir HTTP 200 truequando um backend estiver íntegro. O HAProxy usa as diretivas option httpchk`has_replace` e `has_replace` http-check expectpara remover nós com falha da rotação de novas requisições; consulte a documentação sobre verificação de integridade . Uma verificação bem-sucedida não comprova que a edição de documentos ou o envio de callbacks estejam funcionando corretamente.

Passo 4: Confirme a edição, os WebSockets e salve.

Abra um documento através do seu aplicativo integrado, como um sistema de gerenciamento de documentos conectado ao ONLYOFFICE Docs. Nas ferramentas de desenvolvedor do navegador, use o painel Rede para inspecionar a conexão WebSocket: o handshake de atualização deve ser bem-sucedido, geralmente com o status HTTP 101 Switching Protocols80. Faça uma pequena edição, feche o editor, abra o documento novamente e confirme se a alteração foi salva. Para uma implantação de dois nós com suporte adequado, teste também um segundo colaborador e um teste de drenagem de um único nó durante uma janela de manutenção.

Se a verificação de integridade pública funcionar, mas o editor travar ou desconectar, verifique avisos de conteúdo misto, falhas de WebSocket, incompatibilidades de JWT e se o aplicativo de documentos consegue acessar a URL do Docs anunciada. Se um documento abrir, mas nunca for salvo, investigue a acessibilidade do callback do Servidor de Documentos para o aplicativo de origem, em vez de alterar a política round-robin do HAProxy. Uma sessão WebSocket ativa interrompida ainda pode exigir a reconexão do cliente; as verificações de integridade do backend não garantem uma transição perfeita para a edição em caso de falha.

Verificação final: tanto o endpoint de saúde pública quanto um teste real de edição e reabertura devem ser aprovados. Mantenha em rotação apenas nós verificados e suportados, confirme se a renovação do certificado recarrega o PEM correto e monitore os logs do HAProxy em busca de respostas 502/503 repetidas ou desconexões inesperadas do WebSocket.