Rastreie o upstream para limpar o erro 502 do Nginx da ONLYOFFICE.

Comece verificando a conexão entre o Nginx e o ONLYOFFICE Docs e, em seguida, leia o log de erros correspondente à resposta 502. Um erro 502 Bad Gateway significa que um gateway não conseguiu obter uma resposta válida do servidor upstream; isso, por si só, não prova que a configuração pública do Nginx seja a causa. No Docker, a solução usual é direcionar o Nginx para o nome do serviço do Servidor de Documentos na porta interna 80 e garantir que ambos os contêineres compartilhem a mesma rede.

O que você deve verificar antes de editar o Nginx?

Um proxy reverso é um servidor que aceita uma solicitação do cliente e a encaminha para outro servidor. Em uma implementação comum, o Nginx público lida com HTTPS e encaminha as solicitações para o ONLYOFFICE Docs via HTTP. O ONLYOFFICE Docs também executa seu próprio Nginx internamente, portanto, uma página 502 pode ser gerada pelo proxy externo ou pelo próprio contêiner do servidor de documentos.

Primeiro, identifique qual servidor emitiu a resposta. Compare o cabeçalho do servidor da página e o carimbo de data/hora com o log do proxy externo e os logs do servidor de documentos. Para uma configuração Docker, verifique o status do contêiner e as mensagens de inicialização recentes:

docker ps --filter name=onlyoffice-documentserver
docker logs --tail 100 onlyoffice-documentserver

Se o contêiner estiver reiniciando ou tiver acabado de iniciar, verifique o log antes de alterar as configurações de proxy. A ONLYOFFICE observa que a primeira inicialização pode levar um ou dois minutos enquanto o banco de dados é inicializado. Para uma instalação nativa do Linux, verifique com ds-docservice; os logs do Document Server estão em .ds-convertersystemctl status/var/log/onlyoffice/documentserver/

Se um serviço for interrompido, utilize as instruções oficiais de resolução de problemas do ONLYOFFICE para Linux.

O Nginx consegue alcançar o servidor de documentos upstream?

Faça o teste a partir do contêiner ou host do Nginx, não apenas do seu laptop. Contêineres em redes Docker separadas não conseguem se resolver pelo nome do serviço, mesmo quando ambos estão em execução. Quando o Nginx e o ONLYOFFICE compartilham uma rede Docker definida pelo usuário, use o nome do serviço Compose ou um nome de contêiner resolúvel e a porta de escuta do contêiner. O guia de instalação oficial do Docker identifica a porta 80 como a porta de escuta padrão do Servidor de Documentos; uma porta de host publicada, como 8080:80, não altera a porta interna.

A partir do contêiner proxy, execute:

curl -I http://onlyoffice-documentserver:80/

Substitua onlyoffice-documentserverpelo nome real do seu serviço Compose. Se a solicitação retornar "Não foi possível resolver o host", conecte ambos os contêineres à mesma rede Docker ou corrija o nome do serviço upstream. "Conexão recusada" geralmente significa que o host de destino foi resolvido, mas nenhuma conexão está sendo aceita nessa porta, o contêiner não está pronto ou a porta usada está incorreta. Se esta for uma instalação nativa, teste o endereço local e a porta configurada, por exemplo curl -I http://127.0.0.1/.

O guia do Docker da ONLYOFFICE aborda a porta padrão, mapeamentos de portas, atraso na inicialização e logs do contêiner: Instalação e verificação do Docker .

Como corrigir o alvo do proxy Nginx?

No host virtual HTTPS para o nome de host ONLYOFFICE, aponte proxy_passpara o servidor upstream acessível. Este exemplo pressupõe uma rede Docker compartilhada e o nome do serviço mostrado acima; altere-o para corresponder à sua implementação:

location / {
    proxy_pass http://onlyoffice-documentserver:80;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Não aponte um proxy em contêiner para 127.0.0.1:8080um servidor de documentos a menos que este esteja realmente escutando no mesmo contêiner ou que o endereço do host esteja configurado intencionalmente e acessível. Dentro de um contêiner, 127.0.0.1isso significa o próprio contêiner. Além disso, evite enviar HTTPS para o servidor upstream quando o endpoint do servidor de documentos for HTTP simples.

O protocolo e o host encaminhados informam ao ONLYOFFICE qual URL pública o cliente utilizou, e os cabeçalhos de atualização permitem conexões WebSocket usadas para comunicação em tempo real com o editor. O ONLYOFFICE fornece exemplos com suporte para executar a documentação por trás de um proxy , incluindo sua configuração Nginx HTTPS-para-HTTP . Compare com esse exemplo completo se o seu ambiente tiver vários saltos de proxy ou usar um prefixo de caminho de URL.

Antes de aplicar as alterações, valide a configuração com ` nginx -tnginx checkout`, e então recarregue o Nginx usando o método apropriado para seu host ou contêiner. Não reinicie todos os serviços de uma vez; uma recarga controlada facilita a verificação se a correção upstream alterou o resultado.

E se o ONLYOFFICE ainda retornar um erro 502?

Se o proxy externo conseguir acessar a página inicial do Document Server, mas /healthcheckretornar um erro 502, o problema pode estar no próprio Document Server e não no Nginx público. Verifique os logs do contêiner do Document Server e os logs internos do serviço. Para instalações nativas em Linux, revise os comandos de status do serviço e o diretório de logs mencionados acima. Se /welcome/o serviço responder, mas a verificação de integridade não, trate-os como sinais separados: uma página inicial estática não comprova que o serviço de documentos e suas dependências estejam funcionando corretamente.

Não tente "corrigir" isso desativando o JWT. A validação do JSON Web Token (JWT) autentica as solicitações de integração; uma incompatibilidade de JWT geralmente causa um erro de autorização, e não uma impossibilidade de conexão com um servidor upstream em nível de rede. Verifique as configurações de JWT somente se o proxy responder, mas a integração reportar um erro de autorização ou de token.

Por fim, confirme se o Nginx está roteando o nome de host correto para o host virtual correto. Um erro de digitação em `<hostname>` server_name, nome DNS upstream ou porta pode enviar o tráfego para outro lugar ou fazer com que o proxy use uma configuração desatualizada. Verifique o log de erros do Nginx em busca de linhas como `<hostname>` host not found in upstream, connect() failed`<port>` ou `<port> upstream timed out`; cada uma aponta para uma camada diferente.

Como verificar se a correção foi feita?

Teste novamente a conexão upstream a partir da rede proxy, verifique o endpoint de saúde pública e abra um documento através da plataforma conectada:

curl -I https://docs.example.com/healthcheck

Uma resposta bem-sucedida na verificação de integridade não deve mais ser um erro 502, e um documento real deve abrir e permanecer conectado durante a edição. Se o teste upstream for bem-sucedido, mas a solicitação pública ainda falhar, concentre-se no host virtual Nginx selecionado, em sua configuração carregada e em seus logs. Se a página de boas-vindas pública funcionar, mas a verificação de integridade continuar com erro 502, continue com o diagnóstico de serviço interno do ONLYOFFICE.

Para informações sobre o comportamento das diretivas do Nginx, consulte a documentação oficial do módulo proxy do Nginx . Os comandos e nomes de serviço exatos podem variar de acordo com o projeto Docker Compose, a distribuição Linux e a versão do ONLYOFFICE; portanto, substitua os nomes pelos seus próprios e verifique os logs do componente que gerou a resposta.