Corrigir lentidão na coedição do ONLYOFFICE em um servidor Docker auto-hospedado

Se a edição colaborativa do ONLYOFFICE estiver lenta em um servidor Docker auto-hospedado, não comece alterando parâmetros do editor que não estão documentados. Primeiro, separe o problema em três áreas mensuráveis: pressão sobre os recursos do servidor, comportamento do proxy reverso/WebSocket e erros de armazenamento ou de contêiner. A edição colaborativa depende de comunicação em tempo real e de longa duração; portanto, um servidor que abre documentos com sucesso ainda pode apresentar lentidão quando várias pessoas digitam simultaneamente.

Este guia utiliza um exemplo hipotético : uma pequena equipe executa o ONLYOFFICE Docs em um contêiner Docker por trás do NGINX. Um ou dois usuários conseguem editar normalmente, mas quando seis pessoas abrem o mesmo documento, as atualizações do cursor chegam com atraso e as alterações de outros usuários aparecem após uma pausa perceptível. Este exemplo é apenas um cenário didático, não um teste de desempenho ou um relato de uma implementação real.

Em outubro de 2026, a versão atual do ONLYOFFICE Docs, listada no changelog oficial, era a 9.4. A versão 9.4 também alterou a arquitetura da Community Edition, removendo as dependências do RabbitMQ e de bancos de dados. Portanto, as dicas escritas para versões anteriores podem não ser mais compatíveis com a versão atual da Community Edition. Sempre confirme a edição e a versão instaladas antes de copiar dicas de otimização de uma postagem antiga do fórum.

1. Meça o atraso antes de fazer qualquer alteração.

No caso hipotético, o primeiro erro seria reiniciar serviços aleatórios na esperança de que o atraso desapareça. Em vez disso, crie um teste repetível. Abra o mesmo documento em várias sessões do navegador ou contas de teste, digite pequenas edições e observe o que está atrasado: as teclas digitadas na tela local, o movimento do cursor remoto, o aparecimento do texto de outro usuário, o status de salvamento ou o carregamento inicial do documento.

Esses sintomas apontam para diferentes gargalos. Se o próprio editor congelar no navegador local, o problema pode estar na CPU do lado do cliente ou em um documento muito complexo. Se a digitação local for imediata, mas as edições remotas demorarem, examine o caminho da rede e a sessão WebSocket. Se todas as ações ficarem mais lentas quando mais documentos forem abertos, inspecione a CPU, a memória, o swap e a E/S de disco do servidor.

A ONLYOFFICE descreve sua implantação do Docker e os requisitos básicos no guia oficial de instalação do Docker . Para o Docker Compose, utilize as instruções oficiais do Docker Compose .

2. Verifique a carga da CPU e da memória enquanto os usuários estiverem editando.

No host Docker, execute:

docker stats

Monitore o contêiner do Servidor de Documentos enquanto o grupo de teste edita. Inspecione também os recursos do host com ferramentas como:

free -h
uptime
vmstat 1
df -h

Os requisitos oficiais do Docker da ONLYOFFICE especificam pelo menos 4 GB de RAM e pelo menos 40 GB de espaço livre em disco para as configurações documentadas, além de requisitos de swap. As diretrizes corporativas também deixam claro que a capacidade depende do número de usuários ativos simultâneos e da quantidade, tipo e tamanho dos documentos. Esses valores são parâmetros básicos, não uma garantia de que 4 GB proporcionarão colaboração fluida para todas as cargas de trabalho.

Em nosso exemplo, suponha docker statsque o contêiner do Servidor de Documentos esteja consumindo repetidamente a maior parte da CPU disponível sempre que seis pessoas digitam simultaneamente. Isso é uma evidência significativa: adicionar tempos limite de proxy não aumentará o uso da CPU. O próximo passo é remover um limite de CPU excessivamente restritivo do Docker, mover o contêiner para um host mais rápido ou reduzir a carga de trabalho simultânea. Por outro lado, se o uso da CPU permanecer moderado, continue investigando antes de comprar hardware.

A referência oficial para orientações de capacidade publicadas são os requisitos de sistema Docker da ONLYOFFICE Docs .

3. Verifique o espaço em disco, as montagens e o cache de arquivos.

A documentação do Docker da ONLYOFFICE identifica locais persistentes, incluindo /var/log/onlyofficepara logs e /var/lib/onlyofficecache de arquivos. Verifique o sistema de arquivos que suporta esses caminhos, e não apenas o sistema de arquivos raiz do host.

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

Se uma montagem de diretório apontar para um sistema de arquivos de rede lento ou um disco sobrecarregado, a abertura, conversão e armazenamento em cache de documentos podem adicionar latência. Se o disco estiver quase cheio, resolva esse problema antes de otimizar o aplicativo. A documentação de solução de problemas do ONLYOFFICE para Linux identifica especificamente espaço em disco insuficiente como uma possível causa de problemas de conversão.

O projeto também recomenda armazenar dados relevantes fora do contêiner quando você precisar de logs persistentes, armazenamento em cache ou serviços externos de banco de dados/Redis/RabbitMQ. Consulte as diretrizes oficiais de volumes do Docker .

4. Verifique se o proxy reverso preserva a conexão em tempo real.

Muitas instalações auto-hospedadas colocam o ONLYOFFICE atrás de NGINX, Apache, HAProxy ou Traefik. A documentação oficial do proxy do ONLYOFFICE exige explicitamente cabeçalhos encaminhados, como ` X-Forwarded-Protohttp X-Forwarded-Host://localhost:8080` e `http://localhost:8080`. A configuração fornecida pelo ONLYOFFICE também utiliza o HTTP/1.1 e o tratamento de atualizações do WebSocket.

Para o NGINX, compare sua configuração com o exemplo oficial da ONLYOFFICE em vez de colar um trecho genérico de WebSocket de outro produto. Um padrão representativo inclui:

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;

As diretivas e localizações exatas mapdo proxy são importantes. Use o exemplo completo do fornecedor para sua topologia. As configurações suportadas estão publicadas em "Usando o ONLYOFFICE" na documentação sobre o uso do proxy .

Na equipe hipotética, suponha que o host Docker tenha bastante CPU e RAM, mas o navegador reconecta repetidamente o canal de colaboração por meio de uma camada NGINX corporativa. Isso indica um problema no caminho do proxy, e não na capacidade computacional do servidor de documentos.

5. Confirme a sessão WebSocket no navegador.

Abra as ferramentas de desenvolvedor do navegador, selecione o painel Rede, filtre por tráfego WebSocket e recarregue o editor. Um handshake WebSocket bem-sucedido normalmente mostra HTTP 101 Switching Protocolse uma conexão que permanece aberta. Não considere um WebSocket "pendente" de longa duração como uma falha por si só; espera-se que um WebSocket ativo permaneça aberto.

O que importa é o comportamento repetido de desconexão/reconexão, falhas de handshake, erros de proxy ou longos intervalos que se correlacionam com o atraso na colaboração. Se as edições remotas apresentarem lentidão nos mesmos momentos em que o WebSocket se reconecta, você agora tem um problema concreto de rede para resolver.

Verifique a terminação TLS, os tempos limite de inatividade do proxy, as regras do balanceador de carga, as políticas do WAF e qualquer intermediário que possa não preservar o tráfego WebSocket. Se houver mais de uma camada de proxy, teste cada salto em vez de presumir que a instância pública do NGINX seja a única envolvida.

6. Verifique os contêineres esperados e a arquitetura específica da edição.

Correr:

docker compose ps
# or
docker ps

Não presuma que toda instalação moderna do ONLYOFFICE precise ter a mesma coleção de contêineres Redis, PostgreSQL ou RabbitMQ. É aqui que a versão importa. O ONLYOFFICE afirma que, a partir da versão 9.4 da documentação, a Community Edition de código aberto foi simplificada para uma arquitetura de processo único e removeu as dependências do RabbitMQ e de bancos de dados. As versões Enterprise, Developer, instalações Community mais antigas e stacks Compose personalizadas podem ser diferentes.

Isso significa que um artigo de solução de problemas de 2023 dizendo "O RabbitMQ deve ser o gargalo" pode ser irrelevante para uma instância atual da Community Edition. Identifique a imagem e a versão que você está executando:

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

O changelog oficial do ONLYOFFICE Docs lista a versão 9.4.0 com data de lançamento prevista para 20 de maio de 2026. O anúncio de lançamento do Docs 9.4 do fornecedor explica a mudança na arquitetura da Community Edition.

7. Ative temporariamente o registro de depuração e correlacione-o com o atraso.

A ONLYOFFICE fornece uma variável de ambiente Docker documentada para registro de depuração. Para uma breve janela de solução de problemas, adicione:

DS_LOG_LEVEL=DEBUG

Em seguida, recrie ou reinicie o contêiner relevante de acordo com o seu método de implantação e acompanhe os registros:

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

A documentação oficial afirma que os logs do Docker também estão disponíveis dentro /var/log/onlyoffice/documentserverdo contêiner e no diretório de logs correspondente montado no host, caso você o monte. O log do conversor é útil quando a abertura ou conversão de arquivos está lenta, enquanto problemas de coautoria devem ser correlacionados com os logs do Servidor de Documentos e observações do navegador/rede.

Desative o modo DEBUG após coletar as informações necessárias. O registro detalhado serve para diagnóstico e não como uma configuração permanente de desempenho. Siga o procedimento do fornecedor em " Habilitando o registro de depuração" na documentação do ONLYOFFICE .

8. Atualize com cuidado se estiver usando uma imagem antiga.

Se a implantação estiver significativamente atrasada em relação à versão suportada, uma atualização pode incluir correções de bugs e melhorias de arquitetura. Mas "baixar a versão mais recente e reiniciar" não é uma solução segura para garantir o desempenho em um servidor de colaboração em produção.

Primeiro, registre a tag da imagem atual, o arquivo de composição, as configurações do JWT, os volumes montados, a configuração do proxy reverso e a configuração de integração. Use uma versão fixa quando o processo de alteração exigir reprodutibilidade. O guia de instalação do Docker da ONLYOFFICE documenta como especificar uma versão específica, e o changelog oficial informa o que mudou.

Antes de interromper intencionalmente um servidor de documentos de produção em uso, siga as orientações de desligamento da ONLYOFFICE para sua edição e implantação, garantindo que as sessões de edição ativas sejam gerenciadas com segurança. Não utilize um documento de teste contendo trabalhos de usuários não salvos como teste de atualização.

Como o caso hipotético ajuda a identificar a solução real.

Retorne ao exemplo da equipe com seis coeditores. O resultado da solução de problemas depende do que você observar:

Uma base prática para implantações do Docker

Para uma pequena instalação auto-hospedada, comece com os requisitos mínimos publicados pelo ONLYOFFICE, mas dimensione-os de acordo com sua atividade simultânea real, em vez do total de usuários registrados. Mantenha logs persistentes e cache em um armazenamento com latência previsível. Evite limites rígidos de CPU ou memória, a menos que você tenha medido a carga de trabalho. Evite que o próprio host Docker utilize a memória virtual (swap) sob carga normal de edição.

Configure o ONLYOFFICE atrás de um proxy reverso, seguindo os exemplos fornecidos pelo fornecedor, preservando as atualizações do WebSocket e os cabeçalhos de host/protocolo encaminhados. Monitore o servidor durante a edição colaborativa, não apenas quando ocioso. Se precisar de informações mais detalhadas, habilite temporariamente o registro de depuração (DEBUG) e correlacione os registros de data e hora com o comportamento do WebSocket no navegador e as métricas do host.

O que não fazer

• Não altere valores não documentados local.jsonsó porque uma postagem em um fórum os chama de "ajustes de desempenho".
• Não assuma que um WebSocket persistente exibido como "pendente" esteja com defeito; espera-se que os WebSockets tenham longa duração.
• Não adicione Redis, RabbitMQ ou PostgreSQL apenas porque um diagrama de implantação antigo os utilizava. Verifique primeiro a arquitetura da sua edição e versão.
• Não desative a verificação TLS, a segurança JWT ou as proteções de proxy como um atalho para diminuir a latência.
• Não compare uma métrica de servidor ocioso com o período em que os usuários realmente relatam lentidão.
• Não atualize uma instância de produção sem preservar os volumes, a configuração e um caminho de reversão.

Resumindo

A lentidão na coedição do ONLYOFFICE é mais fácil de corrigir quando tratada como um problema mensurável do sistema. Reproduza o atraso, observe os recursos do Docker e do host sob carga, verifique o armazenamento, confirme se o navegador mantém uma conexão WebSocket íntegra através de todos os proxies e inspecione os logs apenas durante o período em que a lentidão ocorre. Uma vez identificado o gargalo – seja ele computacional, de memória, de disco, de rede/proxy ou uma alteração específica de versão/configuração –, a correção torna-se direcionada em vez de especulativa.

Para obter detalhes atualizados sobre a implementação, consulte a documentação de instalação do Docker do ONLYOFFICE , os exemplos oficiais de proxy reverso , o guia de registro de depuração e o changelog oficial da documentação .