Cómo solucionar el error 502 Bad Gateway del servidor de documentos ONLYOFFICE detrás de Nginx

Un navegador muestra el error "502 Bad Gateway" al abrir una URL de ONLYOFFICE Docs, o bien un conector de Nextcloud/ownCloud no puede acceder al servidor de documentos. En ambos casos, Nginx suele recibir una solicitud, pero no puede obtener una respuesta válida de su servidor de origen. Este servidor podría ser el servicio interno de documentos de ONLYOFFICE, un contenedor Docker u otro proxy inverso. Primero, identifique qué instancia de Nginx devolvió el error 502; luego, pruebe directamente el siguiente salto antes de modificar la configuración.

La guía de solución de problemas de Linux de ONLYOFFICE recomienda revisar los ds-docserviceservicios ds-convertery los registros del servidor de documentos. Su guía de proxy inverso también menciona los encabezados de protocolo y host reenviados. La siguiente secuencia verifica primero el estado del servicio, luego el enrutamiento de Nginx y la red de Docker.

1. Averigüe qué servidor Nginx está devolviendo 502.

La instalación del paquete ONLYOFFICE incluye su propia configuración de Nginx, y una implementación también puede tener un proxy inverso Nginx externo. Docker puede agregar otro salto de red. La apariencia de la página 502 por sí sola puede no identificar la capa, por lo que conviene comparar la URL pública con una comprobación de estado local y el registro de errores de Nginx.

En una instalación de Linux basada en paquetes, pruebe el punto final del servidor de documentos local:

curl -i http://127.0.0.1/healthcheck

Si el servidor está configurado para servir ONLYOFFICE en un puerto local distinto al predeterminado, utilice ese puerto. Una instalación correcta normalmente devuelve una respuesta HTTP exitosa true. Si esta solicitud local falla, corrija el servicio del servidor de documentos antes de editar un proxy externo. Si la solicitud se realiza correctamente a nivel local, pero el nombre de host público devuelve un error 502, concéntrese en la configuración del servidor Nginx externo, el protocolo, los encabezados y la ruta del firewall.

Compruebe qué procesos poseen los puertos esperados:

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

Los puertos varían según la topología. Un mapeo común de Docker publica un puerto del host, como el 8080, en el puerto 80 del contenedor; la instalación de un paquete puede usar su propio Nginx en el host. No asuma que ese 127.0.0.1:80es el servidor ascendente correcto solo porque ambos servicios estén en la misma máquina.

2. Compruebe los servicios y registros de ONLYOFFICE.

En una instalación de paquetes de Linux, inspeccione el servicio de documentos y el convertidor:

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

La guía de solución de problemas de ONLYOFFICE enumera estos servicios e identifica la falta de memoria, un conflicto con el puerto 80 y los registros de servicio como aspectos a revisar cuando los servicios de Docs no se inician. Si un servicio está detenido, primero revise el error; luego, reinicie solo el servicio afectado.

sudo systemctl restart ds-docservice

El directorio principal de registros de Linux es /var/log/onlyoffice/documentserver/. Consulta el registro de errores de Nginx y los registros de docservice para ver mensajes como "conexión rechazada", "tiempo de espera agotado" o un archivo faltante. Estos mensajes indican diferentes causas: una conexión rechazada generalmente significa que el proceso o puerto de origen no está disponible, mientras que un tiempo de espera agotado puede significar que el servicio está sobrecargado o bloqueado.

Compruebe también el espacio en disco y la memoria disponibles si los servicios se cierran repetidamente:

df -h
free -h

No reinicies repetidamente un servicio que está fallando sin revisar sus registros; un reinicio puede ocultar brevemente el síntoma sin solucionar un conflicto de puertos, una dependencia fallida o un problema de recursos.

3. Verifique que Nginx apunte al servidor ascendente accesible.

Lee el host virtual activo y confirma la dirección y el puerto exactos en proxy_pass. Desde la máquina o contenedor donde se ejecuta Nginx, solicita directamente al servidor ascendente. Por ejemplo, si el contenedor publica el puerto 80 como puerto de host 8080:

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

Sustituya la dirección de ejemplo por el punto final al que realmente se puede acceder desde el proxy. Si Nginx se ejecuta en un contenedor Docker independiente, 127.0.0.1se refiere a dicho contenedor, no al host Docker ni al contenedor ONLYOFFICE. Utilice un nombre de servicio accesible en una red Docker compartida o la dirección de host y el puerto publicado correctos.

Verifique que el esquema de origen coincida con el del servidor. Úselo solo http://si el servidor utiliza HTTP simple y https://si está configurado para TLS. Enviar HTTP a un puerto TLS, o TLS a un puerto HTTP simple, puede hacer que un servicio que funciona correctamente aparezca como no disponible para Nginx.

4. Compruebe los encabezados reenviados y el proxy de WebSocket.

La guía de proxy inverso de ONLYOFFICE recomienda conservar el protocolo y el nombre de host originales X-Forwarded-Protopara X-Forwarded-Hostque la aplicación los conozca. Los ejemplos oficiales de Nginx también incluyen encabezados de actualización. Si ONLYOFFICE utiliza un proxy externo, compare su configuración con el escenario oficial que mejor se adapte a su topología.

A continuación se muestra un ejemplo simplificado de un contenedor Docker mapeado al puerto 8080 del host. Coloque la mapdirectiva dentro httpdel contexto de Nginx y adapte el nombre de host, la configuración TLS y el puerto de subida a su configuración:

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 es un patrón de referencia, no un reemplazo directo para todas las instalaciones. En particular, no lo copie sobre la configuración de Nginx de ONLYOFFICE sin saber qué bloque de servidor gestiona los puertos 80 y 443. Si Nginx comparte el host con ONLYOFFICE instalado mediante un paquete, primero confirme que no haya colisión de puertos y redirija el proxy externo al oyente interno configurado para su implementación.

Tras editar, pruebe la configuración antes de recargar Nginx:

sudo nginx -t
sudo systemctl reload nginx

Si la prueba de configuración falla, corrija el archivo y la línea indicados antes de volver a cargar. Un error de sintaxis y un error 502 del servidor de origen son problemas distintos; una prueba exitosa nginx -tconfirma la sintaxis, no que el servidor de origen responda.

5. Si ONLYOFFICE se ejecuta en Docker, inspeccione su estado y la asignación de puertos.

Compruebe si el contenedor está en ejecución y qué puerto de host está publicado:

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

La guía oficial de instalación de Docker asigna los puertos del host al puerto 80 del contenedor, y su ejemplo comprueba los registros del contenedor si la página de bienvenida no se carga. Utilice el puerto que se muestra docker portcomo puerto de origen del host. Cuando tanto Nginx como ONLYOFFICE son contenedores, colóquelos en una red compartida y enrute el tráfico al nombre del servicio ONLYOFFICE y al puerto del contenedor, en lugar de a la dirección de bucle invertido del host.

Compruebe el estado de salud del contenedor si su archivo Compose define una comprobación de estado. El ejemplo actual de Compose realiza la comprobación http://localhost:8000/info/info.jsondentro del contenedor. Un contenedor que se encuentra en ejecución aún puede tener un servicio de documentos con problemas. Si se está reiniciando o presenta problemas, utilice los registros para investigar el inicio de la base de datos, la memoria y la configuración antes de cambiar el proxy externo.

ONLYOFFICE documenta las rutas persistentes de Docker para registros, certificados y caché de archivos. Evite eliminar volúmenes durante la resolución de problemas, ya que pueden contener certificados u otros datos necesarios para recuperar el servicio.

6. Recargue, pruebe el punto final de salud y vuelva a probar la integración.

Tras corregir un problema confirmado, pruebe el nombre de host público y compárelo con el punto final local:

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

Utilice la URL real de su servidor de documentos. Una respuesta exitosa tanto en el servidor local como en el nombre de host público indica que Nginx puede acceder al servidor backend y devolver su respuesta de estado. A continuación, abra la página de bienvenida del servidor de documentos y vuelva a intentar la acción que falló originalmente en Nextcloud, ownCloud o su otro conector.

Si la comprobación de estado se realiza correctamente, pero el conector sigue informando de un error, el problema restante podría estar fuera de la ruta del error 502 de Nginx; por ejemplo, la URL del conector, la confianza TLS o la configuración JWT. Compare esos valores con la configuración del conector y de ONLYOFFICE en lugar de seguir modificando los tiempos de espera del proxy sin criterio.

Diagnóstico rápido

Referencias oficiales

• Solución de problemas de ONLYOFFICE Docs para Linux
• Documentos de ONLYOFFICE detrás de un proxy
• Ejemplo oficial de proxy Nginx HTTPS a HTTPS para ONLYOFFICE
• Documentación de ONLYOFFICE: Instalación de Docker y asignación de puertos.
• Ejemplo de redacción de documentos de ONLYOFFICE Document Server