Como configurar um cluster do Collabora Online com vários nós

Um cluster do Collabora Online não se resume a vários coolwsdservidores íntegros atrás de um balanceador de carga round-robin. A edição colaborativa depende do envio de solicitações para o mesmo documento ao mesmo nó do Collabora. O gráfico do Kubernetes do Collabora documenta o roteamento pelo identificador de documento WOPI, ` WOPISrc<WOPI_DOCUMENT_ID>`, justamente por esse motivo. Este guia utiliza o gráfico Helm do Collabora no Kubernetes como uma configuração concreta com vários nós e indica o que precisa ser alterado para um controlador de entrada diferente ou uma implantação que não seja em Kubernetes.

Verificado: o gráfico do Collabora suporta múltiplas réplicas e descreve a afinidade por documento usando WOPISrc. Dependente da implantação: anotações de entrada, terminação TLS, solicitações de recursos e se um controlador de sessão é apropriado. Não é seguro presumir: que qualquer balanceador de carga ou qualquer configuração de "sessão persistente" preservará a afinidade do documento. Confirme o comportamento específico do controlador e teste-o antes de mover usuários para o cluster.

O que o cluster faz — e o que ele não faz

Em uma implementação padrão com múltiplas réplicas, cada nó do Collabora pode servir documentos, enquanto um proxy envia as solicitações de cada documento para um nó específico. Isso distribui os documentos separadamente pelo conjunto de réplicas. Contudo, isso não significa que todos os nós compartilhem o mesmo processo de edição em tempo real, ou que um documento em execução possa sempre ser transferido sem interrupções caso o nó em que está sendo editado pare.

A Collabora também documenta um Controlador COOL para Kubernetes que adiciona uma abordagem diferente de gerenciamento de sessão. Seu roteamento e configuração diferem de um pool de réplicas independente. Este artigo configura o modelo de afinidade de origem WOPI mais simples; não o combine com configurações de token de rota específicas do controlador, a menos que você tenha implantado e configurado o Controlador para sua versão.

Ação: decida se você precisa de um serviço Collabora replicado básico para redundância de capacidade e nós, ou de uma configuração gerenciada por controlador com comportamento baseado em sessão. Esta última possui componentes adicionais e configuração específica da versão. Consulte a visão geral do Controlador do Collabora Online se estiver avaliando essa opção.

Antes de implantar

• Um cluster Kubernetes em funcionamento, Helm, DNS para um nome de host público da Collabora e um servidor de entrada ou proxy reverso compatível com TLS.
• Uma integração WOPI, como o Nextcloud, configurada para usar o nome de host público único do Collabora em vez de endereços de pods individuais.
• O(s) host(s) WOPI que o Collabora está autorizado a aceitar, inserido(s) na collabora.aliasgroupsconfiguração do gráfico.
• CPU e memória suficientes para a carga de trabalho do documento, além de uma maneira de inspecionar a integridade do pod, os logs de entrada e o uso de recursos.
• Uma janela de manutenção para a implementação inicial e um documento de teste com duas contas de usuário separadas.

Um serviço Collabora Online dedicado é diferente do servidor CODE integrado do Nextcloud. O Nextcloud descreve sua opção integrada como voltada para uso pessoal ou pequenas equipes e sem os recursos avançados de escalabilidade de um servidor dedicado. Ação: se você precisar de um pool Collabora com vários nós, planeje o serviço dedicado e confirme o modelo de licenciamento e suporte adequado para sua implementação. Consulte o guia de instalação do Nextcloud Office .

Passo 1: Escolha o modelo de roteamento

O modelo independente documentado utiliza um hash WOPISrcque identifica o documento nas requisições WOPI. Requisições para um mesmo documento devem chegar ao mesmo pod; requisições para documentos diferentes podem ser distribuídas entre pods. Uma regra genérica de rodízio não atende a esse requisito.

Ação: utilize uma implementação de entrada (ingress) compatível com a documentação do gráfico, como os exemplos documentados de entrada para NGINX ou HAProxy, ou utilize o proxy reverso no namespace do gráfico caso o cluster não permita um controlador de entrada adequado. Se utilizar outro proxy, verifique se ele consegue rotear consistentemente as requisições da origem WOPI, tanto para requisições HTTP comuns quanto para conexões WebSocket de longa duração.

Passo 2: Inspecione o gráfico e selecione uma versão.

O gráfico e seus valores mudam com o tempo. Antes de instalar, consulte o arquivo README oficial atual do gráfico e seus valores, em vez de copiar uma configuração escrita para uma versão anterior. Os exemplos abaixo seguem a documentação do gráfico Collabora atualizada em 6 de outubro de 2026; considere as notas de versão e os valores atuais do repositório como referência para a sua instalação.

helm repo add collabora https://collaboraonline.github.io/online/
helm repo update
helm search repo collabora/collabora-online --versions
helm show values collabora/collabora-online

Ação: escolha uma versão do gráfico que corresponda à sua política de controle de alterações e registre a versão da imagem do Collabora que ela implanta. Fixe a versão do gráfico para atualizações repetíveis; evite depender de uma versão flutuante não revisada em produção. O guia de configuração do gráfico está no README do Collabora Online para Kubernetes .

Etapa 3: Preparar valores para três réplicas

Este exemplo pressupõe o controlador de entrada NGINX, a terminação TLS na entrada e um host WOPI externo em cloud.example.com. Substitua ambos os nomes de host pelos seus próprios. Se a terminação TLS ocorrer em outro local ou se você usar o HAProxy, use a configuração documentada correspondente desse controlador.

replicaCount: 3

autoscaling:
  enabled: false

ingress:
  enabled: true
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/upstream-hash-by: "$arg_WOPISrc"
    nginx.ingress.kubernetes.io/proxy-body-size: "0"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "600"
  hosts:
    - host: office.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific

collabora:
  aliasgroups:
    - host: "https://cloud.example.com:443"
  extra_params: --o:ssl.enable=false --o:ssl.termination=true

A anotação de hash e os valores de tempo limite acima são mostrados no exemplo do NGINX no gráfico. A extra_paramslinha é apropriada somente quando o proxy reverso encerra o TLS e se conecta ao Collabora via HTTP. Não a aplique sem alterações se sua topologia TLS for diferente. Configure o segredo TLS de entrada e o host de acordo com o seu gerenciador de certificados e os valores do gráfico local; o trecho omite essas configurações específicas do provedor.

Ação: salve este arquivo como my_values.yaml, adicione a configuração TLS exigida pelo seu ingress e compare cada chave com a do gráfico selecionado values.yaml. Mantenha o nome de host público do Collabora consistente em DNS, TLS, URL do Collabora da integração e roteamento de proxy.

Etapa 4: Instale a versão do Collabora

Instale em um namespace dedicado. Substitua <chart-version>pela versão selecionada na Etapa 2; os colchetes angulares aqui são apenas marcadores explicativos e não devem ser digitados literalmente.

helm install --create-namespace   --namespace collabora   collabora-online collabora/collabora-online   --version <chart-version>   -f my_values.yaml

Para uma versão existente, utilize uma atualização planejada do Helm após verificar as notas de migração e as alterações renderizadas da versão. Evite implantar uma atualização principal de imagem ou gráfico ao mesmo tempo que sua primeira alteração de escala; alterar uma variável por vez facilita a identificação de falhas.

Ação: inspecione a liberação e aguarde até que todas as réplicas estejam prontas:

helm status collabora-online -n collabora
kubectl get pods,svc,ingress -n collabora
kubectl get events -n collabora --sort-by=.lastTimestamp

A presença de três réplicas desejadas não comprova que três nós íntegros estejam atendendo ao tráfego. Verifique a prontidão, reinicializações recentes, agendamento e endpoints de entrada. Se os pods permanecerem pendentes, inspecione a capacidade disponível do cluster e as solicitações e limites de recursos nos valores do gráfico.

Etapa 5: Conecte o aplicativo WOPI

Nas configurações de integração do Office na plataforma de arquivos, defina a URL do servidor Collabora para o endpoint público, por exemplo, `https://example.com/ https://office.example.comcolaboration/server`. Não aponte o aplicativo para um endereço IP de pod ou um nome de serviço exclusivo do Kubernetes, a menos que a própria integração seja executada dentro do cluster e o roteamento privado seja explicitamente suportado pelo seu projeto.

O nome do host aliasgroupsdeve identificar o host WOPI que armazena e fornece documentos; não é o nome do host do Collabora. Uma incompatibilidade pode causar falhas na validação do host WOPI, mesmo quando os pods e o ingress do Collabora estiverem íntegros.

Ação: insira a mesma URL pública do Collabora na configuração da integração, salve-a e verifique se a conectividade ou a verificação de descoberta foi bem-sucedida. Caso falhe, verifique a lista de permissões WOPI do aplicativo, os grupos de aliases do Collabora, o DNS, o TLS e os cabeçalhos de proxy antes de alterar a contagem de réplicas.

Etapa 6: Teste a afinidade e a colaboração entre documentos

Abra um documento de teste e inspecione os logs de entrada ou proxy para confirmar qual backend o está servindo. Em seguida, abra o mesmo documento a partir de uma segunda sessão de usuário e verifique se ambos os usuários podem editar e visualizar as alterações um do outro. Abra um documento diferente e confirme se o balanceador de carga consegue enviá-lo para outro pod íntegro. O teste visa avaliar o roteamento e a colaboração, e não apenas se a página inicial retorna o código HTTP 200.

Ação: verifique se o hash de origem WOPI está presente e é aplicado de forma consistente às solicitações geradas para o mesmo documento, incluindo a atualização do WebSocket. Se os usuários não visualizarem as edições uns dos outros, compare a seleção do backend para o mesmo documento antes de investigar o host WOPI ou o cache do navegador.

Etapa 7: Teste o gerenciamento de integridade e a perda de nós

As verificações de prontidão devem manter um pod com problemas ou em inicialização fora de serviço. O gráfico inclui configurações de inicialização, prontidão e sondagem de atividade, mas o comportamento e o tempo exatos dependem da versão do gráfico e do cluster selecionados. Um pod que se torna indisponível pode interromper documentos em execução nesse pod; um pool de afinidade básico não deve ser descrito como replicação de sessão em tempo real.

Ação: em um ambiente de teste, remova um pod do serviço durante uma sessão de edição ativa, observe o comportamento do cliente e o roteamento do proxy, depois reabra o documento e confirme se ele chega a um pod íntegro. Não execute este teste em documentos de produção ativos sem um plano de manutenção aprovado. Para uma continuidade de sessão mais rigorosa, avalie o Controlador COOL e sua configuração de token de rota específica da versão.

Etapa 8: Monitore, ajuste e atualize deliberadamente

Monitore reinicializações de pods, uso de CPU e memória, erros de requisição e WebSocket, latência de entrada e relatos de usuários sobre carregamento ou reconexão de documentos. A documentação de gráficos do Collabora inclui orientações para monitoramento do Kubernetes. Defina os recursos com base na carga de trabalho observada, em vez de copiar números de exemplo: tamanho do documento, sessões simultâneas, fontes e padrões de edição afetam a capacidade.

A Collabora recomenda executar a mesma versão em todos os nós com balanceamento de carga para que os clientes recebam recursos da web consistentes e específicos da versão. Durante as atualizações, use a estratégia de implantação compatível com o gráfico, monitore a prontidão e os registros e teste um documento aberto por vários usuários antes de declarar a alteração concluída.

Ação: mantenha a versão do gráfico, a versão da imagem, o arquivo de valores e os resultados dos testes juntos no seu registro de alterações. Agende atualizações, confirme se todas as réplicas convergem para a versão pretendida e mantenha um plano de reversão compatível com o comportamento de reversão suportado pelo gráfico.

Conceitos errôneos comuns a serem verificados

• “Três réplicas criam automaticamente um cluster funcional.” As réplicas por si só não configuram a afinidade de documentos. Confirme se os hashes de entrada estão na origem WOPI ou se o seu controlador fornece o roteamento de sessão pretendido.
• “Sessões persistentes baseadas no IP do usuário são suficientes.” Essa não é a regra descrita no gráfico da Collabora para seu pool Kubernetes independente. Usuários que colaboram em um documento devem convergir para o mesmo nó, mesmo que cheguem de dispositivos ou redes diferentes. Configure a afinidade baseada em documentos e teste com dois usuários.
• “Uma página inicial saudável comprova que o cluster está pronto.” Isso comprova apenas que uma requisição HTTP foi bem-sucedida. Teste a abertura e edição colaborativa de um documento, atualizações do WebSocket e o comportamento quando um pod fica indisponível.
• “Adicionar um nó garante que as sessões ativas sobrevivam à perda de um nó.” Um pool básico de afinidade de origem WOPI direciona um documento para um nó; ele não garante que seu processo de edição em memória seja replicado. Confirme o comportamento de recuperação esperado em um teste controlado ou avalie os recursos de gerenciamento de sessão separados do Controlador.

Para instalações que não utilizam Kubernetes, o princípio da arquitetura é o mesmo, mas os comandos de gráfico do Kubernetes e as anotações de entrada não se aplicam. Utilize a configuração de proxy para a sua versão do Collabora e balanceador de carga, assegure-se de que as conexões WebSocket de longa duração sejam suportadas e implemente o roteamento por documento utilizando a fonte WOPI. O manual do SDK do Collabora Online descreve o balanceamento de carga e o WOPISrcrequisito de afinidade; verifique a seção equivalente no manual para a versão que você utiliza.