Come risolvere l'elevato utilizzo della CPU in Collabora Online causato da loolwsd / coolwsd

Quando Collabora Online utilizza improvvisamente la maggior parte della CPU di un server, il primo passo fondamentale è non riavviarlo ripetutamente o imporre immediatamente un limite di CPU troppo basso. Innanzitutto, è necessario determinare se il carico deriva dal normale lavoro sui documenti, da una sessione di documenti problematica, da un eccessivo lavoro parallelo, da una sessione inattiva che non viene terminata o da una regressione specifica della versione. Il nome del processo può essere presente coolwsdsia nelle versioni più recenti che loolwsdnelle installazioni precedenti.

Scenario illustrativo: immaginiamo un server con 8 vCPU che esegue Collabora Online dietro Nextcloud. Sembra che solo poche persone stiano modificando documenti, ma il container di Collabora rimane con un utilizzo della CPU compreso tra il 250% e il 350% per diversi minuti. Questo è un esempio ipotetico utilizzato in questa guida, non un benchmark misurato o un report di un'implementazione reale.

A ottobre 2026, la versione stabile corrente di Collabora è la 26.04 e le note di rilascio ufficiali indicano Collabora Online 26.04.3.3 come rilasciato il 14 settembre 2026. I modelli di configurazione attuali utilizzano questo coolwsdnome. Gli strumenti di migrazione di Collabora documentano ancora il /etc/loolwsd/loolwsd.xmlpercorso precedente per le installazioni risalenti alla versione 6.4 o precedenti, motivo per cui gli amministratori potrebbero ancora incontrare entrambi i nomi.

1. Conferma quale processo sta effettivamente consumando CPU

Iniziate dal livello del sistema operativo o del container. Un numero elevato accanto coolwsdnon significa automaticamente che il demone di coordinamento stia eseguendo tutto il lavoro oneroso relativo ai documenti. Collabora esegue anche processi kit/forkit per le sessioni dei documenti, quindi è necessario visualizzare l'albero dei processi e l'utilizzo della CPU per processo prima di modificare la configurazione.

ps -eo pid,ppid,pcpu,pmem,etime,cmd --sort=-pcpu | head -n 25
top -H -p $(pgrep -d, -f 'coolwsd|loolwsd|coolkit|loolkit|forkit')

Per Docker, controlla anche l'intero container:

docker stats --no-stream

Nell'esempio illustrativo, supponiamo che il container utilizzi quasi il 300% della CPU e che un processo del kit si trovi costantemente in cima all'elenco dei processi. Questo indica che il problema risiede in una specifica sessione di documenti attiva, piuttosto che in una generica supposizione di sovraccarico dell'intero server.

2. Controlla le metriche di Collabora invece di affidarti solo a quelle dei migliori

Collabora Online espone metriche compatibili con Prometheus all'indirizzo /cool/getMetrics. Il manuale SDK attuale afferma che questo endpoint può segnalare l'utilizzo di CPU e memoria, i processi del kit in esecuzione, le viste e altri dati sull'utilizzo del server. Utilizza la stessa autenticazione della console di amministrazione, a meno che le metriche non siano configurate esplicitamente per l'accesso non autenticato.

Non esporre pubblicamente l'endpoint delle metriche solo per semplificare la risoluzione dei problemi. La configurazione ufficiale di Helm include persino esempi per /cool/getMetricsURL di blocco e di amministrazione in un ingresso. Utilizza un percorso interno autenticato ogni volta che è possibile.

Cerca di individuare una correlazione tra l'utilizzo della CPU e i documenti o le viste attive. Se l'utilizzo della CPU aumenta e diminuisce in concomitanza con attività di modifica legittime, potrebbe esserci un problema di capacità o di concorrenza. Se l'utilizzo della CPU rimane elevato senza alcuna attività interattiva corrispondente, indaga su sessioni inattive, documenti problematici, processi in background ripetuti o problemi software.

3. Leggi i log relativi al momento esatto in cui l'utilizzo della CPU aumenta.

Per l'installazione di un pacchetto gestita da systemd:

journalctl -u coolwsd --since "15 minutes ago" --no-pager
journalctl -u coolwsd -f

Per Docker:

docker logs collabora --since 15m
docker logs -f collabora

Se il servizio o il contenitore ha un nome diverso, sostituiscilo. Cerca caricamenti ripetuti di documenti, creazione ripetuta di kit, salvataggi non riusciti, arresti anomali, cicli di riconnessione o la stessa chiave del documento che appare ripetutamente. Un breve periodo di utilizzo elevato della CPU durante l'apertura, il ricalcolo, il rendering, la conversione o l'esportazione di un documento può essere legittimo. Il segnale di allarme più forte è un utilizzo prolungato della CPU senza progressi utili o la ripetizione dello stesso errore.

4. Riprodurre il picco con un documento alla volta

Torniamo al server ipotetico. Se un processo del kit risulta sovraccarico, chiudiamo o isoliamo il documento sospetto e verifichiamo se l'utilizzo della CPU diminuisce. Quindi, apriamo lo stesso file durante un periodo di inattività, monitorando l'elenco dei processi e le metriche. Ripetiamo l'operazione con un semplice documento di prova.

Questo confronto è più utile che riavviare immediatamente l'intero servizio:

• Se solo un file innesca in modo affidabile il picco, è più probabile che la causa risieda nel contenuto del file stesso, nelle formule, negli oggetti incorporati, nel carico di lavoro di rendering o in un bug specifico del documento.
• Se ogni file causa una saturazione simile quando sono attivi più utenti, è necessario verificare la capacità del server e il numero di utenti simultanei.
• Se l'utilizzo della CPU rimane elevato anche dopo l'interruzione di tutte le attività dell'utente, è opportuno concentrarsi sulla pulizia, sui kit obsoleti, sulle attività in background ripetitive o su una regressione.
• Se il problema si è presentato subito dopo un aggiornamento, annota le versioni vecchia e nuova prima di modificare molte altre variabili.

5. Ridurre la concorrenza per documento quando un documento può monopolizzare i core

Il modello di configurazione di Collabora attualmente in uso per_document.max_concurrencyspecifica il numero massimo di thread utilizzati durante l'elaborazione di un documento. Il valore predefinito del modello è 4. Su un host con risorse limitate, o quando un singolo documento complesso può monopolizzare le risorse del sistema, la riduzione di questo valore può rendere l'utilizzo della CPU più prevedibile.

Ad esempio, si potrebbe testare un valore pari a 2:

<per_document>
    <max_concurrency>2</max_concurrency>
</per_document>

Non copiate ciecamente il valore 2. Se gli utenti gestiscono regolarmente fogli di calcolo o presentazioni di grandi dimensioni e il server dispone di un numero sufficiente di core, un valore inferiore potrebbe semplicemente rallentare il lavoro. Modificate un'impostazione, riproducete lo stesso carico di lavoro e confrontate l'utilizzo della CPU, la reattività e il tempo di completamento.

6. Verificare le impostazioni di pulizia e di sessione inattiva prima di renderle aggressive

Il modello attuale coolwsd.xmlinclude una logica di pulizia per i documenti inattivi che consumano risorse. Al momento della stesura di questo documento, il modello prevede un intervallo di controllo della pulizia di 10.000 ms, un periodo di comportamento anomalo di 60 secondi, una soglia di inattività di 300 secondi e una soglia di utilizzo della CPU dell'85% affinché un documento diventi un candidato per la pulizia. Include inoltre un timeout di inattività per documento di 3.600 secondi.

Lo stesso modello include timeout per singola visualizzazione. I valori attuali indicano 300 secondi prima che una visualizzazione del browser non attiva venga oscurata e gli aggiornamenti si interrompano, e 900 secondi prima che una visualizzazione inattiva venga trattata in modo simile. Questi timeout di visualizzazione non sono equivalenti allo scaricamento immediato di un'intera sessione del documento.

Evitate di impostare una soglia CPU estremamente bassa solo per migliorare l'aspetto del grafico. La funzione di pulizia serve a individuare i documenti danneggiati o inattivi che consumano risorse, non a interrompere le normali modifiche attive ogni volta che diventano computazionalmente onerose.

7. Riavviare solo dopo aver salvato una modifica controllata della configurazione.

Eseguire prima un backup della configurazione attiva. Le installazioni dei pacchetti in genere utilizzano /etc/coolwsd/coolwsd.xml. Le distribuzioni Docker possono passare opzioni come variabili d'ambiente o override da riga di comando, oppure montare un file di configurazione nel container. Verificare quale sorgente è effettivamente attiva prima di apportare qualsiasi modifica.

Per l'installazione di un pacchetto:

sudo cp /etc/coolwsd/coolwsd.xml /etc/coolwsd/coolwsd.xml.before-cpu-tuning
sudo systemctl restart coolwsd
systemctl status coolwsd --no-pager

Per un container Docker:

docker restart collabora
docker ps --filter name=collabora

Se un semplice riavvio risolve temporaneamente il problema della CPU, ma questo si ripresenta ripetutamente, si tratta di un'informazione diagnostica, non di una soluzione definitiva. Continuate a cercare finché non sarete in grado di spiegare quale carico di lavoro o stato causa la ricomparsa del problema.

8. Confrontare la situazione prima e dopo con lo stesso carico di lavoro.

Utilizzate lo stesso documento, un numero di utenti approssimativamente uguale e la stessa sequenza di operazioni. Effettuate le misurazioni per diversi minuti anziché confrontare un singolo istante. Nello scenario illustrativo, il successo si verificherebbe se il server non risultasse più saturo durante il carico di lavoro riprodotto, mentre l'apertura, la modifica, il salvataggio e la collaborazione sui documenti continuassero a funzionare in modo accettabile.

Quando è meglio aggiornare invece di ottimizzare le impostazioni?

Se il problema si è presentato con una specifica versione di Collabora e si riesce a riprodurlo con un file o un'operazione specifica, la configurazione potrebbe semplicemente mascherare un difetto del software. Collabora consiglia di utilizzare la versione più recente del ramo stabile corrente. Al 7 ottobre 2026, la pagina ufficiale delle note di rilascio della versione 26.04 indica la 26.04.3.3 come l'ultima versione di Collabora Online disponibile.

Per gli utenti di CODE, ricordate che Collabora descrive la Development Edition come adatta a piccoli team, uso domestico, sviluppo e alla sperimentazione di nuove funzionalità, pur specificando che non è pensata per ambienti di produzione. Un problema in produzione su CODE potrebbe quindi giustificare il passaggio al prodotto Collabora Online, supportato da terze parti, piuttosto che continuare a cercare di adattarlo al comportamento della versione di sviluppo.

Cosa non fare

• Non dare per scontato che un coolwsdnumero elevato dimostri una perdita di memoria o un ciclo infinito.
• Non impostare in modo permanente la registrazione di debug o di traccia durante un incidente della CPU a meno che non sia effettivamente necessario; la registrazione dettagliata aggiunge un proprio sovraccarico e una maggiore pressione sullo spazio di archiviazione.
• Non esporre la console di amministrazione o l'endpoint delle metriche a Internet pubblico solo per comodità di monitoraggio.
• Non abbassare le soglie di pulizia finché le normali sessioni attive non vengono terminate.
• Non utilizzare le quote CPU come primo strumento diagnostico. Un limite rigido può proteggere gli altri utenti su un host condiviso, ma potrebbe trasformare un problema della CPU in un rendering lento dei documenti e in timeout senza rivelarne la causa.

Ordine consigliato per la risoluzione dei problemi

1. Conferma se il processo in corso è coolwsdun processo più vecchio loolwsdo un processo per kit/forkit per bambini.
2. Registra i dati relativi a CPU, memoria, documenti attivi e viste di Docker o dell'host.
3. Correlare i log con l'esatta finestra temporale del picco.
4. Riproduci il problema utilizzando un documento sospetto e poi un semplice documento di controllo.
5. Eseguire il test per_document.max_concurrencysolo se un documento sta utilizzando troppe risorse della CPU in parallelo.
6. Rivedi le impostazioni di pulizia e di inattività senza renderle inutilmente aggressive.
7. Riavviare il servizio dopo ogni modifica controllata della configurazione e verificarne l'integrità.
8. Confronta lo stesso carico di lavoro prima e dopo, quindi controlla la versione stabile corrente per verificare se il comportamento sembra essere specifico della versione.

Riferimenti ufficiali

I dettagli di configurazione in questa guida si basano sul modello sorgente corrente di Collabora Online: Modello di configurazione coolwsd.xml di Collabora Online . Il manuale ufficiale dell'SDK documenta la registrazione, i controlli delle prestazioni e l'endpoint delle metriche compatibile con Prometheus: Manuale dell'SDK di Collabora Online . Per verificare la versione, consultare le note di rilascio di Collabora Online 26.04 del produttore . Per l'utilizzo previsto della Development Edition, consultare l' annuncio ufficiale del rilascio di CODE 26.04 .

L'obiettivo pratico non è quello di costringere Collabora Online a utilizzare la minor quantità possibile di CPU. Si tratta piuttosto di rendere il consumo di CPU comprensibile e proporzionale al lavoro effettivo, preservando al contempo prestazioni accettabili in termini di modifica e collaborazione.