Directivas de tiempo de espera de NGINX: Guía de configuración completa
Este artículo es una traducción del original en inglés.
Comprender la configuración de tiempos de espera de NGINX es esencial para ejecutar servidores de producción estables. Los tiempos de espera mal configurados provocan caídas prematuras de las conexiones (lo que genera errores 504) o el agotamiento de recursos por conexiones que permanecen abiertas demasiado tiempo. Esta guía cubre cada directiva de tiempo de espera de NGINX, explica cuándo usar cada una y proporciona configuraciones listas para producción.
Las cuatro directivas esenciales de tiempo de espera de NGINX
NGINX tiene docenas de directivas relacionadas con los tiempos de espera, pero cuatro principales cubren la mayoría de los casos de uso:
| Directiva | Valor predeterminado | Propósito |
|---|---|---|
proxy_read_timeout |
60s | Tiempo de espera de la respuesta del upstream |
client_body_timeout |
60s | Tiempo entre los fragmentos del cuerpo de la solicitud que envía el cliente |
keepalive_timeout |
75s | Tiempo que las conexiones inactivas permanecen abiertas |
send_timeout |
60s | Tiempo entre los fragmentos de respuesta que se envían al cliente |
Cada directiva de tiempo de espera de NGINX opera en un punto diferente del ciclo de vida de la solicitud. Comprender cuándo se aplica cada una evita tanto las desconexiones prematuras como el desperdicio de recursos.
proxy_read_timeout: el culpable del error 504
Cuando NGINX actúa como proxy inverso, proxy_read_timeout es la configuración de tiempo de espera de NGINX más crítica. Define cuánto tiempo espera NGINX a que el servidor upstream envíe datos de respuesta. Consulte la documentación oficial de NGINX sobre proxy_read_timeout para obtener la referencia autorizada.
Comportamiento predeterminado
El valor predeterminado de proxy_read_timeout es de 60 segundos. Si su backend necesita más tiempo para procesar una solicitud, verá esto en su registro de errores:
upstream timed out (110: Connection timed out) while reading response header from upstream
Y los clientes reciben una respuesta 504 Gateway Timeout.
Cómo aumentar proxy_read_timeout
Aumente este valor de tiempo de espera de NGINX cuando:
- Ejecute operaciones de API de larga duración
- Procese cargas o exportaciones de archivos grandes
- Ejecute consultas de base de datos lentas
- Gestione la generación de informes o la creación de PDF
Configuración
location / {
proxy_pass http://backend;
# Increase for slow operations
proxy_read_timeout 120s;
}
Para un ajuste específico por ubicación (recomendado en lugar de cambios globales):
# Normal endpoints keep the 60s default
location / {
proxy_pass http://backend;
}
# Las operaciones de administración lentas obtienen más tiempo
location /admin/reports {
proxy_pass http://backend;
proxy_read_timeout 300s;
}
Tiempos de espera de upstream relacionados
Dos directivas complementarias completan el trío de tiempos de espera de NGINX de upstream:
proxy_connect_timeout 60s; # Tiempo para establecer la conexión TCP
proxy_send_timeout 60s; # Tiempo entre escrituras al upstream
proxy_read_timeout 60s; # Tiempo entre lecturas desde el upstream
En la práctica, solo proxy_read_timeout necesita ajustes. El establecimiento de la conexión (proxy_connect_timeout) rara vez tarda más de unos segundos, y los cuerpos de las solicitudes suelen enviarse rápidamente (proxy_send_timeout).
Para un diagnóstico completo de los problemas de tiempos de espera de upstream, consulte nuestra guía dedicada sobre errores 504 Gateway Timeout de NGINX.
client_body_timeout: Tiempos de espera de carga de archivos
La directiva client_body_timeout controla cuánto tiempo espera NGINX entre la recepción de fragmentos del cuerpo de la solicitud provenientes del cliente. Este tiempo de espera de NGINX es fundamental para las cargas de archivos.
Cómo funciona client_body_timeout
Este tiempo de espera de NGINX no mide el tiempo total de carga. En su lugar, mide el intervalo entre paquetes de datos sucesivos. Un cliente lento que carga un archivo grande a través de una conexión deficiente podría activar este tiempo de espera aunque los datos sigan llegando poco a poco.
Según el código fuente de NGINX, el tiempo de espera se aplica a cada operación de lectura en la conexión del cliente:
ngx_add_timer(c->read, clcf->client_body_timeout);
Valor predeterminado
El valor predeterminado de client_body_timeout es de 60 segundos. Para la mayoría de las aplicaciones web, esto es suficiente.
Cómo aumentar client_body_timeout
Aumente este tiempo de espera de NGINX para:
- Cargas de archivos grandes (video, copias de seguridad, imágenes)
- Usuarios móviles con conexiones deficientes
- Puntos de conexión de API que aceptan cargas útiles grandes
Configuración
# Para una ubicación de carga de archivos
location /upload {
client_max_body_size 100M;
client_body_timeout 300s;
proxy_pass http://upload_backend;
proxy_read_timeout 300s;
}
Nota: Al gestionar cargas, normalmente debe aumentar tanto client_body_timeout (NGINX recibiendo del cliente) como proxy_read_timeout (NGINX esperando que el backend procese la carga).
Relación con client_max_body_size
El client_body_timeout funciona junto con client_max_body_size para controlar el comportamiento de las cargas. Una solicitud que supera client_max_body_size se rechaza de inmediato con un error 413, antes de que client_body_timeout pueda aplicarse.
keepalive_timeout: Persistencia de la conexión
La directiva keepalive_timeout determina cuánto tiempo mantiene NGINX abiertas las conexiones de cliente inactivas. Este tiempo de espera de NGINX equilibra la eficiencia de la reutilización de conexiones frente al consumo de recursos.
HTTP Keep-Alive explicado
HTTP/1.1 introdujo las conexiones persistentes (keep-alive) para evitar la sobrecarga de establecer nuevas conexiones TCP para cada solicitud. Un navegador que carga una página con 50 recursos puede reutilizar una conexión en lugar de abrir 50.
Valor predeterminado
NGINX usa 75 segundos de forma predeterminada para keepalive_timeout. La configuración predeterminada de la distribución suele establecerlo en 65 segundos:
keepalive_timeout 65;
Opciones de sintaxis
La directiva acepta uno o dos parámetros:
# Valor único: solo tiempo de espera del lado del servidor
keepalive_timeout 65s;
# Dos valores: tiempo de espera del servidor y valor del encabezado Keep-Alive
keepalive_timeout 65s 60s;
El segundo parámetro establece el encabezado de respuesta Keep-Alive: timeout=60. Esto indica al navegador cuánto tiempo mantener la conexión. Establecerlo ligeramente por debajo del valor del servidor evita condiciones de carrera en las que el cliente cree que la conexión está activa pero el servidor ya la ha cerrado.
Configuración de producción
Para servidores de producción:
http {
# Keep connections open for 65 seconds
keepalive_timeout 65s 60s;
# Enable keepalive to upstream servers too
upstream backend {
server 127.0.0.1:8000;
keepalive 32; # Connection pool size
}
server {
location / {
proxy_pass http://backend;
proxy_http_version 1.1;
proxy_set_header Connection "";
}
}
}
Para obtener detalles sobre el agrupamiento de conexiones hacia upstream, consulte nuestra guía sobre keepalive de upstream en NGINX.
Cuándo ajustar keepalive_timeout
Aumente este tiempo de espera de NGINX cuando:
- Sirva aplicaciones en las que los usuarios realizan solicitudes frecuentes (SPA, paneles en tiempo real)
- Opere detrás de una CDN (las conexiones de CDN son valiosas de mantener abiertas)
Disminuya cuando:
- Ejecute un servidor de alto tráfico con límites de conexiones
- La memoria esté limitada (cada conexión usa memoria del kernel)
Consideraciones sobre HTTP/2 y HTTP/3
Con HTTP/2 y HTTP/3, la importancia de keepalive_timeout cambia. Estos protocolos multiplexan múltiples solicitudes sobre una sola conexión. Esto hace que la reutilización de conexiones sea aún más valiosa. Considere tiempos de espera más largos para el tráfico HTTP/2+:
http2_idle_timeout 180s; # HTTP/2 specific
send_timeout: protección frente a clientes lentos
La directiva send_timeout controla cuánto tiempo espera NGINX entre operaciones de escritura al enviar la respuesta al cliente.
Cómo funciona send_timeout
Al igual que client_body_timeout, este tiempo de espera de NGINX mide los intervalos entre operaciones, no el tiempo total de transferencia. Si un cliente deja de leer los datos de la respuesta, NGINX cierra la conexión tras send_timeout segundos sin actividad.
Valor predeterminado
El valor predeterminado es 60 segundos, lo que funciona para la mayoría de los escenarios.
Cuándo ajustar send_timeout
Aumente para:
- Descargas de archivos muy grandes
- Respuestas en streaming
- Clientes con conexiones extremadamente lentas
Disminuya para:
- Servidores de API en los que los clientes lentos desperdician recursos
- Sitios de alto tráfico que necesitan una rotación rápida de conexiones
Ejemplo de configuración
# For large file downloads
location /downloads {
send_timeout 300s;
# Also increase proxy timeout if proxying
proxy_read_timeout 300s;
}
Tiempos de espera de FastCGI, uWSGI y gRPC
Cuando NGINX se comunica con backends FastCGI (PHP-FPM), uWSGI o gRPC, existen directivas de tiempo de espera equivalentes.
Tiempos de espera de FastCGI (PHP-FPM)
location ~ .php$ {
fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
fastcgi_connect_timeout 60s;
fastcgi_send_timeout 60s;
fastcgi_read_timeout 60s; # Usually the one to increase
include fastcgi_params;
}
Para aplicaciones PHP, fastcgi_read_timeout es casi siempre el tiempo de espera de NGINX que necesita ajuste.
Para conexiones FastCGI persistentes, consulte nuestra guía sobre keepalive de FastCGI en NGINX.
Tiempos de espera de uWSGI (Python)
location / {
uwsgi_pass unix:/tmp/uwsgi.sock;
uwsgi_connect_timeout 60s;
uwsgi_send_timeout 60s;
uwsgi_read_timeout 60s;
include uwsgi_params;
}
Tiempos de espera de gRPC
location /grpc.ServiceName {
grpc_pass grpc://backend;
grpc_connect_timeout 60s;
grpc_send_timeout 60s;
grpc_read_timeout 60s;
}
Diagnóstico de problemas de tiempos de espera en NGINX
Cuando los usuarios informan errores de tiempo de espera, utilice estos enfoques de diagnóstico.
Revise el registro de errores de NGINX
El registro de errores revela qué tiempo de espera se activó:
grep -i "timed out" /var/log/nginx/error.log | tail -20
Mensajes comunes:
| Mensaje | Causa |
|---|---|
upstream timed out ... while reading response header |
proxy_read_timeout demasiado bajo |
upstream timed out ... while connecting |
proxy_connect_timeout demasiado bajo o backend caído |
client timed out |
client_body_timeout o send_timeout |
Ver la configuración de tiempos de espera activa
Vuelque la configuración efectiva para ver todos los valores de tiempo de espera de NGINX:
nginx -T 2>/dev/null | grep -E 'timeout|keepalive'
Medir el tiempo de respuesta del backend
Si observa tiempos de espera de upstream, mida el tiempo de respuesta real del backend:
curl -w "Time: %{time_total}sn" -o /dev/null -s http://127.0.0.1:8000/slow-endpoint
Si el backend tarda 90 segundos pero proxy_read_timeout es de 60 segundos, obtendrá errores 504.
Supervisar patrones de tiempos de espera
Vigile los errores de tiempo de espera en tiempo real:
tail -f /var/log/nginx/error.log | grep -i timeout
Recomendaciones de configuración para producción
Aplicación web general
http {
# Client timeouts
client_body_timeout 60s;
client_header_timeout 60s;
send_timeout 60s;
# Keep-alive
keepalive_timeout 65s 60s;
keepalive_requests 100;
upstream app {
server 127.0.0.1:8000;
keepalive 32;
}
server {
listen 80;
server_name example.com;
location / {
proxy_pass http://app;
proxy_http_version 1.1;
proxy_set_header Connection "";
# Upstream timeouts
proxy_connect_timeout 60s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
}
# Longer timeout for admin operations
location /admin {
proxy_pass http://app;
proxy_read_timeout 180s;
}
}
}
Servidor de API de alto tráfico
Para servidores de API que manejan muchas solicitudes:
http {
# Aggressive client timeouts
client_body_timeout 30s;
send_timeout 30s;
# Shorter keepalive
keepalive_timeout 30s;
keepalive_requests 1000;
upstream api {
server 127.0.0.1:8000;
keepalive 64;
}
server {
location /api {
proxy_pass http://api;
proxy_read_timeout 30s;
}
}
}
Servidor de carga de archivos
Para servidores que manejan cargas grandes:
server {
client_max_body_size 500M;
location /upload {
# Extended timeouts for uploads
client_body_timeout 600s;
proxy_read_timeout 600s;
proxy_pass http://upload_backend;
proxy_request_buffering off; # Stream directly to backend
}
}
Errores comunes con los tiempos de espera
Error 1: aumentar todos los tiempos de espera a ciegas
No establezca todos los tiempos de espera de NGINX en 300 segundos “por si acaso”. Esto desperdicia recursos y oculta problemas de rendimiento subyacentes.
Error 2: olvidar la cadena de tiempos de espera del backend
Si NGINX tiene proxy_read_timeout 120s pero PHP-FPM tiene request_terminate_timeout = 30, PHP muere primero. Asegúrese de que la cadena sea coherente:
NGINX proxy_read_timeout >= Backend process timeout
Para PHP:
; In php.ini
max_execution_time = 120
; In php-fpm pool config
request_terminate_timeout = 120
Error 3: usar tiempos de espera globales para endpoints específicos
En lugar de:
# Bad: global long timeout
proxy_read_timeout 300s;
Use anulaciones específicas por location:
# Good: targeted long timeout
location /reports/generate {
proxy_read_timeout 300s;
}
Error 4: ignorar los proxies intermedios
En arquitecturas de varias capas (NGINX a Varnish a Backend), cada capa tiene tiempos de espera. La capa externa debe tener tiempos de espera iguales o más largos que las capas internas.
Consulte nuestra guía sobre el error 504 Gateway Timeout para ver ejemplos de arquitecturas de varias capas.
Tabla de referencia rápida de tiempos de espera
| Directiva | Predeterminado | Se aplica a | Aumentar para |
|---|---|---|---|
proxy_read_timeout |
60s | Respuesta del upstream | Backends lentos, operaciones largas |
proxy_connect_timeout |
60s | Conexión TCP al upstream | Rara vez es necesario |
proxy_send_timeout |
60s | Envío al upstream | Cuerpos de solicitud grandes |
client_body_timeout |
60s | Cuerpo de la solicitud del cliente | Cargas de archivos |
client_header_timeout |
60s | Encabezados de la solicitud del cliente | Clientes lentos |
send_timeout |
60s | Envío al cliente | DESCARGAS grandes, clientes lentos |
keepalive_timeout |
75s | Conexiones inactivas | SPA, conexiones de CDN |
fastcgi_read_timeout |
60s | Respuesta de FastCGI | Scripts PHP lentos |
uwsgi_read_timeout |
60s | Respuesta de uWSGI | Aplicaciones Python lentas |
grpc_read_timeout |
60s | Respuesta de gRPC | Servicios gRPC lentos |
Resumen
Una configuración eficaz de los tiempos de espera de NGINX requiere comprender qué controla cada directiva:
- proxy_read_timeout gestiona los retrasos del upstream y es el principal culpable de los errores 504
- client_body_timeout gestiona los tiempos de espera de carga de clientes lentos
- keepalive_timeout equilibra la reutilización de conexiones frente al uso de recursos
- send_timeout protege frente a clientes lentos o bloqueados
Comience con los valores predeterminados, supervise sus registros de errores y ajuste tiempos de espera específicos según problemas reales en lugar de establecerlo todo alto de forma preventiva. Para la solución de problemas del error 504 específicamente, consulte nuestra guía complementaria sobre cómo corregir errores 504 Gateway Timeout en NGINX.
Ajustar hoy resuelve el problema de hoy. La regresión de mañana lo deshace en silencio. GetPageSpeed Amplify ejecuta análisis programados de gixy en cada host y vincula los hallazgos con métricas de tiempo de ejecución de NGINX en vivo. Compatible de forma directa con el obsoleto nginx-amplify-agent (fin de vida en enero de 2026).