Fix Collabora Online Black Screen or Blank Document on Load

Start by checking the WebSocket connection and the two servers’ reachability. A Collabora Online editor that opens to a black screen, a white page, or an empty document canvas is often failing before the document UI finishes loading. If the problem affects every file, inspect the browser-to-Collabora route, reverse proxy, and Nextcloud-to-Collabora connection first. If only one file fails, test another document and check that file’s permissions and format before changing server settings.

Use this order: check the browser, test Collabora’s discovery endpoints, read the integration and server logs, then correct only the proxy or WOPI setting that the evidence points to. A browser cache reset can help with stale assets, but it will not repair a broken WebSocket or an unreachable WOPI host. The interface images below are schematic examples; exact labels and request paths vary by browser, cloud platform, proxy, and Collabora release.

Quick diagnosis by symptom

1. Find out whether the problem is browser-side or server-wide

First, open a second document that you know is readable and try the same file in a different browser or private window. If one document fails while others open, check that the user can still download or preview it in the file platform. A damaged file, unsupported format, expired share, or missing permission can look like an editor problem, but changing the reverse proxy will not fix a file-specific issue.

For a browser-side check, open Developer Tools before reloading the blank document. In Chromium-based browsers, press F12 or Ctrl+Shift+I, select Network, enable Preserve log, and reload. Filter for ws, cool, or browser. Also review the Console tab for blocked scripts, certificate warnings, or content-security-policy errors.

Una richiesta non riuscita indica /cool/…/wsun problema di handshake WebSocket o del proxy. Un errore 502di solito significa che il proxy non è riuscito a ottenere una risposta utilizzabile dal suo upstream; un errore di tipo 404può significare che il percorso non è instradato; e un 403errore di tipo può indicare un host o una regola di accesso rifiutati. Questi codici di stato restringono la ricerca, ma sono necessari i log del proxy e di Collabora corrispondenti per identificare la causa esatta. Se le richieste non riuscite riguardano file JavaScript o CSS nella directory /browser, verificare che il proxy inoltri tali risorse statiche al servizio Collabora.

Se le richieste di rete hanno esito positivo in una finestra di navigazione privata, disabilitare temporaneamente le estensioni del browser che bloccano gli script o le richieste cross-site, quindi cancellare i dati del sito solo per i nomi host cloud e Collabora. Eseguire nuovamente il test prima di modificare la configurazione del server. Non considerare la cancellazione della cache come soluzione principale se la stessa richiesta continua a non funzionare nella scheda Rete.

2. Conferma l'URL di Collabora e gli endpoint di rilevamento

Per l'integrazione con Nextcloud, verifica l'URL del server Collabora Online nelle impostazioni di amministrazione di Office. Utilizza l'URL pubblico raggiungibile dai browser, con il nome host e la porta corretti. Le attuali linee guida di Nextcloud indicano che i servizi Collabora e Nextcloud dovrebbero utilizzare lo stesso protocollo; si consiglia HTTPS. Una mancata corrispondenza, ad esempio un servizio configurato con un protocollo diverso da quello http://utilizzato per raggiungere l'altro, https://può causare il blocco delle richieste con contenuto misto o errori nelle callback.

Da un browser sul client interessato, apri https://office.example.com/hosting/discoverye https://office.example.com/hosting/capabilities, sostituendo il nome host di esempio con il tuo. L'endpoint di rilevamento dovrebbe restituire un file XML che descrive le azioni sui documenti supportate; le funzionalità dovrebbero restituire una risposta dal server Collabora. Un errore del browser, una pagina di accesso, un errore 404 con marchio proxy o un errore del gateway indicano che il percorso pubblico non raggiunge l'endpoint Collabora previsto.

Quindi, esegui il test dall'host Nextcloud, perché il solo test tramite browser non dimostra che i server possano comunicare tra loro:

curl -sS -o /dev/null -w "%{http_code}\n" https://office.example.com/hosting/discovery
curl -sS -o /dev/null -w "%{http_code}\n" https://office.example.com/hosting/capabilities

Sostituire office.example.comcon il nome host di Collabora configurato. Una risposta HTTP positiva è un utile controllo di raggiungibilità, mentre un timeout, un errore DNS, un errore TLS o una risposta 5xx devono essere risolti a livello di rete, certificato, DNS o proxy. Per le installazioni in cui il server Collabora deve effettuare una chiamata a Nextcloud, testare anche l'URL di stato di Nextcloud dall'host Collabora:

curl -fsS https://cloud.example.com/status.php

Utilizza il tuo hostname Nextcloud effettivo. Le installazioni CODE integrate possono utilizzare un URL proxy interno anziché un hostname Collabora pubblico separato, quindi segui le istruzioni per tale implementazione anziché applicare letteralmente l'esempio del server standalone.

3. Verificare il percorso WebSocket e il proxy inverso

Collabora fornisce risorse del browser e sessioni di documenti attraverso diversi percorsi. Un proxy inverso deve inoltrare i percorsi previsti dalla versione installata, inclusi le risorse dell'editor, gli endpoint di rilevamento e funzionalità e il percorso WebSocket del documento. La documentazione attuale di Collabora utilizza /cool/…/ws; le implementazioni precedenti potrebbero ancora avere configurazioni per /loolpercorsi legacy. La documentazione di migrazione di Nextcloud menziona specificamente le modifiche storiche del percorso da loleafleta browsere da loola cool.

Nella configurazione del proxy, verifica che la posizione WebSocket corrisponda prima delle regole catch-all più generali, che il proxy inoltri le intestazioni di aggiornamento necessarie per il software proxy e che il server upstream punti al servizio e alla porta effettivi di Collabora. Verifica inoltre che il proxy conservi le informazioni previste sull'host e sullo schema e che consenta alle connessioni di lunga durata di rimanere aperte. Se la connessione TLS termina sul proxy, assicurati che le impostazioni di terminazione SSL di Collabora corrispondano a tale configurazione.

Il breve estratto di codice qui sopra mostra il tipo di intestazioni WebSocket di cui potrebbe aver bisogno un proxy in stile Nginx; non si tratta di una configurazione proxy completa. Non incollarlo da solo né combinare direttive provenienti da versioni diverse. Confronta la tua configurazione completa con la guida ufficiale di Collabora per i proxy inversi, specifica per il proxy e la versione di Collabora in uso. Dopo aver modificato un file proxy, verifica la sintassi con il comando `configuration-test` del server prima di ricaricarlo.

4. Verificare la convalida dell'host WOPI e i log del server.

Collabora utilizza WOPI (Web Application Open Platform Interface) per richiedere un documento da un servizio di archiviazione connesso, come Nextcloud. Il server Collabora deve accettare l'host WOPI e il server di archiviazione deve essere in grado di raggiungere il servizio Collabora. In Nextcloud, verifica le impostazioni di Office e l'elenco degli indirizzi consentiti per le richieste WOPI. Aggiungi solo l'indirizzo del server Collabora previsto; non disabilitare la convalida dell'host né consentire host arbitrari per visualizzare una schermata vuota.

Leggete i log nel momento in cui si verifica il problema. Per un'implementazione Docker, la guida alla risoluzione dei problemi di Nextcloud descrive come controllare il log del container; utilizzate il nome o l'ID effettivo del container:

docker logs --tail 100 collabora

Per un'installazione basata su pacchetti, i nomi dei servizi e le destinazioni dei log dipendono dal sistema operativo e dalla versione del pacchetto. Un controllo systemd comune è:

sudo journalctl -u coolwsd -n 100 --no-pager

Cerca un timestamp corrispondente ed errori relativi a un host WOPI non autorizzato, CheckFileInfouna richiesta non riuscita, una verifica TLS, uno spazio di archiviazione non disponibile o un WebSocket non riuscito. Un messaggio che indica che nessun host WOPI accettabile corrisponde di solito significa che il nome host dello spazio di archiviazione configurato per l'integrazione non corrisponde all'host consentito da Collabora. Correggi il nome host o la voce nella lista di autorizzazione anziché aggiungere domini non correlati.

Controlla anche il log della piattaforma file per lo stesso orario della richiesta. Se Collabora non riesce a raggiungere Nextcloud, verifica la risoluzione DNS dall'host di Collabora, le regole del firewall, il percorso pubblico o interno e se il servizio sta tentando di raggiungere se stesso tramite un nome host che si risolve in modo diverso all'interno della rete del container. Il manuale di risoluzione dei problemi di Nextcloud consiglia di verificare la connettività in entrambe le direzioni e di utilizzare i log del server per identificare il lato non funzionante.

5. Ritesta il documento e apporta solo modifiche mirate.

Dopo aver corretto un percorso, un URL, un certificato o una voce nella lista di autorizzazione, ricarica il proxy e i servizi interessati solo quando la tua distribuzione lo richiede. Riapri gli Strumenti per sviluppatori, ricarica il file e verifica che la richiesta precedentemente non riuscita ora venga completata. Il documento dovrebbe visualizzare le sue pagine o i suoi fogli, accettare una piccola modifica e salvare la modifica correttamente. Una pagina vuota che scompare ma non può essere salvata indica comunque un problema di connessione WOPI o di archiviazione non risolto.

• La fase di rilevamento funziona, ma WebSocket fallisce: concentrarsi sul percorso WebSocket del proxy, sulla gestione degli aggiornamenti, sull'indirizzo upstream e sul timeout di connessione.
• Il browser riesce a raggiungere Collabora, ma Nextcloud no: testare DNS, firewall, attendibilità TLS e routing dall'host Nextcloud.
• Collabora segnala un host WOPI non autorizzato: confronta il nome host di archiviazione esatto nelle impostazioni di integrazione con l'elenco degli host WOPI consentiti.
• Solo le installazioni obsolete non funzionano dopo un aggiornamento: confronta i percorsi proxy con la documentazione della versione installata e aggiorna i percorsi legacy /loolo /loleafletquelli necessari.
• Solo un file non viene elaborato correttamente dopo che i controlli di connettività hanno esito positivo: verifica l'accesso al file e prova una copia o un formato diverso supportato prima di modificare le impostazioni globali.

Ecco come si presenta una soluzione efficace.

Un risultato affidabile va oltre la semplice visualizzazione della barra degli strumenti dell'editor. Il contenuto del documento viene visualizzato correttamente, non si verificano errori persistenti nell'editor o nelle richieste WebSocket e una modifica di prova innocua viene salvata e rimane invariata dopo un aggiornamento. Se il problema persiste, conserva un breve estratto anonimizzato della schermata di rete/console del browser e le corrispondenti righe di log di Nextcloud, proxy e Collabora. I log possono contenere nomi host, nomi utente, identificatori di file o token, quindi rimuovi i valori sensibili prima di condividerli.

Per le procedure di implementazione specifiche, consultare la guida alla risoluzione dei problemi di Nextcloud Office , il riferimento alla configurazione di Nextcloud Office e le note sulla migrazione di Collabora . I controlli esatti per ownCloud, un altro host WOPI, un servizio CODE integrato o una piattaforma container possono differire dagli esempi di Nextcloud.