Back to Blog
January 15, 20261,000 views

Nginx para desarrolladores: la guía de configuración que realmente guardarás en tus favoritos

Las configuraciones de Nginx parecen jeroglíficos hasta que entiendes el modelo conceptual. Esta guía explica qué hace realmente cada directiva, con configuraciones listas para copiar y pegar para las cinco configuraciones más habituales.

El modelo mental: Nginx es una sala de correo

Imagina que Nginx es una sala de correo. Las solicitudes llegan a la recepción (puerto 80/443). La sala de correo comprueba la etiqueta de la dirección (server_name) para enviarlas al departamento adecuado (bloque de servidor). Dentro del departamento, comprueba el asunto (location) para enviarlas a la persona adecuada (upstream/file).

Eso es todo. En Nginx, todo se reduce a: detectar una solicitud → procesarla.

Configuración 1: Next.js + Django detrás de Nginx (la más habitual)

# Upstream blocks: define your app servers
upstream frontend {
    server frontend_container:3000;
    keepalive 16;  # reuse connections (huge perf win)
}

upstream backend {
    server backend_container:8000;
    keepalive 8;
}

server {
    listen 443 ssl;
    server_name yourapp.com;

    # SSL (Let's Encrypt)
    ssl_certificate /etc/letsencrypt/live/yourapp.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourapp.com/privkey.pem;

    # API routes -> Django
    location /api/ {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";  # required for keepalive
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Admin -> Django
    location /admin/ {
        proxy_pass http://backend;
        proxy_set_header Host $host;
    }

    # Static files -> Django (with caching)
    location /static/ {
        proxy_pass http://backend;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    # Everything else -> Next.js
    location / {
        proxy_pass http://frontend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        proxy_buffering off;  # important for streaming SSR
    }
}

Configuración 2: Redireccionamiento HTTPS + URL canónica «www»

Hay dos cosas que todo sitio web de producción necesita: habilitar HTTPS y elegir un dominio canónico (con www o sin www). Sin ello, Google considera que se trata de dos sitios distintos, lo que divide tu posicionamiento SEO.

# Redirect HTTP -> HTTPS
server {
    listen 80;
    server_name yourapp.com www.yourapp.com;
    return 301 https://yourapp.com$request_uri;
}

# Redirect www -> non-www
server {
    listen 443 ssl;
    server_name www.yourapp.com;
    ssl_certificate /etc/letsencrypt/live/yourapp.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourapp.com/privkey.pem;
    return 301 https://yourapp.com$request_uri;
}

# Main site (canonical)
server {
    listen 443 ssl;
    server_name yourapp.com;
    # ... your config
}

Las 5 directrices que debes conocer

DirectivaPara qué sirvePor qué es importante
proxy_http_version 1.1Utiliza HTTP/1.1 para las conexiones de salidaRequisito para que funcione el keepalive
proxy_set_header Connection ""Borra el encabezado de conexiónSin esto, la función «keepalive» queda desactivada
desactivar el almacenamiento en búfer del proxyEnvía la respuesta directamente al clienteNecesario para la transmisión SSR, SSE y el tiempo real
client_max_body_size 20 MBTamaño máximo de subidaEl valor predeterminado es 1 MB; la subida de archivos fallará
proxy_set_header X-Forwarded-Proto $schemeIndica al servidor si la solicitud se realizó mediante HTTPSDjango necesita esto para CSRF y las redirecciones

Depuración: cuando las cosas salen mal

502 Bad Gateway: Nginx no puede conectarse a tu servidor de origen. El contenedor de tu aplicación no se está ejecutando o se encuentra en una red de Docker diferente.

504 Tiempo de espera de la puerta de enlace agotado: tu aplicación es demasiado lenta. Aumenta el valor de `proxy_read_timeout` u optimiza tu aplicación.

413 Entidad de solicitud demasiado grande: la carga supera el valor de `client_max_body_size`. Aumenta ese valor.

Bucle de redireccionamiento 301: Tu aplicación redirige a HTTPS, pero el encabezado X-Forwarded-Proto no está configurado, por lo que siempre cree que se trata de HTTP.

# Quick debugging commands
nginx -t                    # test config syntax
nginx -s reload             # reload without downtime
tail -f /var/log/nginx/error.log   # watch errors live
curl -I https://yourapp.com  # check response headers

Nginx es el portero de tu discoteca. Decide quién entra, adónde va y a qué velocidad. Dedica 30 minutos a entenderlo y te ahorrarás 30 horas de depuración de problemas en producción.

— alokknight Ingeniería