Comprensión de los Bloques de Servidor de Nginx: Preguntas Comunes de Configuración

Comprender los bloques de servidor de Nginx es una de las formas más rápidas de hacer que tu configuración de Nginx parezca menos misteriosa. Los bloques de servidor deciden qué sitio maneja una solicitud, qué nombres de dominio coinciden, qué archivos se sirven y hacia dónde va el tráfico del proxy.

Si alojas más de un dominio, rediriges HTTP a HTTPS o ejecutas aplicaciones detrás de Nginx, los bloques de servidor son donde comienza la mayor parte de ese enrutamiento.

¿Qué es un Bloque de Servidor de Nginx?

Un bloque de servidor de Nginx es una sección de configuración que define cómo debe responder Nginx para una combinación específica de dirección, puerto y nombre de host.

Un bloque de servidor básico para un sitio estático se ve así:

server {
    listen 80;
    server_name example.com www.example.com;

    root /var/www/example.com/public;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

Esto le dice a Nginx que escuche en el puerto 80, que coincida con las solicitudes de example.com y www.example.com, que sirva archivos desde el directorio público y que devuelva 404 cuando no se encuentre un archivo.

El nombre "bloque de servidor" es común en Nginx. Los usuarios de Apache pueden conocer una idea similar como host virtual. El propósito es el mismo: permitir que un servidor web maneje múltiples sitios o aplicaciones.

Los bloques de servidor generalmente se almacenan en /etc/nginx/sites-available/ y se habilitan con enlaces simbólicos en /etc/nginx/sites-enabled/ en sistemas Debian y Ubuntu. Algunas distribuciones usan /etc/nginx/conf.d/ en su lugar. La disposición exacta es menos importante que saber qué archivos están incluidos por nginx.conf.

¿Cómo elige Nginx el Bloque de Servidor Correcto?

La selección de Nginx ocurre en etapas. Primero, considera la dirección IP y el puerto de la directiva listen. Luego compara el nombre de host de la solicitud con server_name.

Si ningún nombre de host coincide, Nginx usa el servidor predeterminado para esa dirección y puerto. Puedes marcar uno explícitamente:

server {
    listen 80 default_server;
    server_name _;
    return 444;
}

Algunos equipos usan un bloque predeterminado como este para descartar solicitudes no coincidentes. Otros devuelven un 404 simple. La mejor elección depende de tus preferencias de registro y seguridad.

Si aún estás aprendiendo, un 404 visible por defecto puede ser más fácil de depurar que return 444, porque 444 es un cierre de conexión específico de Nginx y puede parecer un problema de red desde el lado del cliente. En producción, algunos equipos prefieren el cierre silencioso para hosts no coincidentes aleatorios. Cualquier elección está bien si el equipo la entiende.

Los nombres exactos se prefieren sobre los nombres comodín. Por ejemplo, api.example.com es más específico que *.example.com. Los nombres de servidor con expresiones regulares son posibles, pero deberían ser raros porque son más difíciles de leer y solucionar.

Un error común es agregar un nuevo dominio a DNS pero olvidar agregarlo a server_name. La solicitud llega al servidor, pero Nginx la envía al bloque predeterminado. Desde la vista del usuario, aparece el sitio incorrecto o la solicitud falla.

Otro error común es crear dos bloques que ambos reclaman el mismo listen y server_name. Nginx puede advertir sobre nombres de servidor conflictivos e ignorar uno de ellos. Siempre prueba la configuración después de agregar un sitio.

Usa esto cuando el sitio incorrecto responda:

sudo nginx -T | grep -n "server_name"
curl -I -H 'Host: example.com' http://127.0.0.1/

nginx -T imprime la configuración completa cargada, incluidos los archivos incluidos. Esto suele ser más rápido que abrir cada archivo en sites-enabled.

¿Qué Contiene un Bloque de Servidor?

Un bloque de servidor generalmente contiene directivas para la coincidencia de dominios, TLS, raíz del documento, registro, redirecciones y uno o más bloques location.

Para un proxy inverso, el bloque puede verse así:

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

    ssl_certificate /etc/letsencrypt/live/app.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/app.example.com/privkey.pem;

    location / {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_pass http://127.0.0.1:3000;
    }
}

Aquí, Nginx termina HTTPS y reenvía el tráfico a una aplicación local en el puerto 3000. Esto es común para aplicaciones Node.js, Python, Ruby, Go y Java.

Si la aplicación ascendente necesita conocer el esquema original o la IP del cliente, esas líneas proxy_set_header son importantes. Sin ellas, la aplicación puede pensar que cada solicitud provino de 127.0.0.1 a través de HTTP simple. Eso puede romper redirecciones, registros de auditoría, límites de velocidad y URL de devolución de llamada generadas.

Usa rutas de registro claras al alojar múltiples sitios:

access_log /var/log/nginx/app.example.com.access.log;
error_log /var/log/nginx/app.example.com.error.log;

Los registros separados facilitan mucho la solución de problemas. Cuando cada sitio escribe en un registro de acceso, lleva más tiempo detectar qué dominio está fallando.

Para un host ocupado, esto también facilita la retención. Puede que quieras registros detallados para una API durante un incidente y un registro más ligero para un sitio estático. Mantener los archivos separados te da esa opción sin cambiar cada bloque de servidor a la vez.

¿En Qué se Diferencian los Bloques de Servidor de los Bloques de Ubicación?

Los bloques de servidor eligen el sitio. Los bloques de ubicación eligen qué hacer con las rutas dentro de ese sitio.

Por ejemplo:

server {
    server_name example.com;

    location /assets/ {
        expires 30d;
    }

    location /api/ {
        proxy_pass http://api_backend;
    }

    location / {
        try_files $uri $uri/ /index.html;
    }
}

Las solicitudes de /assets/logo.png obtienen almacenamiento en caché de archivos estáticos. Las solicitudes de /api/users van a un backend ascendente. Otras solicitudes pasan a la aplicación frontend.

Esta división es importante. Si el dominio incorrecto responde, mira la coincidencia del bloque de servidor. Si el dominio correcto responde pero ocurre un comportamiento de ruta incorrecto, mira la coincidencia de ubicación.

Esta distinción ahorra tiempo. Una solicitud para api.example.com/users puede fallar porque api.example.com coincidió con el bloque de servidor incorrecto, o porque /users coincidió con la ubicación incorrecta dentro del bloque correcto. Esos son problemas diferentes.

Para más detalles sobre el enrutamiento de rutas, consulta Explicación de los bloques de ubicación de Nginx.

¿Cómo Debo Organizar Múltiples Sitios?

Usa un archivo por sitio o aplicación cuando sea posible. Dale a cada archivo un nombre que coincida con el dominio o propósito:

/etc/nginx/sites-available/example.com
/etc/nginx/sites-available/api.example.com
/etc/nginx/sites-available/admin.example.com

Esto facilita las revisiones y reduce la posibilidad de cambiar el servicio incorrecto. También ayuda cuando necesitas deshabilitar un sitio rápidamente.

Mantén los fragmentos compartidos pequeños y obvios. La configuración de TLS, los encabezados de proxy y los encabezados de seguridad son buenos candidatos para includes. Evita ocultar el comportamiento de enrutamiento principal en un archivo include genérico, porque dificulta la depuración.

Una configuración práctica podría incluir:

include snippets/proxy-headers.conf;
include snippets/security-headers.conf;

Usa includes para reducir la repetición, no para hacer que cada sitio se comporte de manera idéntica. Un panel de administración interno, una API pública y un sitio de marketing estático a menudo necesitan diferentes límites y encabezados.

Antes de eliminar o renombrar un archivo de bloque de servidor, verifica cómo está incluido. En diseños estilo Debian, eliminar el archivo de sites-available no hace nada si todavía existe otra copia en conf.d. Por otro lado, eliminar un enlace simbólico en sites-enabled deshabilita el sitio sin eliminar el archivo fuente.

ls -l /etc/nginx/sites-enabled/
sudo nginx -T | grep -n "include"

Esa verificación rápida previene el caso frustrante donde editas el archivo que parece correcto y Nginx sigue usando uno diferente.

Cuándo Buscar Ayuda con Problemas de Bloques de Servidor

Pide ayuda a un ingeniero DevOps o especialista en Nginx cuando los cambios en los bloques de servidor afecten dominios de producción, certificados HTTPS, redirecciones orientadas al cliente o múltiples aplicaciones en el mismo host. Pequeños errores pueden enviar a los usuarios a la aplicación incorrecta o romper la renovación de certificados.

También debes buscar ayuda si Nginx sigue sirviendo el sitio incorrecto después de que crees que la configuración es correcta. El problema puede involucrar DNS, IPv6, un balanceador de carga, una CDN o un archivo include que no notaste.

Los bloques de servidor son el mapa que Nginx usa para enrutar el tráfico a nivel de dominio. Mantenlos específicos, prueba después de cada cambio, usa registros separados y separa la coincidencia de dominios del enrutamiento de rutas en tu modelo mental. Una vez que eso haga clic, la mayoría de las preguntas de configuración de Nginx serán mucho más fáciles de responder.