Execute o Collabora Online em vários nós do Kubernetes

Para uma implementação do Collabora Online com vários nós, utilize o gráfico Helm do Kubernetes do Collabora por trás de um Ingress ou proxy reverso que mantenha todas as solicitações para o mesmo documento no mesmo pod do Collabora. Essa afinidade de sessão é essencial: o balanceamento round-robin comum pode enviar as solicitações de edição e de área de transferência de um usuário para pods diferentes e interromper a edição colaborativa. O exemplo abaixo utiliza três réplicas, um Ingress NGINX e um número fixo de réplicas; substitua os nomes de host e o segredo TLS do exemplo pelos seus próprios.

O que você precisa antes de adicionar réplicas?

Você precisa de um cluster Kubernetes em execução com pelo menos dois nós de trabalho, Helm, um controlador de entrada que suporte a regra de afinidade necessária, um nome DNS como `<nome_do_nome_de_usuário>` office.example.come um certificado TLS para esse nome. O Nextcloud deve ser acessível por cada pod do Collabora em sua origem WOPI pública, por exemplo, `<origem_WOPI>` https://cloud.example.com. CODE e Nextcloud são serviços separados; este guia configura a camada do Collabora e, em seguida, conecta seu URL público ao Nextcloud Office.

Utilize a configuração de múltiplas réplicas documentada do gráfico Collabora em vez de colocar vários contêineres Docker independentes atrás de um balanceador de carga genérico. Um balanceador de carga que distribui cada solicitação sem levar em consideração a origem WOPI do documento pode interromper as sessões. Este guia segue as instruções oficiais do gráfico Helm do Collabora, disponíveis em 10 de outubro de 2026. Os valores do gráfico podem mudar, portanto, verifique os valores da versão exata do gráfico que você planeja instalar.

1. Configure as réplicas, a afinidade de entrada e o host WOPI.

Adicione o repositório de gráficos, atualize seu índice e inspecione as configurações padrão atuais do gráfico antes de escrever seu arquivo de personalização:

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

Crie my_values.yamlcom as configurações principais abaixo. O exemplo usa a anotação NGINX Ingress mostrada no README do gráfico da Collabora. Ela utiliza um hash para WOPISrcque as solicitações vinculadas a um documento cheguem ao mesmo pod. Ela também encerra o TLS público no ponto de entrada; as configurações do servidor Collabora mostradas são para esse padrão de TLS com proxy.

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
  tls:
    - secretName: office-example-tls
      hosts:
        - office.example.com

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

A aliasgroupsentrada é o host WOPI do Nextcloud, não o nome do host do Collabora. Mantenha-a restrita e use o esquema, o nome do host e a porta exatos apresentados pelo Nextcloud. O segredo TLS de entrada deve existir no namespace de entrada e conter um certificado válido para < nome do host office.example.com>. Se o TLS terminar em outro lugar, siga o padrão de proxy correspondente na documentação do gráfico em vez de copiar os dois extra_paramsparâmetros cegamente.

Existe uma ressalva importante sobre o dimensionamento automático, que varia conforme a versão: o exemplo no README do gráfico desativa o dimensionamento automático e alerta que ele pode interromper a edição colaborativa e o copiar/colar, enquanto o arquivo de valores publicado atualmente tem o dimensionamento automático ativado por padrão. Para um cluster inicial previsível, desative-o explicitamente e escolha um número fixo de réplicas. Reavalie o dimensionamento automático somente após verificar as orientações da versão específica do gráfico e testar o aumento e a redução de escala com sessões de edição reais.

2. Instale o gráfico e verifique o posicionamento do pod.

Instale o gráfico em um namespace dedicado. O repositório oficial de gráficos documenta esse padrão de comando:

helm install --create-namespace \
  --namespace collabora \
  collabora-online collabora/collabora-online \
  -f my_values.yaml

Em seguida, verifique se a implantação atingiu o número desejado de réplicas e veja quais nós de trabalho hospedam os pods:

kubectl get pods -n collabora -o wide
kubectl get ingress -n collabora
helm status collabora-online -n collabora

Confirme se todos os três pods estão prontos, se o Ingress está configurado com o host esperado e se as réplicas estão distribuídas entre os nós de trabalho, caso seja necessária resiliência em nível de nó. A contagem de réplicas por si só não garante que o Kubernetes alocará os pods em nós separados. O modelo de gráfico oficial expõe as configurações de seleção de nó, afinidade e tolerância; configure regras de agendamento adequadas para o seu cluster e valide o gráfico gerado antes de utilizá-las. Se a versão do seu gráfico não expõe a política necessária, use uma extensão de gráfico compatível ou uma personalização de implantação do Kubernetes em vez de presumir que os pods estão distribuídos.

3. Conecte o Nextcloud e verifique a afinidade do documento.

No Nextcloud, instale ou habilite o aplicativo Nextcloud Office e, em seguida, abra Configurações de administração → Office . Selecione o servidor Collabora externo e insira o https://office.example.comendereço do servidor. O URL do servidor é o endpoint TLS público que tanto o servidor Nextcloud quanto os navegadores dos usuários podem acessar; não insira um endereço IP de pod ou um endereço de serviço interno.

Abra um arquivo DOCX ou ODT de teste no Nextcloud. Edite-o a partir de duas sessões de usuário separadas e confirme se ambos os usuários visualizam as alterações. Verifique também as ferramentas de desenvolvedor do navegador ou os logs do Ingress em busca de erros de WebSocket; o Ingress deve manter a conexão de longa duração do editor aberta. Se as solicitações de um arquivo estiverem distribuídas entre vários pods, verifique se o WOPISrcparâmetro de consulta está presente onde o Ingress aplica a regra de hash e se o controlador Ingress instalado respeita a anotação.

O que comprova um cluster saudável?

Um teste bem-sucedido confirma que o Nextcloud consegue alcançar o endpoint do Collabora e que um documento pode ser editado através do ingress configurado. Isso não comprova que todas as sessões ativas sobrevivem a uma falha de pod ou nó. O estado de edição é gerenciado pelo pod que serve o documento, portanto, uma falha pode exigir que os usuários se reconectem ou reabram o arquivo, mesmo que outras réplicas permaneçam disponíveis. Teste cenários de manutenção e falha com documentos não críticos e planeje atualizações de forma que as sessões WebSocket de longa duração sejam gerenciadas de maneira adequada.

Para obter informações sobre a sintaxe atual e possíveis problemas, consulte o README e os valores do gráfico Helm do Kubernetes oficial da Collabora , o arquivo de valores do gráfico publicado e o manual de configuração do Office do Nextcloud . Verifique as configurações em relação à versão do gráfico que você instalar, pois os exemplos e os valores padrão do repositório podem não ser idênticos.