Análisis de los registros de errores de Nginx para solucionar problemas de conexión rechazada

Analizar los registros de errores de Nginx para solucionar problemas de conexión rechazada le ayuda a pasar de una página genérica 502 a una falla específica del backend. La frase "conexión rechazada" generalmente significa que Nginx intentó conectarse a una dirección upstream, pero ningún proceso aceptó la conexión.

Esto es diferente de un tiempo de espera, una falla de DNS o una respuesta incorrecta. Una vez que reconozca el patrón del registro, puede reducir la solución rápidamente.

Qué significa "Conexión rechazada"

En los registros de Nginx, un mensaje común se ve así:

connect() failed (111: Connection refused) while connecting to upstream

Esto significa que el sistema operativo rechazó el intento de conexión. Nginx alcanzó el host de destino, pero no había nada escuchando en el puerto de destino, o la conexión fue rechazada activamente.

Puede verlo cuando Nginx redirige a:

proxy_pass http://127.0.0.1:3000;

pero la aplicación está detenida o escuchando en un puerto diferente.

Este error es común después de implementaciones. Un administrador de procesos puede no reiniciar la aplicación, un contenedor puede fallar o una nueva configuración puede cambiar el puerto de la aplicación sin actualizar Nginx.

No trate cada 502 como una conexión rechazada. Un mensaje de tiempo de espera apunta en una dirección diferente. Un mensaje de permiso denegado a menudo apunta a sockets o políticas de seguridad. El texto exacto del registro es importante.

Encontrar el registro de errores de Nginx correcto

La ruta predeterminada del registro de errores suele ser:

/var/log/nginx/error.log

Pero los bloques de servidor pueden definir registros personalizados:

error_log /var/log/nginx/app-error.log warn;

Verifique la configuración relevante de Nginx si el registro predeterminado no muestra entradas recientes. En algunos sistemas, los mensajes a nivel de servicio también aparecen en el diario del sistema.

Los comandos útiles incluyen:

tail -n 100 /var/log/nginx/error.log

y:

journalctl -u nginx -n 100

Al realizar pruebas, active una solicitud en el navegador o con curl, luego verifique inmediatamente las líneas de registro más nuevas. Esto facilita mucho la conexión del error visible para el usuario con la falla del backend.

Una buena revisión del registro captura cuatro piezas de información:

• La marca de tiempo de la solicitud fallida.
• La dirección y el puerto upstream.
• La ruta de la solicitud.
• El error exacto del sistema, como 111: Connection refused.

Para una solución de problemas más amplia de Nginx, consulte cómo solucionar errores 502 Bad Gateway de Nginx.

Mapear la entrada del registro al upstream

Una línea de registro típica puede incluir un valor upstream como:

upstream: "http://127.0.0.1:3000/api/status"

Eso le dice exactamente a dónde Nginx intentó enviar la solicitud. Ahora verifique si hay algo escuchando allí:

ss -ltnp

Busque 127.0.0.1:3000, 0.0.0.0:3000 o la dirección esperada. Si falta el puerto, la aplicación no está escuchando donde Nginx espera.

Pruebe el upstream directamente:

curl -i http://127.0.0.1:3000/api/status

Si esto falla con conexión rechazada, ha confirmado el problema sin Nginx de por medio.

Si la aplicación se ejecuta en Docker, tenga cuidado con 127.0.0.1. Desde el host, significa el host. Desde dentro de un contenedor de Nginx, significa el propio contenedor de Nginx. En una configuración de Compose, Nginx generalmente necesita redirigir a un nombre de servicio como:

proxy_pass http://app:3000;

siempre que ambos contenedores compartan la misma red de Docker.

Para sockets Unix, el registro puede apuntar a una ruta en lugar de un puerto:

upstream: "http://unix:/run/app/app.sock:/"

En ese caso, verifique si el socket existe y si el usuario del trabajador de Nginx puede acceder a él.

Causas comunes y soluciones

La causa más común es un servicio backend detenido. Verifíquelo con:

systemctl status your-app

Si falló, lea los registros de la aplicación antes de reiniciar. Un reinicio puede restaurar el sitio, pero los registros explican por qué falló.

Otra causa común es una discrepancia de puerto. Por ejemplo, la aplicación cambió del puerto 3000 al 8080, pero Nginx aún redirige al 3000. Corrija el destino upstream de Nginx o restaure el puerto esperado de la aplicación.

Una tercera causa es la vinculación a la interfaz incorrecta. Una aplicación que escucha solo en 127.0.0.1 es accesible desde Nginx local en el mismo host. Pero si Nginx se ejecuta en otro contenedor o en otro servidor, no será accesible a través de esa dirección de loopback. En esas configuraciones, es posible que la aplicación necesite vincularse a 0.0.0.0 dentro de la red privada.

Las reglas del firewall también pueden rechazar conexiones, especialmente entre servidores. Si Nginx redirige a otro host, confirme que el puerto upstream está abierto desde la máquina Nginx, no solo desde su computadora portátil.

Finalmente, el momento de la implementación puede causar errores breves de conexión rechazada. Si Nginx envía tráfico antes de que el nuevo proceso de la aplicación esté listo, los usuarios pueden ver 502 intermitentes. Una verificación de salud, un sondeo de preparación o una estrategia de reinicio gradual pueden evitar eso.

Un flujo práctico de solución de problemas

Use este orden cuando el registro diga conexión rechazada:

1. Copie el host y el puerto upstream del registro de errores de Nginx.
2. Ejecute curl hacia ese upstream exacto desde el servidor Nginx.
3. Ejecute ss -ltnp para confirmar que un proceso está escuchando.
4. Verifique el estado del servicio backend y los registros de la aplicación.
5. Compare el valor proxy_pass de Nginx con la dirección de enlace real de la aplicación.
6. Recargue Nginx solo después de que la configuración sea correcta y nginx -t pase.

Este flujo evita un error común: editar Nginx cuando la aplicación simplemente está caída. También evita el error opuesto: reiniciar la aplicación repetidamente cuando Nginx apunta al lugar equivocado.

Para conceptos básicos de comandos, consulte comandos de monitoreo de registros de Nginx.

Cuándo llamar a un profesional

Busque ayuda cuando los errores de conexión rechazada ocurran solo bajo carga, a través de múltiples upstreams, o durante implementaciones continuas. Esos casos pueden involucrar supervisión de procesos, redes de contenedores, verificaciones de salud del balanceador de carga o límites de capacidad.

También debe escalar si el upstream es un servicio de producción de pagos, autenticación o API orientado al cliente. La recuperación rápida es importante, pero preservar los registros y comprender la falla también lo es.

La conexión rechazada es uno de los errores de Nginx más claros una vez que lo lee con atención. Encuentre el upstream en el registro, pruebe ese destino directamente y corrija el servicio, puerto, interfaz o ruta de red que impide que Nginx se conecte. El registro ya le da el punto de partida.