Implante o Collabora CODE no Kubernetes com o Helm.
Instale o gráfico Helm oficial da Collabora, configure o acesso WOPI e a afinidade de entrada e verifique a implantação sem erros comuns de configuração.
Rastrear um documento em branco do Collabora até a camada com falha
Comece verificando se a tela em branco afeta um arquivo específico ou todos os arquivos. Em seguida, inspecione os painéis de Rede e Console do navegador, juntamente com os registros do Collabora e da plataforma de armazenamento. Uma tela em branco é um sintoma, não um diagnóstico: o editor pode ter sido carregado enquanto a conexão com o documento, a autorização WOPI ou os recursos incorporados falharam.
1. Determine se o problema está no arquivo, no navegador ou no serviço.
Abra um documento funcional no mesmo aplicativo e, em seguida, tente abrir o arquivo afetado em outro navegador compatível ou em uma janela anônima. Não edite o arquivo original durante o diagnóstico. Um único arquivo com problemas indica uma falha no formato, conteúdo ou permissões; falhas generalizadas apontam para serviços compartilhados ou alterações na rede.
| O que você observa | A próxima verificação mais útil | Troca |
|---|---|---|
| Um dos documentos está em branco. | Experimente com um arquivo diferente, mas do mesmo formato; inspecione os registros de arquivos e WOPI do aplicativo de armazenamento. | Isolamento rápido, mas não descarta um problema específico de análise ou permissão do arquivo. |
| Todos os documentos falham em um navegador. | Janela privada, outro navegador, extensões e console do navegador. | De baixo risco e rápido, mas uma solução alternativa no navegador não resolve um problema no servidor. |
| Todos os usuários e navegadores falham | Requisições de rede, proxy reverso, política de host WOPI e logs do servidor. | Possui maior valor diagnóstico, mas as alterações podem afetar todos os usuários; primeiro, registre as configurações atuais. |
Uma janela anônima é um teste, não uma solução. Se funcionar nela, desative as extensões uma de cada vez ou limpe os dados do site afetado somente depois de confirmar que não há trabalhos não sincronizados. Limpar todos os dados do navegador pode desconectar os usuários e remover o estado de sites irrelevantes.
2. Localize a solicitação que falhou antes de alterar as configurações.
No Chrome ou Chromium, abra as Ferramentas do Desenvolvedor ( F12 ou Ctrl+Shift+I ), selecione Rede , ative Preservar registro e recarregue a página. Filtre por WS (WebSocket) e inspecione as falhas; a referência de Rede das Ferramentas do Desenvolvedor do Chrome explica os filtros de requisição e os detalhes de status. Verifique o Console em busca de erros de CSP, certificado, conteúdo misto ou JavaScript.
Interprete as evidências em vez de aplicar uma receita genérica por procuração:
- Erro 404 em recursos ou
/browser/caminhos do editor: verifique se o proxy reverso está encaminhando os caminhos atuais do Collabora para o servidor upstream correto. - Erros 502, tempo limite excedido ou um WebSocket que se fecha imediatamente: verifique a acessibilidade do servidor upstream, os logs do proxy, o tratamento do WebSocket e o caminho da requisição. Um
/hosting/discoveryendpoint acessível comprova apenas o acesso HTTP básico; não comprova que a conexão ativa do editor esteja funcionando. - Erro 403 ou “Host WOPI não autorizado” nos logs: verifique se o host de armazenamento mencionado na URL WOPI está listado entre os hosts WOPI permitidos pela Collabora.
- Erro de CSP ou certificado: corrija a origem exata da incorporação ou a cadeia de certificados. Não desative a segurança do navegador nem flexibilize amplamente uma Política de Segurança de Conteúdo (CSP) para que a tela carregue.
Para solicitações WebSocket, o objetivo é um handshake bem-sucedido; o status exibido depende da versão HTTP e do caminho do proxy, portanto, não considere um único número de status esperado como universal.
3. Associe a correção à camada com falha.
Verifique ambas as direções e o esquema da URL.
As diretrizes de solução de problemas atuais do Nextcloud indicam que o navegador do usuário deve acessar ambos os servidores via HTTP(S), o Nextcloud deve acessar o Collabora e o Collabora deve acessar o Nextcloud. Também é necessário que ambos os serviços utilizem o mesmo protocolo. Teste o endereço público do Collabora em um navegador em https://office.example.com/hosting/discoverye https://office.example.com/hosting/capabilities. No host do Nextcloud, use:
curl -fsS https://office.example.com/hosting/discovery -o /dev/null
curl -fsS https://office.example.com/hosting/capabilities -o /dev/null
Substitua o nome de host de exemplo pelo seu URL real do Collabora. Essas verificações estabelecem a conectividade HTTP, não a edição bem-sucedida. Se o servidor funcionar, mas o navegador falhar, verifique o DNS público, o TLS, o firewall ou a exposição do proxy. O guia de solução de problemas do Nextcloud Office lista essas verificações de conexão e recomenda a revisão dos logs de ambos os aplicativos.
Reparar o roteamento do proxy somente quando as solicitações o implicarem.
Se os recursos do editor estático retornarem 404 ou a conexão em tempo real retornar 502, compare as rotas do seu proxy reverso com as configurações oficiais de proxy da Collabora . Certifique-se de que o proxy envie os caminhos necessários da Collabora para o servidor upstream correto e que suporte a conexão WebSocket usada pelo navegador. Preserve as informações de host externo e HTTPS esperadas pela sua implementação. Não copie uma configuração para um proxy, prefixo de URL ou versão da Collabora diferente sem verificar suas premissas. Um nome de host dedicado para a Collabora geralmente é mais fácil de depurar; o roteamento baseado em caminho requer um tratamento consistente de prefixos.
Corrija as listas de permissões WOPI sem torná-las públicas.
WOPI é o protocolo que o Collabora usa para buscar e salvar um documento por meio da plataforma de armazenamento. O host WOPI geralmente é o host do Nextcloud ou de outro serviço de armazenamento, e não o host do Collabora. Se os logs indicarem que o host WOPI não foi encontrado No acceptable WOPI hosts found, adicione ou corrija o host de armazenamento exato na configuração de host WOPI do Collabora e, em seguida, confirme se a lista de permissões de solicitações WOPI da plataforma de armazenamento contém o endereço do servidor Collabora. O Nextcloud recomenda limitar as solicitações WOPI aos endereços IP esperados do Collabora e configurar o Collabora para confiar nos hosts esperados, conforme indicado em seu guia de configuração do Office .
Adicionar um host confiável específico é mais seguro do que desativar a validação de host ou permitir domínios amplos. Registre a configuração atual, altere apenas a entrada relevante e reinicie ou recarregue os serviços somente quando necessário para sua implantação. Se você usa Docker, inspecione a saída recente do Collabora com docker logs --since=10m <collabora-container>`docker-compose up`; substitua o marcador pelo nome real do contêiner. Para instalações de pacotes ou Kubernetes, use os logs de serviço ou de pod.
4. Verifique o editor, não apenas o endpoint de integridade.
Recarregue o mesmo documento. Confirme se os recursos são carregados, se a conexão em tempo real permanece aberta, se o conteúdo aparece e se os erros no Console param. Teste com um segundo documento e com outro usuário, caso o problema ocorra com ambos. Salve uma edição de teste inofensiva e abra-a novamente para verificar se a leitura e o salvamento estão funcionando corretamente.
Se a tela em branco permanecer, mas as solicitações agora forem bem-sucedidas, verifique os logs do servidor em busca de erros de conversão de documentos ou erros específicos do arquivo e compare com outro arquivo no mesmo formato. Se o problema começou imediatamente após uma atualização do Collabora, do navegador ou do proxy, teste um rollback controlado ou uma alteração de proxy específica da versão em uma janela de manutenção, em vez de alterar várias variáveis de uma só vez. A limpeza do cache do navegador só é útil quando há indícios de arquivos de cliente desatualizados; ela não pode corrigir rotas bloqueadas ou solicitações WOPI rejeitadas.
Rastrear um documento em branco do Collabora até a camada com falha
Use solicitações do navegador, registros WOPI e verificações de proxy direcionadas para descobrir por que o Collabora abre um documento em branco e escolha uma solução que se adeque às evidências.
Ativar verificação ortográfica multilíngue no Collabora Online CODE
Configure os dicionários do CODE Docker e marque as passagens do documento corretamente para que o inglês, o francês e outros idiomas suportados recebam a verificação ortográfica adequada.
Defina o temporizador de inatividade do Collabora para visualizações de documentos ativos.
Ajuste o limite de inatividade por visualização no coolwsd e diferencie-o do escurecimento da aba em segundo plano, do descarregamento de documentos, do salvamento automático e da expiração de login.
Desative as verificações de atualização do Collabora CODE e as conexões indesejadas.
Interrompa as verificações de atualização de código agendadas, revise os serviços remotos opcionais e use os controles de rede de saída sem interromper a edição de documentos.
Conecte o Seafile e colabore com o URL WOPI correto.
Habilite a edição segura de documentos no Seafile configurando o URL de descoberta do Collabora, o HTTPS e o acesso WOPI para sua implementação.
Restaurar a função copiar e colar entre os aplicativos Collabora e Desktop.
Teste a área de transferência do sistema, ajuste as permissões do navegador e identifique quando uma integração incorporada do Collabora precisa de uma alteração na política de iframe.
Disponibilize fontes personalizadas no Collabora CODE Docker.
Integre os arquivos de fonte ao Docker e ao systemplate do Collabora para que as fontes personalizadas apareçam no editor e sejam renderizadas corretamente nos documentos.
Restaurar configurações do Collabora CODE sem perder as alterações de implantação
Faça backup do arquivo coolwsd.xml e de suas fontes de implantação, restaure-os com segurança e verifique o código antes que os usuários voltem a editá-lo.
Corrija a verificação de host WOPI do CODE fazendo a correspondência da origem do host.
Permita a origem exata do Nextcloud ou de outro servidor WOPI no código e, em seguida, verifique a lista de permissões do host ativo e diferencie-a da restrição de IP de origem do Nextcloud.