Quando Collabora Online segnala la chiusura imprevista di una connessione socket, verificare innanzitutto se la richiesta WebSocket del browser passa coolwsdattraverso il proxy inverso. Impostare il percorso del proxy in modo che corrisponda alla versione di Collabora, mantenere l'aggiornamento WebSocket e il percorso URL, quindi testare un documento monitorando il pannello Rete del browser e i log del server. Se il problema è iniziato dopo un aggiornamento a CODE 26.04 dietro Apache, verificare ProxyPassprima le regole di Apache: le note di rilascio di Collabora 26.04 menzionano una modifica per l'URL WebSocket compatto.
Un WebSocket è la connessione bidirezionale e persistente che Collabora utilizza tra il browser e il suo server mentre un documento è aperto. Un reverse proxy è il servizio che accetta la richiesta pubblica e la inoltra a Collabora. Il messaggio di errore fa riferimento a tale connessione, ma non dimostra che il proxy ne sia la causa; anche un host WOPI rifiutato, un URL pubblico errato, una mancata corrispondenza TLS o un backend errato possono interrompere la sessione.
Annota la versione o il tag dell'immagine di Collabora, il software proxy, il nome host pubblico di Collabora e se la connessione TLS termina sul proxy o su Collabora. Verifica il nome del servizio e l'immagine corrente senza modificare la distribuzione:
docker compose ps collabora
docker compose images collaboraSostituisci collaboracon il nome del servizio nel tuo file Compose. Per un container non Compose, usa docker pse docker inspectper identificare il container e l'immagine. Non dare per scontato che il latesttag punti ancora alla stessa versione che hai testato la settimana scorsa.
Nel browser, apri gli Strumenti per sviluppatori, seleziona Rete , filtra per WS o WebSocket e prova ad aprire nuovamente un documento. L'URL della richiesta dovrebbe essere utilizzato wss://quando la pagina pubblica è HTTPS. Seleziona la richiesta non riuscita e annota il suo stato, il percorso URL e le intestazioni di risposta. Un handshake riuscito in genere restituisce un valore 101 Switching Protocolse rimane aperto finché la sessione del documento è attiva.
coolwsdla dicitura "Richiesta non valida o sconosciuta" può significare che la richiesta ha raggiunto Collabora con un percorso non accettato.Utilizza le impostazioni di reverse proxy correnti di Collabora per il software proxy e la versione in uso. Verifica che il percorso WebSocket venga gestito come un WebSocket, che il proxy inoltri le intestazioni di aggiornamento e che preservi il percorso e la stringa di query codificata anziché reindirizzarli o riscriverli. Il proxy deve inoltre inviare l'host pubblico e lo schema in modo coerente con il nome del server esterno e le impostazioni di terminazione TLS configurate in Collabora.
Per Nginx, esamina la posizione specifica per WebSocket e le relative direttive HTTP/1.1 Upgradee Connectiondi inoltro nell'esempio corrente di Collabora. Per Apache, confronta la ProxyPassregola e l'ordine con l'esempio corrente; non incollare una vecchia /cool/…/wscorrispondenza senza verificarne le specifiche richieste dalla versione installata.
Questo controllo della versione è importante per CODE 26.04. Le note di rilascio di Collabora, pubblicate l'8 giugno 2026, descrivono un URL WebSocket più compatto e indicano che gli utenti di proxy inverso Apache devono adattarsi ProxyPassdi conseguenza. Successivamente, nella versione 26.04 è stato aggiunto un comportamento di fallback per gli URL legacy, quindi una regola precedente potrebbe ancora funzionare su alcune build; il report di Collabora relativo alla risoluzione del problema WebSocket nella versione 26.04 documenta questo aggiornamento. Il fallback non sostituisce la necessità di adattare la configurazione del proxy corrente alla versione installata. Si consiglia di leggere insieme le note di rilascio di CODE 26.04 e l'esempio SDK aggiornato.
Avvia un breve flusso di log prima di riprovare il documento. L'opzione di Docker --sincelimita l'output iniziale, mentre --followi flussi di nuove righe; vedi la documentazione di riferimento sui log di Docker Compose .
docker compose logs --since=2m --follow collaboraAnnota l'ora del test e cerca la stessa richiesta nei log di Collabora e del proxy. Se il browser richiede un percorso che il proxy instrada al backend errato, aggiorna solo quella rotta WebSocket utilizzando l'esempio di Collabora corrispondente alla versione. Se la richiesta raggiunge Collabora ma l'host, l'origine o lo schema vengono rifiutati, confronta il nome host pubblico e la porta con il nome del server configurato e le intestazioni inoltrate. Se invece il log mostra un rifiuto dell'host WOPI o una richiesta di informazioni sul file non riuscita, verifica l'host consentito del server di integrazione e la sua raggiungibilità dal container di Collabora; questo è un passaggio separato dall'handshake WebSocket del browser.
Riavvia il proxy dopo averne convalidato la configurazione con il comando di verifica della sintassi del proxy stesso. Evita di modificare contemporaneamente la terminazione TLS, le liste di host consentiti e le riscritture URL: la modifica di una causa per test rende il risultato successivo interpretabile. Non disattivare la verifica TLS né consentire tutti gli host WOPI come scorciatoia.
Riprova con lo stesso documento. Negli Strumenti per sviluppatori, verifica che la richiesta WebSocket venga risposta 101 Switching Protocolse rimanga aperta. Verifica che il documento si carichi completamente, rimanga connesso e accetti una piccola modifica che venga salvata correttamente. Un corretto stato della connessione non è sufficiente se l'accesso o il salvataggio del file WOPI continuano a fallire.
Se l'handshake continua a fallire, confronta il percorso della richiesta del browser, la riga di accesso/errore del proxy e la corrispondente coolwsdvoce di registro allo stesso timestamp. Questo confronto a tre punti mostra se il browser, il proxy, il percorso di Collabora o l'host WOPI sono i prossimi elementi da esaminare. Quando richiedi assistenza, oscura i token di accesso, gli identificativi dei documenti, i nomi utente e i nomi host privati sia dai dettagli del browser che dai log.
Distribuisci repliche di Collabora CODE con Helm, mantieni ogni documento su un singolo pod tramite l'affinità WOPI e verifica l'ingress, il posizionamento dei nodi e la modifica su Nextcloud.
Traccia un handshake socket non riuscito dal browser a coolwsd, quindi abbina il percorso del reverse proxy alla tua versione di Collabora, inclusa la modifica Apache CODE 26.04.
Traccia gli errori di WOPI di Collabora dovuti a chiavi non corrispondenti, dati di rilevamento obsoleti, deriva dell'orologio o modifiche all'URL del proxy, senza indebolire la convalida.
Reimposta lo zoom del browser, testa una sessione pulita e identifica quando un menu di dimensioni non corretto richiede un aggiornamento del server Collabora.
Implementa Collabora CODE con Docker, connettilo in modo sicuro a Nextcloud Office e verifica la modifica dei documenti con pratici controlli WOPI e proxy.
Attivare temporaneamente la modalità di debug di coolwsd, acquisire un'apertura non riuscita e utilizzare la sequenza di log per separare i problemi relativi a WebSocket, WOPI, proxy e container.
Configura l'accesso amministrativo a Collabora Online per Docker o Linux, riavvia il servizio appropriato e verifica la nuova password senza esporla.
Prima di modificare le impostazioni di Collabora o riavviare il servizio, verifica se il carico della CPU deriva da documenti attivi, processi worker inattivi o capacità del server.
Verifica se Docker sta imponendo un limite a Collabora CODE, aumenta in modo sicuro il limite di memoria di Compose e conferma che il container in esecuzione abbia ricevuto il nuovo limite.
Semplifica Collabora CODE con la modalità Compatta o a schede e i controlli WOPI PostMessage per nascondere in modo sicuro pulsanti, comandi e schede selezionati.
