Skip to content

Nginx Hoja de referencia

Servidor HTTP y proxy inverso de alto rendimiento.

01

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.

nginx
# /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 nginx

Directivas 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.

nginx
# 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.

nginx
# 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 nginx

Contexto 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.

nginx
# 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.

nginx
# 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.

nginx
# 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 stop
02

Bloques 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.

nginx
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.

nginx
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.

nginx
# 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 header

Directiva 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.

nginx
# 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.

nginx
# 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.

nginx
# 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;
}
03

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.

nginx
# 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.

nginx
# 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.

nginx
# 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.

nginx
# 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.

nginx
# 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).

nginx
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;
    }
}
04

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.

nginx
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.

nginx
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.

nginx
# 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_status

Timeouts 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.

nginx
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.

nginx
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.

nginx
# 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;
    }
}
05

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.

nginx
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 duration

Algoritmos 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.

nginx
# 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.

nginx
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=2

Comprobaciones 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.

nginx
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.

nginx
# 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.

nginx
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;
}
06

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.

nginx
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.

nginx
# 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'.

nginx
# 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.

nginx
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.

nginx
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.

nginx
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;
}
07

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.

nginx
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.css

Directiva 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.

nginx
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 Forbidden

try_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.

nginx
# 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.

nginx
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.

nginx
# 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.

nginx
# 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;
}
08

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).

nginx
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.

nginx
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.

nginx
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.

nginx
# 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 originals

Brotli

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.

nginx
# 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-Encoding

Gzip 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.

nginx
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
}
09

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.

nginx
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.

nginx
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.

nginx
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.

nginx
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.

nginx
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, HIT

Caché 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.

nginx
# 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 cache
10

Reescritura 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.

nginx
# 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 redirects

Directiva 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.

nginx
# 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 redirect

Flags 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.

nginx
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 instead

Capturas 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.

nginx
# 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 readability

Directiva 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.

nginx
# 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 chains

Directiva 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'.

nginx
# "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;
}
11

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.

nginx
# 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.

nginx
# 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.

nginx
# 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.

nginx
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.

nginx
# 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.

nginx
# 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;
    }
}
12

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.

nginx
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.

nginx
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.

nginx
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.

nginx
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.

nginx
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 out

try_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.

nginx
# 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;
    }
}
13

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.

nginx
# 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.

nginx
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.

nginx
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.

nginx
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 above

Varias 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.

nginx
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).

nginx
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 backend
14

Headers 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.

nginx
# 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.

nginx
# 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).

nginx
# 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.

nginx
# 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 support

Referrer-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.

nginx
# 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.

nginx
# 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;
15

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.

nginx
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 default

Deny 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.

nginx
# 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.

nginx
# 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.

nginx
# 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.

nginx
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.

nginx
# 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;
16

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.

nginx
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.

nginx
# /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/.htpasswd

Autenticació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.

nginx
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.

nginx
# 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 auth

Mó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.

nginx
# 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 -> error

Autenticació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.

nginx
# 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 request
17

Logging

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.

nginx
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.

nginx
# 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.

nginx
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.

nginx
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.

nginx
# 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 thing

Desactivar 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.

nginx
# 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;
18

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.

nginx
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.

nginx
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 immediately

limit_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.

nginx
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.

nginx
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 rate

Lí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.

nginx
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.

nginx
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;
19

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.

nginx
# 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.

nginx
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 65535

keepalive_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'.

nginx
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.

nginx
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'.

nginx
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.

nginx
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 30s
20

Despliegue 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.

nginx
# 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 nginx

Docker 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.

nginx
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.

nginx
# 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 deployments

Montajes 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.

nginx
# 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 directory

Proxy 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
# 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.

nginx
# 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 unhealthy

Was this helpful?