Primeros pasos
Configuración básica
La configuración de Nginx usa una estructura de bloques jerárquica. worker_processes fija el número de procesos. El bloque http contiene bloques server, que contienen bloques location. Prueba siempre con nginx -t antes de recargar.
# /etc/nginx/nginx.conf
worker_processes auto;
events {
worker_connections 1024;
}
http {
server {
listen 80;
server_name example.com;
location / {
root /var/www/html;
index index.html;
}
}
}
# Test config: nginx -t
# Reload: nginx -s reload
# Start: systemctl start nginxDirectivas y contextos
Los contextos se anidan: main > events/http/mail > server > location. Las directivas simples terminan en punto y coma; las directivas de bloque usan llaves. Algunas directivas solo son válidas en contextos concretos.
# Contexts are hierarchical blocks
# Global context (main) - outside any block
user nginx;
worker_processes auto;
# events context
events {
worker_connections 1024;
}
# http context
http {
# server context
server {
listen 80;
# location context
location / {
root /var/www/html;
}
}
}
# Directives: simple (name value;) or block (name { ... })Probar y recargar
nginx -t comprueba la sintaxis Y intenta abrir los archivos referenciados (certificados, logs). Ejecútalo siempre antes de recargar. reload envía SIGHUP — los workers terminan las peticiones actuales y luego se recargan. restart causa una breve caída.
# test configuration for syntax errors
nginx -t
# test and print full config
nginx -T
# reload config without dropping connections
nginx -s reload
# stop gracefully (finishes current requests)
nginx -s quit
# stop immediately
nginx -s stop
# reopen log files (after log rotation)
nginx -s reopen
# systemd alternative
systemctl reload nginx
systemctl restart nginxContexto main vs HTTP
worker_processes y events viven en el contexto main. El enrutado, el proxy, la caché y los bloques server viven en http. SSL, logging y gzip pueden fijarse en http y heredarse en server/location.
# main context - global settings
user nginx;
worker_processes auto;
worker_rlimit_nofile 65535;
pid /var/run/nginx.pid;
events {
worker_connections 4096;
}
http {
# all HTTP-related config lives here
include /etc/nginx/mime.types;
default_type application/octet-stream;
sendfile on;
keepalive_timeout 65;
include /etc/nginx/conf.d/*.conf;
}Archivos include
Los includes mantienen la configuración modular. El glob conf.d (*.conf) es la convención moderna. sites-enabled con symlinks es el patrón de Debian/Ubuntu. mime.types mapea extensiones de archivo a Content-Type.
# main config: /etc/nginx/nginx.conf
http {
include /etc/nginx/mime.types;
include /etc/nginx/conf.d/*.conf;
include /etc/nginx/sites-enabled/*;
}
# /etc/nginx/conf.d/default.conf
server {
listen 80;
server_name example.com;
root /var/www/html;
}
# Disable a site: remove the file from sites-enabled/
# Available sites kept in sites-available/, symlinked into enabled/Operaciones de línea de comandos
nginx -V muestra las opciones de compilación incluidos los módulos integrados. -g fija directivas que anulan la configuración. -c es útil para probar configuraciones alternativas sin tocar la predeterminada.
# start nginx (if not managed by systemd)
nginx
# specify a custom config file
nginx -c /path/to/nginx.conf
# set a global directive from command line
nginx -g "worker_processes 4;"
# test config
nginx -t
# print version and build configuration
nginx -V
# send signal to master process
nginx -s reload
nginx -s stopBloques server
Bloque server básico
Un bloque server define un host virtual. listen fija el puerto. server_name coincide con el header Host. root fija la raíz de documentos. index especifica qué archivos servir para peticiones de directorio.
server {
listen 80;
server_name example.com www.example.com;
root /var/www/example;
index index.html index.htm;
location / {
try_files $uri $uri/ =404;
}
}Varios nombres de servidor
Nginx empareja server_name por exacto, luego comodín (*.foo.com), luego regex. El primer bloque server que coincida maneja la petición. Usa bloques separados para apps distintas en el mismo puerto.
server {
listen 80;
server_name example.com www.example.com;
# ...
}
server {
listen 80;
server_name api.example.com;
# ...
}
# Wildcard: matches any single-level subdomain
server_name *.example.com;
# Regex (starts with ~)
server_name ~^www\d+\.example\.com$;Servidor por defecto
default_server maneja las peticiones cuyo header Host no coincide con ningún server_name. El guion bajo es una convención (hostname inválido, nunca coincide con tráfico real). return 444 cierra la conexión sin respuesta.
# mark a server block as default for the port
server {
listen 80 default_server;
server_name _;
return 444; # drop connection (no response)
}
# handles all requests that don't match another server_name
# _ is an invalid hostname, used as catch-all convention
# useful to block requests with no matching Host headerDirectiva listen
listen puede enlazarse a una dirección concreta, IPv6, socket UNIX, o fijar el default_server. El parámetro ssl habilita TLS para ese listener. Se permiten varias directivas listen en un bloque server.
# listen on port 80
listen 80;
# IPv6
listen [::]:80;
# HTTPS (ssl flag)
listen 443 ssl;
listen [::]:443 ssl;
# specific address
listen 127.0.0.1:8080;
# default server for this port
listen 80 default_server;
# listen on UNIX socket
listen unix:/var/run/nginx.sock;Emparejamiento de server_name
La prioridad de emparejamiento es exacto > comodín inicial > comodín final > regex. Las regex se comprueban en el orden de configuración, así que gana la primera coincidencia. Aumenta el tamaño del bucket de hash si los nombres de servidor son largos o numerosos.
# Order of precedence (highest to lowest):
# 1. Exact name: example.com
# 2. Longest wildcard starting with *: *.example.com
# 3. Longest wildcard ending with *: www.*
# 4. First matching regex (in config order): ~^www\d+\.
# If nothing matches, the default_server handles it
# Tune hash sizes for many server names
http {
server_names_hash_bucket_size 64;
server_names_hash_max_size 512;
}Servidor catch-all
Un catch-all evita que las peticiones con headers Host arbitrarios alcancen tus apps. return 301 redirige a un host conocido. return 444 corta la conexión, útil contra escáneres que golpean tu IP directamente.
# catch all requests regardless of host header
server {
listen 80 default_server;
server_name _; # invalid name, never matches real host
return 301 https://$host$request_uri;
}
# or drop the connection silently
server {
listen 80 default_server;
server_name _;
return 444;
}
# redirect unknown subdomains to main site
server {
listen 80 default_server;
return 301 https://example.com;
}Bloques location
Modificadores de location
Los modificadores cambian el comportamiento de emparejamiento: = (exacto), ^~ (prefijo, salta regex), ~ (regex sensible a mayúsculas), ~* (regex sin distinguir mayúsculas), ninguno (prefijo). Regex es lo mejor para extensiones de archivo; prefijo para árboles de rutas.
# exact match - fastest, stops search if matched
location = /favicon.ico {
log_not_found off;
}
# prefix match with ^~ - skips regex if longest prefix matches
location ^~ /static/ {
root /var/www;
}
# case-sensitive regex
location ~ \.php$ {
fastcgi_pass unix:/run/php/php-fpm.sock;
}
# case-insensitive regex
location ~* \.(jpg|jpeg|png|gif|ico)$ {
expires 30d;
}
# prefix match (no modifier)
location / {
try_files $uri $uri/ /index.php;
}Prioridad de location
Nginx evalúa primero el exacto (=), luego las coincidencias de prefijo (gana la más larga), luego las regex en orden de configuración. ^~ hace que una coincidencia de prefijo se salte la evaluación de regex. Entender este orden evita sorpresas con locations solapadas.
# Priority order (highest to lowest):
# 1. = exact match
# 2. ^~ prefix match (skips regex if matched)
# 3. ~ ~* regex (first match in config order)
# 4. (none) prefix match (longest wins)
location = /api {
# exact, highest priority
}
location ^~ /assets/ {
# prefix, beats regex
}
location ~ \.php$ {
# regex
}
location /api/ {
# prefix, lowest of these
}Root vs alias
root añade el URI a su valor; alias reemplaza el prefijo emparejado. Usa root cuando la location se mapea a un subdirectorio de un árbol. Usa alias cuando la ruta del URI difiere de la ruta del sistema de archivos. alias con regex necesita captura $1.
# root: appends the full URI to the path
# request /img/cat.png -> /var/www/img/cat.png
location /img/ {
root /var/www;
}
# alias: replaces the matched location part
# request /img/cat.png -> /data/images/cat.png
location /img/ {
alias /data/images/;
}
# alias with regex requires capturing the path
location ~ ^/img/(.*)$ {
alias /data/images/$1;
}try_files
try_files comprueba cada argumento en orden; el último es el respaldo (sin comprobación de archivo). $uri comprueba el archivo, $uri/ el directorio. El respaldo puede ser un URI, =código o @nombrado. Esencial para SPAs y enrutado de CMS.
# try files in order, fall back to last option
location / {
try_files $uri $uri/ /index.html;
}
# serve index.php if file/dir not found (pretty URLs)
location / {
try_files $uri $uri/ /index.php?$query_string;
}
# return 404 if nothing matches
location / {
try_files $uri =404;
}
# named location as fallback
location / {
try_files $uri $uri/ @drupal;
}Locations con nombre
Las locations con nombre (@nombre) son solo internas — nunca emparejadas directamente por un URI de petición. Son objetivos de try_files, error_page y rewrite. Genial para compartir un bloque de configuración (como un manejador de respaldo) entre varias locations.
# named locations start with @, can't be reached externally
# used as try_files fallback or rewrite target
location / {
try_files $uri $uri/ @app;
}
location @app {
fastcgi_pass unix:/run/php.sock;
# ... fastcgi config
}
# useful for organizing common error logic
location @error_page {
return 500 "Internal Server Error";
}
# can also be used with error_page
error_page 404 @fallback;
location @fallback {
proxy_pass http://backend;
}Locations anidadas
Las locations pueden anidarse. Las interiores heredan y pueden anular directivas de las exteriores. Útil para casos especiales de una ruta dentro de un prefijo más amplio (por ejemplo, un tamaño de body mayor para subidas, o servir archivos estáticos desde un subcamino).
location /api {
# /api/users, /api/posts handled here
proxy_pass http://backend;
location /api/upload {
# override for upload endpoint
client_max_body_size 50M;
proxy_pass http://upload_backend;
}
location ~ ^/api/static/(.*)$ {
# regex inside prefix location
root /var/www;
}
}Proxy inverso
Proxy pass básico
proxy_pass reenvía peticiones a un servidor upstream. Una barra final en proxy_pass hace que el prefijo de location emparejado se reemplace. Sin barra final, el URI original pasa sin cambios.
server {
listen 80;
server_name app.example.com;
location / {
proxy_pass http://localhost:3000;
}
}
# proxy_pass with URI replacement (trailing slash matters)
location /api/ {
proxy_pass http://backend/; # /api/foo -> /foo
}
# without trailing slash, URI is preserved
location /api/ {
proxy_pass http://backend; # /api/foo -> /api/foo
}Headers de proxy
Por defecto nginx no pasa la IP del cliente ni el host original. Fijar X-Real-IP y X-Forwarded-For deja que el backend identifique al cliente real. X-Forwarded-Proto le dice el esquema original, crítico para la lógica de redirección HTTPS.
location / {
proxy_pass http://backend;
# preserve original host
proxy_set_header Host $host;
# real client IP (not nginx's)
proxy_set_header X-Real-IP $remote_addr;
# forwarded-for chain
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
# scheme (http or https)
proxy_set_header X-Forwarded-Proto $scheme;
# original host
proxy_set_header X-Forwarded-Host $host;
}Proxy upstream
Un bloque upstream define un pool de servidores con nombre al que puede referirse proxy_pass. Esto habilita el balanceo de carga, las comprobaciones de salud y las conexiones keepalive. Las variables upstream son útiles para registrar qué backend manejó cada petición.
# define a named pool of backend servers
upstream backend {
server 10.0.0.1:8080;
server 10.0.0.2:8080;
server 10.0.0.3:8080;
}
server {
listen 80;
location / {
proxy_pass http://backend;
}
}
# useful upstream variables:
# $upstream_addr, $upstream_status,
# $upstream_response_time, $upstream_cache_statusTimeouts del proxy
proxy_connect_timeout es el límite del handshake TCP; los timeouts de lectura/escritura aplican a los periodos de inactividad durante la transferencia de datos. Sube read_timeout para endpoints lentos (exportaciones, inferencia de IA). El keepalive upstream reutiliza conexiones para reducir latencia.
location / {
proxy_pass http://backend;
# connect timeout (TCP handshake to upstream)
proxy_connect_timeout 5s;
# time between reads from upstream (response)
proxy_read_timeout 60s;
# time between writes to upstream (request body)
proxy_send_timeout 60s;
# for slow backends (large uploads/downloads)
proxy_read_timeout 300s;
}
# keepalive connections to upstream
upstream backend {
server 10.0.0.1:8080;
keepalive 32;
}Buffering del proxy
El buffering guarda la respuesta del upstream en memoria/disco antes de enviarla al cliente — eficiente para clientes lentos pero rompe el streaming. Desactívalo para SSE, WebSocket o streaming por fragmentos. buffer_size es la primera parte (headers); buffers guardan el resto.
location / {
proxy_pass http://backend;
# enable buffering (default on)
proxy_buffering on;
proxy_buffer_size 4k;
proxy_buffers 8 4k;
# busy buffers during streaming
proxy_busy_buffers_size 16k;
# disable for streaming/SSE
proxy_buffering off;
proxy_cache off;
}
# Server-Sent Events or streaming responses
location /events {
proxy_pass http://backend;
proxy_buffering off;
proxy_cache off;
chunked_transfer_encoding on;
}Actualización WebSocket
WebSocket necesita HTTP/1.1 más los headers Upgrade y Connection. El bloque map convierte el header Upgrade en el valor Connection correcto (upgrade vs close). Un proxy_read_timeout largo evita que los WebSockets inactivos se cierren.
# Map the Upgrade header to a Connection value
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 80;
location /ws {
proxy_pass http://backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
# keepalive for long-lived connections
proxy_read_timeout 3600s;
}
}Balanceo de carga
Bloque upstream
Un bloque upstream define servidores backend. El balanceo por defecto es round-robin. max_fails y fail_timeout configuran las comprobaciones pasivas de salud: tras max_fails fallos dentro de fail_timeout, el servidor se marca caído durante fail_timeout segundos.
upstream backend {
server backend1.example.com weight=5;
server backend2.example.com;
server backend3.example.com max_fails=3 fail_timeout=30s;
}
server {
location / {
proxy_pass http://backend;
}
}
# default algorithm: round-robin
# max_fails: failed attempts before marking server down
# fail_timeout: window for counting fails AND downtime durationAlgoritmos de balanceo
round-robin reparte uniformemente; least_conn envía al servidor menos cargado; ip_hash mantiene a un cliente en el mismo servidor (sesiones sticky por IP); hash reparte por una clave personalizada. El parámetro consistent minimiza la redistribución al añadir/quitar servidores.
# round-robin (default) - even distribution
upstream backend {
server s1.example.com;
server s2.example.com;
}
# least connections - fewest active connections
upstream backend {
least_conn;
server s1.example.com;
server s2.example.com;
}
# ip_hash - sticky by client IP (session persistence)
upstream backend {
ip_hash;
server s1.example.com;
server s2.example.com;
}
# generic hash (key-based, e.g., by URI or header)
upstream backend {
hash $request_uri consistent;
server s1.example.com;
server s2.example.com;
}Round robin ponderado
weight controla la distribución de tráfico proporcionalmente. El weight por defecto es 1. Fija pesos mayores para servidores más potentes para que manejen una cuota mayor. Los pesos funcionan con round-robin, least_conn e ip_hash.
upstream backend {
server s1.example.com weight=3; # 3x traffic
server s2.example.com weight=2; # 2x traffic
server s3.example.com weight=1; # 1x traffic (default)
}
# total weight = 6
# s1 gets 3/6 = 50%, s2 gets 2/6 = 33%, s3 gets 1/6 = 17%
# useful when servers have different capacity
# e.g., a 4-core server gets weight=4, a 2-core gets weight=2Comprobaciones de salud
El nginx open source usa comprobaciones pasivas de salud (max_fails/fail_timeout) basadas en fallos de peticiones reales. NGINX Plus añade comprobaciones activas que sondean periódicamente un URI. Un servidor debe pasar 'passes' comprobaciones consecutivas para volver a marcarse saludable.
upstream backend {
server s1.example.com max_fails=3 fail_timeout=30s;
server s2.example.com max_fails=3 fail_timeout=30s;
# passive health check (default behavior):
# 3 failures within 30s marks the server down
# it stays down for fail_timeout (30s) before retry
}
# NGINX Plus active health check
upstream backend {
server s1.example.com;
server s2.example.com;
health_check interval=10s fails=3 passes=2;
health_check uri=/health;
}Persistencia de sesión
ip_hash aporta sesiones sticky por IP del cliente pero se rompe si la IP cambia (redes móviles). La directiva hash con consistent ofrece una redistribución mínima de claves cuando cambia el pool. sticky cookie (Plus) fija una cookie para anclar a un cliente a un servidor.
# ip_hash: routes by client IP (uses first 3 IPv4 octets)
upstream backend {
ip_hash;
server s1.example.com:8080;
server s2.example.com:8080;
}
# sticky cookie (NGINX Plus only)
upstream backend {
sticky cookie srv_id expires=1h domain=.example.com path=/;
server s1.example.com;
server s2.example.com;
}
# hash with consistent parameter for minimal redistribution
upstream backend {
hash $http_x_session_id consistent;
server s1.example.com;
server s2.example.com;
}Servidores de respaldo
Marcados con el parámetro backup, estos servidores solo reciben tráfico cuando falla la totalidad de los primarios. Patrón común: los primarios sirven la app; un respaldo sirve una página estática de mantenimiento. Los servidores de respaldo se excluyen del balanceo normal.
upstream backend {
server s1.example.com;
server s2.example.com;
# used only when all primaries are down
server s3.example.com backup;
server s4.example.com backup;
}
# backup servers receive traffic ONLY when all
# non-backup servers are unavailable
# useful for a maintenance page or DR fallback
upstream backend {
server primary.example.com;
server standby.example.com backup;
}Configuración SSL/TLS
Servidor HTTPS básico
El parámetro ssl en listen habilita TLS. ssl_certificate apunta a la cadena de certificados (cert del servidor + intermedios); ssl_certificate_key apunta a la clave privada. Usa siempre fullchain.pem para que los clientes puedan verificar la cadena.
server {
listen 443 ssl;
server_name example.com;
ssl_certificate /etc/ssl/certs/example.com.crt;
ssl_certificate_key /etc/ssl/private/example.com.key;
root /var/www/html;
index index.html;
location / {
try_files $uri $uri/ =404;
}
}Configuración del certificado SSL
Let's Encrypt guarda los certificados bajo /etc/letsencrypt/live/<dominio>/. fullchain.pem incluye los intermedios; privkey.pem es la clave privada. nginx soporta varios tipos de certificado por servidor, eligiendo según la capacidad del cliente.
# Let's Encrypt paths
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
# multiple cert types (RSA + ECDSA) on one server
server {
listen 443 ssl;
server_name example.com;
ssl_certificate /etc/ssl/example.com.rsa.crt;
ssl_certificate_key /etc/ssl/example.com.rsa.key;
ssl_certificate /etc/ssl/example.com.ecdsa.crt;
ssl_certificate_key /etc/ssl/example.com.ecdsa.key;
}Redirección HTTP a HTTPS
El patrón más limpio es un servidor dedicado del puerto 80 que redirige. $host conserva el hostname original. Usar if ($scheme) en un bloque combinado funciona pero el enfoque de servidor separado es el preferido y evita las trampas de 'if is evil'.
# redirect all HTTP traffic to HTTPS
server {
listen 80;
server_name example.com www.example.com;
return 301 https://$host$request_uri;
}
# single server block handling both
server {
listen 80;
listen 443 ssl;
server_name example.com;
ssl_certificate /etc/ssl/example.com.crt;
ssl_certificate_key /etc/ssl/example.com.key;
if ($scheme != "https") {
return 301 https://$host$request_uri;
}
}Protocolos y cifrados SSL
Desactiva los protocolos antiguos (SSLv3, TLSv1.0/1.1). TLS 1.3 es el más rápido y seguro. Usa el Mozilla SSL Configuration Generator para un perfil probado. La caché shared:SSL acelera la reanudación de sesiones entre workers.
server {
listen 443 ssl;
server_name example.com;
ssl_certificate /etc/ssl/example.com.crt;
ssl_certificate_key /etc/ssl/example.com.key;
# modern configuration (Mozilla SSL Config Generator)
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
ssl_prefer_server_ciphers off;
# session settings
ssl_session_tickets off;
ssl_session_timeout 1d;
ssl_session_cache shared:SSL:50m;
}HSTS
HSTS indica a los navegadores que usen siempre HTTPS para el dominio, previniendo ataques de SSL-stripping. max-age va en segundos (31536000 = 1 año). includeSubDomains cubre cada subdominio. preload somete el sitio a una lista integrada de los navegadores — esencialmente irreversible, úsalo con cuidado.
server {
listen 443 ssl;
server_name example.com;
# HSTS: force HTTPS for 1 year (include subdomains)
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
# preload list (be very careful — requires permanent HTTPS)
add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
}
# Preload commits your domain to a browser-baked HTTPS-only list.
# Only enable preload after verifying all subdomains work on HTTPS.OCSP stapling
OCSP stapling permite a nginx obtener y servir el estado de revocación del certificado, ahorrando al cliente un viaje al respondedor OCSP. Se necesita ssl_trusted_certificate para verificar la respuesta OCSP. Se requiere un resolver para que nginx alcance al servidor OCSP.
server {
listen 443 ssl;
server_name example.com;
ssl_certificate /etc/ssl/example.com/fullchain.pem;
ssl_certificate_key /etc/ssl/example.com/privkey.pem;
ssl_stapling on;
ssl_stapling_verify on;
# trust chain for verification
ssl_trusted_certificate /etc/ssl/example.com/chain.pem;
# DNS resolver needed for OCSP requests
resolver 8.8.8.8 8.8.4.4 valid=300s;
resolver_timeout 5s;
}Servicio de archivos estáticos
Servir archivos estáticos
root define la raíz de documentos; nginx mapea el URI de la petición a una ruta de archivo. try_files comprueba el archivo, luego el directorio, y devuelve 404. Fjar root a nivel de server deja que todas las locations lo hereden, pero puedes anularlo por location.
server {
listen 80;
server_name example.com;
root /var/www/html;
location / {
try_files $uri $uri/ =404;
}
}
# root set at server level is inherited by all locations
# request /images/logo.png -> /var/www/html/images/logo.png
# request /css/style.css -> /var/www/html/css/style.cssDirectiva index
index lista los archivos a probar cuando la petición es para un directorio. Se sirve el primer archivo existente. Si no existe ninguno y autoindex está apagado, nginx devuelve 403. El orden importa — lista primero los archivos preferidos.
server {
listen 80;
root /var/www/html;
# try these files in order when request targets a directory
index index.html index.htm index.php;
location / {
try_files $uri $uri/ =404;
}
}
# request / -> tries /var/www/html/index.html, then index.htm
# request /about/ -> tries /var/www/html/about/index.html
# if no index file found and autoindex off -> 403 Forbiddentry_files para SPA
Las SPAs usan enrutado del lado del cliente, así que las rutas desconocidas deben servir index.html. try_files $uri $uri/ /index.html hace exactamente eso. Cachea los recursos con hash por un año con immutable, ya que sus nombres de archivo direccionados por contenido garantizan una URL nueva cuando cambia el contenido.
# Single Page Application (React, Vue, Angular)
server {
listen 80;
root /var/www/spa;
location / {
# serve static files, fall back to index.html for client routing
try_files $uri $uri/ /index.html;
}
# cache static assets aggressively (filename usually hashed)
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ {
expires 1y;
add_header Cache-Control "public, immutable";
}
}Autoindex (listado de directorio)
autoindex genera un listado HTML del directorio. Útil para sitios de descarga de archivos. Apaga exact_size por legibilidad y enciende localtime para marcas de tiempo correctas. Nunca lo actives en directorios con archivos sensibles — emparéjalo siempre con control de acceso.
location /files/ {
autoindex on;
autoindex_exact_size off; # human-readable sizes (KB, MB)
autoindex_localtime on; # show local time instead of UTC
root /var/www;
}
# /files/ -> directory listing
# /files/doc.pdf -> downloads the file
# /files/sub/ -> listing of subdirectory
# disable for security on sensitive directories
location /private/ {
autoindex off;
deny all;
}Headers de expiración
expires fija el max-age de Cache-Control. immutable indica a los navegadores que el archivo nunca cambia (saltarse la revalidación). Para recursos con hash (file.abc123.js), 1y + immutable es lo ideal. El HTML debería revalidarse siempre para que los usuarios reciban actualizaciones de inmediato.
# cache static assets for a year
location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2)$ {
expires 1y;
add_header Cache-Control "public, immutable";
access_log off;
}
# never cache HTML (always revalidate)
location ~* \.html$ {
add_header Cache-Control "no-cache, no-store, must-revalidate";
}
# short cache for API responses
location /api/ {
add_header Cache-Control "no-cache";
}Desactivar logging para estáticos
Las peticiones de recursos estáticos y de favicon/robots saturan los logs de acceso. access_log off detiene el registro; log_not_found off suprime las entradas de 404. Esto mantiene los logs centrados en tráfico significativo y reduce la I/O de disco en sitios concurridos.
# don't log requests for static assets
location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf|eot)$ {
access_log off;
log_not_found off;
expires 1y;
}
# don't log favicon requests (often 404 from browsers)
location = /favicon.ico {
log_not_found off;
access_log off;
}
# don't log robots.txt
location = /robots.txt {
log_not_found off;
access_log off;
}Compresión gzip
Habilitar gzip
gzip comprime respuestas, reduciendo el ancho de banda. gzip_vary añade 'Vary: Accept-Encoding' para las cachés. gzip_proxied any comprime para peticiones proxied. comp_level 6 equilibra CPU y tamaño. min_length 256 se salta las respuestas diminutas (la sobrecarga supera la ganancia).
http {
gzip on;
gzip_vary on;
gzip_proxied any;
gzip_comp_level 6;
gzip_min_length 256;
gzip_types
text/plain
text/css
text/xml
application/json
application/javascript
application/xml+rss
application/atom+xml
image/svg+xml;
}Tipos de gzip
gzip_types lista los tipos MIME a comprimir. text/html se comprime siempre por defecto. No comprimas formatos binarios que ya están comprimidos (imágenes, vídeo, archivos agrupados) — desperdicias CPU sin reducción de tamaño e incluso puedes agrandar la salida.
http {
gzip on;
gzip_types
text/plain
text/css
text/xml
text/javascript
application/javascript
application/x-javascript
application/json
application/xml
application/xml+rss
application/rss+xml
application/atom+xml
image/svg+xml
font/ttf
font/otf
application/vnd.ms-fontobject;
# text/html is always compressed (implicitly, cannot disable)
# DON'T compress already-compressed: jpg, png, gif, mp4, zip, gz
}Nivel de compresión gzip
comp_level intercambia CPU por compresión. 6 es el punto dulce — 9 usa muchísima más CPU por una salida <2% menor. min_length evita comprimir respuestas diminutas donde la sobrecarga del header gzip supera el ahorro. gzip_disable excluye al IE6 heredado que tiene soporte de gzip roto.
http {
gzip on;
gzip_comp_level 6; # 1-9, higher = more compression, more CPU
# level 1: fast, low compression
# level 6: good balance (recommended default)
# level 9: slow, marginal size gain
# minimum response size to compress (bytes)
gzip_min_length 256;
# disable gzip for old browsers
gzip_disable "MSIE [1-6]\.";
}Gzip estático
gzip_static sirve archivos .gz preconstruidos, eliminando el coste de CPU de compresión en runtime. El paso de build crea archivos .gz junto a los originales. nginx sirve el .gz a los clientes que envían Accept-Encoding: gzip y el original a los demás. Ideal para pipelines de recursos estáticos.
# serve pre-compressed .gz files (no runtime compression cost)
# requires ngx_http_gzip_static_module
location / {
gzip_static on;
# on: serve .gz if it exists
# always: serve .gz even without Accept-Encoding header
root /var/www/html;
}
# pre-compress files at build time:
# find /var/www/html -type f ( -name "*.css" -o -name "*.js" \
# -o -name "*.html" ) -exec gzip -k -9 {} \;
# creates file.css.gz, file.js.gz alongside the originalsBrotli
Brotli supera a gzip para contenido de texto, especialmente a niveles de compresión mayores. Requiere el módulo de terceros ngx_brotli. brotli_static sirve archivos .br preconstruidos. Los navegadores modernos anuncian 'br' en Accept-Encoding, así que nginx elige el mejor disponible.
# requires ngx_brotli module (not built-in)
http {
brotli on;
brotli_comp_level 6;
brotli_types
text/plain
text/css
application/javascript
application/json
image/svg+xml;
# serve pre-compressed .br files
brotli_static on;
}
# Brotli typically 10-20% smaller than gzip for text
# supported by all modern browsers (not IE)
# nginx can serve both .br and .gz; picks based on Accept-EncodingGzip proxied
Por defecto nginx no comprime las respuestas proxied (para no comprimir dos veces upstreams ya comprimidos). gzip_proxied any lo habilita para todas las peticiones proxied. gzip_vary garantiza que las cachés guarden versiones separadas para clientes comprimidos/sin comprimir.
http {
gzip on;
gzip_proxied any;
# gzip_proxied controls compression for proxied requests:
# off: never compress proxied requests
# expired: compress if response has Expires header
# no-cache: compress if Cache-Control: no-cache
# no-store: compress if Cache-Control: no-store
# private: compress if Cache-Control: private
# no_last_modified: compress if no Last-Modified header
# no_etag: compress if no ETag header
# auth: compress if Authorization header present
# any: compress all proxied requests
gzip_vary on; # add "Vary: Accept-Encoding" header
}Caché
Caché de proxy
proxy_cache guarda las respuestas del upstream en disco. keys_zone define una zona de memoria compartida para las claves de caché (10m ≈ 80.000 claves). max_size limita el uso de disco; inactive elimina las entradas no accedidas en ese tiempo. use_temp_path=off escribe directamente en la caché por velocidad.
http {
# define cache zone on disk
proxy_cache_path /var/cache/nginx levels=1:2
keys_zone=api_cache:10m
max_size=1g
inactive=60m
use_temp_path=off;
server {
location /api/ {
proxy_pass http://backend;
proxy_cache api_cache;
proxy_cache_valid 200 10m;
proxy_cache_valid 404 1m;
}
}
}Zona de caché
levels=1:2 crea un árbol de directorios de dos niveles a partir del hash MD5 de la clave de caché para evitar demasiados archivos en un directorio. Zonas separadas por tipo de contenido permiten ajustar max_size e inactive independientemente — estáticos cacheados más tiempo, API cacheada brevemente.
http {
proxy_cache_path /var/cache/nginx
levels=1:2 # directory hierarchy depth
keys_zone=my_cache:10m # zone name + shared memory size
max_size=1g # max disk size for cache
inactive=60m # remove if not accessed in 60min
use_temp_path=off; # write directly (faster, no temp copy)
# multiple zones for different content types
proxy_cache_path /var/cache/static levels=1:2
keys_zone=static:10m max_size=500m inactive=24h;
proxy_cache_path /var/cache/api levels=1:2
keys_zone=api:10m max_size=200m inactive=10m;
}Clave de caché
La clave de caché determina la unicidad de la caché. La clave por defecto puede causar colisiones entre hosts virtuales — incluye $host. Para contenido por usuario, incluye un identificador de usuario. proxy_cache_bypass se salta la caché (aun así guarda); proxy_no_cache no guarda la respuesta.
location / {
proxy_pass http://backend;
proxy_cache api_cache;
# default key: $scheme$proxy_host$request_uri
proxy_cache_key "$scheme$request_method$host$request_uri";
# include user-specific data to avoid cross-user leaks
proxy_cache_key "$scheme$host$request_uri$http_x_user_id";
# bypass cache for authenticated users
proxy_cache_bypass $http_authorization;
proxy_no_cache $http_authorization;
}Validez de la caché
proxy_cache_valid fija TTLs por código de estado. 0s u omitir un estado impide cachearlo. proxy_cache_lock serializa los fallos de caché concurrentes para la misma clave — solo una petición golpea al upstream; las demás esperan la respuesta cacheada.
location / {
proxy_pass http://backend;
proxy_cache api_cache;
# cache by response status code
proxy_cache_valid 200 302 10m;
proxy_cache_valid 404 1m;
proxy_cache_valid 500 502 503 504 0s; # don't cache errors
# fallback for any other status
proxy_cache_valid any 1m;
# cache lock: collapse concurrent misses into one upstream call
proxy_cache_lock on;
proxy_cache_lock_timeout 5s;
}Saltarse la caché
proxy_cache_bypass se salta leer la caché (va al upstream) pero puede seguir guardando la respuesta. proxy_no_cache se salta guardar. El header X-Cache-Status es inestimable para depurar — HIT significa servido desde caché, MISS significa obtenido del upstream.
location / {
proxy_pass http://backend;
proxy_cache api_cache;
# bypass cache (always go to upstream)
proxy_cache_bypass $http_authorization $arg_nocache;
# don't store in cache
proxy_no_cache $http_authorization;
# add header showing cache status for debugging
add_header X-Cache-Status $upstream_cache_status;
}
# $upstream_cache_status values:
# MISS, BYPASS, EXPIRED, STALE, UPDATING, REVALIDATED, HITCaché del navegador
La caché del navegador reduce la latencia de visitas repetidas. immutable se salta la revalidación por completo (solo seguro para nombres de archivo direccionados por contenido). no-cache significa revalidar cada vez (aun así permite GET condicional). no-store significa nunca guardar. Emparéjalo con ETags para respuestas 304 eficientes.
# cache static assets in the browser
location ~* \.(jpg|jpeg|png|gif|ico|css|js|woff2?)$ {
expires 1y;
add_header Cache-Control "public, immutable";
}
# HTML - revalidate always
location ~* \.html$ {
add_header Cache-Control "no-cache, must-revalidate";
etag on;
}
# API responses - never cache
location /api/ {
add_header Cache-Control "no-store";
}
# public: any cache (browser, CDN) may store
# private: only the browser may store
# immutable: file never changes, skip revalidation
# no-store: never cacheReescritura de URLs
Directiva return
return es la forma más simple de redirigir o responder. Detiene el procesamiento de inmediato. Usa 301 para permanente, 302 para temporales. Puedes devolver un código de estado con un body (200, 418) o una redirección a una URL. Prefiere return sobre rewrite para redirecciones.
# simplest redirect/rewrite - return stops processing
server {
location /old {
return 301 /new;
}
location /external {
return 301 https://example.com$request_uri;
}
location /api {
return 200 "OK\n";
}
location /teapot {
return 418 "I'm a teapot";
}
}
# return is preferred over rewrite for simple redirectsDirectiva rewrite
rewrite empareja el URI contra una regex y lo reemplaza. last re-evalúa el emparejamiento de locations con el nuevo URI (como empezar de nuevo). break detiene la reescritura pero se queda en la location actual. redirect/permanent envían una redirección al navegador.
# rewrite regex replacement [flag]
server {
# rewrite /old/* to /new/* preserving the captured part
rewrite ^/old/(.*)$ /new/$1 permanent;
# rewrite old blog URLs to new structure
rewrite ^/blog/(\d{4})/(\d{2})/(.*)$ /articles/$1/$2/$3 last;
# capture with named groups
rewrite ^/download/(.*)$ /assets/$1 last;
}
# flags:
# last: re-search locations with the new URI
# break: stop rewrite, continue in current location
# redirect: 302 temporary redirect
# permanent: 301 permanent redirectFlags de rewrite
last vs break es la parte más confusa. last re-ejecuta la búsqueda de location (útil cuando la reescritura apunta a otra location). break detiene la reescritura pero se queda (útil cuando la reescritura solo ajusta una ruta interna). redirect/permanent cambian la URL del navegador.
location / {
# last: restart location matching with new URI
rewrite ^/api/(.*)$ /backend/$1 last;
# break: stop processing rewrites, stay in current location
rewrite ^/static/(.*)$ /assets/$1 break;
# redirect: 302 temporary redirect (browser URL changes)
rewrite ^/old/(.*)$ /new/$1 redirect;
# permanent: 301 permanent redirect (browser URL changes)
rewrite ^/old/(.*)$ /new/$1 permanent;
}
# avoid rewrite inside if blocks - use location + try_files insteadCapturas con nombre
Las capturas con nombre (?<nombre>patrón) crean variables ($nombre) más claras que las posicionales $1, $2. Funcionan tanto en location regex como en rewrite. Los valores capturados están disponibles en proxy_pass, fastcgi_param, add_header y log_format dentro de esa location.
# named captures in regex locations
location ~ ^/users/(?<username>[a-z]+)/?$ {
proxy_pass http://backend/users/$username;
}
# named captures in rewrite
location / {
rewrite ^/articles/(?<year>\d{4})/(?<slug>[a-z-]+)/?$
/blog?year=$year&slug=$slug last;
}
# named captures become variables: $year, $slug, $username
# accessible in proxy_pass, fastcgi_pass, headers, etc.
# safer than $1, $2 positional captures for readabilityDirectiva map
map construye una tabla de búsqueda de una variable a otra, evaluada perezosamente. Es mucho más eficiente y legible que cadenas de sentencias if. La rama default maneja los valores sin coincidencia. Las coincidencias regex (con prefijo ~) se comprueban en orden.
# map creates a new variable based on another variable's value
map $http_host $backend {
default "http://default.backend";
"a.com" "http://a.backend";
"b.com" "http://b.backend";
"~^.*\.app\.com$" "http://app.backend";
}
server {
server_name a.com b.com;
location / {
proxy_pass $backend;
}
}
# map is evaluated lazily and cached per request
# more efficient than if/else chainsDirectiva if (precaución)
if tiene un comportamiento sorprendente dentro de los bloques location — puede reescribir configuraciones impredeciblemente. Los únicos usos universalmente seguros son return y rewrite. Para comprobaciones de existencia de archivo, usa try_files. Para lógica compleja, usa map o bloques location separados. Mira la wiki: 'If Is Evil'.
# "if is evil" — use sparingly! Only safe for:
# return / rewrite, and with these checks:
# -f, -d, -e, -x (file/dir/exists/executable)
# =, !=, ~, ~* (string/regex comparison)
location / {
if ($request_method = POST) {
return 405;
}
if ($http_user_agent ~* "bot") {
return 403;
}
# BAD: don't do this inside if
# if (-f $request_filename) { ... }
# use try_files instead
try_files $uri $uri/ /index.html;
}Redirección
Redirección permanente (301)
301 significa 'movido permanentemente' — navegadores y motores de búsqueda lo cachean, así que úsalo solo para cambios verdaderamente permanentes. Prueba las redirecciones con 302 primero para no fijar un error. 301 transfiere el valor de los enlaces (SEO) a la nueva URL.
# 301 - permanent redirect (cached by browsers indefinitely)
server {
listen 80;
server_name old-domain.com;
# redirect entire site to a new domain
return 301 https://new-domain.com$request_uri;
}
location /old-page {
return 301 /new-page;
}
# 301 caches indefinitely in browsers — test with 302 first!
# Search engines treat 301 as a permanent move and update indexes.Redirección temporal (302)
302 convierte POST en GET al redirigir (comportamiento histórico). 307 y 308 conservan el verbo — importante para reenviar POSTs. 303 convierte explícitamente a GET (útil tras enviar un formulario para evitar doble envío al refrescar). Elige según si el verbo debe conservarse.
# 302 - temporary redirect (not cached by default)
location /maintenance {
return 302 /maintenance.html;
}
# 307 - temporary, preserves HTTP method (POST stays POST)
location /api/v1 {
return 307 /api/v2;
}
# 308 - permanent, preserves HTTP method
location /api/v1 {
return 308 /api/v2;
}
# 303 - see other (always uses GET for the new request)
location /form-submit {
return 303 /success;
}Redirigir www a no-www
Elige una forma canónica (www o no-www) y redirige la otra. Dos bloques server es el patrón más limpio: el no canónico solo redirige. $request_uri conserva la ruta y la query string. Aplica la misma lógica para las redirecciones HTTPS.
# www to non-www
server {
listen 80;
server_name www.example.com;
return 301 https://example.com$request_uri;
}
server {
listen 80;
server_name example.com;
# ... main site config
}
# non-www to www (reverse direction)
server {
listen 80;
server_name example.com;
return 301 https://www.example.com$request_uri;
}Redirigir HTTP a HTTPS
$host conserva el hostname original, así que la redirección funciona para cualquier server_name. $request_uri conserva la ruta y la query. Para puertos no estándar, añade :puerto a $host. Un bloque server dedicado al puerto 80 es más limpio que comprobaciones if por location.
server {
listen 80;
server_name example.com www.example.com;
return 301 https://$host$request_uri;
}
# with a non-standard HTTPS port
server {
listen 8080;
return 301 https://$host:8443$request_uri;
}
# redirect only a specific path
location /secure {
if ($scheme = http) {
return 301 https://$host$request_uri;
}
}Redirigir a otro dominio
Para migraciones de dominio, $request_uri conserva la ruta completa y la query para que los enlaces no se rompan. Usa rewrite con una captura cuando cambia la estructura de la ruta. 301 es lo correcto para migraciones permanentes — transfiere el ranking SEO al nuevo dominio.
# domain migration — preserve all paths
server {
listen 80;
server_name old.com www.old.com;
return 301 https://new.com$request_uri;
}
# preserve path and query string
location /docs/ {
return 301 https://docs.new.com$request_uri;
}
# with path rewrite using capture groups
location /old-blog/ {
rewrite ^/old-blog/(.*)$ https://blog.new.com/$1 permanent;
}Redirección por ruta
Las redirecciones por ruta son útiles para limpiar URLs (quitar barras finales, extensiones de archivo) y mover contenido. Las locations regex con capturas ($1) habilitan reescrituras de ruta flexibles. Las redirecciones basadas en parámetros de query usan $arg_nombre para leer parámetros de query individuales.
# redirect specific paths
location /promo/2023 {
return 301 /promo/2024;
}
# remove trailing slash
location ~ ^/(.*)/$ {
return 301 /$1;
}
# remove .html extension
location ~ ^/(.*)\.html$ {
return 301 /$1;
}
# redirect based on query parameter
location /download {
if ($arg_version = "1") {
return 301 /download?v=2;
}
}FastCGI (PHP-FPM)
Configuración básica de PHP-FPM
fastcgi_pass envía las peticiones PHP a PHP-FPM vía un socket UNIX (más rápido, solo local) o un puerto TCP. include fastcgi_params fija las variables CGI estándar. SCRIPT_FILENAME indica a PHP qué archivo ejecutar — combinando la raíz de documentos con la ruta del script.
server {
listen 80;
server_name example.com;
root /var/www/laravel/public;
index index.php;
location ~ \.php$ {
fastcgi_pass unix:/run/php/php8.2-fpm.sock;
# or: fastcgi_pass 127.0.0.1:9000;
fastcgi_index index.php;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}
}Parámetros FastCGI
fastcgi_params fija las variables de entorno pasadas a PHP. SCRIPT_FILENAME es la más crítica — sin ella, PHP no puede encontrar el script. Los parámetros personalizados (APP_ENV, DB_HOST) te permiten inyectar configuración sin modificar la app. PATH_INFO habilita URLs limpias en algunos frameworks.
location ~ \.php$ {
fastcgi_pass unix:/run/php/php-fpm.sock;
# standard CGI parameters
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param PATH_INFO $fastcgi_path_info;
# custom application parameters
fastcgi_param APP_ENV production;
fastcgi_param DB_HOST db.internal;
# flag for HTTPS (so PHP knows the original scheme)
fastcgi_param HTTPS $https_flag;
}Caché FastCGI
fastcgi_cache guarda las respuestas PHP, reduciendo dramáticamente la carga para páginas cacheables. fastcgi_cache_use_stale sirve una respuesta cacheada rancia si el backend falla o agota el tiempo — mejora la resiliencia. Ten cuidado de no cachear contenido por usuario o autenticado.
http {
fastcgi_cache_path /var/cache/nginx/php
levels=1:2
keys_zone=phpcache:100m
max_size=1g
inactive=60m;
server {
location ~ \.php$ {
fastcgi_pass unix:/run/php/php-fpm.sock;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_cache phpcache;
fastcgi_cache_valid 200 10m;
fastcgi_cache_key $scheme$host$request_uri;
fastcgi_cache_use_stale error timeout invalid_header;
}
}
}Búferes FastCGI
Los búferes guardan la respuesta PHP antes de enviarla al cliente. Búferes pequeños hacen que nginx escriba a disco (lento) para respuestas grandes. Si ves errores 'upstream sent too big header', aumenta fastcgi_buffer_size. Para respuestas de API grandes, usa búferes mayores/menos numerosos.
location ~ \.php$ {
fastcgi_pass unix:/run/php/php-fpm.sock;
# buffer settings
fastcgi_buffering on;
fastcgi_buffer_size 16k;
fastcgi_buffers 16 16k;
fastcgi_busy_buffers_size 32k;
# for large responses (e.g., PHP generating big JSON)
fastcgi_buffers 64 16k;
fastcgi_buffer_size 32k;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}Timeouts FastCGI
fastcgi_read_timeout es cuánto espera nginx a que PHP produzca salida. Los scripts de larga ejecución (importaciones de datos, generación de reportes, llamadas de IA) necesitan valores mayores. Asegúrate de que el max_execution_time de PHP sea al menos igual de alto, o PHP agotará el tiempo primero.
location ~ \.php$ {
fastcgi_pass unix:/run/php/php-fpm.sock;
fastcgi_connect_timeout 5s;
fastcgi_read_timeout 300s; # for long-running scripts
fastcgi_send_timeout 300s;
# increase for very slow PHP scripts (imports, exports, reports)
fastcgi_read_timeout 600s;
}
# also adjust max_execution_time in php.ini to match
# otherwise PHP kills the script before nginx times outtry_files con PHP
try_files $uri $uri/ /index.php?$args es el patrón estándar para frameworks PHP (WordPress, Laravel, Drupal). Sirve archivos/directorios reales, si no enruta a index.php con la query string. $args conserva los parámetros de query originales.
# WordPress-style pretty URLs
server {
root /var/www/wordpress;
location / {
try_files $uri $uri/ /index.php?$args;
}
location ~ \.php$ {
fastcgi_pass unix:/run/php/php-fpm.sock;
fastcgi_index index.php;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}
# deny access to sensitive files
location ~* /wp-config.php {
deny all;
}
}Proxy WebSocket
Proxy WebSocket
WebSocket exige HTTP/1.1 más los headers Upgrade y Connection. El bloque map convierte el header Upgrade del cliente en el valor Connection correcto: 'upgrade' para WebSocket, 'close' para HTTP normal. El read_timeout largo mantiene vivas las conexiones WebSocket inactivas.
# Map the Upgrade header to a Connection value
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 80;
server_name ws.example.com;
location / {
proxy_pass http://backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 3600s; # 1 hour
proxy_send_timeout 3600s;
}
}Headers de upgrade
HTTP/1.1 es obligatorio para WebSocket (HTTP/2 maneja la multiplexación de forma distinta). Connection puede fijarse a 'upgrade' a fuego, pero el enfoque de variable map también maneja peticiones no WebSocket en la misma location. Pasa Host para que el backend pueda validar el header Origin.
location /ws {
proxy_pass http://backend;
# HTTP/1.1 is required for the Upgrade mechanism
proxy_http_version 1.1;
# pass the Upgrade header through
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
# preserve host for origin checks on the backend
proxy_set_header Host $host;
# real client IP
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}Timeout WebSocket
El proxy_read_timeout por defecto (60s) cierra las conexiones WebSocket inactivas. Fíjalo alto (86400s = 24h) para mantener las conexiones vivas entre mensajes. proxy_buffering off garantiza que los mensajes lleguen al cliente de inmediato en lugar de agruparse.
location /ws {
proxy_pass http://backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
# WebSocket connections are long-lived
# default 60s would close them during idle periods
proxy_read_timeout 86400s; # 24 hours
proxy_send_timeout 86400s;
# disable buffering for real-time messages
proxy_buffering off;
}Proxy Socket.io
Socket.io empieza con long-polling HTTP y luego se actualiza a WebSocket si está disponible. Ambos transportes pasan por el mismo proxy_pass, así que una location se encarga de la totalidad. Pasar X-Forwarded-Proto permite a socket.io saber que está tras HTTPS y así construir URLs correctas.
server {
listen 80;
server_name socket.example.com;
location / {
proxy_pass http://backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header Host $host;
proxy_read_timeout 86400s;
# socket.io needs these for correct client IP and scheme
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
# socket.io uses both polling (HTTP) and WebSocket transports
# both are handled by the proxy_pass aboveVarias rutas WebSocket
Diferentes servicios WebSocket pueden enrutarse por ruta a backends distintos. Cada location necesita los mismos headers de upgrade. El bloque map se define una vez a nivel http y se comparte. Ajusta read_timeout por servicio — el chat puede estar activo a menudo; las notificaciones pueden quedar inactivas horas.
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 80;
# chat application
location /ws/chat/ {
proxy_pass http://chat_backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 3600s;
}
# notifications service
location /ws/notify/ {
proxy_pass http://notify_backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 86400s;
}
}WSS (WebSocket seguro)
WSS es WebSocket sobre TLS. nginx termina el TLS (maneja el certificado) y hace proxy de un WebSocket plano al backend. El backend no necesita configuración TLS. Esta es la configuración estándar de producción — los navegadores exigen WSS para páginas HTTPS (reglas de contenido mixto).
server {
listen 443 ssl;
server_name ws.example.com;
ssl_certificate /etc/ssl/ws.example.com.crt;
ssl_certificate_key /etc/ssl/ws.example.com.key;
location / {
proxy_pass http://backend:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header Host $host;
proxy_read_timeout 86400s;
}
}
# browser connects with wss://ws.example.com
# nginx terminates TLS, proxies plain WebSocket to the backendHeaders de seguridad
X-Frame-Options
X-Frame-Options evita que tu sitio se incruste en iframes, bloqueando ataques de clickjacking. SAMEORIGIN permite que tus propias páginas se enmarquen a sí mismas. El reemplazo moderno es CSP frame-ancestors, que es más flexible. always garantiza que el header se envíe también en respuestas de error.
# prevent clickjacking (your site embedded in an iframe)
add_header X-Frame-Options "SAMEORIGIN" always;
# options:
# DENY - no framing at all
# SAMEORIGIN - only same-site can frame
# ALLOW-FROM - deprecated, use CSP frame-ancestors instead
# modern equivalent via Content-Security-Policy
add_header Content-Security-Policy "frame-ancestors 'self'" always;X-Content-Type-Options
nosniff indica a los navegadores que confíen en el header Content-Type y no olfateen el contenido. Sin él, un navegador podría ejecutar una imagen subida como HTML si olfatea contenido HTML. Es un header de poco esfuerzo y gran valor — actívalo siempre.
# prevent MIME-type sniffing
add_header X-Content-Type-Options "nosniff" always;
# forces the browser to respect the declared Content-Type
# prevents XSS via uploaded files (e.g., an image containing HTML
# being executed as a script)
# related: block Adobe Flash / PDF cross-domain policies
add_header X-Permitted-Cross-Domain-Policies "none" always;Content-Security-Policy
CSP es la defensa más potente contra XSS — lista blanca las fuentes permitidas para scripts, estilos, imágenes, etc. Empieza con Report-Only para hallar violaciones sin romper nada, y luego aplica. 'self' significa mismo origen; 'unsafe-inline' permite scripts/estilos en línea (necesario para muchas apps).
# strict CSP — restricts where resources can load from
add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' https://fonts.gstatic.com; connect-src 'self' https://api.example.com; frame-ancestors 'none'; base-uri 'none'; form-action 'self'" always;
# report-only mode (logs violations without blocking)
add_header Content-Security-Policy-Report-Only "default-src 'self'; report-uri /csp-report" always;X-XSS-Protection
X-XSS-Protection activaba el filtro integrado de XSS reflejado del navegador. Los navegadores modernos han eliminado esta característica en favor de CSP. mode=block impedía la sanitización (que podía introducir nuevas vulnerabilidades) y simplemente bloqueaba la página. Incluirlo es inofensivo para navegadores heredados, pero CSP es la defensa real.
# legacy XSS auditor (older browsers)
add_header X-XSS-Protection "1; mode=block" always;
# values:
# 0 - disable the filter
# 1 - enable (sanitize)
# 1; mode=block - enable and block the page entirely
# NOTE: deprecated in modern browsers (Chrome, Edge, Safari removed it)
# CSP is the modern replacement, but this doesn't hurt to include
# for legacy browser supportReferrer-Policy
Referrer-Policy controla cuánta información de URL se filtra vía el header Referer cuando los usuarios hacen clic en enlaces. strict-origin-when-cross-origin (el valor por defecto del navegador) envía la URL completa para peticiones del mismo origen pero solo el origen para entre orígenes, y nada al degradar a HTTP.
# control what the Referer header contains
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
# options:
# no-referrer - never send Referer
# no-referrer-when-downgrade - default; no Referer on HTTPS->HTTP
# same-origin - only same-site
# origin - send only scheme+host
# strict-origin - origin, but not on downgrade
# origin-when-cross-origin - full for same, origin for cross
# strict-origin-when-cross-origin - recommended default
# unsafe-url - send full URL (not recommended)Permissions-Policy
Permissions-Policy te permite deshabilitar características del navegador (cámara, micrófono, geolocalización, etc.) incluso si la página las pide. Un () vacío deshabilita la característica por completo. Esto limita el radio de impacto de un XSS — un script comprometido no puede encender la cámara si la política lo prohíbe.
# control which browser features the page can use
# (formerly Feature-Policy)
add_header Permissions-Policy "geolocation=(), microphone=(), camera=(), payment=(), usb=(), magnetometer=(), gyroscope=()" always;
# allow only for same origin
add_header Permissions-Policy "geolocation=(self), microphone=(self)" always;
# allow for specific origins
add_header Permissions-Policy "camera=(self https://trusted.com)" always;Control de acceso
Allow/Deny por IP
Las reglas allow/deny se evalúan en orden; gana la primera coincidencia. El deny all final bloquea cualquier cosa no permitida explícitamente. Es útil para cerrar los paneles de administración a las IPs corporativas. Las reglas pueden usar rangos CIDR o IPs individuales, y soportan IPv4 e IPv6.
location /admin {
allow 192.168.1.0/24; # internal network
allow 10.0.0.0/8; # VPN range
allow 203.0.113.5; # specific IP
deny all;
proxy_pass http://backend;
}
# rules are checked in order — first match wins
# if no rule matches, access is allowed by defaultDeny all
deny all bloquea a cualquiera; emparéjalo con allow para una lista blanca. El inverso — denegar IPs concretas, permitir a cualquiera — es una lista negra. Las listas blancas son más seguras (denegación por defecto). Sin un allow/deny explícito, el acceso está permitido, así que termina siempre con deny all en las áreas restringidas.
# deny all access to a location
location /private {
deny all;
return 403;
}
# deny specific IPs, allow everyone else
location / {
deny 192.168.1.100; # block one IP
deny 203.0.113.0/24; # block a range
allow all;
}
# deny a range, allow the rest
location /api {
deny 10.0.0.0/8;
allow all;
proxy_pass http://backend;
}Permitir subred
Los rangos de IP privados (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) no son enrutables en internet, así que permitirlos restringe el acceso a las redes internas. Para IPv6, ::1 es localhost. Combínalo con una VPN para acceso remoto seguro a herramientas internas.
# allow only local/private networks
location /internal {
allow 192.168.0.0/16; # private class B
allow 172.16.0.0/12; # private class B range
allow 10.0.0.0/8; # private class A
deny all;
root /var/www/internal;
}
# IPv6
location / {
allow 2001:db8::/32; # example IPv6 range
allow ::1; # IPv6 localhost
deny all;
}Módulo geo
geo está optimizado para búsquedas de IP usando un árbol radix — mucho más rápido que una lista larga de allow/deny. Fija una variable (aquí $allowed_ip) según la IP del cliente. La forma 'ranges' soporta rangos de IP inicio-fin. Usa la variable en if() o map para un control de acceso flexible.
# map IPs to values (binary search, very fast)
geo $allowed_ip {
default 0;
192.168.0.0/24 1;
10.0.0.0/8 1;
203.0.113.5 1;
}
server {
location /admin {
if ($allowed_ip = 0) {
return 403;
}
proxy_pass http://backend;
}
}
# geo with IP ranges (uses 'ranges' directive)
geo $country_code {
ranges;
default ZZ;
10.0.0.0-10.255.255.255 US;
}Límite por IP (limit_req)
limit_req_zone define una tasa por IP usando $binary_remote_addr (compacto). limit_req la aplica. burst permite picos cortos (encola hasta 20). nodelay sirve la ráfaga de inmediato en lugar de estrangular — bueno para APIs. Sin nodelay, las peticiones en exceso se retrasan, no se rechazan.
http {
# define rate limit zone (10 requests/sec per IP)
limit_req_zone $binary_remote_addr zone=mylimit:10m rate=10r/s;
server {
location /api/ {
limit_req zone=mylimit burst=20 nodelay;
proxy_pass http://backend;
}
}
}
# $binary_remote_addr uses binary form (more memory-efficient)
# 10m zone stores ~160,000 unique IP addresses
# rate=10r/s: 10 requests per second per IP
# burst=20: allow 20 requests to queue
# nodelay: serve the burst immediately (no artificial delay)Bloqueo por país (GeoIP)
El módulo GeoIP mapea las IPs de los clientes a códigos de país usando una base de datos de MaxMind. Combinado con map, puedes bloquear o permitir países enteros. Ojo: el GeoLite2 gratuito de MaxMind exige el módulo de terceros maxminddb (el módulo GeoIP heredado usa el formato antiguo .dat). La precisión no es del 100% — úsalo solo para filtrado grueso.
# requires the GeoIP module and a MaxMind database
geoip_country /usr/share/GeoIP/GeoIP.dat;
map $geoip_country_code $allowed_country {
default yes;
CN no;
RU no;
KP no;
}
server {
location / {
if ($allowed_country = no) {
return 403;
}
proxy_pass http://backend;
}
}
# GeoIP2 (maxminddb module) for the newer GeoLite2 format
# maxminddb /etc/nginx/geoip2/GeoLite2-Country.mmdb;
# $geoip2_country_code source=$remote_addr country iso_code;Autenticación
Configuración de Basic auth
auth_basic dispara el diálogo nativo de usuario/contraseña del navegador. La cadena de realm ('Área de administración') se muestra al usuario. auth_basic_user_file apunta a un archivo htpasswd. Usa auth_basic off para desactivar la autenticación en una sublocation que deba ser pública.
location /admin {
auth_basic "Admin Area";
auth_basic_user_file /etc/nginx/.htpasswd;
proxy_pass http://backend;
}
location /public {
# disable auth inherited from parent location
auth_basic off;
}
# create users with htpasswd (apache2-utils / httpd-tools):
# htpasswd -c /etc/nginx/.htpasswd user1 (create file)
# htpasswd /etc/nginx/.htpasswd user2 (append, no -c)Archivo htpasswd
El archivo htpasswd guarda pares usuario:hash. bcrypt (-B) es el hash más fuerte; MD5 (-m, por defecto) es aceptable; SHA1 (-s) es débil; PLAIN es inseguro. Restringe los permisos del archivo para que solo nginx pueda leerlo — el archivo contiene hashes de contraseñas que no deben filtrarse.
# /etc/nginx/.htpasswd format:
# user1:$apr1$qHR...$hashedpassword
# user2:{PLAIN}plaintext (insecure!)
# user3:{SHA}base64sha1hash
# generate with htpasswd:
# -c create new file (overwrites!)
# -B bcrypt (most secure, recommended)
# -m MD5 (default, APR1)
# -s SHA1
# bcrypt (recommended)
# htpasswd -B /etc/nginx/.htpasswd user1
# protect the file permissions
chown root:nginx /etc/nginx/.htpasswd
chmod 640 /etc/nginx/.htpasswdAutenticación para una location concreta
auth_basic se hereda en las locations anidadas. Para hacer pública una subruta, fija auth_basic off. Esto es útil cuando la mayor parte de /admin exige autenticación pero /admin/health (un endpoint de comprobación de salud) debería ser accesible sin credenciales para las herramientas de monitoreo.
server {
# no auth at server level
location /admin {
auth_basic "Admin";
auth_basic_user_file /etc/nginx/.htpasswd;
}
location /admin/api {
# inherits auth from /admin
proxy_pass http://admin_api;
}
location /admin/public {
# explicitly disable inherited auth
auth_basic off;
proxy_pass http://public_api;
}
}Allow/Deny con autenticación
satisfy any significa que pasar la comprobación de IP O la autenticación concede el acceso — cómodo para usuarios internos (sin contraseña) mientras se exige contraseña a los externos. satisfy all exige ambos — la opción más restrictiva, útil para áreas muy sensibles.
# satisfy: ALL (default) or ANY
location / {
# allow corporate IPs without password
# require password from outside the corporate network
satisfy any;
allow 192.168.0.0/16;
deny all;
auth_basic "Restricted";
auth_basic_user_file /etc/nginx/.htpasswd;
proxy_pass http://backend;
}
# satisfy all: must pass BOTH IP check AND auth
# satisfy any: pass EITHER IP check OR authMódulo auth request
auth_request envía una subpetición interna a un servicio de autenticación antes de la petición principal. El servicio valida el token (JWT, cookie de sesión, etc.) y devuelve 2xx (permitir) o 401/403 (denegar). internal impide el acceso externo a /auth. Esto desacopla la autenticación de tu app.
# delegate authentication to a subrequest (OAuth, JWT, etc.)
location / {
auth_request /auth;
proxy_pass http://backend;
}
location = /auth {
internal; # can't be called directly
proxy_pass http://auth-service/validate;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_set_header X-Original-URI $request_uri;
}
# auth-service returns:
# 2xx -> allow (continue to backend)
# 401/403 -> deny (return to client)
# other -> errorAutenticación JWT
La validación JWT puede hacerse en proceso con njs (módulo JavaScript de nginx) para baja latencia, o delegarse a un servicio externo vía auth_request. njs ejecuta un subconjunto de JavaScript dentro de nginx — rápido pero limitado. El enfoque auth_request es más flexible e independiente del lenguaje.
# requires the njs (nginx JavaScript) module
js_import auth.js;
location /api/ {
js_content auth.validateJwt;
proxy_pass http://backend;
}
# auth.js defines the validateJwt function:
# function validateJwt(r) {
# var token = r.headersIn.Authorization;
# if (!token || !verifyJwt(token)) {
# r.return(401);
# return;
# }
# }
# alternative: use auth_request with an external JWT validator service
# more portable than njs, but adds a network hop per requestLogging
Log de acceso
access_log registra cada petición. log_format define qué campos capturar. El formato 'combined' por defecto es compatible con Apache. Para sitios de alto tráfico, buffer+flush reduce la I/O de disco agrupando escrituras. syslog envía los logs a un servidor central para agregación.
http {
log_format main '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent"';
access_log /var/log/nginx/access.log main;
# or use the built-in 'combined' format
access_log /var/log/nginx/access.log combined;
}
# disable access log
access_log off;
# log to syslog
access_log syslog:server=localhost,facility=local7 main;
# buffer writes (reduce I/O)
access_log /var/log/nginx/access.log main buffer=32k flush=5s;Log de errores
error_log captura los errores de nginx y los problemas del upstream. El nivel filtra por severidad — warn es un buen valor por defecto. debug es muy verboso (úsalo solo para solucionar problemas) y exige una compilación con debug. memory: guarda los logs en RAM — útil para diagnosticar problemas de arranque que el logging a disco no puede capturar.
# error log location and severity level
error_log /var/log/nginx/error.log warn;
# levels (low to high severity):
# debug, info, notice, warn, error, crit, alert, emerg
# debug requires nginx built with --with-debug
error_log /var/log/nginx/error.log debug;
# log to memory (for debugging, lost on restart)
error_log memory:32m debug;
# disable (NOT recommended — hides real errors)
error_log /dev/null crit;Formatos de log
Los formatos de log personalizados capturan lo que te importa. request_time es el tiempo total de procesamiento; upstream_response_time aísla al backend. escape=json produce JSON válido para los agregadores de logs (ELK, Loki, Datadog). Sin escape=json, los caracteres especiales en los URIs podrían romper el parseo JSON.
http {
# combined (Apache-compatible, the default)
log_format combined '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent"';
# main with upstream timing
log_format main '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent" '
'rt=$request_time uct="$upstream_connect_time" '
'urt="$upstream_response_time"';
# JSON format for log aggregation (ELK, Loki, etc.)
log_format json escape=json
'{"time":"$time_iso8601",'
'"remote":"$remote_addr",'
'"method":"$request_method",'
'"uri":"$request_uri",'
'"status":$status,'
'"bytes":$body_bytes_sent,'
'"ua":"$http_user_agent"}';
}Logging condicional
El parámetro if= registra condicionalmente según una variable. map $status te permite registrar solo errores (4xx/5xx), reduciendo ruido y uso de disco en sitios de alto tráfico. La variable debe ser 0/vacía para saltarse el registro, no cero para registrar.
http {
# don't log successful 2xx/3xx, only errors
map $status $loggable {
~^[23] 0;
default 1;
}
server {
access_log /var/log/nginx/access.log main if=$loggable;
}
}
# skip logging for static assets
map $request_uri $log_skip {
default 1;
~*\.(jpg|png|gif|css|js)$ 0;
}
access_log /var/log/nginx/access.log main if=$log_skip;Rotación de logs
logrotate renombra y comprime los logs antiguos. postrotate envía USR1 a nginx, que reabre sus archivos de log — sin esto, nginx sigue escribiendo en el archivo renombrado. sharedscripts corre postrotate una vez (no por archivo). delaycompress comprime en la segunda rotación, así que el log más reciente queda sin comprimir.
# logrotate config: /etc/logrotate.d/nginx
/var/log/nginx/*.log {
daily
missingok
rotate 14
compress
delaycompress
notifempty
create 0640 www-data adm
sharedscripts
postrotate
if [ -f /var/run/nginx.pid ]; then
kill -USR1 $(cat /var/run/nginx.pid)
fi
endscript
}
# USR1 signal tells nginx to reopen log files
# without dropping connections
# nginx -s reopen does the same thingDesactivar logging
Desactivar access_log para las comprobaciones de salud y los recursos estáticos reduce significativamente el ruido de logs y la I/O de disco. log_not_found off suprime las entradas de 404 (útil para favicon.ico). Mantén siempre error_log activado al menos a nivel 'error' — los fallos silenciosos son difíciles de diagnosticar.
# disable access log entirely
access_log off;
# disable for a specific location
location /health {
access_log off;
return 200 "ok\n";
}
# disable for static assets
location ~* \.(jpg|png|gif|ico|css|js)$ {
access_log off;
log_not_found off;
}
# only log errors (reduce error log verbosity)
error_log /var/log/nginx/error.log error;Rate limiting
limit_req_zone
limit_req_zone define un límite de tasa indexado por una variable (normalmente la IP del cliente). El tamaño de la zona (10m) determina cuántas claves únicas pueden rastrearse. rate es la frecuencia de peticiones permitida. Define las zonas en el contexto http y aplícalas en el contexto location con limit_req.
http {
# 10 requests per second per IP
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
# 1 request per second per IP (for login)
limit_req_zone $binary_remote_addr zone=login:10m rate=1r/s;
# 100 requests per minute per IP
limit_req_zone $binary_remote_addr zone=general:10m rate=100r/m;
}
# $binary_remote_addr uses binary form (more memory-efficient than text)
# 10m zone stores ~160,000 unique IP addresses
# rate can be per second (r/s) or per minute (r/m)limit_req
limit_req aplica una zona a una location. burst permite picos cortos (encola hasta N peticiones en exceso). nodelay sirve la ráfaga a toda velocidad en lugar de espaciarla — bueno para APIs donde importa la latencia. Sin burst, toda petición que exceda la tasa se rechaza de inmediato.
http {
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
server {
location /api/ {
limit_req zone=api burst=20 nodelay;
proxy_pass http://backend;
}
location /login {
limit_req zone=api burst=5 nodelay;
proxy_pass http://backend;
}
}
}
# burst: max number of requests allowed to queue
# nodelay: serve the burst immediately (no artificial throttling)
# without burst: requests exceeding the rate get 503 immediatelylimit_conn
limit_conn limita las conexiones concurrentes, no la tasa de peticiones. Útil para evitar que una sola IP abra cientos de descargas simultáneas. Combinado con limit_req (tasa) aporta tanto protección contra ráfagas como contra concurrencia. limit_conn_zone usa el mismo patrón de zona por clave.
http {
# limit concurrent connections per IP
limit_conn_zone $binary_remote_addr zone=conn_per_ip:10m;
# limit total connections per server name
limit_conn_zone $server_name zone=conn_per_server:10m;
server {
limit_conn conn_per_ip 10;
limit_conn conn_per_server 1000;
location /download {
limit_conn conn_per_ip 1; # one download at a time per IP
proxy_pass http://backend;
}
}
}Cola de ráfagas
burst es el tamaño de cola para las peticiones en exceso. nodelay sirve toda la ráfaga de inmediato (bueno para APIs). delay=N sirve N de inmediato y estrangula el resto a la tasa configurada (más suave). Sin nodelay, todas las peticiones en exceso se retrasan para coincidir con la tasa, repartiendo la carga uniformemente.
http {
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
server {
location /api/ {
# burst=20: allow 20 requests to queue
# nodelay: serve them immediately (no artificial delay)
limit_req zone=api burst=20 nodelay;
# delay: first 10 immediate, next 10 delayed, rest rejected
limit_req zone=api burst=20 delay=10;
proxy_pass http://backend;
}
}
}
# without burst: requests over rate get 503 immediately
# with burst: excess requests queue (default delayed)
# nodelay: queue served at full speed (allows spikes)
# delay=N: first N immediate, rest throttled to the rateLímite de tasa por IP
Define zonas separadas por tipo de endpoint con tasas adecuadas. Los endpoints de API toleran tasas mayores; los endpoints de autenticación (login, restablecimiento de contraseña) necesitan límites estrictos para prevenir fuerza bruta; las subidas necesitan tasas muy bajas para evitar abusos. burst da una pequeña concesión para picos legítimos.
http {
# different limits for different endpoints
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
limit_req_zone $binary_remote_addr zone=auth:10m rate=1r/s;
limit_req_zone $binary_remote_addr zone=upload:10m rate=2r/m;
server {
location /api/ {
limit_req zone=api burst=20 nodelay;
}
location /login {
limit_req zone=auth burst=5 nodelay;
}
location /upload {
limit_req zone=upload burst=3 nodelay;
client_max_body_size 100M;
}
}
}Respuesta personalizada de límite de tasa
Por defecto, las peticiones limitadas por tasa reciben un 503 (Service Unavailable). 429 (Too Many Requests) es semánticamente más correcto y lo que esperan la mayoría de APIs. Usa error_page para devolver un body JSON que explique el límite. Incluye un header Retry-After para que los clientes sepan cuándo retirarse.
http {
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
limit_req_status 429; # default is 503
server {
location /api/ {
limit_req zone=api burst=20 nodelay;
# custom error response
error_page 429 = @rate_limited;
}
location @rate_limited {
default_type application/json;
return 429 '{"error":"rate_limit_exceeded","retry_after":60}';
}
}
}
# also available: limit_conn_status 429;Ajuste de rendimiento
worker_processes
worker_processes debería coincidir con el número de núcleos de CPU — auto lo hace automáticamente. Cada worker es un proceso monohilo que maneja muchas conexiones vía event loop. worker_cpu_affinity fija a los workers a núcleos concretos, mejorando la localidad de caché. La afinidad auto deja decidir al planificador del sistema operativo.
# main context
worker_processes auto; # one per CPU core (recommended)
# or set an explicit count
worker_processes 4;
# each worker handles connections independently
# 'auto' uses the number of available CPU cores
# CPU affinity (pin workers to specific cores)
worker_processes auto;
worker_cpu_affinity auto;
# or manual bitmask (one mask per worker)
worker_processes 4;
worker_cpu_affinity 0001 0010 0100 1000;worker_connections
worker_connections es por worker; la capacidad total es worker_processes * worker_connections. También está limitada por el tope de descriptores de archivo del sistema operativo (worker_rlimit_nofile). Debes subir tanto el límite de nginx como el del sistema (limits.conf o el LimitNOFILE de systemd). multi_accept toma todas las conexiones pendientes de una vez.
events {
# connections per worker process
worker_connections 4096;
# accept multiple connections at once under high load
multi_accept on;
}
# total max connections = worker_processes * worker_connections
# but also bounded by worker_rlimit_nofile (file descriptor limit)
# main context — raise the FD limit
worker_rlimit_nofile 65535;
# also raise system limits (outside nginx):
# /etc/security/limits.conf:
# * soft nofile 65535
# * hard nofile 65535keepalive_timeout
El keepalive del cliente reutiliza conexiones para varias peticiones, reduciendo la latencia. keepalive_timeout es cuánto tiempo una conexión inactiva permanece abierta. El keepalive upstream (la directiva keepalive en upstream) cachea conexiones a los backends — fija Connection a vacío para que nginx no envíe 'close'.
http {
# keep-alive timeout (client side)
keepalive_timeout 65s;
keepalive_requests 1000; # max requests per connection
# upstream keepalive (reuse connections to backends)
upstream backend {
server 10.0.0.1:8080;
keepalive 32; # cache of 32 idle upstream connections
}
location / {
proxy_pass http://backend;
proxy_http_version 1.1;
proxy_set_header Connection ""; # clear to enable keepalive
}
}sendfile y tcp_nopush
sendfile usa un camino de copia cero a nivel de kernel para enviar archivos, saltándose los búferes de espacio de usuario — mucho más rápido para archivos estáticos. tcp_nopush trabaja con sendfile para enviar los headers y el inicio del archivo en un paquete. tcp_nodelay desactiva Nagle para baja latencia. aio threads descarga la I/O de disco del event loop.
http {
# use kernel sendfile() for static files (zero-copy)
sendfile on;
# send headers + start of file in one TCP packet
tcp_nopush on;
# disable Nagle's algorithm (send small packets immediately)
tcp_nodelay on;
# for static file serving
location /static/ {
sendfile on;
tcp_nopush on;
aio threads; # asynchronous I/O via thread pool
root /var/www;
}
}
# sendfile: zero-copy file transfer (kernel space, no user-space copy)
# tcp_nopush: coalesce headers + file data into one packet
# tcp_nodelay: don't wait to batch small packets (low latency)Tamaños de búfer
Ajusta los búferes a tu tráfico. client_max_body_size acota el tamaño de subida (1M por defecto — demasiado pequeño para subidas de archivos). Los búferes proxy/fastcgi guardan las respuestas del upstream; búferes demasiado pequeños desbordan a disco. large_client_header_buffers maneja URLs/cookies largas. Monitorea los errores de 'buffer overflow'.
http {
# client body buffer (in-memory before writing to disk)
client_body_buffer_size 16k;
client_max_body_size 50m;
# client header buffers
client_header_buffer_size 1k;
large_client_header_buffers 4 8k;
# proxy buffers (responses from upstream)
proxy_buffer_size 4k;
proxy_buffers 8 4k;
proxy_busy_buffers_size 16k;
# fastcgi buffers (responses from PHP-FPM, etc.)
fastcgi_buffer_size 4k;
fastcgi_buffers 8 4k;
}
# if a request body exceeds client_body_buffer_size,
# nginx writes it to a temp file (slower)Caché de archivos abiertos
open_file_cache cachea descriptores de archivo y metadatos, evitando syscalls repetidas de open()/stat() para archivos populares. Esto acelera significativamente el servicio de archivos estáticos. valid controla con qué frecuencia nginx reexamina el archivo (atrapa actualizaciones). min_uses evita cachear peticiones puntuales. Cachea también los errores para evitar aperturas fallidas repetidas.
http {
open_file_cache max=10000 inactive=20s;
open_file_cache_valid 30s;
open_file_cache_min_uses 2;
open_file_cache_errors on;
server {
root /var/www/html;
location / {
open_file_cache max=10000 inactive=20s;
open_file_cache_valid 30s;
try_files $uri $uri/ =404;
}
}
}
# caches file descriptors, sizes, modification times
# reduces stat() and open() syscalls for popular files
# max=10000: cache up to 10000 files
# inactive=20s: remove if not accessed in 20 seconds
# min_uses=2: only cache files accessed 2+ times
# valid=30s: re-validate cache every 30sDespliegue con Docker
Nginx en Docker
La imagen oficial de nginx sirve /usr/share/nginx/html por defecto y lee la configuración de /etc/nginx. Monta tu configuración y contenido como volúmenes. :ro (solo lectura) evita que el contenedor modifique archivos del host. nginx -s reload recoge los cambios de configuración sin recrear el contenedor.
# run the official nginx image
docker run -d --name nginx \
-p 80:80 -p 443:443 \
-v /etc/nginx/nginx.conf:/etc/nginx/nginx.conf:ro \
-v /var/www/html:/usr/share/nginx/html:ro \
-v /etc/nginx/conf.d:/etc/nginx/conf.d:ro \
nginx:latest
# interactive shell into the running container
docker exec -it nginx sh
# reload config without restarting the container
docker exec nginx nginx -s reload
# view logs
docker logs nginx
docker logs -f nginxDocker Compose
Docker Compose orquesta nginx con sus backends. expose hace un puerto disponible para los servicios enlazados (no para el host). depends_on garantiza que el backend arranque primero. restart: unless-stopped sobrevive a reinicios pero respeta las paradas manuales. Monta los logs con acceso de escritura (sin :ro) para que nginx pueda escribirlos.
version: '3.8'
services:
nginx:
image: nginx:latest
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf:ro
- ./conf.d:/etc/nginx/conf.d:ro
- ./html:/usr/share/nginx/html:ro
- ./certs:/etc/nginx/certs:ro
- ./logs:/var/log/nginx
depends_on:
- backend
restart: unless-stopped
backend:
image: myapp:latest
expose:
- "3000"Imagen nginx personalizada
Hornear la configuración en la imagen hace los despliegues inmutables y reproducibles — sin montajes de volúmenes en runtime. La variante alpine mantiene la imagen diminuta (~7MB de base). Es ideal para Kubernetes o CI/CD donde quieres un artefacto autosuficiente. Reconstruye para actualizar la configuración.
# Dockerfile
FROM nginx:alpine
# copy custom config
COPY nginx.conf /etc/nginx/nginx.conf
COPY conf.d/ /etc/nginx/conf.d/
# copy static files
COPY html/ /usr/share/nginx/html/
# copy SSL certificates
COPY certs/ /etc/nginx/certs/
# build and run
# docker build -t mynginx .
# docker run -d -p 80:80 mynginx
# alpine is ~7MB; the image stays small
# bake config in for immutable deploymentsMontajes de volúmenes
Los montajes de volúmenes te permiten iterar sobre la configuración sin reconstruir la imagen — ideal para desarrollo. Montar un directorio es robusto; montar un archivo único puede romperse si el archivo del host no existe (Docker crea un directorio en su lugar). Los volúmenes con nombre persisten entre recreaciones de contenedor y los gestiona Docker.
# mount config and content as volumes (dev workflow)
docker run -d --name nginx \
-p 80:80 \
-v $(pwd)/nginx.conf:/etc/nginx/nginx.conf:ro \
-v $(pwd)/conf.d:/etc/nginx/conf.d:ro \
-v $(pwd)/html:/usr/share/nginx/html:ro \
-v $(pwd)/logs:/var/log/nginx \
nginx:alpine
# read-only mounts (:ro) for security
# logs need write access (no :ro)
# use named volumes for persistent data:
# -v nginx_logs:/var/log/nginx
# IMPORTANT: mounting a single file (nginx.conf) requires
# the file to exist on the host, or Docker creates a directoryProxy inverso en Docker
En Docker Compose, los servicios se resuelven entre sí por nombre de servicio (app1, app2). El upstream de nginx puede referenciar estos nombres directamente — sin necesidad de direcciones IP. Esto convierte a nginx en un potente balanceador para apps contenedorizadas. Usa la red por defecto de Compose, o define una personalizada para el aislamiento.
# nginx as reverse proxy for other containers
version: '3.8'
services:
nginx:
image: nginx:alpine
ports:
- "80:80"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf:ro
depends_on:
- app1
- app2
restart: unless-stopped
app1:
image: myapp:latest
app2:
image: myapp:latest
# nginx.conf:
# upstream apps {
# server app1:3000;
# server app2:3000;
# }
# server {
# listen 80;
# location / { proxy_pass http://apps; }
# }Comprobación de salud
Las comprobaciones de salud permiten a Docker (y a orquestadores como Swarm) saber si nginx realmente está sirviendo, no solo corriendo. wget --spider comprueba el estado HTTP sin descargar el body. start_period difiere la primera comprobación para que nginx pueda arrancar. En Kubernetes, usa una sonda readiness/liveness en lugar del HEALTHCHECK de Docker.
# Dockerfile with a health check
FROM nginx:alpine
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
CMD wget --quiet --tries=1 --spider http://localhost/ || exit 1
COPY nginx.conf /etc/nginx/nginx.conf
# docker-compose health check
version: '3.8'
services:
nginx:
image: nginx:alpine
healthcheck:
test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost/"]
interval: 30s
timeout: 3s
retries: 3
start_period: 5s
# start_period gives nginx time to boot before checking
# a failed health check marks the container unhealthyFragmentos de Nginx relacionados
Copy-paste ready code for common tasks.
Server Block
Configure a virtual host with root, index, and try_files.
Reverse Proxy
Forward requests to upstream HTTP services.
Load Balancing
Distribute traffic across multiple upstream servers.
HTTPS & SSL
Terminate TLS with certificates and HTTP/2.
Location Rules
Match request URIs with prefix, regex, and exact locations.
Rewrite & Redirect
Rewrite URIs and issue HTTP redirects.
Gzip Compression
Compress text responses to reduce bandwidth.
Proxy Caching
Cache upstream responses to reduce backend load.
Was this helpful?