Corrigir erro de conexão "Bem, isto é embaraçoso" no Collabora Online

A mensagem do Collabora Online "Que pena, não conseguimos conectar ao seu documento" é um sintoma, não um diagnóstico. Ela aparece após o carregamento do editor, mas a sessão do documento não pode ser concluída. Nas implementações atuais, a maneira mais rápida de corrigir o problema é identificar qual conexão no caminho WOPI está falhando, em vez de alterar configurações aleatórias do Collabora.

Este guia utiliza a documentação de administração atual do Nextcloud 35 e as orientações do SDK 25.04 do Collabora Online como pontos de referência. A mesma lógica de resolução de problemas se aplica a muitas integrações personalizadas do ownCloud e do WOPI, mas os nomes exatos das configurações podem variar de acordo com a plataforma e a versão.

O que normalmente causa esse erro de conexão no Collabora?

Uma sessão de navegador funcional depende de vários caminhos distintos. O navegador do usuário precisa acessar tanto o servidor de armazenamento quanto o Collabora; o servidor de armazenamento precisa acessar o Collabora; o Collabora precisa acessar o servidor de armazenamento; os protocolos e certificados precisam ser compatíveis; e o proxy reverso precisa encaminhar corretamente as rotas HTTP e WebSocket do Collabora. A página oficial de solução de problemas do Nextcloud lista explicitamente esses requisitos de conectividade bidirecional.

Isso significa que não existe uma única solução universalmente correta. Escolha o caminho de reparo com base no primeiro teste com falha:

1. Verifique os endpoints de descoberta e recursos do Collabora

Comece com a URL pública do Collabora que sua integração utiliza. Abra esses endpoints em um navegador e no servidor de armazenamento:

https://office.example.com/hosting/discovery
https://office.example.com/hosting/capabilities

A documentação de resolução de problemas atual do Nextcloud recomenda ambos os testes. O endpoint de descoberta deve retornar XML, enquanto o endpoint de capacidades retorna os dados de capacidade do Collabora. Um tempo limite, aviso de certificado, erro 404, página de erro com a marca do proxy ou loop de redirecionamento significa que você deve corrigir a rede ou o proxy reverso antes de alterar as configurações do WOPI.

Verifique primeiro os URLs públicos de descoberta e recursos do Collabora; ambos devem ser acessíveis pelo mesmo nome de host usado pela integração.

Para obter orientações oficiais sobre endpoints, consulte a seção de solução de problemas do Nextcloud Office e o manual do SDK do Collabora Online 25.04 .

2. Teste todas as quatro direções da rede, não apenas o navegador.

Um erro comum é presumir que, pelo fato de office.example.como Collabora abrir em um navegador de desktop, ele também consegue buscar arquivos no servidor de armazenamento. Isso não é garantido. Teste a partir dos hosts ou contêineres reais:

# From the Nextcloud/storage server
curl -fsS https://office.example.com/hosting/discovery >/dev/null && echo OK

# From the Collabora host/container
curl -fsS https://cloud.example.com/status.php

# Then inspect Collabora logs
docker logs --tail 100 collabora

Se o nome de host público for resolvido de forma diferente dentro do Docker, Kubernetes ou em uma rede privada, decida se deve corrigir o DNS interno, adicionar um mapeamento de host apropriado ou rotear pelo endpoint público. O DNS interno geralmente é mais organizado em grande escala; uma entrada no arquivo hosts é rápida para uma pequena instalação estática, mas torna-se mais difícil de manter.

Execute testes de acessibilidade a partir dos próprios servidores e, em seguida, use o log do Collabora para diferenciar uma falha de rede de uma falha de confiança WOPI.

3. Corrija o proxy reverso se as rotas WebSocket ou Collabora estiverem ausentes.

O Collabora não é uma aplicação web estática comum. Seu proxy reverso precisa de rotas para recursos do navegador, descoberta/capacidades, tráfego de documentos e WebSockets. No manual do SDK do Collabora, o exemplo do Nginx encaminha /browsero /hosting/discoverycaminho /hosting/capabilitiesdo /cool/.../wsWebSocket e /coolo tráfego relacionado /lool.

Para a rota WebSocket, o proxy deve preservar o host e permitir a atualização HTTP. Um padrão simplificado do Nginx é:

location ~ ^/cool/(.*)/ws$ {
    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 $host;
    proxy_read_timeout 36000s;
}

Não copie isso cegamente se você encerra o TLS de forma diferente. A Collabora documenta padrões separados para o encerramento de ponta a ponta de TLS e SSL. Se o TLS for encerrado no Nginx e a conexão de backend for HTTP, as configurações SSL internas da Collabora devem corresponder a esse padrão. Usar HTTPS em todos os lugares é mais simples de entender, enquanto o encerramento de TLS no proxy reduz o gerenciamento de certificados dentro dos contêineres, mas introduz uma nova barreira de configuração.

Um proxy reverso correto deve encaminhar as rotas HTTP do Collabora e preservar a atualização do WebSocket para a sessão do documento.

4. Verifique a consistência do protocolo, certificado e nome do host.

A documentação atual de configuração do Office do Nextcloud afirma que o servidor Collabora Online deve usar o mesmo protocolo da instalação do Nextcloud, sendo o HTTPS recomendado. Na prática, configurações mistas de HTTP/HTTPS públicas podem resultar em conteúdo bloqueado, redirecionamentos incorretos ou falhas na validação do certificado de backend.

Verifique estes itens em conjunto:

• O URL do Collabora salvo em sua plataforma de armazenamento é o mesmo URL público que os usuários acessam.
• O certificado apresentado por esse nome de host é válido para o nome de host e é confiável para o servidor de armazenamento.
• A Collabora pode validar o certificado HTTPS do servidor de armazenamento.
• Seu proxy reverso encaminha corretamente o host e o esquema originais.
• Não há redirecionamento do nome de host Collabora configurado para outro nome de host que o WOPI não espere.

Um certificado autoassinado pode ser aceitável em um ambiente de laboratório se cada componente estiver explicitamente configurado para confiar nele, mas essa conveniência sacrifica a portabilidade e frequentemente causa falhas em atualizações ou reconstruções de contêineres posteriormente. Para produção, uma cadeia de certificados publicamente confiável ou confiável pela organização é a opção mais segura.

5. Corrija as listas de permissões do WOPI em vez de desativá-las.

Se a descoberta funcionar e os logs do Collabora mostrarem mensagens como " Unauthorized WOPI hostnenhum host WOPI aceitável correspondendo ao destino", o problema passou de conectividade básica para configuração de confiança. A documentação oficial de solução de problemas do Nextcloud direciona especificamente os administradores para os logs do contêiner neste caso.

No que diz respeito ao armazenamento, o Nextcloud recomenda restringir as solicitações WOPI aos endereços IP dos servidores Collabora usando a configuração "Lista de permissões para solicitações WOPI" . No lado do Collabora, os hosts de armazenamento WOPI permitidos devem corresponder aos URLs de armazenamento que o Collabora realmente recebe. Para vários domínios de armazenamento, o SDK atual do Collabora documenta os grupos de aliases WOPI.

Mantenha o URL do servidor Collabora e a lista de permissões WOPI alinhados com a implementação real; use entradas confiáveis ​​restritas em vez de desativar a validação.

Consulte a configuração do Nextcloud Office para obter o URL atual do servidor e as orientações sobre a lista de permissões WOPI. Se você usa o ownCloud Infinite Scale, o serviço de colaboração utiliza COLLABORATION_APP_ADDRo endereço IP do aplicativo Office e COLLABORATION_WOPI_SRCo endereço de origem WOPI acessível externamente; consulte a documentação do serviço de colaboração do ownCloud .

Quando você deve usar o CODE integrado em vez de um servidor Collabora separado?

Para uma instalação pequena do Nextcloud, o servidor CODE integrado reduz o número de componentes gerenciados externamente. A desvantagem é que ele ainda depende da instância do Nextcloud conseguir se conectar através do nome de host usado no navegador. A documentação de solução de problemas do Nextcloud menciona isso diretamente e sugere resolver o nome de host corretamente quando o CODE integrado não conseguir se conectar.

Um servidor Collabora separado geralmente é mais adequado quando você precisa de escalonamento independente, serviço centralizado para várias instâncias de armazenamento ou uma arquitetura de produção com limites de recursos mais claros. Ele adiciona configuração de DNS, proxy, certificado, firewall e confiança WOPI, portanto, a carga operacional é maior.

O que não fazer

• Não desative a validação WOPI como primeira solução. Isso pode ocultar a incompatibilidade real do nome do host e enfraquecer a segurança.
• Não exponha a porta 9980 diretamente só porque o proxy está falhando. Corrija o proxy, a menos que a exposição direta seja intencional e tenha sido projetada com segurança.
• Não assuma que uma resposta 200 da página inicial do Collabora comprove que a edição de documentos está funcionando. Descoberta, recursos, acesso a arquivos WOPI e WebSockets são caminhos distintos.
• Não altere várias camadas de uma só vez. Teste após cada alteração para saber se a causa real do problema estava no DNS, TLS, proxy ou na confiança WOPI.

Lista de verificação final

Após efetuar uma alteração, verifique o sistema nesta ordem:

1. Abra /hosting/discoveryo /hosting/capabilitiesnavegador.
2. Recupere os mesmos endpoints do servidor de armazenamento.
3. A partir do servidor Collabora, obtenha o URL de status do servidor de armazenamento.
4. Abra um documento enquanto monitora os registros do Collabora e do armazenamento.
5. Confirme se o navegador estabelece a conexão WebSocket do Collabora sem desconexões repetidas.
6. Confirme se um segundo usuário pode abrir e editar um documento de teste, caso seja necessária a edição colaborativa.

Se todas as seis verificações forem bem-sucedidas, a mensagem genérica "Bem, isso é constrangedor" não deverá mais mascarar uma falha de conexão. Se a mensagem persistir, capture as linhas exatas do log do Collabora e a falha de rede do navegador para uma tentativa de abertura de documento; essas duas evidências são mais úteis do que a própria mensagem genérica da interface do usuário.