Traccia gli errori di connessione di Collabora con i log di coolwsd

Per un container Collabora Online Development Edition (CODE), aumenta coolwsdil livello di registrazione debug, assicurati che le aree Sockete WebSocketnon siano disabilitate, quindi riproduci un'apertura di documento non riuscita seguendo i log del container. In Docker Compose, passa le impostazioni tramite la variabile d'ambiente dell'immagine CODE extra_paramse ricrea il servizio. Usa tracesolo se l'output di debug non mostra dove si interrompe la connessione e torna al livello precedente al termine.

Questo metodo è adatto a una distribuzione Docker o Compose in cui è possibile aggiornare la configurazione del container. Un'installazione nativa del pacchetto utilizza /etc/coolwsd/coolwsd.xmlinvece il relativo gestore di servizi. L'impostazione aggiunge dettagli diagnostici; non risolve autonomamente un problema di proxy, host WOPI, certificato o rete.

1. Inizia con una riproduzione controllata

Scegli un documento e annota l'ora in cui provi ad aprirlo, l'URL pubblico di Collabora e il nome del contenitore o del servizio Compose. Evita di aggiornare ripetutamente diversi file: un singolo tentativo semplifica l'individuazione del problema nel browser, nel log del proxy, nel log del server di integrazione e nelle voci di coolwsd.

Verifica che il container sia in esecuzione e identifica il suo nome:

docker ps --format 'table {.Names}	{.Status}	{.Ports}'

Sostituisci collaborail nome del container mostrato sul tuo host con quello riportato di seguito. Avvia l'output seguente poco prima di riprodurre il problema:

docker logs --since 2m --follow --timestamps collabora

--followvisualizza nuovi output, --sincelimita la cronologia iniziale e --timestampsaggiunge timestamp Docker. Docker documenta queste opzioni nel suo riferimento ai log dei container . In Compose, puoi usare docker compose logs --since=2m --follow collabora, dove collaboraè la chiave del servizio.

2. Porta coolwsd in modalità debug per il test

Lo schema di configurazione di Collabora supporta livelli denominati, tra cui warning, notice, information, debug, e trace. Definisce anche disabled_areas; il valore predefinito documentato disabilita l'output ad alta verbosità da Sockete WebSocket, tra le altre aree. Questo è importante per la risoluzione dei problemi di connessione: la sola modifica del livello potrebbe comunque sopprimere i dettagli più utili dell'handshake. Queste opzioni sono documentate nel modello di configurazione coolwsd di Collabora e nel manuale dell'SDK di Collabora Online (sezione di configurazione Docker; verificato a ottobre 2026).

Per l'immagine ufficiale collabora/code, aggiungi le due opzioni al extra_paramsvalore esistente del servizio. Mantieni tutte le opzioni già richieste dalla tua installazione, come la terminazione SSL o il nome del server:

services:
  collabora:
    environment:
      extra_params: "--o:logging.level=debug --o:logging.disabled_areas=Admin,Pixel"

La seconda opzione lascia Sockete WebSocketdisponibili per la registrazione ad alta verbosità mantenendo Admine Pixeldisabilitati. Non aggiungere nuovamente queste due aree all'elenco disabilitato durante questo test. La documentazione dell'immagine CODE descrive extra_paramscome un modo per passare opzioni da riga di comando a coolwsd. Se la tua distribuzione utilizza un file di configurazione montato o un'immagine gestita dal fornitore, segui invece il metodo di configurazione di tale distribuzione.

Applica la modifica Compose ricreando il servizio:

docker compose up -d --force-recreate collabora

Utilizza il nome effettivo del tuo servizio Compose. Per un container di breve durata avviato con docker run, aggiorna la sua configurazione di esecuzione e ricrealo con gli stessi volumi, reti, porte e altre opzioni. Il manuale di CODE afferma che l'immagine accetta extra_paramsall'avvio; non dare per scontato che la modifica dell'ambiente di un container già creato modifichi il processo coolwsd in esecuzione.

3. Leggere la connessione in ordine

Riproduci l'errore una volta e analizza solo quell'intervallo. Cerca nell'output termini come WebSocket, WOPI, ERR, e WRN, quindi confronta i timestamp. La formulazione esatta e le aree del log variano a seconda della versione di Collabora, quindi considerale come categorie da esaminare piuttosto che come messaggi letterali garantiti.

• Nessuna nuova voce coolwsd al momento del test: la richiesta potrebbe non raggiungere questo container. Verifica l'URL pubblico configurato, il DNS, il bilanciatore di carico, i log di accesso/errore del reverse proxy e assicurati di monitorare la replica corretta.
• Il browser raggiunge il servizio ma la connessione WebSocket non rimane aperta: esaminare la gestione del proxy dell'aggiornamento WebSocket, l'host e lo schema di inoltro, la terminazione TLS, il routing del percorso e i timeout di inattività. Confrontare con la console per sviluppatori del browser e i log del proxy; coolwsd non è in grado di spiegare una richiesta che il proxy non inoltra mai.
• Viene visualizzata una richiesta WOPI che fallisce: verificare l'URL WOPI del server di integrazione, la configurazione della lista di autorizzazione o dell'alias dell'host, la raggiungibilità dal container Collabora e la risposta del server di integrazione. Un errore WOPI rappresenta una fase separata dalla connessione WebSocket tra il browser e Collabora.
• WOPI ha successo ma il browser continua a disconnettersi: concentriamoci ora sul percorso WebSocket e sugli errori di connessione lato browser. Questa sequenza restringe il campo di ricerca, ma non dimostra quale proxy o impostazione di rete sia errata.

Se Docker non mostra alcun output anche se il servizio è attivo, controlla la configurazione di logging all'interno del container. Il comando `log` di Docker legge i flussi di output e di errore standard del container; un'installazione configurata per scrivere su un file potrebbe invece utilizzare un percorso come `/etc/log/log/` /var/log/coolwsd.log, come definito dalla sua configurazione. Controlla il file effettivo invece di presumere che il percorso sia quello corretto.

docker exec collabora sh -c 'grep -n -A25 "<logging>" /etc/coolwsd/coolwsd.xml'

Se la registrazione dei file è abilitata, utilizzare il percorso configurato, ad esempio:

docker exec collabora sh -c 'tail -n 200 /var/log/coolwsd.log'

4. Verificare il risultato e ripristinare la registrazione normale

Dopo il test, eseguire una lettura limitata per confermare che il tentativo previsto abbia prodotto nuove voci:

docker logs --since 5m --timestamps collabora

Si ottiene un risultato utile quando è possibile allineare l'apertura fallita con un evento coolwsd o stabilire che la richiesta non ha mai raggiunto questo container, quindi identificare quale fase della connessione richiede un seguito. Se è necessario filtrare l'output, utilizzare prima una finestra temporale breve:

docker logs --since 5m collabora | grep -Ei 'coolwsd|WOPI|WebSocket|ERR|WRN'

Ripristina i valori precedenti logging.level, disabled_areasquindi ricrea nuovamente il servizio. I livelli di debug e di traccia possono produrre un output molto più dettagliato e includere informazioni operative sensibili. Prima di condividere i log, oscura i token di accesso, i nomi dei documenti, gli identificativi utente, i nomi host e gli indirizzi interni. Se il servizio non è l'immagine ufficiale di CODE, conferma il percorso di configurazione e i parametri supportati con il responsabile di tale immagine.