Como corrigir o erro 502 Bad Gateway do servidor de documentos ONLYOFFICE atrás do Nginx

Um navegador exibe o erro “502 Bad Gateway” ao abrir um URL do ONLYOFFICE Docs, ou um conector Nextcloud/ownCloud não consegue acessar o servidor de documentos. Em ambos os casos, o Nginx geralmente recebe uma solicitação, mas não consegue obter uma resposta válida do seu servidor upstream. O servidor upstream pode ser o serviço de documentos interno do ONLYOFFICE, um contêiner Docker ou outro proxy reverso. Primeiro, identifique qual Nginx retornou o erro 502; em seguida, teste o próximo salto diretamente antes de alterar a configuração.

O guia de solução de problemas do ONLYOFFICE para Linux recomenda verificar os ds-docserviceserviços ds-convertere os logs do Servidor de Documentos. O guia de proxy reverso também menciona os cabeçalhos de host e protocolo encaminhados. A sequência abaixo verifica primeiro a integridade do serviço e, em seguida, o roteamento do Nginx e a rede do Docker.

1. Descubra qual Nginx está retornando o erro 502.

A instalação do pacote ONLYOFFICE inclui sua própria configuração do Nginx, e uma implantação também pode ter um proxy reverso Nginx externo. O Docker pode adicionar mais um salto de rede. A aparência da página 502 por si só pode não identificar a camada, portanto, compare o URL público com uma verificação de integridade local e o log de erros do Nginx.

Em uma instalação Linux baseada em pacotes, teste o endpoint local do Servidor de Documentos:

curl -i http://127.0.0.1/healthcheck

Se o servidor estiver configurado para servir o ONLYOFFICE em uma porta local não padrão, use essa porta. Uma instalação saudável normalmente retorna uma resposta HTTP de sucesso com true. Se essa solicitação local falhar, corrija o serviço do Servidor de Documentos antes de editar um proxy externo. Se a solicitação for bem-sucedida localmente, mas o nome de host público retornar 502, concentre-se no upstream externo do Nginx, no protocolo, nos cabeçalhos e no caminho do firewall.

Verifique quais processos possuem as portas esperadas:

sudo ss -ltnp | grep -E ':(80|443|8080|8000)\b'

As portas variam de acordo com a topologia. Um mapeamento comum do Docker publica uma porta do host, como 8080, para a porta 80 do contêiner; a instalação de um pacote pode usar seu próprio Nginx no host. Não assuma que esse 127.0.0.1:80seja o upstream correto simplesmente porque ambos os serviços estão na mesma máquina.

2. Verifique os serviços e registros do ONLYOFFICE.

Em uma instalação de pacote Linux, inspecione o serviço de documentos e o conversor:

sudo systemctl status ds-docservice ds-converter
sudo journalctl -u ds-docservice -u ds-converter --since "15 minutes ago" --no-pager

O guia de solução de problemas do ONLYOFFICE lista esses serviços e identifica memória insuficiente, conflito na porta 80 e logs de serviço como itens a serem verificados quando os serviços do Docs não iniciam. Se um serviço estiver parado, verifique primeiro o erro; em seguida, reinicie apenas o serviço afetado.

sudo systemctl restart ds-docservice

O diretório principal de logs do Linux é ` /var/log/onlyoffice/documentserver//var/logs`. Verifique o log de erros do Nginx e os logs do docservice em busca de mensagens como "conexão recusada", "tempo limite do upstream excedido" ou um arquivo ausente. Essas mensagens indicam causas diferentes: uma conexão recusada geralmente significa que o processo ou a porta upstream está indisponível, enquanto um tempo limite excedido pode significar que o serviço está sobrecarregado ou travado.

Verifique também o espaço em disco e a memória disponíveis caso os serviços estejam sendo encerrados repetidamente:

df -h
free -h

Não reinicie um serviço com falhas repetidamente sem antes analisar seus registros; uma reinicialização pode mascarar temporariamente o sintoma sem corrigir um conflito de portas, uma dependência com falha ou um problema de recursos.

3. Verifique se o Nginx está apontando para o servidor upstream acessível.

Leia o host virtual ativo e confirme o endereço e a porta exatos proxy_pass. A partir da máquina ou do contêiner onde o Nginx está em execução, faça uma solicitação direta ao servidor upstream. Por exemplo, se o contêiner publicar a porta 80 como porta 8080 do host:

curl -i http://127.0.0.1:8080/healthcheck

Substitua o endereço de exemplo pelo endpoint que realmente pode ser alcançado a partir do proxy. Se o Nginx estiver sendo executado em um contêiner Docker separado, o 127.0.0.1endereço se refere ao próprio contêiner Nginx, e não ao host Docker ou ao contêiner ONLYOFFICE. Use um nome de serviço acessível em uma rede Docker compartilhada ou o endereço do host e a porta publicada corretos.

Verifique se o esquema de encaminhamento (upstream) corresponde ao do backend. Use-o http://se o listener do backend estiver em HTTP puro e https://somente se estiver configurado para TLS. Enviar HTTP para uma porta TLS, ou TLS para uma porta HTTP pura, pode fazer com que um serviço em funcionamento pareça indisponível para o Nginx.

4. Verifique os cabeçalhos encaminhados e o proxy WebSocket.

O guia de proxy reverso da ONLYOFFICE recomenda preservar o protocolo e o nome do host originais X-Forwarded-Protopara X-Forwarded-Hostque o aplicativo os conheça. Os exemplos oficiais do Nginx também repassam os cabeçalhos de atualização. Se houver um proxy externo na frente da ONLYOFFICE, compare a configuração dele com o cenário oficial que corresponde à sua topologia.

Abaixo, você encontrará um exemplo simplificado de um contêiner Docker mapeado para a porta 8080 do host. Insira a mapdiretiva no httpcontexto do Nginx e adapte o nome do host, a configuração TLS e a porta upstream à sua configuração:

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

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

    location / {
        proxy_pass http://127.0.0.1:8080;
        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 $connection_upgrade;
    }
}

Este é um padrão de referência, não um substituto direto para todas as instalações. Em particular, não o copie e cole sobre a configuração do Nginx incluída no pacote ONLYOFFICE sem entender qual bloco de servidor possui as portas 80 e 443. Se o Nginx compartilhar o host com o ONLYOFFICE instalado por pacote, primeiro confirme se não há conflito de portas e direcione o proxy externo para o listener interno configurado para sua implantação.

Após editar, teste a configuração antes de recarregar o Nginx:

sudo nginx -t
sudo systemctl reload nginx

Se o teste de configuração falhar, corrija o arquivo e a linha relatados antes de recarregar. Um erro de sintaxe e um erro 502 do servidor upstream são problemas distintos; um teste bem-sucedido nginx -tconfirma a sintaxe, não que o servidor upstream esteja respondendo.

5. Se o ONLYOFFICE estiver sendo executado no Docker, verifique seu estado de funcionamento e o mapeamento de portas.

Verifique se o contêiner está em execução e qual porta do host está publicada:

docker ps --filter name=onlyoffice
docker port <container_name_or_id>
docker logs --tail 100 <container_name_or_id>

O guia oficial de instalação do Docker mapeia as portas do host para a porta 80 do contêiner, e o exemplo verifica os logs do contêiner caso a página de boas-vindas não carregue. Use a porta exibida docker portcomo upstream do host. Quando o Nginx e o ONLYOFFICE estiverem em contêineres, coloque-os em uma rede compartilhada e direcione o tráfego para o nome do serviço ONLYOFFICE e a porta do contêiner, em vez do endereço de loopback do host.

Verifique o estado de integridade do contêiner se o seu arquivo Compose definir uma verificação de integridade. O exemplo atual do Compose verifica o estado de integridade http://localhost:8000/info/info.jsondentro do contêiner. Um contêiner que está "em execução" ainda pode ter um serviço de documentos com problemas. Se ele estiver reiniciando ou apresentar problemas, use os logs para investigar a inicialização do banco de dados, a memória e a configuração antes de alterar o proxy externo.

O ONLYOFFICE documenta os caminhos persistentes do Docker para logs, certificados e cache de arquivos. Evite excluir volumes durante a resolução de problemas; eles podem conter certificados ou outros dados necessários para recuperar o serviço.

6. Recarregue a página, teste o endpoint de integridade e teste novamente a integração.

Após corrigir um problema confirmado, teste o nome do host público e compare-o com o endpoint local:

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

Use a URL real do seu servidor de documentos. Uma resposta bem-sucedida tanto no servidor upstream local quanto no hostname público indica que o Nginx consegue acessar o backend e retornar a resposta de integridade. Em seguida, abra a página de boas-vindas do servidor de documentos e tente novamente a ação que falhou originalmente no Nextcloud, ownCloud ou em seu outro conector.

Se a verificação de integridade for bem-sucedida, mas o conector ainda reportar um erro, o problema restante pode estar fora do caminho do erro 502 do Nginx — por exemplo, na URL do conector, na confiança TLS ou nas configurações do JWT. Compare esses valores com a configuração do conector e do ONLYOFFICE em vez de continuar alterando os tempos limite do proxy indiscriminadamente.

Diagnóstico rápido

Referências oficiais

• Solução de problemas do ONLYOFFICE Docs para Linux
• Documentos do ONLYOFFICE atrás de um proxy
• Exemplo oficial de proxy Nginx HTTPS para HTTP do ONLYOFFICE
• Documentação ONLYOFFICE: Instalação do Docker e mapeamento de portas
• Exemplo de composição do servidor de documentos ONLYOFFICE