Restaurar a conexão WebSocket da Collabora através do proxy.

Quando o Collabora Online reporta que uma conexão de socket foi fechada inesperadamente, verifique primeiro se a requisição WebSocket do navegador está passando coolwsdpelo proxy reverso. Verifique se a rota do proxy corresponde à versão do Collabora, mantenha a atualização do WebSocket e o caminho da URL, e então teste um documento enquanto observa o painel de Rede do navegador e os logs do servidor. Se o problema começou após uma atualização para o CODE 26.04 em um servidor Apache, verifique ProxyPassprimeiro as regras do Apache: as notas de lançamento do Collabora 26.04 mencionam uma alteração na URL compacta do WebSocket.

Um WebSocket é a conexão bidirecional de longa duração que o Collabora usa entre o navegador e seu servidor enquanto um documento está aberto. Um proxy reverso é o serviço que aceita a solicitação pública e a encaminha para o Collabora. A mensagem de erro aponta para essa conexão, mas não prova que o proxy seja a causa; um host WOPI rejeitado, uma URL pública incorreta, uma incompatibilidade de TLS ou um backend incorreto também podem interromper a sessão.

Antes de alterar qualquer coisa, identifique sua rota.

Anote a versão ou a tag da imagem do Collabora, o software proxy, o nome do host público do Collabora e se o TLS termina no proxy ou no Collabora. Verifique o nome do serviço e a imagem atual sem alterar a implantação:

docker compose ps collabora
docker compose images collabora

Substitua collabora`<service_name>` pelo nome do serviço no seu arquivo Compose. Para um contêiner que não seja Compose, use `<service_name>` docker pse docker inspect`<service_name>` para identificar o contêiner e a imagem. Não assuma que a latesttag ainda aponta para a mesma versão que você testou na semana passada.

1. Veja onde o handshake do WebSocket termina.

No navegador, abra as Ferramentas do Desenvolvedor, selecione Rede , filtre por WS ou WebSocket e tente abrir um documento novamente. A URL da solicitação deve ser usada wss://quando a página pública for HTTPS. Selecione a solicitação com falha e anote seu status, caminho da URL e cabeçalhos de resposta. Um handshake bem-sucedido normalmente retorna um resultado positivo 101 Switching Protocolse a conexão permanece aberta enquanto a sessão do documento estiver ativa.

• Nenhuma solicitação WebSocket é exibida: verifique o URL do Collabora no aplicativo de integração, o console do navegador, o DNS e quaisquer erros de redirecionamento ou conteúdo misto antes de editar as regras do servidor.
• A solicitação retorna 400 ou 404: compare o caminho solicitado com a rota encaminhada pelo seu proxy e com a rota suportada pela versão do Collabora instalada. Um código 400 coolwsdque indica "Solicitação inválida ou desconhecida" pode significar que a solicitação chegou ao Collabora por meio de um caminho que ele não aceita.
• A solicitação retorna 502 ou 504: verifique se o proxy consegue alcançar o servidor Collabora upstream configurado e se o endereço e a porta apontam para o contêiner ou host correto.
• A solicitação retorna 101 e, em seguida, é fechada posteriormente: verifique os tempos limite de inatividade do proxy, balanceador de carga, firewall e rede do cliente. Um WebSocket tem longa duração, portanto, um intermediário que fecha conexões ociosas muito cedo pode interromper uma abertura que, de outra forma, seria bem-sucedida.

2. Compare a regra de proxy com a sua versão do Collabora.

Utilize as configurações atuais de proxy reverso da Collabora para o software e a versão de proxy que você está executando. Verifique se a rota WebSocket está sendo tratada como um WebSocket, se o proxy está encaminhando os cabeçalhos de atualização e se ele preserva o caminho e a string de consulta codificada, em vez de redirecioná-los ou reescrevê-los. O proxy também deve enviar o host público e o esquema de forma consistente com o nome do servidor externo e as configurações de terminação TLS configuradas pela Collabora.

Para o Nginx, revise a localização específica do WebSocket e suas diretivas HTTP/1.1 Upgradee Connectionde encaminhamento no exemplo atual da Collabora. Para o Apache, compare a ProxyPassregra e a ordem com o exemplo atual; não cole uma /cool/…/wscorrespondência antiga sem verificar o que a sua versão instalada solicita atualmente.

Esta verificação de versão é importante para o CODE 26.04. As notas de lançamento da Collabora, publicadas em 8 de junho de 2026, descrevem uma URL WebSocket mais compacta e informam que os usuários de proxy reverso Apache precisam se adaptar ProxyPassa ela. Trabalhos posteriores na versão 26.04 adicionaram um comportamento alternativo para URLs legadas, portanto, uma regra antiga ainda pode funcionar em algumas versões; o relatório de problemas resolvidos do WebSocket na versão 26.04 da Collabora documenta esse acompanhamento. O comportamento alternativo não substitui a configuração atual do proxy para corresponder à versão instalada. Leia as notas de lançamento do CODE 26.04 e o exemplo atualizado do SDK em conjunto.

3. Identifique uma falha e faça uma mudança específica.

Inicie um fluxo de logs curto antes de tentar novamente o documento. --sinceA opção do Docker limita a saída inicial, enquanto --followo comando `docker logs` envia novas linhas; consulte a referência de logs do Docker Compose .

docker compose logs --since=2m --follow collabora

Registre o horário do teste e procure a mesma solicitação nos logs do Collabora e do proxy. Se o navegador solicitar um caminho que o proxy roteia para o backend errado, atualize apenas essa rota WebSocket usando o exemplo correspondente à versão do Collabora. Se a solicitação chegar ao Collabora, mas o host, a origem ou o esquema forem rejeitados, compare o nome do host público e a porta com o nome do servidor configurado e os cabeçalhos encaminhados. Se, em vez disso, o log mostrar uma rejeição de host WOPI ou uma solicitação de informações de arquivo com falha, verifique o host permitido do servidor de integração e sua acessibilidade a partir do contêiner do Collabora; essa é uma etapa separada do handshake WebSocket do navegador.

Recarregue o proxy após validar sua configuração com o comando de verificação de sintaxe próprio do proxy. Evite alterar a terminação TLS, as listas de permissão de hosts e as reescritas de URL simultaneamente: alterar uma causa por teste torna o próximo resultado interpretável. Não desative a verificação TLS nem permita todos os hosts WOPI como atalho.

4. Verifique a correção do navegador para o documento.

Tente novamente com o mesmo documento. Nas Ferramentas do Desenvolvedor, confirme se a solicitação WebSocket retorna 101 Switching Protocolse permanece aberta. Confirme se o documento termina de carregar, permanece conectado e aceita uma pequena edição que é salva com sucesso. Um status de conexão saudável por si só não é suficiente se o acesso ou o salvamento do arquivo WOPI ainda falhar.

Se o handshake ainda falhar, compare o caminho da requisição do navegador, a linha de acesso/erro do proxy e a coolwsdentrada de log correspondente no mesmo carimbo de data/hora. Essa comparação de três pontos mostra se o navegador, o proxy, a rota do Collabora ou o host WOPI é o próximo local a ser investigado. Ao solicitar ajuda, oculte tokens de acesso, identificadores de documentos, nomes de usuário e nomes de host privados dos detalhes do navegador e dos logs.