Coloque o Collabora atrás do Nginx sem quebrar o WebSockets

Configure o Collabora em um hostname HTTPS dedicado no Nginx, encaminhe os caminhos de edição e descoberta para ` coolwsd<nome_do_servidor>` e passe explicitamente os cabeçalhos de atualização do WebSocket nas rotas de socket ativas. Para um único host, o Nginx pode encerrar o TLS público e enviar HTTP para o Collabora em uma interface privada; se o Nginx e o Collabora estiverem em contêineres diferentes, use o nome do serviço Collabora na rede compartilhada em vez de `<nome_do_serviço>` 127.0.0.1.

Este exemplo pressupõe que os usuários abram o servidor https://office.example.come que o Nginx gerencie o certificado. A porta de escuta padrão do Collabora é 9980; use a porta acessível em sua implementação. Um prefixo de URL como `<nome_do_usuário>` https://example.com/collabora/requer configurações coordenadas de caminho e de host raiz do serviço; portanto, esta configuração de host raiz não será aplicada sem alterações.

1. Defina o mapeamento de conexões upstream e WebSocket.

No httpcontexto do Nginx, adicione um nome upstream para o Collabora e um mapa que defina o cabeçalho de conexão para upgradesomente quando um cliente solicitar um WebSocket. Coloque este bloco fora de qualquer outro serverbloco. Substitua o endereço se o Nginx acessar o Collabora de outra forma.

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

upstream coolwsd {
    server 127.0.0.1:9980;
}

Se o Nginx for um contêiner, o parâmetro `--upstream` 127.0.0.1se refere a esse contêiner do Nginx, e não ao contêiner do Collabora. Em uma rede Docker compartilhada, o upstream pode ser `--upstream` server collabora:9980;, usando o nome do serviço que é resolvido nessa rede.

2. Adicione o host virtual HTTPS e as rotas do Collabora.

Dentro do serverbloco HTTPS para office.example.com, encaminhe os recursos do navegador, os endpoints de descoberta, as conexões WebSocket e os caminhos restantes do Collabora. Os locais seguem as diretrizes de proxy do Collabora. Mantenha os locais de socket específicos acima da rota cool/ mais ampla loolpara que o Nginx aplique os cabeçalhos WebSocket corretamente.

server {
    listen 443 ssl;
    server_name office.example.com;

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/private-key.pem;

    location ^~ /browser {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
    }

    location ^~ /hosting/discovery {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
    }

    location ^~ /hosting/capabilities {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
    }

    location ~ ^/cool/(.*)/ws$ {
        proxy_pass http://coolwsd;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }

    location ^~ /cool/adminws {
        proxy_pass http://coolwsd;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }

    location ~ ^/(c|l)ool {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Substitua os caminhos dos certificados pelos arquivos do seu host. Se a sua instalação não utiliza o console de administração, o /cool/adminwslocal pode não ser necessário para a edição de documentos; a /cool/.../wsrota principal é essencial. O proxy_read_timeoutvalor de uma hora aqui é apenas um exemplo, não um requisito universal. O tempo limite de leitura padrão do proxy do Nginx é de 60 segundos entre leituras sucessivas. Escolha um valor maior do que os períodos ociosos necessários para suas sessões ou utilize o tráfego de ping do WebSocket, quando compatível.

3. Combine o modo TLS da Collabora com o salto do proxy.

Os usuários devem acessar o Collabora via HTTPS, mesmo quando o salto privado do Nginx para o Collabora usar HTTP. Nesse cenário de terminação TLS, configure coolwsdo proxy para ser tratado como o terminador TLS: o SSL é desativado no listener interno e a terminação SSL é ativada. Aplique essas configurações pelo método compatível com seu pacote ou imagem de contêiner e, em seguida, reinicie/recarregue o Collabora conforme indicado na documentação.

Use um servidor upstream HTTP somente em uma rede privada confiável e bloqueie o acesso público à porta 9980. Se a política exigir criptografia entre o Nginx e o Collabora, use um servidor upstream HTTPS e configure a verificação de certificado corretamente; não desative a verificação para ocultar uma incompatibilidade de certificado. A documentação de configurações de proxy do Collabora distingue SSL no proxy de SSL entre o proxy e o servidor coolwsd.

Configure também o URL do Collabora na integração de armazenamento para o nome de host HTTPS público. Para o Nextcloud, o manual de administração exige que o navegador e ambos os servidores consigam se comunicar via HTTP(S), com protocolos externos compatíveis. Restrinja a lista de permissões do WOPI ao host de armazenamento esperado e ao endereço do Collabora; não a amplie amplamente para resolver um erro de roteamento de proxy.

4. Teste a configuração de ambos os lados.

Verifique a sintaxe do Nginx antes de recarregá-lo:

sudo nginx -t
sudo systemctl reload nginx

Se o Nginx estiver sendo executado em um contêiner, use o procedimento de validação e recarregamento desse contêiner. No host do Nextcloud, teste os endpoints públicos do Collabora com o nome de host real:

curl -fsS https://office.example.com/hosting/discovery -o /dev/null
curl -fsS https://office.example.com/hosting/capabilities -o /dev/null

Abra também esses URLs HTTPS a partir do navegador do usuário. Eles verificam a acessibilidade, mas uma resposta de descoberta bem-sucedida por si só não comprova que a edição do documento funciona. Abra um documento e use o painel de Rede do navegador para confirmar se os recursos são carregados e se a /cool/.../wsconexão permanece aberta. Um WebSocket HTTP/1.1 bem-sucedido geralmente exibe o código 101 Switching Protocols; a exibição exata pode depender do navegador e do protocolo de transporte. Se essa configuração padrão funcionar no Firefox, mas falhar no Chromium, inspecione o método e o protocolo da solicitação. Um relatório de problema do Collabora aberto para a versão 25.04 documenta um WebSocket do Chromium sobre HTTP/2 usando CONNECTe recebendo 405; ele permanece aberto, conforme verificado em 9 de outubro de 2026. Este é um relatório específico da versão, não um comportamento universal. Compare suas versões do Collabora, Nginx e navegador antes de alterar as configurações do HTTP/2. Consulte o problema 12155 do Collabora .

Se a descoberta falhar, inspecione o log de erros do Nginx e verifique o nome do host, a porta e o protocolo do servidor upstream. Se a descoberta funcionar, mas a edição não conectar, verifique a rota do WebSocket, os cabeçalhos, o tempo limite e os logs do Collabora. Um erro de autorização WOPI indica um problema na lista de permissões do host de armazenamento. O guia de solução de problemas do Nextcloud Office recomenda verificar a acessibilidade a partir do navegador, do Nextcloud e do Collabora e, em seguida, revisar os logs de ambos os servidores.

O guia de proxy WebSocket do Nginx explica por que os parâmetros `--route` Upgradee Connection`--timeout` devem ser passados ​​explicitamente e por que o comportamento do tempo limite de inatividade é importante. Consulte a referência do módulo proxy do Nginx para obter informações sobre o comportamento da diretiva. Depois que as verificações forem aprovadas, abra, edite, salve e reabra um documento de teste antes de convidar os usuários a utilizarem a nova rota.