Eseguire Collabora Online su nodi Kubernetes

Per una distribuzione Collabora Online multi-nodo, utilizza il grafico Helm di Collabora per Kubernetes dietro un ingress o un reverse proxy che mantenga ogni richiesta per lo stesso documento sullo stesso pod di Collabora. Questa affinità di sessione è essenziale: il bilanciamento round-robin tradizionale può inviare le richieste di modifica e di copia negli appunti di un utente a pod diversi, interrompendo la modifica collaborativa. L'esempio seguente utilizza tre repliche, NGINX Ingress e un numero fisso di repliche; sostituisci i nomi host e il segreto TLS dell'esempio con i tuoi.

Di cosa hai bisogno prima di aggiungere le repliche?

È necessario un cluster Kubernetes in esecuzione con almeno due nodi worker, Helm, un controller ingress che supporti la regola di affinità richiesta, un nome DNS come office.example.come un certificato TLS per tale nome. Nextcloud deve essere raggiungibile da ciascun pod di Collabora al suo URL pubblico di origine WOPI, ad esempio https://cloud.example.com. CODE e Nextcloud sono servizi separati; questa guida configura il livello Collabora e quindi collega il suo URL pubblico a Nextcloud Office.

Utilizza la configurazione multi-replica documentata del chart di Collabora anziché posizionare diversi container Docker indipendenti dietro un bilanciatore di carico generico. Un bilanciatore di carico che distribuisce ogni richiesta senza tenere conto della sorgente WOPI del documento può interrompere le sessioni. Questa guida segue le istruzioni ufficiali del chart Helm di Collabora disponibili il 10 ottobre 2026. I valori del chart possono cambiare, quindi verifica i valori per la versione esatta del chart che intendi installare.

1. Configurare le repliche, l'affinità di ingresso e l'host WOPI

Aggiungi il repository del grafico, aggiorna il suo indice e controlla le impostazioni predefinite correnti del grafico prima di scrivere il file di override:

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

Crea my_values.yamlcon le impostazioni di base riportate di seguito. L'esempio utilizza l'annotazione NGINX Ingress mostrata nel file README del grafico di Collabora. Esegue l'hashing in WOPISrcmodo che le richieste associate a un documento raggiungano lo stesso pod. Inoltre, termina il TLS pubblico all'ingresso; le impostazioni del server Collabora mostrate si riferiscono a questo modello di TLS terminato tramite 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

La aliasgroupsvoce da inserire è l'host WOPI di Nextcloud, non il nome host di Collabora. Assicurati di utilizzare lo schema, il nome host e la porta esatti forniti da Nextcloud. Il segreto TLS di ingresso deve esistere nello spazio dei nomi di ingresso e contenere un certificato valido office.example.com. Se la terminazione TLS avviene altrove, segui il modello proxy corrispondente nella documentazione del grafico anziché copiare extra_paramsciecamente i due flag.

Esiste un'avvertenza relativa all'autoscaling che dipende dalla versione: l'esempio nel file README del grafico disattiva l'autoscaling e avverte che il ridimensionamento può interferire con la modifica collaborativa e le operazioni di copia/incolla, mentre il file dei valori attualmente pubblicato ha l'autoscaling abilitato per impostazione predefinita. Per un cluster iniziale prevedibile, disabilitarlo esplicitamente e scegliere un numero fisso di repliche. Riconsiderare l'autoscaling solo dopo aver verificato le indicazioni specifiche della versione del grafico e aver testato il ridimensionamento in aumento e in diminuzione con sessioni di modifica reali.

2. Installare il grafico e verificare il posizionamento del pod

Installa il chart in un namespace dedicato. Il repository ufficiale dei chart documenta questo schema di comando:

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

Verifica quindi che il deployment abbia raggiunto il numero di repliche desiderato e controlla quali nodi worker ospitano i pod:

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

Verifica che tutti e tre i pod siano pronti, che l'ingress abbia l'host previsto e che le repliche siano distribuite sui nodi worker se è richiesta la resilienza a livello di nodo. Il solo conteggio delle repliche non garantisce che Kubernetes posizioni i pod su nodi separati. Il modello di chart ufficiale espone le impostazioni di selezione del nodo, affinità e tolleranza; configura le regole di pianificazione appropriate per il tuo cluster e convalida il chart generato prima di farvi affidamento. Se la tua versione del chart non espone la policy di cui hai bisogno, utilizza un'estensione del chart supportata o una personalizzazione del deployment di Kubernetes anziché presumere che i pod siano distribuiti.

3. Connetti Nextcloud e verifica l'affinità del documento

In Nextcloud, installa o abilita l' app Nextcloud Office , quindi apri le impostazioni di amministrazione → Office . Seleziona il server Collabora esterno e inserisci l'URL https://office.example.comdel server. L'URL del server è l'endpoint TLS pubblico raggiungibile sia dal server Nextcloud che dai browser degli utenti; non inserire un indirizzo IP del pod o un indirizzo di servizio interno.

Apri un file DOCX o ODT di prova da Nextcloud. Modificalo da due sessioni utente separate e verifica che entrambi gli utenti visualizzino le modifiche. Controlla anche gli strumenti per sviluppatori del browser o i log di Ingress per eventuali errori WebSocket; Ingress deve mantenere aperta la connessione di lunga durata dell'editor. Se le richieste di un file sono distribuite su più pod, verifica che il WOPISrcparametro di query sia presente nel punto in cui Ingress applica la regola hash e che il controller Ingress installato rispetti l'annotazione.

Che cosa dimostra un cluster sano?

Un test riuscito conferma che Nextcloud può raggiungere l'endpoint di Collabora e che un documento può essere modificato tramite l'ingress configurato. Non dimostra, tuttavia, che ogni sessione attiva sopravviva a un errore del pod o del nodo. Lo stato di modifica viene gestito dal pod che serve quel documento, quindi un errore potrebbe richiedere agli utenti di riconnettersi o riaprire un file anche se altre repliche rimangono disponibili. Testa gli scenari di manutenzione e di errore con documenti non critici e pianifica gli aggiornamenti in modo che le sessioni WebSocket di lunga durata vengano gestite in modo appropriato.

Per la sintassi e le avvertenze aggiornate, consultare il file README e i valori ufficiali del chart Helm di Kubernetes di Collabora , il file dei valori del chart pubblicato e il manuale di configurazione di Nextcloud Office . Verificare le impostazioni rispetto alla versione del chart installata, poiché gli esempi e i valori predefiniti del repository potrebbero non essere identici.