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)
# Bloques de upstream: define los servidores de
tu aplicaciónupstream frontend {
server frontend_container:3000;
keepalive 16; # reutiliza las conexiones (gran mejora de rendimiento)
}
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;
# Rutas API -> Django
location /api/ {
proxy_pass http://backend;
proxy_http_version 1.1;
proxy_set_header Connection ""; # necesario para 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;
}
# Archivos estáticos -> Django (con almacenamiento en caché)
location /static/ {
proxy_pass http://backend;
expires 30d;
add_header Cache-Control "public, immutable";
}
# Todo lo demás -> Next.js
location / {
proxy_pass http://frontend;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_set_header Host $host;
proxy_buffering off; # importante para la transmisión de 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.
# Redirigir HTTP a
HTTPSserver {
listen 80;
server_name yourapp.com www.yourapp.com;
return 301 https://yourapp.com$request_uri;
}
# Redirigir www a
no-wwwserver {
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;
}
# Sitio principal (canónico)
server {
listen 443 ssl;
server_name yourapp.com;
# ... tu configuración
}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.
# Comandos
rápidos de depuraciónnginx -t # comprobar la sintaxis
de la configuraciónnginx -s reload # recargar sin
interrupcionestail -f /var/log/nginx/error.log # ver los errores en tiempo
realcurl -I https://yourapp.com # comprobar los encabezados de respuestaNginx 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