Collabora Online can look healthy at first glance and still fail as soon as the editor tries to establish its live WebSocket. The familiar symptom is a document that begins loading and then reports that the socket connection closed unexpectedly, sometimes accompanied by a failed wss:// request in the browser. In 2026 there is one version-specific reason to check before changing anything else: the 26.04 branch introduced a more compact WebSocket URL, and older reverse-proxy rules can conflict with it.
Collabora's official CODE 26.04 release notes say that CODE 26.04.1, released June 8, 2026, required Apache2 reverse-proxy users to change their ProxyPass rule for the new compact WebSocket URL. The later 26.04.2.x notes say that CODE can fall back to the legacy URL when the new route cannot be used and emits an audit warning that points administrators back to the current proxy recommendations. The enterprise Collabora Online 26.04 branch is also current in 2026, so administrators should compare any proxy configuration copied from an older 24.04 or 25.04 guide with the latest vendor documentation before treating the problem as a random network fault.
The message does not identify a single root cause. It means the browser-to-Collabora WebSocket either never upgraded successfully or was established and then terminated unexpectedly. That distinction matters because the fixes differ.
| Observed behavior | Most useful first check | Typical causes |
|---|---|---|
| Fails immediately when a document opens | Browser Network > WS and reverse-proxy access/error logs | Wrong /cool/ route, missing Upgrade headers, Apache rule incompatible with 26.04, Host/Origin mismatch |
| Works briefly, then disconnects at a repeatable interval | Proxy, ingress, load balancer, and firewall idle timeouts | Timeout too short for a long-lived WebSocket |
| Discovery works but editing fails | Test the WebSocket separately from /hosting/discovery | HTTP endpoints are reachable while the WebSocket route is not |
| Only one browser or network path fails | Compare request protocol and proxy behavior | HTTP/2 or HTTP/3 handling, CONNECT forwarding, intermediary filtering |
| Server log explicitly rejects the upgrade | Read the exact coolwsd error | Origin, Host, port, WOPI host, or proxy configuration mismatch |
Se o problema surgiu imediatamente após a migração da versão 25.04 ou de uma imagem CODE anterior para a 26.04, considere o proxy reverso como o principal suspeito. Isso não é mera especulação: a Collabora documentou a alteração do URL compacto do WebSocket nas notas de lançamento da versão 26.04, e um problema relatado oficialmente no projeto indicava falhas no WebSocket após a atualização para a versão 26.04.1 até que as regras do proxy do Apache fossem alteradas.
Não resolva isso fazendo um downgrade cego e deixando o proxy antigo intacto. Um rollback pode ser uma medida de recuperação temporária, mas a solução definitiva é alinhar o proxy com a versão que você pretende executar. Para o Apache, use as configurações de proxy atuais do Collabora Online em vez de uma cópia anterior à versão 26.04. O próprio registro de problemas do WebSocket na versão 26.04 da Collabora documenta um caso em que a atualização das regras do Apache restaurou a operação.
Teste primeiro os endpoints comuns do Collabora:
curl -I https://office.example.com/hosting/discovery
curl -I https://office.example.com/hosting/capabilitiesUma resposta bem-sucedida comprova que o DNS, o TLS, o proxy de front-end e pelo menos parte do serviço Collabora estão acessíveis. Isso não comprova que a edição de documentos funcionará. O editor depende de uma rota WebSocket em /cool/, que possui requisitos de proxy diferentes.
Em seguida, abra as ferramentas de desenvolvedor do navegador, reproduza a falha e inspecione o painel Rede com o filtro WS. Um handshake WebSocket bem-sucedido normalmente atualiza a conexão HTTP; a RFC 6455 define a resposta do servidor como status HTTP 101 quando a atualização é bem-sucedida. Se, em vez disso, você vir 400, 404, 405, 502 ou uma solicitação com falha imediata, correlacione esse registro de data e hora com os logs do proxy reverso e do coolwsd.
Para o Nginx, as propriedades importantes são simples: a solicitação deve chegar ao /cool/caminho do Collabora, o proxy deve usar HTTP/1.1 para um fluxo clássico de atualização do WebSocket, os cabeçalhos `Authorization` Upgradee Connection`Authorization` devem ser encaminhados, o host original deve ser preservado e o tempo limite de leitura deve ser longo o suficiente para uma sessão de edição.
O manual do SDK do Collabora já mostrava há tempos um local dedicado para WebSocket com `<websocket_name>` Upgrade, Connection`<websocket_name> Host`, `<websocket_name>` e um longo ` proxy_read_timeout<websocket_name>`. Uma questão oficial na documentação do projeto Collabora também destacou a necessidade de cabeçalhos WebSocket na /coolrota mais ampla. Um padrão conservador e compatível com o Ubuntu 26.04 é:
location ^~ /cool/ {
proxy_pass http://127.0.0.1:9980;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 3600s;
}Não copie e cole este código sobre uma configuração de produção em funcionamento sem adaptar o endereço upstream, o modelo TLS, o tratamento de caminhos e quaisquer controles de segurança existentes. A opção correta é preservar sua topologia, mantendo a conformidade com os requisitos atuais de rota e cabeçalho do Collabora.
As sessões de edição via WebSocket são de longa duração. Os valores Helm atuais do projeto Collabora descrevem isso explicitamente e utilizam um tempo limite de proxy grande para o proxy Nginx incluído. Se o seu balanceador de carga de borda, entrada do Kubernetes, CDN, firewall ou proxy reverso fechar conexões ociosas antes do esperado pela aplicação, os usuários poderão editar normalmente por um tempo e, em seguida, serão desconectados em intervalos consistentes.
Quando a falha ocorre aproximadamente após o mesmo número de segundos todas as vezes, inspecione todos os intermediários no caminho em vez de aumentar apenas o tempo limite do Nginx. O menor tempo limite prevalece.
Uma implementação comum encerra o HTTPS no Nginx, Apache, HAProxy, Traefik ou em um controlador de entrada e encaminha o HTTP simples para o Collabora na porta 9980. Nesse modelo, a configuração oficial do Collabora exige que o back-end saiba que o TLS está sendo encerrado pelo proxy. O manual do SDK documenta isso ssl.enable=falseem conjunto com outras ssl.termination=trueinformações sobre esse modelo.
Para uma implementação Docker, isso geralmente é expresso por meio de parâmetros extras do Collabora:
--o:ssl.enable=false --o:ssl.termination=trueUse essas opções somente quando o TLS for realmente encerrado na origem. Se o proxy se conectar ao Collabora via HTTPS, configure essa topologia de forma consistente, em vez de misturar os dois modelos. Uma incompatibilidade pode gerar esquemas incorretos, URLs WebSocket incorretas, falhas de certificado ou redirecionamentos que interrompem a atualização.
O Collabora valida as origens do WebSocket. Se o log contiver termos como ` Rejecting WebSocket upgrade<origem>` seguidos por uma origem e um host esperado, corrija a relação entre o nome do host externo e a porta, em vez de adicionar cabeçalhos permissivos aleatoriamente. O rastreador de problemas oficial do Collabora contém um exemplo documentado em que um nome de servidor configurado, incluindo ` :443<origem>`, não correspondia à origem do navegador sem a porta explícita.
Os comandos úteis dependem da sua instalação:
docker logs collabora --tail 200
journalctl -u coolwsd --since "10 minutes ago"
nginx -t
apachectl configtestProcure o primeiro erro simultaneamente à falha na solicitação WS. Mensagens sobre atualizações rejeitadas, sintaxe de URI incorreta, um host inesperado ou um upstream indisponível são mais úteis do que o pop-up genérico do navegador.
Este é um caso mais específico, mas vale a pena verificar antes de reconstruir o servidor. O projeto Collabora documentou um caso relacionado ao Chromium em que um proxy encaminhou uma solicitação WebSocket HTTP/2 CONNECT diretamente para o coolwsd e recebeu o erro 405 Method Not Allowed. Outro problema relata falhas no carregamento de documentos relacionadas ao HTTP/3/QUIC em um caminho de proxy específico. Esses relatos não significam que o HTTP/2 ou o HTTP/3 devam ser sempre desativados; significam que o intermediário deve traduzir o comportamento do cliente em uma conexão WebSocket compatível com o Collabora.
Se o Firefox funcionar enquanto o Chrome falhar na mesma conta e documento, capture o protocolo e o código de status no proxy. Dê preferência a corrigir o comportamento do proxy/entrada em vez de desativar globalmente os protocolos modernos, a menos que seu ambiente não tenha uma alternativa compatível.
Primeiro, teste a sintaxe do proxy. Em seguida, recarregue a página em vez de reiniciar repetidamente sem saber o que está fazendo.
sudo nginx -t && sudo systemctl reload nginx
sudo apachectl configtest && sudo systemctl reload apache2Para contêineres, reinicie o serviço Collabora somente quando você alterar o ambiente ou as configurações dele coolwsd. Uma alteração que afeta apenas o proxy normalmente requer apenas a recarga do proxy.
Utilize uma sequência de verificação curta em vez de depender de uma única abertura de documento bem-sucedida:
/hosting/discoveryque /hosting/capabilitiesos usuários podem acessá-los através do mesmo nome de host público que eles utilizam.Se você atualizou para a versão 26.04 e usa o Apache, atualizar as regras de proxy é a ação prioritária, pois a Collabora documentou explicitamente essa alteração. Se a desconexão ocorrer após um período fixo, concentre-se nas configurações de tempo limite em cada salto de rede. Se a falha for imediata em todos os navegadores, verifique /cool/o roteamento, os cabeçalhos de atualização, a consistência de host/origem e a terminação TLS. Se apenas uma família de navegadores apresentar problemas, compare o tratamento do protocolo HTTP antes de alterar o próprio Collabora.
A chave é evitar tratar "conexão de socket fechada inesperadamente" como uma falha do aplicativo Collabora por padrão. Em muitas implementações, o editor, o endpoint de descoberta e o host WOPI estão funcionando corretamente, enquanto o proxy reverso está lidando incorretamente com o tipo de conexão mais importante para a edição em tempo real: o WebSocket, que possui alta estabilidade.
Conecte os editores de desktop ONLYOFFICE ao seu servidor ownCloud, faça login, abra arquivos na nuvem, gerencie a conexão e solucione problemas comuns de configuração.
Solucione problemas de alto uso da CPU no Collabora Online identificando processos de kit ocupados, verificando métricas e logs, ajustando a simultaneidade e a limpeza, e verificando as correções com segurança.
Aprenda como personalizar o ONLYOFFICE Docs com um logotipo de cabeçalho e cores de interface, incluindo limites de licença, configuração JSON do tema, caminhos do Docker e testes.
Fix hard-to-read text in LibreOffice Calc by checking the app theme, cell font and fill colors, styles, and conditional formatting—then verify print output.
Remova o aviso de bloqueio de usuário desconhecido do LibreOffice com segurança. Verifique as sessões ativas, proteja uma cópia, remova apenas bloqueios obsoletos verificados e teste o documento.
Corrija textos em árabe ou hebraico que fluem, se alinham ou se misturam incorretamente com o inglês no LibreOffice Writer. Ative o layout de texto complexo, defina a direção do parágrafo e verifique o resultado.
Learn VLOOKUP and XLOOKUP in LibreOffice Calc, including exact matches, left lookups, not-found results, reverse search, INDEX/MATCH alternatives, and common errors.
Solucione problemas de falhas na validação de provas WOPI do Collabora Online verificando chaves de descoberta, rotação de chaves, URLs de proxy, carimbos de data/hora e listas de permissões de hosts.
Ative o recurso "Controlar alterações" para todos em um documento do ONLYOFFICE, mantenha-o ativo após a reabertura e entenda as limitações de uma configuração padrão global.
Compare os tempos limite por visualização, fora de foco, ociosidade do documento, salvamento automático e proxy do Collabora Online e, em seguida, escolha e verifique as configurações para sua implementação.
