Collabora Online può sembrare funzionare correttamente a prima vista, ma può comunque fallire non appena l'editor tenta di stabilire una connessione WebSocket attiva. Il sintomo più comune è un documento che inizia a caricarsi e poi segnala che la connessione socket si è chiusa inaspettatamente, a volte accompagnato da un errore wss://di richiesta nel browser. Nella versione 2026, prima di apportare qualsiasi altra modifica, è necessario verificare un motivo specifico: la versione 26.04 ha introdotto un URL WebSocket più compatto e le vecchie regole del reverse proxy potrebbero entrare in conflitto con esso.
Le note di rilascio ufficiali di Collabora CODE 26.04 affermano che CODE 26.04.1, rilasciato l'8 giugno 2026, richiedeva agli utenti del reverse proxy Apache2 di modificare la propria regola ProxyPass per il nuovo URL WebSocket compatto. Le successive note della versione 26.04.2.x indicano che CODE può ripiegare sull'URL precedente quando il nuovo percorso non può essere utilizzato ed emette un avviso di controllo che rimanda gli amministratori alle raccomandazioni proxy più recenti. Anche la versione enterprise di Collabora Online 26.04 è aggiornata nel 2026, quindi gli amministratori dovrebbero confrontare qualsiasi configurazione proxy copiata da una guida precedente (24.04 o 25.04) con la documentazione più recente del fornitore prima di considerare il problema come un guasto di rete casuale.
Il messaggio non identifica una singola causa principale. Significa che la connessione WebSocket tra il browser e Collabora non è mai stata aggiornata correttamente oppure è stata stabilita e poi terminata inaspettatamente. Questa distinzione è importante perché le soluzioni sono diverse.
| Comportamento osservato | Il primo controllo più utile | cause tipiche |
|---|---|---|
| Si verifica un errore immediato all'apertura di un documento. | Rete del browser > Registri di accesso/errore WS e proxy inverso | Percorso errato /cool/, intestazioni di aggiornamento mancanti, regola Apache incompatibile con la versione 26.04, mancata corrispondenza tra host e origine. |
| Funziona per un breve periodo, poi si disconnette a intervalli ripetibili. | Timeout di inattività per proxy, ingresso, bilanciamento del carico e firewall | Timeout troppo breve per un WebSocket di lunga durata |
| La scoperta funziona, ma la modifica fallisce. | Testare il WebSocket separatamente da/hosting/discovery | Gli endpoint HTTP sono raggiungibili mentre il percorso WebSocket non lo è |
| Solo un browser o un percorso di rete non funziona | Confronta il protocollo di richiesta e il comportamento del proxy. | Gestione di HTTP/2 o HTTP/3, inoltro CONNECT, filtraggio intermedio |
| Il registro del server rifiuta esplicitamente l'aggiornamento. | Leggi l'errore esatto di coolwsd | Mancata corrispondenza di origine, host, porta, host WOPI o configurazione proxy. |
Se il problema si è presentato immediatamente dopo l'aggiornamento dalla versione 25.04 o da un'immagine CODE precedente alla 26.04, il primo sospettato dovrebbe essere il reverse proxy. Non si tratta di una supposizione: Collabora ha documentato la modifica dell'URL compatto dei WebSocket nelle note di rilascio della versione 26.04 e un problema ufficiale del progetto ha segnalato il malfunzionamento dei WebSocket dopo un aggiornamento alla versione 26.04.1, fino alla modifica delle regole del proxy Apache.
Non risolvete il problema eseguendo un downgrade alla cieca e lasciando il vecchio proxy intatto. Un rollback può essere una soluzione temporanea, ma la soluzione definitiva è allineare il proxy alla versione che intendete utilizzare. Per Apache, utilizzate le impostazioni proxy correnti di Collabora Online anziché una copia precedente alla versione 26.04. Il report ufficiale di Collabora relativo ai problemi con WebSocket nella versione 26.04 documenta un caso in cui l'aggiornamento delle regole di Apache ha ripristinato il corretto funzionamento.
Innanzitutto, testa gli endpoint Collabora standard:
curl -I https://office.example.com/hosting/discovery
curl -I https://office.example.com/hosting/capabilitiesUna risposta positiva dimostra che DNS, TLS, il proxy front-end e almeno una parte del servizio Collabora sono raggiungibili. Non garantisce , tuttavia , che la modifica dei documenti funzionerà. L'editor dipende da una rotta WebSocket sotto /cool/, che ha requisiti proxy diversi.
Successivamente, apri gli strumenti per sviluppatori del browser, riproduci l'errore e controlla il pannello Rete con il filtro WS. Un handshake WebSocket riuscito normalmente aggiorna la connessione HTTP; RFC 6455 definisce la risposta del server come stato HTTP 101 quando l'aggiornamento ha successo. Se invece visualizzi 400, 404, 405, 502 o una richiesta fallita immediatamente, confronta quel timestamp con i log del reverse proxy e di coolwsd.
Per Nginx, le proprietà importanti sono semplici: la richiesta deve raggiungere il /cool/percorso Collabora, il proxy deve utilizzare HTTP/1.1 per un flusso WebSocket Upgrade classico, le intestazioni Upgradee Connectiondevono essere inoltrate, l'Host originale deve essere conservato e il timeout di lettura deve essere sufficientemente lungo per una sessione di modifica.
Il manuale dell'SDK di Collabora ha a lungo mostrato una posizione WebSocket dedicata con Upgrade, Connection, Host, e un lungo proxy_read_timeout. Un problema di documentazione ufficiale del progetto Collabora ha anche evidenziato la necessità di intestazioni WebSocket sul /coolpercorso più ampio. Un modello conservativo compatibile con 26.04 è:
location ^~ /cool/ {
proxy_pass http://127.0.0.1:9980;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 3600s;
}Non sovrascrivere una configurazione di produzione funzionante con questo codice senza adattare l'indirizzo upstream, il modello TLS, la gestione del percorso e gli eventuali controlli di sicurezza esistenti. La scelta corretta è quella di preservare la topologia esistente, rispettando al contempo i requisiti di routing e di intestazione di Collabora.
Le sessioni di modifica WebSocket hanno una durata prolungata. I valori Helm attuali del progetto Collabora lo descrivono esplicitamente e utilizzano un timeout del proxy elevato per il proxy Nginx incluso. Se il bilanciatore di carico edge, l'ingress di Kubernetes, la CDN, il firewall o il reverse proxy chiudono le connessioni inattive prima di quanto previsto dall'applicazione, gli utenti possono modificare normalmente per un certo periodo di tempo e poi essere disconnessi a intervalli regolari.
Quando l'errore si verifica ogni volta dopo circa lo stesso numero di secondi, invece di aumentare solo il timeout di Nginx, è opportuno esaminare ogni passaggio intermedio nel percorso. Il timeout più breve ha la precedenza.
Una configurazione comune termina HTTPS su Nginx, Apache, HAProxy, Traefik o un controller di ingresso e inoltra HTTP non crittografato a Collabora sulla porta 9980. In tale configurazione, la configurazione ufficiale di Collabora richiede che il back-end sappia che TLS viene terminato dal proxy. Il manuale dell'SDK documenta ssl.enable=falsequesto ssl.termination=truemodello.
Nel caso di un'implementazione Docker, ciò viene comunemente espresso tramite i parametri aggiuntivi di Collabora:
--o:ssl.enable=false --o:ssl.termination=trueUtilizzate queste opzioni solo quando la connessione TLS viene effettivamente terminata a monte. Se il proxy si connette a Collabora tramite HTTPS, configurate tale topologia in modo coerente anziché combinare i due modelli. Una discrepanza può generare schemi errati, URL WebSocket non corretti, errori di certificato o reindirizzamenti che compromettono l'aggiornamento.
Collabora convalida le origini WebSocket. Se il log contiene una dicitura come Rejecting WebSocket upgradeseguita da un'origine e un host previsto, correggi la relazione hostname/porta esterna anziché aggiungere intestazioni permissive a caso. Il sistema di tracciamento dei bug ufficiale di Collabora contiene un esempio documentato in cui un nome server configurato, incluso, :443non corrispondeva all'origine del browser senza quella porta esplicita.
I comandi utili dipendono dalla configurazione del tuo sistema:
docker logs collabora --tail 200
journalctl -u coolwsd --since "10 minutes ago"
nginx -t
apachectl configtestCerca il primo errore contemporaneamente alla richiesta WS non riuscita. I messaggi relativi ad aggiornamenti rifiutati, sintassi URI errata, un host imprevisto o un upstream non disponibile sono più utili rispetto al popup generico del browser.
Questo è un caso più specifico, ma vale la pena verificarlo prima di ricostruire il server. Il progetto Collabora ha documentato un caso relativo a Chromium in cui un proxy ha inoltrato una richiesta WebSocket HTTP/2 CONNECT direttamente a coolwsd, ricevendo un errore 405 Method Not Allowed. Un altro problema segnala errori di caricamento dei documenti relativi a HTTP/3/QUIC in un particolare percorso proxy. Queste segnalazioni non significano che HTTP/2 o HTTP/3 debbano essere sempre disabilitati; significano che l'intermediario deve tradurre il comportamento del client in una connessione WebSocket supportata da Collabora.
Se Firefox funziona mentre Chrome non funziona con lo stesso account e documento, è necessario acquisire il protocollo e il codice di stato del proxy. È preferibile correggere il comportamento del proxy/del punto di ingresso piuttosto che disabilitare globalmente i protocolli moderni, a meno che il proprio ambiente non offra alternative compatibili.
Prima di procedere, verifica la sintassi del proxy. Quindi ricaricalo anziché effettuare ripetuti riavvii alla cieca:
sudo nginx -t && sudo systemctl reload nginx
sudo apachectl configtest && sudo systemctl reload apache2Per i container, riavviare il servizio Collabora solo dopo aver modificato il suo ambiente o coolwsdle sue impostazioni. Una modifica che riguarda solo il proxy richiede in genere solo il ricaricamento del proxy.
Utilizza una breve sequenza di verifica anziché affidarti alla singola apertura di un documento andata a buon fine:
/hosting/discoveryche /hosting/capabilitiessono raggiungibili tramite lo stesso hostname pubblico a cui accedono gli utenti.Se hai eseguito l'aggiornamento alla versione 26.04 e utilizzi Apache, l'aggiornamento delle regole del proxy è l'azione prioritaria, poiché Collabora ha documentato esplicitamente questa modifica. Se la disconnessione si verifica dopo un periodo fisso, concentrati sulle impostazioni di timeout per ogni passaggio di rete. Se l'errore è immediato su tutti i browser, verifica /cool/il routing, le intestazioni di aggiornamento, la coerenza di Host/Origin e la terminazione TLS. Se il problema si verifica solo con una famiglia di browser, confronta la gestione del protocollo HTTP prima di modificare Collabora stesso.
Il punto cruciale è evitare di trattare l'errore "connessione socket chiusa inaspettatamente" come un arresto anomalo dell'applicazione Collabora per impostazione predefinita. In molte implementazioni, l'editor, l'endpoint di rilevamento e l'host WOPI funzionano correttamente, mentre il proxy inverso gestisce in modo errato il tipo di connessione più importante per la modifica in tempo reale: la connessione WebSocket, che ha una durata di connessione elevata.
Esegui LibreOffice in modalità headless in Docker per la conversione di file DOCX, XLSX, PPTX e PDF con un'immagine riproducibile, mount sicuri, font, profili e verifica.
Risolvi i problemi di avvio lento di LibreOffice su Windows 11 e Linux con la modalità di risoluzione dei problemi, i controlli delle estensioni, la riparazione del profilo e gli aggiornamenti specifici dell'installazione.
Configura lo sviluppo di plugin in ONLYOFFICE Desktop Editors: installa un archivio .plugin locale, collega la cartella sorgente, abilita gli strumenti per sviluppatori e testa le modifiche.
Scopri quando utilizzare le macro Python direttamente in Calc e come richiamare le funzioni Python da LibreOffice Basic con esempi pratici di UNO e ScriptForge.
Risolvi l'errore "Unauthorized WOPI Host" di Collabora Online CODE verificando la corrispondenza del nome host WOPI, configurando i gruppi di host Docker, controllando l'elenco IP consentito separato di Nextcloud e verificando la connettività.
Risolvi gli errori "Token non valido" di ONLYOFFICE in Nextcloud verificando il segreto JWT, l'intestazione di autorizzazione, le impostazioni Docker, il comportamento del proxy e lo stato del connettore.
Risolvi l'errore "Impossibile salvare il documento" di ONLYOFFICE in Nextcloud verificando callback, URL interni, JWT, TLS, routing proxy, log e spazio di archiviazione.
Risolvi gli errori di connessione socket di Collabora Online verificando la modifica WebSocket 26.04, le route proxy, le intestazioni di aggiornamento, i timeout, TLS e i log.
Abilita il controllo ortografico multilingue in Collabora Online aggiungendo dizionari server, consentendo i codici lingua, assegnando lingue al testo e testando documenti multilingue.
Crea una stampa unione affidabile con LibreOffice Writer, includendo immagini per ogni record, utilizzando i dati di Calc, un segnaposto per l'immagine con nome e una macro di base, con istruzioni per la risoluzione dei problemi e la verifica.
