Solución de errores de Nginx 'Connection Refused': una guía práctica de solución de problemas

Encontrarse con un error de 'Connection Refused' al intentar acceder a un servicio que se ejecuta detrás de Nginx es una experiencia común, pero frustrante. A diferencia de un error de 'Timeout', que sugiere un retraso en la red o pérdida de paquetes, un error de 'Connection Refused' es definitivo: el sistema operativo rechazó inmediatamente el intento de conexión porque ninguna aplicación estaba escuchando activamente en el puerto y la dirección IP especificados.

Este rechazo inmediato centra el problema en unas pocas áreas críticas: el servicio no está en funcionamiento, el firewall está bloqueando el tráfico localmente o la configuración dirige el tráfico a un puerto inexistente. Esta guía proporciona un enfoque sistemático de cuatro fases para diagnosticar y resolver errores de 'Connection Refused', asegurando que pueda restaurar rápidamente la conectividad del servicio.

Fase 1: Comprobación del estado del servidor Nginx (El oyente principal)

La causa más básica de un rechazo de conexión es que el propio servicio Nginx no se está ejecutando o está mal configurado.

1. Verificar el estado del servicio Nginx

Utilice el gestor de servicios de su sistema (normalmente systemd) para confirmar que Nginx está activo y en funcionamiento. Un fallo aquí es la causa directa del rechazo en el puerto de escucha principal (normalmente 80 o 443).

sudo systemctl status nginx

Salida esperada (éxito): Busque Active: active (running).

Solución aplicable: Si el estado muestra inactive o failed, intente iniciar el servicio y compruebe los registros para obtener detalles del fallo.

sudo systemctl start nginx
sudo journalctl -xe | grep nginx

2. Confirmar puertos de escucha activos

Utilice la herramienta ss (estadísticas de socket) o netstat para verificar que Nginx se está enlazando realmente a la dirección IP y al puerto esperados (por ejemplo, 0.0.0.0:80 o 127.0.0.1:8080).

# Usando ss (preferido en distribuciones Linux modernas)
sudo ss -tuln | grep 80

# Usando netstat
sudo netstat -tuln | grep 80

Si no ve el puerto esperado (por ejemplo, :80 o :443) listado bajo un proceso (PID) asociado con Nginx, significa que Nginx no pudo enlazarse, probablemente debido a un error de configuración o a que otro servicio ya está ocupando ese puerto.

Consejo: Si otro servicio está ocupando el puerto, debe detener ese servicio o modificar la configuración de Nginx para que escuche en un puerto diferente y disponible.

Fase 2: Configuración de firewall y red

Si Nginx se está ejecutando y escuchando localmente, el rechazo de la conexión podría estar ocurriendo externamente al servicio, normalmente debido a reglas de firewall que bloquean el tráfico entrante.

1. Comprobar firewalls del servidor local

Asegúrese de que los puertos en los que Nginx está escuchando (por ejemplo, 80, 443) estén explícitamente permitidos a través del firewall del host (UFW, firewalld o iptables).

Ejemplo de UFW (Ubuntu/Debian)

sudo ufw status verbose
# Si está cerrado, permita los puertos:
sudo ufw allow 'Nginx Full'
# O específicamente:
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

Ejemplo de Firewalld (CentOS/RHEL)

sudo firewall-cmd --list-all
# Si está cerrado, añada los servicios:
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

2. Verificar grupos de seguridad del proveedor de la nube

Si su servidor está alojado en un entorno de nube (AWS EC2, Azure VM, GCP Compute Engine), el rechazo de la conexión podría originarse en la capa de seguridad de la red virtual.

Grupos de seguridad de AWS (SG): Compruebe el SG asociado y asegúrese de que las reglas de entrada permitan el tráfico en los puertos 80 y 443 desde las direcciones IP de origen (normalmente 0.0.0.0/0 para acceso público).
Grupos de seguridad de red de Azure (NSG): Verifique las reglas de puertos de entrada.

Fase 3: Validación de la configuración de Nginx

Las directivas de configuración incorrectas pueden llevar a Nginx a intentar escuchar en un puerto o IP no disponible, lo que resulta en un fallo de inicio y un posterior rechazo de conexión.

1. Revisar las directivas `listen`

Inspeccione su archivo de configuración principal (a menudo /etc/nginx/nginx.conf) y cualquier bloque de servidor relevante (normalmente en /etc/nginx/conf.d/ o /etc/nginx/sites-enabled/). Asegúrese de que las directivas listen sean correctas.

Ejemplo de un bloque listen correctamente configurado:

server {
    listen 80;
    listen [::]:80;
    server_name example.com;
    # ... otras directivas
}

Si Nginx está configurado para escuchar solo en 127.0.0.1 (localhost) pero usted intenta acceder a él usando la IP pública, la conexión será rechazada.

2. Comprobar la sintaxis de la configuración

Antes de reiniciar Nginx, valide siempre la sintaxis de la configuración. Un error de análisis impedirá que el servicio se inicie, causando el rechazo.

sudo nginx -t

Si la prueba falla, corrija el error identificado, vuelva a ejecutar la prueba y luego recargue o reinicie Nginx.

sudo systemctl reload nginx

Fase 4: Solución de problemas de proxy inverso (upstream)

Si Nginx se está ejecutando correctamente en los puertos 80/443, pero acceder a una ruta específica (/api/) resulta en 'Connection Refused', el problema radica entre Nginx y el servicio backend (el upstream).

En este escenario, Nginx aceptó la conexión inicial, pero cuando intentó pasar la solicitud, la conexión al backend fue rechazada. Los registros de errores confirmarán esto.

1. Comprobar los registros de errores de Nginx

Examine los registros de errores de Nginx (normalmente /var/log/nginx/error.log) inmediatamente después de intentar la conexión fallida. Busque mensajes relacionados con la directiva proxy_pass, específicamente mencionando errores de conexión.

tail -f /var/log/nginx/error.log

Podría ver una entrada como:

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

2. Verificar el estado del servicio backend

Esta es la solución más común en escenarios de proxy: la aplicación backend (por ejemplo, Node.js, Python Gunicorn, Apache) no está en funcionamiento o no está escuchando donde Nginx espera.

Pasos aplicables:

a. Comprobar el estado del servicio backend: Confirme que la aplicación backend se está ejecutando.

b. Verificar el puerto de escucha del backend: Utilice ss -tuln en el servidor que aloja el backend para confirmar que la aplicación está escuchando en la IP/Puerto especificado en la directiva proxy_pass de Nginx.

3. Probar la conectividad del backend directamente

Pruebe la conexión desde el servidor Nginx al backend usando curl o telnet para aislar el problema de Nginx.

Suponga que su proxy_pass está configurado como http://127.0.0.1:8080:

# Probar la conexión desde el servidor Nginx al puerto del backend
curl -v http://127.0.0.1:8080

# O usando telnet
telnet 127.0.0.1 8080

Si curl o telnet fallan: El servicio backend es definitivamente el problema (no está escuchando o su firewall interno está bloqueando el acceso a 127.0.0.1).
Si curl o telnet tienen éxito: El problema podría ser un error sutil en su directiva proxy_pass (por ejemplo, punto y coma faltante, resolución de host incorrecta o una discrepancia en el protocolo: HTTP frente a HTTPS).

Error común de `proxy_pass`

Asegúrese de que la dirección IP en su proxy_pass coincida con la IP en la que el backend está realmente enlazado. Si el backend se enlaza a una IP específica (por ejemplo, 192.168.1.10:8080) pero Nginx usa localhost:8080, la conexión fallará si el enlace es restrictivo.

Resumen de los pasos clave de solución de problemas

Comprobación del sistema: ¿Está Nginx en funcionamiento (systemctl status nginx)?
Comprobación del puerto: ¿Está Nginx escuchando en la IP/Puerto correctos (ss -tuln)?
Comprobación del firewall: ¿Está el puerto de entrada abierto en el firewall del host (UFW, iptables)?
Comprobación de la configuración: ¿Pasa nginx -t y son correctas las directivas listen?
Comprobación del proxy (si corresponde): ¿Está el servicio upstream en funcionamiento y escuchando en la IP/Puerto exactos definidos en proxy_pass? Pruebe la conectividad directamente usando curl.

Siguiendo este proceso metódico, puede identificar rápidamente si el error 'Connection Refused' se debe a un servicio inactivo, un firewall restrictivo o una configuración de proxy incorrecta, minimizando el tiempo de inactividad y restaurando el acceso de manera eficiente.