Come configurare un cluster Collabora Online con più nodi

Un cluster Collabora Online non è semplicemente costituito da diversi coolwsdserver funzionanti dietro un bilanciatore di carico round-robin. La modifica collaborativa si basa sull'invio delle richieste per lo stesso documento allo stesso nodo Collabora. WOPISrcPer questo motivo, il chart Kubernetes di Collabora documenta il routing tramite l'identificativo del documento WOPI. Questa guida utilizza il chart Helm di Collabora su Kubernetes come configurazione multi-nodo concreta e indica cosa deve essere modificato per un diverso controller di ingresso o per un'implementazione non Kubernetes.

Verificato: il grafico di Collabora supporta più repliche e descrive l'affinità per documento utilizzando WOPISrc. Dipendente dalla distribuzione: annotazioni ingress, terminazione TLS, richieste di risorse e se un controller di sessione è appropriato. Non è sicuro presumere: che qualsiasi bilanciatore di carico o ogni impostazione di "sessione persistente" preservi l'affinità del documento. Confermare il comportamento specifico del controller e testarlo prima di spostare gli utenti sul cluster.

Cosa fa il cluster e cosa non fa

In una distribuzione multi-replica standard, ogni nodo Collabora può gestire i documenti, mentre un proxy instrada le richieste di ciascun documento a un nodo specifico. Questo distribuisce i singoli documenti nell'intero pool. Ciò non significa che ogni nodo condivida lo stesso processo di modifica in tempo reale o che un documento in esecuzione possa essere sempre spostato senza interruzioni se il nodo a cui è associato si arresta.

Collabora documenta anche un COOL Controller per Kubernetes che aggiunge un approccio diverso alla gestione delle sessioni. Il suo routing e la sua configurazione differiscono da un pool di repliche autonomo. Questo articolo configura il modello di affinità sorgente WOPI più semplice; non combinarlo con le impostazioni del token di routing specifiche del controller a meno che non si sia già distribuito e configurato il Controller per la propria release.

Azione: decidi se hai bisogno di un servizio Collabora replicato di base per la capacità e la ridondanza dei nodi, oppure di una configurazione gestita da un controller con comportamento basato sulla sessione. Quest'ultima prevede componenti aggiuntivi e una configurazione specifica per la versione. Consulta la panoramica di Collabora Online Controller se stai valutando questa opzione.

Prima di implementare

• Un cluster Kubernetes funzionante, Helm, DNS per un hostname pubblico di Collabora e un proxy in entrata o inverso compatibile con TLS.
• Un'integrazione WOPI come Nextcloud, configurata per utilizzare il singolo hostname pubblico di Collabora anziché i singoli indirizzi dei pod.
• L'host o gli host WOPI che Collabora è autorizzato ad accettare, inseriti nella collabora.aliasgroupsconfigurazione del chart.
• CPU e memoria sufficienti per il carico di lavoro dei documenti, oltre a un modo per ispezionare lo stato di salute dei pod, i log di ingresso e l'utilizzo delle risorse.
• Una finestra di manutenzione per il lancio iniziale e un documento di prova con due account utente separati.

Un servizio Collabora Online dedicato è diverso dal server CODE integrato di Nextcloud. Nextcloud descrive la sua opzione integrata come pensata per uso personale o piccoli team e priva delle funzionalità di scalabilità avanzate di un server dedicato. Azione: se hai bisogno di un pool Collabora multi-nodo, pianifica il servizio dedicato e verifica il modello di licenza e supporto più adatto alla tua implementazione. Consulta la guida all'installazione di Nextcloud Office .

Passaggio 1: Scegliere il modello di routing

Il modello standalone documentato esegue l'hashing su WOPISrc, che identifica il documento nelle richieste WOPI. Le richieste per un documento devono raggiungere lo stesso pod; le richieste per documenti diversi possono essere distribuite tra i pod. Una regola round-robin generica non soddisfa questo requisito.

Azione: utilizzare un'implementazione ingress supportata dalla documentazione del chart, come gli esempi di ingress documentati per NGINX o HAProxy, oppure utilizzare il reverse proxy in-namespace del chart laddove il cluster non consenta un controller ingress adeguato. Se si utilizza un altro proxy, verificare che sia in grado di instradare in modo coerente le richieste provenienti dalla sorgente WOPI sia per le normali richieste HTTP che per le connessioni WebSocket a lunga durata.

Passaggio 2: Esamina il grafico e seleziona una versione

Il grafico e i relativi valori cambiano nel tempo. Prima dell'installazione, consultare il file README ufficiale del grafico e i relativi valori, anziché copiare una configurazione scritta per una versione precedente. Gli esempi seguenti si basano sulla documentazione del grafico di Collabora aggiornata al 6 ottobre 2026; considerare le note di rilascio e i valori correnti del repository come autorevoli per la data di installazione.

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

Azione: scegli una versione del chart compatibile con la tua policy di controllo delle modifiche e annota la versione dell'immagine di Collabora che viene distribuita. Blocca la versione del chart per garantire aggiornamenti ripetibili; evita di utilizzare una versione fluttuante non verificata in produzione. La guida di configurazione del chart è il file README di Collabora Online per Kubernetes .

Passaggio 3: Preparare i valori per tre repliche

Questo esempio presuppone l'utilizzo di NGINX Ingress Controller, la terminazione TLS all'ingresso e un host WOPI esterno all'indirizzo cloud.example.com. Sostituisci entrambi i nomi host con i tuoi. Se la terminazione TLS avviene altrove o se utilizzi HAProxy, usa la configurazione corrispondente e documentata di tale controller.

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

I valori di annotazione hash e timeout sopra riportati sono mostrati nell'esempio NGINX del grafico. La extra_paramsriga è appropriata solo quando il proxy inverso termina TLS e si connette a Collabora tramite HTTP. Non applicarla senza modifiche se la topologia TLS è diversa. Configura il segreto TLS di ingresso e l'host in base al tuo gestore di certificati e ai valori del grafico locale; l'estratto omette queste impostazioni specifiche del provider.

Azione: salva questo file come my_values.yaml, aggiungi la configurazione TLS richiesta dal tuo ingresso e confronta ogni chiave con quella della versione del grafico selezionata values.yaml. Mantieni coerente l'hostname pubblico di Collabora tra DNS, TLS, l'URL di Collabora dell'integrazione e il routing del proxy.

Passaggio 4: Installare la versione Collabora

Installare in uno spazio dei nomi dedicato. Sostituire <chart-version>con la versione selezionata nel passaggio 2; le parentesi angolari qui sono segnaposto esplicativi e non devono essere digitate letteralmente.

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

Per una release esistente, utilizza un aggiornamento Helm pianificato dopo aver verificato le note di migrazione della release e le modifiche renderizzate. Evita di implementare un aggiornamento importante dell'immagine o del chart contemporaneamente alla prima modifica di scalabilità; modificare una variabile alla volta semplifica l'isolamento dei problemi.

Azione: ispeziona la release e attendi che tutte le repliche siano pronte:

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

La presenza di tre repliche desiderate non è una prova sufficiente che tre nodi funzionanti stiano gestendo il traffico. Verificare la disponibilità, i riavvii recenti, la pianificazione e gli endpoint di ingresso. Se i pod risultano ancora in stato di attesa, esaminare la capacità disponibile del cluster e le richieste e i limiti delle risorse nei valori del grafico.

Passaggio 5: Connetti l'applicazione WOPI

Nelle impostazioni di integrazione con Office della piattaforma file, imposta l'URL del server Collabora sull'endpoint pubblico, ad esempio https://office.example.com. Non indirizzare l'applicazione a un IP di pod o a un nome di servizio specifico di Kubernetes a meno che l'integrazione stessa non venga eseguita all'interno del cluster e il routing privato non sia esplicitamente supportato dalla tua progettazione.

Il nome host aliasgroupsdeve identificare l'host WOPI che archivia e distribuisce i documenti; non è il nome host di Collabora. Una mancata corrispondenza può causare errori di convalida dell'host WOPI anche quando i pod di Collabora e l'ingress sono integri.

Azione: inserisci lo stesso URL pubblico di Collabora nella configurazione dell'integrazione, salvala e verifica che la connettività o il controllo di rilevamento abbiano esito positivo. In caso di esito negativo, controlla l'elenco di elementi consentiti WOPI dell'applicazione, i gruppi di alias di Collabora, DNS, TLS e le intestazioni proxy prima di modificare il numero di repliche.

Passaggio 6: Verifica l'affinità e la collaborazione sui documenti

Apri un documento di prova e controlla i log di ingresso o del proxy per confermare quale backend lo gestisce. Quindi apri lo stesso documento da una seconda sessione utente e verifica che entrambi gli utenti possano modificarlo e visualizzare le modifiche reciproche. Apri un documento diverso e conferma che il bilanciatore di carico possa inviarlo a un altro pod funzionante. Il test riguarda il routing e la collaborazione, non solo la verifica che la pagina di destinazione restituisca un codice HTTP 200.

Azione: verificare che l'hash della sorgente WOPI sia presente e applicato in modo coerente alle richieste generate per lo stesso documento, incluso l'aggiornamento WebSocket. Se gli utenti non visualizzano le modifiche reciproche, confrontare la selezione del backend per lo stesso documento prima di esaminare l'host WOPI o la cache del browser.

Passaggio 7: Testare la gestione dello stato di salute e la perdita dei nodi

I controlli di disponibilità dovrebbero impedire la messa in servizio di un pod non integro o in fase di avvio. Il grafico include le impostazioni di avvio, disponibilità e monitoraggio della vitalità, ma il comportamento e la tempistica esatti dipendono dalla versione del grafico e dal cluster selezionati. L'indisponibilità di un pod può interrompere i documenti attualmente in esecuzione su tale pod; un pool di affinità di base non deve essere descritto come replica di sessione live.

Azione: in un ambiente di test, rimuovere un pod dal servizio durante una sessione di modifica attiva, osservare il comportamento del client e il routing del proxy, quindi riaprire il documento e verificare che raggiunga un pod funzionante. Non eseguire questo test su documenti di produzione attivi senza un piano di manutenzione approvato. Per una continuità di sessione più rigorosa, valutare COOL Controller e la sua configurazione del token di routing specifica per la versione.

Passaggio 8: Monitorare, ottimizzare e aggiornare in modo mirato

Monitora i riavvii dei pod, l'utilizzo di CPU e memoria, gli errori di richiesta e WebSocket, la latenza di ingresso e le segnalazioni degli utenti relative al caricamento o alla riconnessione dei documenti. La documentazione dei grafici di Collabora include indicazioni sul monitoraggio di Kubernetes. Imposta le risorse in base al carico di lavoro osservato anziché copiare i valori di esempio: le dimensioni dei documenti, le sessioni simultanee, i font e le modalità di modifica influiscono sulla capacità.

Collabora consiglia di eseguire la stessa versione su tutti i nodi con bilanciamento del carico, in modo che i client ricevano risorse web coerenti e specifiche per la versione. Durante gli aggiornamenti, utilizzare la strategia di implementazione supportata dal chart, monitorare lo stato di preparazione e i log e testare un documento aperto da più utenti prima di dichiarare la modifica completata.

Azione: conservare insieme la versione del grafico, la versione dell'immagine, il file dei valori e i risultati dei test nel record delle modifiche. Pianificare gli aggiornamenti, verificare che tutte le repliche convergano sulla versione prevista e mantenere un piano di rollback compatibile con il comportamento di rollback supportato dal grafico.

Idee sbagliate comuni da verificare

• "Tre repliche creano automaticamente un cluster funzionante." Le sole repliche non configurano l'affinità dei documenti. Verificare che gli hash in ingresso sulla sorgente WOPI o che il controller fornisca il routing di sessione previsto siano corretti.
• "Le sessioni persistenti basate sull'indirizzo IP dell'utente sono sufficienti." Questa non è la regola descritta dal diagramma di Collabora per il suo pool Kubernetes standalone. Gli utenti che collaborano su un documento devono convergere sullo stesso nodo anche se si connettono da dispositivi o reti diversi. Configurate l'affinità basata sul documento ed eseguite un test con due utenti.
• "Una homepage funzionante dimostra che il cluster è pronto." Dimostra solo che una richiesta HTTP è andata a buon fine. Testa l'apertura e la modifica collaborativa di un documento, gli aggiornamenti WebSocket e il comportamento quando un pod diventa non disponibile.
• "L'aggiunta di un nodo garantisce che le sessioni attive sopravvivano alla perdita del nodo." Un pool di affinità di origine WOPI di base instrada un documento a un nodo; non stabilisce che il suo processo di modifica in memoria venga replicato. Confermare il comportamento di ripristino previsto in un test controllato o valutare le funzionalità separate di gestione delle sessioni del Controller.

Per le installazioni non Kubernetes, il principio architetturale è lo stesso, ma i comandi del chart di Kubernetes e le annotazioni di ingress non si applicano. Utilizza la configurazione proxy per la tua versione di Collabora e il bilanciatore di carico, assicurati che siano supportate le connessioni WebSocket a lunga durata e implementa il routing per documento utilizzando la sorgente WOPI. Il manuale di Collabora Online SDK descrive il bilanciamento del carico e i WOPISrcrequisiti di affinità; verifica la sezione equivalente nel manuale per la versione in uso.