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
| Directiva | Para qué sirve | Por qué es importante |
|---|---|---|
| proxy_http_version 1.1 | Utiliza HTTP/1.1 para las conexiones de salida | Requisito para que funcione el keepalive |
| proxy_set_header Connection "" | Borra el encabezado de conexión | Sin esto, la función «keepalive» queda desactivada |
| desactivar el almacenamiento en búfer del proxy | Envía la respuesta directamente al cliente | Necesario para la transmisión SSR, SSE y el tiempo real |
| client_max_body_size 20 MB | Tamaño máximo de subida | El valor predeterminado es 1 MB; la subida de archivos fallará |
| proxy_set_header X-Forwarded-Proto $scheme | Indica al servidor si la solicitud se realizó mediante HTTPS | Django 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 headersNginx 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