Rastreie falhas de conexão do Collabora com os logs do coolwsd.

Para um contêiner do Collabora Online Development Edition (CODE), aumente o coolwsdnível de registro de logs para debug, certifique-se de que as áreas Sockete não estejam desativadas e, em seguida, reproduza uma falha na abertura de um documento enquanto acompanha os logs do contêiner. No Docker Compose, passe as configurações por meio da variável de ambiente WebSocketda imagem CODE e recrie o serviço. Use somente se a saída de depuração não mostrar onde a conexão é interrompida e retorne ao nível anterior ao concluir.extra_paramstrace

Este método é adequado para implantações Docker ou Compose, onde você pode atualizar a configuração do contêiner. Uma instalação de pacote nativa utiliza /etc/coolwsd/coolwsd.xmlo gerenciador de serviços. Essa configuração adiciona detalhes de diagnóstico; ela não corrige problemas de proxy, host WOPI, certificado ou rede por si só.

1. Comece com uma reprodução controlada.

Escolha um documento e anote a hora em que você tenta abri-lo, o URL público do Collabora e o nome do contêiner ou do serviço Compose. Evite atualizar vários arquivos repetidamente: uma única tentativa facilita a comparação do sintoma do navegador, do log do proxy, do log do servidor de integração e das entradas do coolwsd.

Verifique se o contêiner está em execução e identifique seu nome:

docker ps --format 'table {.Names}	{.Status}	{.Ports}'

Substitua collaboraabaixo pelo nome do contêiner exibido em seu host. Comece a acompanhar a saída logo antes de reproduzir o problema:

docker logs --since 2m --follow --timestamps collabora

--followO Docker envia novas saídas, --sincelimita o histórico inicial e --timestampsadiciona timestamps do Docker. O Docker documenta essas opções em sua referência de logs de contêiner . No Compose, você pode usar ` --service-key` docker compose logs --since=2m --follow collabora, onde collabora`service` é a chave do serviço.

2. Aumente o nível de depuração do coolwsd para o teste.

O esquema de configuração do Collabora suporta níveis nomeados, incluindo ` --no- level` warning, ... e `--no-level` . Ele também define `--no-level` ; o padrão documentado desativa a saída detalhada de `--no-level` e `--no-level`, entre outras áreas. Isso é importante para a solução de problemas de conexão: alterar o nível por si só pode resultar na supressão dos detalhes mais úteis do handshake. Essas opções estão documentadas no modelo de configuração do Collabora Coolwsd e no manual do SDK Online do Collabora (seção de configuração do Docker; consultado em outubro de 2026).noticeinformationdebugtracedisabled_areasSocketWebSocket

Para a imagem oficial collabora/code, adicione as duas opções ao extra_paramsvalor existente do serviço. Mantenha quaisquer opções já exigidas pela sua instalação, como terminação SSL ou nome do servidor:

services:
  collabora:
    environment:
      extra_params: "--o:logging.level=debug --o:logging.disabled_areas=Admin,Pixel"

A segunda opção deixa `--disabled` Sockete WebSocket`--disabled` disponíveis para registro detalhado, enquanto `--disabled` Admine Pixel`--disabled` permanecem desativados. Não adicione essas duas áreas de volta à lista de desativadas durante este teste. A documentação da imagem CODE descreve `--disabled` extra_paramscomo uma forma de passar opções de linha de comando para o coolwsd. Se sua implantação usa um arquivo de configuração montado ou uma imagem gerenciada pelo fornecedor, siga o método de configuração dessa implantação.

Aplique a edição "Compor" recriando o serviço:

docker compose up -d --force-recreate collabora

Use o nome real do seu serviço Compose. Para um contêiner de curta duração iniciado com `--no-compose-name` docker run, atualize sua configuração de execução e recrie-o com os mesmos volumes, redes, portas e outras opções. O manual do CODE afirma que a imagem aceita `--no-compose- extra_paramsname` na inicialização; não presuma que alterar o ambiente de um contêiner já criado altere o processo `coolwsd` em execução.

3. Leia a conexão em ordem

Reproduza a falha uma única vez e analise apenas esse intervalo. Procure na saída por termos como WebSocket, WOPI, ERR, e WRN, e compare os registros de data e hora. A redação exata e as áreas de registro variam de acordo com a versão do Collabora, portanto, considere-as como categorias a serem inspecionadas, e não como mensagens literais garantidas.

• Nenhuma nova entrada do coolwsd no momento do teste: a solicitação pode não estar chegando a este contêiner. Verifique o URL público configurado, o DNS, o balanceador de carga, os logs de acesso/erro do proxy reverso e se você está monitorando a réplica correta.
• O navegador acessa o serviço, mas o WebSocket não permanece aberto: verifique o tratamento do proxy na atualização do WebSocket, o host e o esquema encaminhados, a terminação TLS, o roteamento de caminho e os tempos limite de inatividade. Compare com o console do desenvolvedor do navegador e os logs do proxy; o coolwsd não consegue explicar uma solicitação que o proxy nunca encaminha.
• Uma solicitação WOPI é exibida e falha: verifique a URL WOPI do servidor de integração, a lista de permissões do host ou a configuração do alias, a acessibilidade a partir do contêiner do Collabora e a resposta do servidor de integração. Um erro WOPI é uma etapa separada da conexão WebSocket do navegador para o Collabora.
• O WOPI funciona, mas o navegador ainda desconecta: concentre-se agora na rota do WebSocket e nos erros de conexão do lado do navegador. Essa sequência restringe a busca; ela não prova qual proxy ou configuração de rede está incorreta.

Se o Docker não exibir nenhuma saída mesmo com o serviço ativo, verifique a configuração de registro (logging) dentro do contêiner. O comando `log` do Docker lê os fluxos de saída padrão e de erro do contêiner; uma instalação configurada para gravar em um arquivo pode, em vez disso, usar um caminho como `/var/ /var/log/coolwsd.loglog`, conforme definido em sua configuração. Inspecione o arquivo real em vez de presumir esse caminho:

docker exec collabora sh -c 'grep -n -A25 "<logging>" /etc/coolwsd/coolwsd.xml'

Se o registro em arquivo estiver ativado, use o caminho configurado, por exemplo:

docker exec collabora sh -c 'tail -n 200 /var/log/coolwsd.log'

4. Verifique o resultado e restaure o registro normal.

Após o teste, execute uma leitura limitada para confirmar se a tentativa pretendida produziu novas entradas:

docker logs --since 5m --timestamps collabora

Você obtém um resultado útil quando consegue alinhar a falha na abertura com um evento do coolwsd ou constatar que a requisição nunca chegou a este contêiner, identificando então qual etapa da conexão precisa de acompanhamento. Se precisar filtrar a saída, utilize inicialmente um intervalo de tempo curto.

docker logs --since 5m collabora | grep -Ei 'coolwsd|WOPI|WebSocket|ERR|WRN'

Restaure os valores anteriores logging.levele disabled_areas, em seguida, recrie o serviço. Os níveis de depuração e rastreamento podem gerar muito mais informações e podem incluir detalhes operacionais confidenciais. Antes de compartilhar os registros, oculte tokens de acesso, nomes de documentos, identificadores de usuário, nomes de host e endereços internos. Se o serviço não for a imagem oficial do CODE, confirme o caminho de configuração e os parâmetros compatíveis com o responsável pela manutenção dessa imagem.