Como executar o servidor de documentos ONLYOFFICE por trás de um balanceador de carga HAProxy

A regra mais importante é a seguinte: colocar o ONLYOFFICE Document Server atrás do HAProxy é simples para um único backend, mas um cluster de editores com vários nós exige mais do que um simples balanceamento de carga round-robin. A documentação atual da API do ONLYOFFICE afirma que as solicitações para o mesmo documento devem chegar ao mesmo nó do Document Server durante a edição colaborativa. Para integrações modernas, o mecanismo recomendado é o shardkeyparâmetro de consulta, que o balanceador de carga pode usar para garantir a afinidade com base no documento.

Se você tiver apenas um servidor de documentos e quiser usar o HAProxy para terminação HTTPS, um nome de host público estável ou verificações de integridade centralizadas, a configuração é mais simples. Se você tiver dois ou mais nós de servidor de documentos, use os mesmos fundamentos de proxy, mas adicione roteamento baseado em lógica de roteamento shardkeyem vez de assumir que o round-robin comum seja suficiente.

Os exemplos abaixo foram verificados em relação à documentação atual do proxy ONLYOFFICE , à documentação da chave de fragmentação ONLYOFFICE e às diretrizes atuais do HAProxy WebSocket .

Quando essa configuração for adequada

O HAProxy é uma interface adequada quando você precisa de uma única URL pública, como por exemplo https://docs.example.com, terminação TLS no balanceador de carga, verificações de integridade ativas ou vários nós do Document Server por trás de um único endpoint. Ele também é útil quando seu Nextcloud, ownCloud, DMS personalizado ou aplicativo nunca deve se conectar diretamente a um nó individual do Document Server.

Este guia pressupõe:

• O HAProxy consegue alcançar cada servidor de documentos através da rede interna.
• Cada servidor de documentos já funciona diretamente antes da introdução do balanceador de carga.
• O nome de host público resolve para HAProxy.
• Seu certificado TLS abrange o nome de host público.
• Se você executar vários nós, eles serão implantados como uma arquitetura ONLYOFFICE com vários servidores, em vez de servidores independentes não relacionados que simplesmente compartilham um balanceador de carga.

Passo 1: Verifique todos os servidores de documentos antes de adicionar o HAProxy.

Não comece pelo balanceador de carga. Primeiro, verifique se todos os servidores de backend estão íntegros a partir do host do HAProxy. A documentação do ONLYOFFICE /healthcheckindica o endpoint para verificar a disponibilidade do editor. Um servidor íntegro retorna um resultado positivo true; a verificação abrange dependências essenciais como o banco de dados, o broker de mensagens, a conexão com o Redis e o armazenamento.

curl -sS http://10.0.10.21/healthcheck
curl -sS http://10.0.10.22/healthcheck

Resultado esperado:

true
true

Se um dos servidores de backend falhar, solucione o problema desse nó primeiro. Causas comuns incluem regras de firewall, uma porta interna incorreta, serviços do Servidor de Documentos não em execução ou serviços de suporte indisponíveis.

Passo 2: Defina o modo HTTP e os tempos limite que tolerem conexões do editor.

O ONLYOFFICE é um aplicativo HTTP e utiliza conexões WebSocket de longa duração durante a edição. O HAProxy pode encaminhar WebSockets automaticamente após a atualização para HTTP, mas sua política de tempo limite ainda é importante. A própria documentação do HAProxy recomenda um timeout tunnelvalor para conexões WebSocket atualizadas.

Um ponto de partida prático é:

global
    log /dev/log local0
    log /dev/log local1 notice
    daemon
    maxconn 4096

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

Um tempo limite de túnel de uma hora é apenas um exemplo, não um requisito universal. Escolha um valor que se adeque ao comportamento de edição, à política de segurança e aos limites de recursos da sua organização. Se os editores se desconectarem em intervalos muito regulares, compare esse intervalo com os tempos limite de inatividade do HAProxy e de qualquer firewall ou proxy reverso upstream.

Etapa 3: Encerrar o HTTPS e preservar o contexto da solicitação original

O ONLYOFFICE exige explicitamente cabeçalhos encaminhados quando executado por trás de um proxy. Em particular, o cabeçalho `<hostname> X-Forwarded-Proto` informa ao Document Server se o cliente original usou HTTP ou HTTPS, enquanto X-Forwarded-Hosto cabeçalho `<hostname>` preserva o nome do host solicitado pelo cliente.

Um frontend HAProxy limpo pode ter esta aparência:

frontend onlyoffice_http
    bind *:80
    mode http
    http-request redirect scheme https code 301

frontend onlyoffice_https
    bind *:443 ssl crt /etc/haproxy/certs/docs.example.com.pem
    mode http
    option httplog

    http-request set-header X-Forwarded-Proto https
    http-request set-header X-Forwarded-Host %[req.hdr(Host)]

    default_backend onlyoffice_docs

Normalmente, não é necessário recriar manualmente as regras de cabeçalho Upgradee estilo NGINX Connectionno modo HTTP moderno do HAProxy. O HAProxy reconhece a atualização de HTTP para WebSocket e alterna a conexão para o modo túnel. O importante é não inserir regras que removam ou interrompam a solicitação de atualização.

Para obter visibilidade do IP do cliente, adicione isso option forwardforno backend. Isso gera um X-Forwarded-Forcabeçalho a partir do endereço de origem do cliente.

Passo 4: Adicione verificações de saúde e escolha a regra de balanceamento adequada.

Servidor de Documentos Únicos

Se o HAProxy estiver na frente de um servidor de documentos, o backend pode ser simples:

backend onlyoffice_docs
    mode http
    option forwardfor
    option httpchk GET /healthcheck
    http-check expect status 200
    timeout tunnel 1h

    server ds1 10.0.10.21:80 check

Nesse projeto, o HAProxy funciona principalmente como um proxy reverso, um ponto de extremidade TLS e um mecanismo de verificação de integridade (health gate).

Vários nós do servidor de documentos

Para uma implementação real com vários nós, não confie no simples esquema round-robin para edição colaborativa. A documentação atual do ONLYOFFICE afirma que todas as solicitações referentes ao mesmo documento devem chegar ao mesmo servidor. As solicitações de edição do navegador para o servidor incluem automaticamente uma chave de fragmentação, e os aplicativos devem adicioná-la ?shardkey=<document-key>às solicitações de comando, conversão e do Construtor de Documentos, conforme documentado.

O HAProxy suporta hashing em parâmetros de consulta de URL, portanto, um backend adequado para a API padrão de documentação do ONLYOFFICE é:

backend onlyoffice_docs
    mode http
    option forwardfor
    option httpchk GET /healthcheck
    http-check expect status 200
    timeout tunnel 1h

    balance url_param shardkey

    server ds1 10.0.10.21:80 check
    server ds2 10.0.10.22:80 check

O algoritmo do HAProxy url_paramaplica um hash ao parâmetro de consulta selecionado. Se esse parâmetro estiver ausente, o HAProxy utiliza o comportamento padrão de balanceamento de carga. Isso torna especialmente importante que sua integração envie a chave de fragmentação (shard key) nas solicitações em que a ONLYOFFICE recomenda.

WOPI é diferente. A ONLYOFFICE afirma que as integrações WOPI usam o WOPISrcparâmetro de consulta para a mesma finalidade de roteamento. Não copie a balance url_param shardkeylinha sem alterações para um projeto WOPI e assuma que ela fornece a afinidade necessária.

Valide e recarregue o HAProxy com segurança.

Antes de recarregar o serviço, valide a configuração:

sudo haproxy -c -f /etc/haproxy/haproxy.cfg

Recarregar somente após a validação da sintaxe ser bem-sucedida:

sudo systemctl reload haproxy
sudo systemctl status haproxy

Se a sua distribuição usa um gerenciador de serviços ou caminho de configuração diferente, adapte esses comandos de acordo. Uma recarga é preferível a uma reinicialização forçada desnecessária quando o seu pacote HAProxy oferece suporte a recarregamentos de configuração controlados.

Teste através do URL público, não apenas de dentro da rede de back-end.

Agora teste o que os usuários e sua plataforma de gerenciamento de documentos realmente alcançarão:

curl -sS https://docs.example.com/healthcheck

O corpo esperado é:

true

Em seguida, verifique o certificado TLS:

openssl s_client -connect docs.example.com:443   -servername docs.example.com </dev/null 2>/dev/null   | openssl x509 -noout -subject -issuer -dates

Por fim, abra um documento real por meio do aplicativo de integração. Uma verificação de integridade apenas comprova que o endpoint do Servidor de Documentos está pronto; ela não comprova se os URLs de retorno de chamada, a configuração JWT, os downloads de documentos, os retornos de chamada de salvamento ou a afinidade de vários nós estão todos corretos.

O que verificar quando o editor carrega, mas desconecta ou não consegue salvar?

Você precisa de sessões persistentes?

A persistência tradicional de IP de origem não é a melhor solução padrão para o ONLYOFFICE. Vários usuários editando o mesmo arquivo podem ter endereços IP de cliente diferentes, e um usuário pode abrir documentos diferentes que não precisam estar no mesmo nó. A afinidade com reconhecimento de documento baseada na chave de fragmentação do ONLYOFFICE é mais precisa porque a chave de roteamento representa o documento em edição, e não o endereço de rede do usuário.

Essa mesma distinção explica por que uma sessão persistente baseada em cookies não deve ser tratada como substituta do comportamento de roteamento documentado pelo ONLYOFFICE. Use a chave de fragmentação documentada do aplicativo ao criar uma implantação da API de Documentação em vários nós.

Lista de verificação da configuração final

• Cada servidor de documentos retorna trueo estado /healthcheckanterior à sua adição ao HAProxy.
• O HAProxy é executado em modo HTTP para o frontend e backend do ONLYOFFICE.
• O HTTPS é encerrado com um certificado válido para o nome de host público do Servidor de Documentos.
• X-Forwarded-Protoe X-Forwarded-Hostsão encaminhadas corretamente.
• O tempo limite do túnel WebSocket é suficientemente longo para sessões de edição reais.
• As verificações de integridade do backend removem os nós com falha do serviço.
• O tráfego da API Docs em vários nós usa shardkeyafinidade baseada em , e não apenas o método round-robin simples.
• As implementações WOPI usam roteamento apropriado para WOPISrc.
• A verificação de saúde pública funciona e um documento real pode ser aberto, editado e salvo por meio da integração.

Para um único servidor de documentos, o HAProxy funciona principalmente como um proxy reverso limpo e uma camada TLS. Para vários nós de servidor de documentos, a diferença crucial reside no roteamento orientado a documentos. Construa o proxy em torno desse requisito primeiro e, em seguida, adicione verificações de integridade, HTTPS e ajustes de tempo limite.