Risolvere il problema di lag nella modifica collaborativa di ONLYOFFICE su un server Docker autogestito

Se la modifica collaborativa di ONLYOFFICE risulta lenta su un server Docker self-hosted, non iniziate modificando parametri dell'editor non documentati. Innanzitutto, suddividete il problema in tre aree misurabili: pressione sulle risorse del server, comportamento del reverse proxy/WebSocket ed errori a livello di storage o container. La modifica collaborativa si basa su una comunicazione in tempo reale e di lunga durata, quindi un server che apre correttamente i documenti può comunque risultare lento quando più persone digitano contemporaneamente.

Questa guida utilizza un esempio ipotetico : un piccolo team esegue ONLYOFFICE Docs in Docker dietro NGINX. Uno o due utenti possono modificare normalmente, ma quando sei persone aprono lo stesso documento, gli aggiornamenti del cursore arrivano in ritardo e le modifiche degli altri utenti vengono visualizzate dopo una pausa percettibile. Questo esempio è solo uno scenario didattico, non un benchmark o un report di un'implementazione reale.

A partire da ottobre 2026, ONLYOFFICE Docs 9.4 è la versione corrente indicata nel changelog ufficiale. La versione 9.4 ha anche modificato l'architettura della Community Edition rimuovendo le dipendenze da RabbitMQ e dai database, pertanto i consigli scritti per le versioni precedenti potrebbero non essere più validi per un container della Community Edition corrente. Verificate sempre l'edizione e la versione installate prima di copiare consigli di ottimizzazione da un vecchio post del forum.

1. Misura il ritardo prima di modificare qualsiasi cosa

In questo caso ipotetico, il primo errore sarebbe quello di riavviare servizi a caso e sperare che il ritardo scompaia. Invece, create un test ripetibile. Aprite lo stesso documento da diverse sessioni del browser o account di prova, digitate brevi modifiche e annotate cosa viene ritardato: la pressione dei tasti sullo schermo locale, il movimento del cursore remoto, la comparsa del testo di un altro utente, il salvataggio dello stato o il caricamento iniziale del documento.

Questi sintomi indicano diversi colli di bottiglia. Se l'editor si blocca nel browser locale, il problema potrebbe essere legato alla CPU lato client o alla complessità del documento. Se la digitazione in locale è immediata ma le modifiche remote arrivano in ritardo, è necessario esaminare il percorso di rete e la sessione WebSocket. Se ogni operazione rallenta all'aumentare del numero di documenti aperti, è opportuno controllare la CPU del server, la memoria, lo swap e l'I/O del disco.

ONLYOFFICE descrive la distribuzione di Docker e i requisiti di base nella guida ufficiale all'installazione di Docker . Per Docker Compose, consultare le istruzioni ufficiali di Docker Compose .

2. Controllare la pressione della CPU e della memoria durante la modifica da parte degli utenti.

Sull'host Docker, eseguire:

docker stats

Monitora il contenitore del Document Server mentre il gruppo di test effettua le modifiche. Ispeziona inoltre le risorse dell'host con strumenti quali:

free -h
uptime
vmstat 1
df -h

I requisiti Docker ufficiali di ONLYOFFICE specificano almeno 4 GB di RAM e almeno 40 GB di spazio libero su disco per le configurazioni documentate, inclusi i requisiti di swap. Le linee guida aziendali chiariscono inoltre che la capacità dipende dal numero di utenti attivi simultanei e dal numero, dal tipo e dalle dimensioni dei documenti. Questi valori rappresentano dei parametri di riferimento, non una garanzia che 4 GB assicurino una collaborazione fluida per qualsiasi carico di lavoro.

Nel nostro esempio, supponiamo docker statsche il container Document Server consumi ripetutamente la maggior parte della CPU disponibile ogni volta che sei persone digitano contemporaneamente. Questa è una prova significativa: l'aggiunta di timeout del proxy non aumenterà il consumo di CPU. Il passo successivo è rimuovere un limite di CPU Docker eccessivamente restrittivo, spostare il container su un host più veloce o ridurre il carico di lavoro simultaneo. Al contrario, se il consumo di CPU rimane modesto, è consigliabile continuare a indagare prima di acquistare hardware.

Il riferimento ufficiale per le linee guida sulla capacità pubblicate è il documento ONLYOFFICE Docs Docker system requirements .

3. Verificare lo spazio su disco, i punti di montaggio e la cache dei file.

La documentazione Docker di ONLYOFFICE identifica le posizioni persistenti, incluse quelle /var/log/onlyofficeper i log e /var/lib/onlyofficeper la cache dei file. Controlla il filesystem che supporta questi percorsi, non solo il filesystem root dell'host.

df -h
docker inspect documentserver --format '{json .Mounts}'

Se un bind mount punta a un filesystem di rete lento o a un disco sovraccarico, l'apertura dei documenti, la conversione e l'attività della cache possono aggiungere latenza. Se il disco è quasi pieno, è necessario risolvere il problema prima di ottimizzare le applicazioni. La documentazione di ONLYOFFICE sulla risoluzione dei problemi di Linux identifica specificamente lo spazio su disco insufficiente come possibile causa di problemi di conversione.

Il progetto raccomanda inoltre di archiviare i dati rilevanti al di fuori del container quando sono necessari log persistenti, archiviazione cache o servizi esterni di database/Redis/RabbitMQ. Consultare le linee guida ufficiali di Docker relative ai volumi .

4. Verificare che il proxy inverso mantenga la connessione in tempo reale

Molte implementazioni self-hosted posizionano ONLYOFFICE dietro NGINX, Apache, HAProxy o Traefik. La documentazione ufficiale del proxy ONLYOFFICE richiede esplicitamente l'inoltro di intestazioni come X-Forwarded-Protoe X-Forwarded-Host. La configurazione fornita da ONLYOFFICE utilizza anche HTTP/1.1 e la gestione degli aggiornamenti WebSocket.

Per NGINX, confronta la tua configurazione con l'esempio ufficiale di ONLYOFFICE anziché incollare un frammento WebSocket generico da un altro prodotto. Un modello rappresentativo include:

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $proxy_connection;
proxy_set_header X-Forwarded-Host $the_host;
proxy_set_header X-Forwarded-Proto $the_scheme;

Le direttive circostanti mape le posizioni proxy esatte sono importanti. Utilizzare l'esempio completo del fornitore per la propria topologia. Le configurazioni supportate sono pubblicate nella documentazione "Using ONLYOFFICE Docs behind the proxy" .

Ipotizziamo che, nel team in questione, l'host Docker disponga di CPU e RAM in abbondanza, ma che il browser riconnetta ripetutamente il canale di collaborazione attraverso un livello NGINX aziendale. Questo indica un problema con il percorso proxy, non con la capacità di calcolo del Document Server.

5. Conferma la sessione WebSocket nel browser

Apri gli strumenti per sviluppatori del browser, seleziona il pannello Rete, filtra per traffico WebSocket e ricarica l'editor. Un handshake WebSocket riuscito in genere mostra HTTP 101 Switching Protocolse una connessione che rimane aperta. Non considerare un WebSocket "in sospeso" di lunga durata come un errore a sé stante; un WebSocket attivo dovrebbe rimanere aperto.

Ciò che conta sono i ripetuti problemi di disconnessione/riconnessione, gli handshake falliti, gli errori del proxy o le lunghe interruzioni che si correlano al ritardo nella collaborazione. Se le modifiche remote subiscono ritardi negli stessi momenti in cui il WebSocket si riconnette, allora hai un problema di rete concreto da risolvere.

Verifica la terminazione TLS, i timeout di inattività del proxy, le regole del bilanciatore di carico, le policy WAF e qualsiasi intermediario che potrebbe non preservare il traffico WebSocket. Se è presente più di un livello proxy, testa ogni hop invece di presumere che l'istanza pubblica di NGINX sia l'unica coinvolta.

6. Verificare i contenitori previsti e l'architettura specifica dell'edizione

Correre:

docker compose ps
# or
docker ps

Non bisogna dare per scontato che ogni implementazione moderna di ONLYOFFICE debba avere la stessa collezione di container Redis, PostgreSQL o RabbitMQ. È qui che la versione diventa importante. ONLYOFFICE afferma che, a partire dalla versione 9.4 della documentazione, la Community Edition open-source è stata semplificata in un'architettura a processo singolo, eliminando le dipendenze da RabbitMQ e dai database. Le versioni Enterprise, Developer, le precedenti implementazioni Community e gli stack Compose personalizzati possono differire.

Ciò significa che un articolo del 2023 sulla risoluzione dei problemi, che afferma che "RabbitMQ deve essere il collo di bottiglia", potrebbe non essere pertinente per un'istanza attuale di Community Edition. Identifica l'immagine e la versione che stai effettivamente utilizzando:

docker inspect documentserver --format '{.Config.Image}'
docker image ls onlyoffice/documentserver

Il registro ufficiale delle modifiche di ONLYOFFICE Docs elenca la versione 9.4.0 con data di rilascio 20 maggio 2026. L'annuncio di rilascio di Docs 9.4 da parte del fornitore spiega il cambiamento di architettura della Community Edition.

7. Abilitare temporaneamente la registrazione di debug e correlarla con il ritardo

ONLYOFFICE fornisce una variabile d'ambiente Docker documentata per la registrazione di debug. Per una breve finestra di risoluzione dei problemi, aggiungi:

DS_LOG_LEVEL=DEBUG

Quindi ricrea o riavvia il container pertinente in base al tuo metodo di distribuzione e consulta i log:

docker logs -f documentserver
# Docker Compose:
docker compose logs -f documentserver

La documentazione ufficiale afferma che i log di Docker sono disponibili anche all'interno /var/log/onlyoffice/documentserverdel container e nella corrispondente directory dei log montata sull'host, se quest'ultima viene montata. Il log del convertitore è utile quando l'apertura o la conversione dei file è lenta, mentre i problemi di co-creazione dovrebbero essere correlati con i log del Document Server e con le osservazioni del browser/rete.

Disattiva la modalità DEBUG dopo aver raccolto le informazioni necessarie. La registrazione dettagliata serve per la diagnostica, non è un'impostazione permanente per le prestazioni. Segui la procedura del fornitore descritta in " Abilitazione della registrazione di debug" nella documentazione di ONLYOFFICE .

8. Aggiorna con attenzione se stai utilizzando un'immagine obsoleta

Se l'implementazione è significativamente indietro rispetto alla linea di rilascio supportata, un aggiornamento può includere correzioni di bug e miglioramenti dell'architettura. Tuttavia, "scarica l'ultima versione e riavvia" non è una procedura sicura per garantire prestazioni ottimali su un server di collaborazione in produzione.

Innanzitutto, annota il tag dell'immagine corrente, il file di composizione, le impostazioni JWT, i volumi montati, la configurazione del reverse proxy e la configurazione dell'integrazione. Utilizza una versione bloccata quando il processo di modifica richiede riproducibilità. La guida all'installazione di Docker di ONLYOFFICE documenta come specificare una versione particolare, e il registro delle modifiche ufficiale indica le modifiche apportate.

Prima di arrestare intenzionalmente un Document Server di produzione molto occupato, segui le istruzioni di arresto di ONLYOFFICE specifiche per la tua edizione e distribuzione, in modo che le sessioni di modifica attive vengano gestite in modo sicuro. Non utilizzare un documento di riferimento contenente lavoro utente non salvato come test di aggiornamento.

Come il caso ipotetico restringe il campo della soluzione reale

Torniamo all'esempio del team con sei co-editori. Il risultato della risoluzione dei problemi dipende da ciò che osservi:

Una base pratica per le implementazioni Docker

Per una piccola installazione self-hosted, iniziate con i requisiti minimi pubblicati da ONLYOFFICE, ma dimensionate le risorse in base al vostro effettivo numero di utenti simultanei piuttosto che al numero totale di utenti registrati. Mantenete i log e la cache persistenti su un'unità di archiviazione con latenza prevedibile. Evitate limiti stringenti per CPU o memoria, a meno che non abbiate misurato il carico di lavoro. Impedite all'host Docker di utilizzare lo swap durante un normale carico di lavoro di modifica.

Posiziona ONLYOFFICE dietro una configurazione di reverse proxy derivata dagli esempi supportati dal fornitore, preservando gli aggiornamenti WebSocket e le intestazioni host/protocollo inoltrate. Monitora il server durante la co-editing effettiva, non solo quando è inattivo. Se hai bisogno di prove più approfondite, abilita temporaneamente la registrazione DEBUG e correla i timestamp dei log con il comportamento WebSocket del browser e le metriche dell'host.

Cosa non fare

• Non modificare valori non documentati local.jsonsolo perché un post su un forum li definisce "ottimizzazioni delle prestazioni".
• Non dare per scontato che un WebSocket persistente visualizzato come "in sospeso" sia interrotto; è normale che i WebSocket abbiano una lunga durata.
• Non aggiungere Redis, RabbitMQ o PostgreSQL solo perché un vecchio diagramma di distribuzione li prevedeva. Verifica prima l'architettura della tua edizione e versione.
• Non disabilitare la verifica TLS, la sicurezza JWT o le protezioni proxy come scorciatoia per ridurre la latenza.
• Non confrontare una metrica del server inattivo con il periodo in cui gli utenti segnalano effettivamente rallentamenti.
• Non aggiornare un'istanza di produzione senza aver prima preservato i volumi, la configurazione e un percorso di ripristino.

In conclusione

Il ritardo nella modifica collaborativa di ONLYOFFICE è più facile da risolvere se lo si considera un problema di sistema misurabile. Riproduci il ritardo, osserva le risorse di Docker e dell'host sotto carico, verifica lo spazio di archiviazione, conferma che il browser mantenga una connessione WebSocket stabile attraverso ogni proxy e ispeziona i log solo per l'intervallo di tempo in cui si verifica il ritardo. Una volta individuato se il collo di bottiglia è dovuto a problemi di elaborazione, memoria, disco, comportamento della rete/proxy o a una specifica modifica di versione/configurazione, la soluzione diventa mirata anziché basata su supposizioni.

Per i dettagli di implementazione attuali, consultare la documentazione di installazione Docker di ONLYOFFICE , gli esempi ufficiali di reverse proxy , la guida alla registrazione di debug e il registro delle modifiche ufficiale della documentazione .