Solución de problemas de Nginx: Soluciones comunes desde la línea de comandos para problemas del servidor web

Cuando Nginx falla, los primeros minutos suelen dedicarse a acotar el problema. ¿El servicio está detenido? ¿Falló un cambio de configuración? ¿Otro proceso ya está usando el puerto 80? ¿Nginx está funcionando pero la aplicación upstream está caída? La línea de comandos te da respuestas rápidas si ejecutas las comprobaciones en el orden correcto.

Me gusta empezar con los comandos menos destructivos: inspeccionar el estado, probar la configuración, leer los registros, y solo entonces recargar o reiniciar. Un reinicio puede ocultar evidencia útil, así que trátalo como una solución solo después de saber qué estás solucionando.

Comandos esenciales de gestión de Nginx

El primer paso en la solución de problemas suele ser verificar el estado del propio servicio de Nginx. Dependiendo de tu sistema operativo, normalmente interactuarás con systemd o service (SysVinit).

1. Verificar el estado del servicio de Nginx

Saber si Nginx está en ejecución, detenido o fallando es crucial. El comando status proporciona esta visión general.

Usando systemd (Común en distribuciones modernas de Linux como Ubuntu 16.04+, CentOS 7+):

sudo systemctl status nginx

Salida esperada (Activo/En ejecución):

● nginx.service - Un servidor web de alto rendimiento y un servidor proxy inverso
   Cargado: cargado (/lib/systemd/system/nginx.service; habilitado; vendor preset: habilitado)
   Activo: activo (en ejecución) desde mar 2023-10-24 10:00:00 UTC; hace 1h
     Docs: man:nginx(8)
 PID principal: 1234 (nginx)
    Tareas: 2 (límite: 4915)
   CGroup: /system.slice/nginx.service
           ├─1234 nginx: proceso maestro /usr/sbin/nginx -g daemon on;
           └─1235 nginx: proceso trabajador

Si la salida muestra Activo: inactivo (muerto) o Activo: falló, sabes que Nginx no está sirviendo tráfico actualmente. Eso no te dice por qué. La siguiente pista suele ser una prueba de configuración o el registro del sistema.

sudo journalctl -u nginx -n 80 --no-pager

Esto muestra los registros recientes del servicio, incluidos los fallos de inicio de systemd. Busca mensajes sobre directivas desconocidas, archivos de certificados faltantes, fallos de enlace o errores de permisos.

2. Iniciar, detener y recargar Nginx

Una vez que identifiques el estado, necesitas gestionarlo. Usa los siguientes comandos según sea necesario:

Acción	Comando (usando `systemctl`)
Detener Servicio	`sudo systemctl stop nginx`
Iniciar Servicio	`sudo systemctl start nginx`
Reiniciar Servicio	`sudo systemctl restart nginx` (Detiene y luego inicia de nuevo)
Recargar Configuración	`sudo systemctl reload nginx` (Aplica nuevas configuraciones sin interrumpir conexiones)

Mejor práctica: Usa reload en lugar de restart Al realizar cambios de configuración (como actualizar hosts virtuales o certificados SSL), usa siempre reload. Esto aplica los cambios de forma gradual mientras las conexiones existentes continúan sin interrupción. Usa restart solo si reload falla o si necesitas restablecer completamente los procesos trabajadores.

Antes de cualquier recarga, ejecuta:

sudo nginx -t && sudo systemctl reload nginx

Ese patrón de una línea evita el error más común: recargar una configuración rota y derribar un servidor en funcionamiento. Si nginx -t falla, el comando de recarga no se ejecutará.

Validar archivos de configuración

La causa más común de fallo de inicio o comportamiento inesperado en Nginx es un error de sintaxis en los archivos de configuración (nginx.conf o archivos incluidos en /etc/nginx/sites-available/). Nginx proporciona una excelente utilidad de prueba incorporada.

3. Probar la sintaxis de la configuración

La bandera -t prueba los archivos de configuración en busca de errores de sintaxis y verifica si las rutas de los archivos de configuración son válidas.

sudo nginx -t

Ejemplo de salida exitosa:

nginx: el archivo de configuración /etc/nginx/nginx.conf la sintaxis es correcta
nginx: prueba del archivo de configuración /etc/nginx/nginx.conf exitosa

Ejemplo de salida de error:

Si existe un error, Nginx te señalará el archivo y número de línea exactos. Por ejemplo, un punto y coma faltante:

nginx: [emerg] directiva desconocida "server_name example.com" en /etc/nginx/sites-enabled/default:15
nginx: prueba del archivo de configuración /etc/nginx/nginx.conf falló

Esta retroalimentación inmediata te permite saltar directamente a la línea 15 del archivo especificado para corregir el error tipográfico.

A veces, la línea informada es solo donde Nginx finalmente notó el problema. Una } o ; faltante puede estar unas líneas antes. Si el error apunta a una directiva de aspecto normal, inspecciona el bloque superior.

4. Mostrar la configuración activa

Para ver exactamente lo que Nginx está ejecutando actualmente (especialmente útil después de múltiples fusiones de configuración o includes complejos), usa la bandera -T (T mayúscula):

sudo nginx -T

Esto genera toda la configuración activa, que se puede canalizar a un archivo para comparación o revisión detallada:

sudo nginx -T > current_nginx_config.txt

Ten cuidado al compartir la salida de nginx -T. Puede incluir nombres de host internos, rutas de certificados, encabezados de proxy y, a veces, secretos pasados como encabezados. Para trabajo de incidentes, es excelente. Para tickets o chat, redacta primero.

Verificar puertos y listeners

Si Nginx no se inicia y los registros mencionan bind() to 0.0.0.0:80 failed, otro proceso puede estar ya escuchando en el puerto.

sudo ss -ltnp | grep -E ':80|:443'

La salida típica muestra la dirección local, el puerto y el nombre del proceso. Si Apache, Caddy, un proxy de contenedor o un proceso antiguo de Nginx está ocupando el puerto, Nginx no puede enlazarse a él.

También puedes confirmar el comportamiento público desde el propio servidor:

curl -I http://127.0.0.1
curl -Ik https://127.0.0.1

-I obtiene solo los encabezados. -k ignora la validación del certificado, lo cual es útil al probar localhost contra un certificado emitido para un nombre de dominio. Desde otra máquina, prueba también el nombre de host real:

curl -I https://example.com

Si localhost funciona pero el nombre de host público falla, revisa las reglas del firewall, los grupos de seguridad en la nube, DNS, balanceadores de carga o la configuración de CDN.

Vale la pena verificar DNS por separado porque puede hacer que un servidor Nginx saludable parezca roto desde el exterior:

dig +short example.com
dig +short www.example.com

Asegúrate de que la dirección devuelta sea el servidor o balanceador de carga que esperas. Si recientemente moviste el sitio, un DNS obsoleto puede enviar a algunos usuarios al host antiguo mientras tus propias pruebas alcanzan el nuevo.

Monitoreo y análisis de registros

Si Nginx se inicia correctamente pero sirve páginas incorrectas o devuelve errores 5xx, los registros se convierten en la fuente principal de verdad.

5. Localizar archivos de registro clave

Por defecto, los registros de Nginx se encuentran típicamente en /var/log/nginx/. Los dos archivos esenciales son:

access.log: Registra cada solicitud manejada por el servidor, incluyendo IP, hora de la solicitud, código de estado y recurso solicitado.
error.log: Registra advertencias, avisos y errores críticos encontrados durante la operación o el procesamiento de solicitudes.

6. Monitoreo de registros en tiempo real con `tail`

Para monitorear errores a medida que ocurren, usa el comando tail con la opción de seguimiento (-f) en el registro de errores.

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

Esto es invaluable al probar un endpoint de aplicación recién implementado, ya que puedes ver inmediatamente si Nginx o la aplicación upstream están generando errores.

Para un servidor más ocupado, sigue solo las nuevas líneas de error y mantén las marcas de tiempo visibles:

sudo tail -n 50 -f /var/log/nginx/error.log

Luego reproduce la solicitud fallida en otra terminal:

curl -I https://example.com/ruta/fallida

Este flujo de trabajo simple de dos terminales suele ser más rápido que hacer clic en un navegador porque cada solicitud y entrada de registro se pueden emparejar directamente.

7. Analizar códigos de estado del registro de acceso

Para problemas de alto tráfico, escanear rápidamente el registro de acceso en busca de códigos de estado puede revelar problemas:

Códigos 4xx (Errores de cliente): A menudo indican enlaces rotos, archivos faltantes (404) o problemas de permisos.
Códigos 5xx (Errores de servidor): Indican que el propio Nginx falló al cumplir la solicitud, a menudo debido a tiempos de espera de conexión upstream (502/504) o fallos internos de procesamiento del servidor (500).

Usa grep para filtrar códigos específicos. Por ejemplo, encontrar todos los errores 502 Bad Gateway:

sudo grep ' 502 ' /var/log/nginx/access.log | tail -n 20

Un conteo rápido de códigos de estado puede mostrar si estás lidiando con una URL incorrecta o un incidente más amplio:

sudo awk '{print $9}' /var/log/nginx/access.log | sort | uniq -c | sort -nr | head

Patrones comunes:

Picos de 404 a menudo significan una ruta de implementación incorrecta, archivos estáticos faltantes o rutas cambiadas.
403 a menudo apunta a permisos de archivo, permisos de directorio o una regla de acceso intencional.
502 generalmente significa que Nginx no pudo obtener una respuesta válida del servicio upstream.
504 generalmente significa que el servicio upstream aceptó la conexión pero no respondió a tiempo.

Para fallos upstream, verifica también el servicio de la aplicación:

sudo systemctl status miapp
sudo journalctl -u miapp -n 100 --no-pager

Reemplaza miapp con el nombre real del servicio. Nginx solo puede proxy lo que está vivo y accesible.

Diagnóstico avanzado: Verbosidad e ID de proceso

8. Forzar registro de depuración (Precaución aconsejada)

En situaciones muy complicadas, aumentar el nivel de registro puede revelar información más detallada sobre el procesamiento de solicitudes. Esto se hace modificando la directiva error_log en tu configuración a debug.

Advertencia: El registro de depuración genera cantidades masivas de datos muy rápidamente y solo debe usarse temporalmente para la solución de problemas activa, ya que afecta gravemente el rendimiento.

Después de cambiar la directiva, debes usar reload o restart en Nginx para que el cambio surta efecto.

9. Encontrar el ID del proceso maestro de Nginx (PID)

El ID del proceso (PID) es útil para enviar señales específicas al proceso maestro en ejecución (por ejemplo, para un apagado gradual o una recarga gradual fuera de systemctl). El PID generalmente se almacena en un archivo, normalmente /var/run/nginx.pid.

cat /var/run/nginx.pid
# Ejemplo de salida: 1234

Luego puedes usar el comando kill si es necesario (por ejemplo, sudo kill -HUP 1234 para forzar una recarga usando el PID):

La mayoría de los operadores deberían preferir systemctl reload nginx porque pasa a través del administrador de servicios y es más fácil de auditar. Las señales siguen siendo útiles en sistemas mínimos, contenedores o hosts antiguos donde systemd no está gestionando el proceso.

Soluciones comunes desde la línea de comandos por síntoma

Si Nginx falla después de una edición de configuración:

sudo nginx -t
sudo journalctl -u nginx -n 80 --no-pager

Corrige el archivo y la línea informados, luego prueba de nuevo antes de recargar.

Si HTTPS falla después de la renovación del certificado:

sudo nginx -t
sudo ls -l /etc/letsencrypt/live/example.com/
sudo openssl x509 -in /etc/letsencrypt/live/example.com/fullchain.pem -noout -dates -subject

Esto confirma que el archivo del certificado existe y muestra el asunto y las fechas de validez.

Si los archivos estáticos devuelven 403:

namei -l /var/www/example.com/index.html

namei -l imprime los permisos para cada directorio en la ruta. Nginx necesita permiso de ejecución en los directorios padre y permiso de lectura en los archivos.

Si un proxy inverso devuelve 502:

sudo grep 'connect() failed' /var/log/nginx/error.log | tail
sudo ss -ltnp | grep 3000
curl -I http://127.0.0.1:3000

Esto verifica si el upstream está escuchando y si responde localmente.

Si el upstream es un socket Unix en lugar de un puerto TCP, verifica la ruta del socket y los permisos:

sudo ls -l /run/miapp/miapp.sock
sudo grep -R "proxy_pass" /etc/nginx/sites-enabled /etc/nginx/conf.d

El usuario trabajador de Nginx necesita permiso para acceder al socket. En muchos sistemas, ese usuario es www-data o nginx, pero confírmalo en nginx.conf antes de cambiar la propiedad o los grupos.

Para fallos intermitentes, compara las solicitudes exitosas y fallidas en el registro de acceso. Una muestra pequeña suele ser suficiente:

sudo grep ' 504 ' /var/log/nginx/access.log | tail -n 20
sudo grep ' 200 ' /var/log/nginx/access.log | tail -n 20

Busca patrones en las rutas, campos de tiempo de respuesta upstream si tu formato de registro los incluye, o una IP de cliente específica que esté desencadenando solicitudes pesadas.

Flujo de trabajo de solución de problemas

Cuando te enfrentes a un problema de Nginx, sigue esta secuencia:

Verificar Estado: sudo systemctl status nginx.
Probar Configuración: Si falló al iniciar, ejecuta sudo nginx -t. Corrige los errores informados.
Reiniciar/Recargar: Si se modificó la configuración, usa sudo systemctl reload nginx.
Monitorear Registros: Si está en ejecución pero roto, usa sudo tail -f /var/log/nginx/error.log mientras reproduces el problema.
Analizar Acceso: Revisa access.log en busca de códigos de estado que indiquen la naturaleza del fallo (4xx vs 5xx).

Este orden evita que adivines. El estado te dice si Nginx está en ejecución, las pruebas de configuración te dicen si puede cargar, los registros te dicen lo que sucedió durante las solicitudes reales, y las comprobaciones locales de curl separan los problemas de Nginx de los problemas upstream o de red.

Mantén una nota breve del incidente mientras trabajas: comando ejecutado, resultado visto y cambio realizado. Evita comprobaciones repetidas y facilita mucho la transferencia.