Cómo diagnosticar y solucionar un error 504 Gateway Timeout en un servidor Linux con Nginx, PHP-FPM y WordPress aunque Nginx y MariaDB estén funcionando correctamente

Introducción

Un error 504 Gateway Timeout en un servidor Linux con Nginx y WordPress puede resultar especialmente desconcertante cuando los servicios principales parecen funcionar con normalidad. Nginx está activo, MariaDB acepta consultas, PHP-FPM figura como iniciado y el servidor dispone de memoria, CPU y espacio en disco. Sin embargo, la web tarda demasiado en responder y termina mostrando una página de error 504.

En este escenario, el problema puede encontrarse en el límite de procesos disponibles de PHP-FPM. El servicio continúa activo, pero todos sus trabajadores están ocupados y no queda ninguno libre para atender nuevas peticiones. Nginx espera la respuesta de PHP hasta alcanzar el tiempo máximo configurado y finalmente devuelve el error.

Este artículo explica cómo diagnosticar el problema paso a paso, cómo distinguirlo de una caída completa del servidor, cómo comprobar si PHP-FPM ha alcanzado el límite pm.max_children y cómo ampliar prudentemente su capacidad. El procedimiento está especialmente pensado para pequeños servidores que alojan varios sitios WordPress con un mismo pool de PHP-FPM.

Índice

Qué significa un error 504 Gateway Timeout

El código HTTP 504 indica que un servidor que actúa como puerta de enlace o proxy no ha recibido a tiempo la respuesta del servicio situado detrás. En una instalación habitual de WordPress con Nginx, el servidor web recibe la petición y la deriva a PHP-FPM para ejecutar el archivo PHP correspondiente.

La secuencia normal es la siguiente:

1. El navegador solicita una página.
2. Nginx recibe la petición HTTPS.
3. Nginx entrega el archivo PHP a PHP-FPM.
4. PHP ejecuta WordPress.
5. WordPress consulta MariaDB cuando necesita datos.
6. PHP-FPM devuelve el resultado a Nginx.
7. Nginx entrega la página al navegador.

Cuando PHP-FPM tarda demasiado, Nginx no puede completar la petición y termina mostrando un 504. Por tanto, un error de este tipo no significa necesariamente que Nginx esté detenido. De hecho, es Nginx quien genera y entrega la página del error.

Cómo intervienen Nginx, PHP-FPM, WordPress y MariaDB

Para interpretar correctamente la incidencia conviene separar las funciones de cada componente.

Comprobar que un servicio tiene estado active (running) es necesario, pero no suficiente. También hay que comprobar si responde con rapidez y si dispone de capacidad libre.

Síntomas que apuntan a la saturación de PHP-FPM

Los siguientes indicios, cuando aparecen juntos, apuntan con bastante claridad a un pool de PHP-FPM saturado:

• La web muestra temporalmente 504 Gateway Timeout.
• El acceso mediante SSH continúa funcionando.
• El servidor no se ha reiniciado.
• La carga de CPU es baja.
• Existe espacio libre en disco.
• Nginx aparece activo y escucha en los puertos 80 y 443.
• MariaDB aparece activo y acepta consultas.
• PHP-FPM aparece activo, pero muestra todos sus procesos ocupados.
• El log incluye el aviso server reached pm.max_children setting.
• La web vuelve a funcionar por sí sola unos minutos después.

Este patrón es diferente de una caída completa del servidor. En realidad, la infraestructura sigue operativa, pero se ha formado una cola de peticiones PHP que no puede atenderse a tiempo.

Diagnóstico inicial del servidor Linux

Antes de modificar PHP-FPM conviene descartar problemas generales del sistema.

Comprobar el tiempo desde el último arranque

who -b
uptime --pretty
last reboot | head -20

Si el servidor lleva días o semanas encendido, se puede descartar un reinicio reciente como causa inmediata.

Comprobar carga, memoria y procesos

uptime
free -h
vmstat 1 5
ps aux --sort=-%mem | head
ps aux --sort=-%cpu | head

Una carga baja no descarta una saturación de PHP-FPM. Los procesos pueden estar esperando una consulta, una conexión externa, un bloqueo de archivos o una tarea lenta sin utilizar intensamente la CPU.

Comprobar espacio e inodos

df -h
df -i

Una partición llena puede provocar fallos en sesiones, cachés, logs o archivos temporales. El agotamiento de inodos también puede impedir crear ficheros aunque queden gigabytes disponibles.

Buscar procesos eliminados por falta de memoria

dmesg | grep -i -E "oom|out of memory|killed process"
journalctl -k | grep -i -E "oom|out of memory|killed process"

Si no aparecen eventos OOM y existe memoria disponible, es más probable que el problema sea un límite de concurrencia que una falta real de RAM.

Comprobar Nginx, PHP-FPM y MariaDB

El siguiente bloque permite revisar rápidamente los servicios principales:

systemctl --failed

systemctl status nginx --no-pager
systemctl status php8.1-fpm --no-pager
systemctl status mariadb --no-pager

La versión incluida en el nombre del servicio debe adaptarse a la instalada. Por ejemplo, podría ser php8.2-fpm, php8.3-fpm o una versión posterior.

Comprobar que Nginx escucha

ss -tulpn | grep -E ':80|:443'

Una salida con Nginx escuchando en 0.0.0.0:80 y 0.0.0.0:443 confirma que el servidor web ha abierto los puertos. Esto no demuestra que WordPress pueda responder, pero descarta que Nginx esté completamente detenido.

Validar la configuración de Nginx

nginx -t

Antes de reiniciar Nginx siempre debe verificarse la sintaxis. Un error en un bloque de servidor puede impedir que el servicio vuelva a arrancar.

Comprobar MariaDB

mysqladmin ping
journalctl -u mariadb -n 100 --no-pager

El mensaje mysqld is alive o un estado equivalente confirma que MariaDB responde. No obstante, todavía podrían existir consultas lentas, bloqueos o credenciales incorrectas utilizadas por alguna aplicación.

Probar la respuesta desde el propio servidor

Las pruebas con curl ayudan a separar un problema interno de otro relacionado con DNS, router, firewall o conectividad exterior.

Probar Nginx mediante localhost

curl -I http://localhost
curl -kI https://localhost

Una respuesta rápida, incluso si es un código 301 de redirección, demuestra que Nginx puede atender conexiones locales.

Probar el dominio real

curl -I https://ejemplo.com

Si localhost responde, pero el dominio devuelve un 504, es posible que el virtual host correspondiente esté enviando la petición a PHP-FPM y que este no responda a tiempo.

Medir cuánto tarda

time curl -I https://ejemplo.com

Una espera cercana al tiempo de espera configurado en Nginx refuerza la hipótesis de que el backend PHP no está contestando.

Probar el dominio contra la IP local sin depender del DNS

curl -kI --resolve ejemplo.com:443:127.0.0.1 https://ejemplo.com/

Esta prueba fuerza el nombre de dominio y la cabecera Host, pero dirige la conexión a la propia máquina. Resulta útil para comprobar el virtual host correcto sin salir a Internet ni depender de la resolución pública.

Detectar si PHP-FPM ha alcanzado pm.max_children

PHP-FPM utiliza procesos trabajadores, también llamados hijos o children, para ejecutar las peticiones PHP. En un pool configurado como dinámico, el número de procesos crece y disminuye entre unos límites establecidos.

Consultar la configuración activa del pool

grep -E "^[[:space:]]*pm[[:space:]]*=|^[[:space:]]*pm\.max_children|^[[:space:]]*pm\.start_servers|^[[:space:]]*pm\.min_spare_servers|^[[:space:]]*pm\.max_spare_servers|^[[:space:]]*pm\.max_requests" \
/etc/php/8.1/fpm/pool.d/www.conf

Una configuración pequeña podría mostrar:

pm = dynamic
pm.max_children = 5
pm.start_servers = 2
pm.min_spare_servers = 1
pm.max_spare_servers = 3

Comprobar el estado de PHP-FPM

systemctl status php8.1-fpm --no-pager

Una línea como la siguiente es especialmente significativa:

Status: "Processes active: 5, idle: 0"

Significa que los cinco trabajadores están ocupados y que no existe ninguno libre. Si pm.max_children también está configurado en 5, PHP-FPM no puede crear procesos adicionales.

Revisar los procesos en ejecución

ps -ef | grep '[p]hp-fpm'

Normalmente se verá un proceso maestro ejecutado por root y varios procesos del pool ejecutados por www-data.

Buscar la confirmación en el log

grep -n "max_children" /var/log/php8.1-fpm.log
tail -100 /var/log/php8.1-fpm.log

El mensaje decisivo es:

WARNING: [pool www] server reached pm.max_children setting (5), consider raising it

Este aviso confirma que PHP-FPM necesitó crear más procesos, pero no pudo hacerlo porque había alcanzado el límite configurado.

Por qué la web puede recuperarse sola

Alcanzar pm.max_children no significa necesariamente que los procesos estén muertos. Lo habitual es que estén ocupados durante demasiado tiempo.

La secuencia puede ser la siguiente:

1. Los cinco procesos de PHP-FPM comienzan a atender peticiones.
2. Una o varias peticiones tardan mucho debido a WordPress, un plugin, una consulta o una conexión externa.
3. Se reciben nuevas solicitudes, pero no hay trabajadores libres.
4. Las solicitudes quedan en cola.
5. Nginx espera hasta alcanzar su tiempo límite.
6. Nginx devuelve un error 504.
7. Uno de los procesos PHP termina su tarea o alcanza un límite de tiempo.
8. El trabajador queda libre y empieza a atender nuevas peticiones.
9. La web vuelve a responder sin que nadie reinicie el servicio.

La recuperación espontánea no significa que el problema haya quedado resuelto. Solo indica que el atasco temporal se ha disuelto. Si el pool sigue siendo demasiado pequeño o persiste una operación lenta, la incidencia puede repetirse.

Cómo ampliar el límite de PHP-FPM

La ampliación debe hacerse con prudencia. Subir el número de procesos aporta capacidad para atender más peticiones simultáneas, pero cada proceso consume memoria y puede generar consultas adicionales contra MariaDB.

Crear una copia de seguridad

cp /etc/php/8.1/fpm/pool.d/www.conf \
/etc/php/8.1/fpm/pool.d/www.conf.bak-$(date +%Y%m%d-%H%M%S)

Ejemplo de configuración para un servidor con margen de memoria

pm = dynamic
pm.max_children = 15
pm.start_servers = 4
pm.min_spare_servers = 2
pm.max_spare_servers = 6
pm.max_requests = 500

Qué significa cada parámetro

Modificar temporalmente los permisos si se utiliza un editor SFTP

Algunos editores integrados en clientes SSH abren los archivos con el usuario normal de la sesión, aunque en la terminal se haya utilizado su para convertirse en root. En ese caso, puede concederse temporalmente permiso de escritura al archivo:

chmod 666 /etc/php/8.1/fpm/pool.d/www.conf

Después de guardar, deben restaurarse inmediatamente los permisos y el propietario:

chmod 644 /etc/php/8.1/fpm/pool.d/www.conf
chown root:root /etc/php/8.1/fpm/pool.d/www.conf

No se debe dejar permanentemente un archivo de configuración del sistema con permisos de escritura para todos.

Activar el registro de peticiones PHP lentas

Aumentar pm.max_children evita que unas pocas peticiones ocupadas bloqueen inmediatamente todo el pool, pero no identifica la causa de la lentitud. Para ello conviene activar el slowlog de PHP-FPM.

En el archivo del pool pueden añadirse o descomentarse estas directivas:

slowlog = /var/log/php8.1-fpm-slow.log
request_slowlog_timeout = 10s
request_terminate_timeout = 120s

Funcionamiento de estas opciones

• slowlog define el archivo donde se escribirán las trazas de las peticiones lentas.
• request_slowlog_timeout = 10s registra una traza cuando una petición supera diez segundos.
• request_terminate_timeout = 120s finaliza un proceso que permanece ejecutando la misma petición durante más de dos minutos.

El límite de terminación debe ajustarse a las tareas reales del servidor. Una importación legítima, una copia de seguridad o un proceso administrativo pesado podrían necesitar más tiempo. No conviene imponer un tiempo demasiado corto sin revisar primero el funcionamiento de las aplicaciones.

Consultar el slowlog

tail -100 /var/log/php8.1-fpm-slow.log

Para seguirlo en tiempo real:

tail -F /var/log/php8.1-fpm-slow.log

Si el archivo permanece vacío, significa que ninguna petición ha superado el umbral configurado desde que se aplicó la configuración.

Validar la configuración y reiniciar PHP-FPM

Nunca debe reiniciarse PHP-FPM después de editar el archivo sin comprobar antes la sintaxis.

Validar

php-fpm8.1 -t

La salida esperada es similar a:

NOTICE: configuration file /etc/php/8.1/fpm/php-fpm.conf test is successful

Reiniciar

systemctl restart php8.1-fpm

Comprobar el estado

systemctl status php8.1-fpm --no-pager

Después del reinicio debería aparecer:

Active: active (running)
Status: "Ready to handle connections"

Confirmar el número inicial de trabajadores

ps -C php-fpm8.1 -o pid,ppid,user,%cpu,%mem,rss,etime,cmd

Con pm.start_servers = 4 se espera encontrar un proceso maestro y cuatro procesos del pool al arrancar. El número podrá aumentar dinámicamente hasta 15 cuando exista demanda.

Comprobar varios sitios WordPress después del cambio

Cuando un mismo pool PHP-FPM atiende varios dominios, hay que comprobarlos todos después del reinicio:

curl -I https://sitio1.com
curl -I https://sitio2.com
curl -I https://sitio3.com

Una respuesta correcta normalmente mostrará:

HTTP/1.1 200 OK
Server: nginx
Content-Type: text/html; charset=UTF-8

También debe revisarse una página interna y el acceso administrativo:

curl -I https://sitio1.com/blog/
curl -I https://sitio1.com/wp-login.php

Una portada puede estar almacenada en caché mientras otras rutas siguen dependiendo de PHP. Por ello es útil comprobar varias URL dinámicas.

Monitorizar Nginx y PHP-FPM conjuntamente

En un servidor con varios sitios web resulta útil seguir simultáneamente los registros de acceso de Nginx y los logs de PHP-FPM.

tail -F /var/log/nginx/sitio1.log | sed 's/^/SITIO1: /' & \
tail -F /var/log/nginx/sitio2.log | sed 's/^/SITIO2: /' & \
tail -F /var/log/nginx/sitio3.log | sed 's/^/SITIO3: /' & \
tail -Fv /var/log/php8.1-fpm.log /var/log/php8.1-fpm-slow.log | sed 's/^/SLOW-PHP: /'

La opción -F sigue el archivo por su nombre y vuelve a abrirlo si se rota o se recrea. Es más adecuada para logs que -f, que puede continuar siguiendo el archivo antiguo después de una rotación.

La opción -v muestra una cabecera cuando se siguen varios archivos. De este modo puede distinguirse si una línea procede del log general de PHP-FPM o del slowlog.

Los prefijos añadidos mediante sed facilitan reconocer qué sitio ha generado cada petición cuando las líneas se mezclan en la terminal.

Interpretar los códigos 499, 502, 503 y 504

Una línea como esta resulta especialmente informativa:

"POST /wp-admin/admin-ajax.php HTTP/1.1" 499

Puede indicar que una operación AJAX del administrador tardó tanto que el navegador o el usuario cerró la petición. Si coincide con un aviso de pm.max_children, esa operación pudo contribuir a mantener ocupado el pool.

Causas habituales de la saturación

Actividad en wp-admin

La biblioteca multimedia, editores visuales, importadores, generadores de miniaturas y operaciones AJAX pueden ejecutar procesos costosos. Una sola acción administrativa puede realizar varias peticiones simultáneas.

Bots y rastreadores

Buscadores, herramientas SEO, redes sociales, bots de inteligencia artificial y escáneres automatizados pueden acceder a muchas URL dinámicas. El tráfico no necesita ser masivo para saturar un pool limitado a cinco procesos.

WP-Cron

WordPress puede ejecutar tareas programadas durante una visita normal. Copias de seguridad, limpiezas, publicaciones programadas, envíos, sincronizaciones o comprobaciones de plugins pueden prolongar la respuesta.

Consultas lentas de MariaDB

MariaDB puede estar activo y, aun así, una consulta concreta tardar demasiado. PHP permanece esperando la respuesta mientras el trabajador continúa ocupado.

Llamadas a servicios externos

Un plugin puede conectarse a una API, comprobar una licencia, descargar datos, validar un captcha o enviar información a otro servicio. Si la conexión externa tarda, el proceso PHP queda retenido.

Plugins o temas deficientes

Un bucle, una consulta no optimizada, una búsqueda excesiva en la base de datos o una función que procesa demasiados registros puede consumir un trabajador durante mucho tiempo.

Falta de caché

Sin caché de página, cada visita pública ejecuta WordPress completo. En sitios con muchas URL y rastreadores frecuentes, esto incrementa notablemente el número de peticiones PHP.

Varios sitios compartiendo el mismo pool

Si tres WordPress utilizan el socket /run/php/php8.1-fpm.sock, todos compiten por los mismos trabajadores del pool www. Una incidencia en un sitio puede dejar temporalmente sin capacidad a los otros dos.

Cómo dimensionar el pool sin excederse

No existe un número universal para pm.max_children. Debe calcularse teniendo en cuenta la memoria disponible y el consumo real de cada proceso.

Medir el consumo de los procesos PHP

ps --no-headers -o rss -C php-fpm8.1 | awk '
{ total += $1; n++ }
END {
  if (n > 0)
    printf "Procesos: %d\nRSS medio: %.1f MB\nRSS total: %.1f MB\n",
           n, total/n/1024, total/1024;
  else
    print "No se encontraron procesos php-fpm8.1";
}'

Estimación básica

Una aproximación prudente consiste en reservar memoria para Linux, MariaDB, Nginx, cachés y otros servicios, y dividir solo la memoria restante entre el consumo medio o alto de cada trabajador PHP.

pm.max_children aproximado =
memoria reservada para PHP / consumo por trabajador

Por ejemplo, si se reservan 3 GB para PHP y cada trabajador puede consumir unos 200 MB:

3072 MB / 200 MB ≈ 15 procesos

La cifra debe revisarse con mediciones reales. Elevar el límite de 5 a 15 puede ser razonable en una máquina con suficiente memoria, pero subirlo indiscriminadamente a 50 o 100 podría provocar presión de memoria, más intercambio en disco y demasiadas conexiones simultáneas a MariaDB.

Cuándo crear pools independientes por sitio

Para un servidor pequeño, compartir un único pool puede simplificar la administración. Sin embargo, cuando existen varios WordPress con cargas diferentes, los pools independientes ofrecen aislamiento.

Una posible estructura sería:

/etc/php/8.1/fpm/pool.d/sitio1.conf
/etc/php/8.1/fpm/pool.d/sitio2.conf
/etc/php/8.1/fpm/pool.d/sitio3.conf

Cada pool tendría su propio socket:

listen = /run/php/php8.1-fpm-sitio1.sock
listen = /run/php/php8.1-fpm-sitio2.sock
listen = /run/php/php8.1-fpm-sitio3.sock

Y cada virtual host de Nginx enviaría las peticiones al socket correspondiente:

fastcgi_pass unix:/run/php/php8.1-fpm-sitio1.sock;

Ventajas

• Una web no puede consumir todos los procesos asignados a las demás.
• Se pueden establecer límites diferentes según el tráfico.
• Los logs pueden separarse por sitio.
• Es más fácil identificar qué aplicación genera procesos lentos.
• Puede utilizarse un usuario Linux diferente para cada proyecto.

Inconvenientes

• Aumenta el número de archivos de configuración.
• Puede reservarse más memoria en procesos ociosos.
• La administración y actualización requieren más cuidado.
• Una asignación demasiado rígida puede dejar capacidad libre en un pool mientras otro se satura.

Para tres sitios pequeños, ampliar primero el pool común y activar el slowlog es una intervención razonable. Si las incidencias se repiten o un sitio presenta una carga claramente superior, conviene plantear la separación.

Medidas para prevenir nuevos errores 504

1. Dimensionar PHP-FPM con datos reales: medir el consumo de memoria antes de aumentar considerablemente los procesos.
2. Activar el slowlog: identificar scripts y plugins que superen un tiempo razonable.
3. Revisar periódicamente el aviso de max_children: comprobar si el nuevo límite vuelve a alcanzarse.
4. Controlar los bots: limitar rastreadores agresivos mediante Nginx, robots.txt, firewall o una capa de protección adecuada.
5. Configurar caché: reducir la ejecución completa de WordPress en visitas públicas repetidas.
6. Revisar WP-Cron: trasladarlo a una tarea cron real cuando el sitio tenga actividad suficiente.
7. Optimizar MariaDB: detectar consultas lentas, tablas grandes y bloqueos.
8. Actualizar PHP y Ubuntu: utilizar versiones con soporte de seguridad y compatibilidad con WordPress.
9. Separar pools cuando sea necesario: evitar que una web afecte a todas las demás.
10. Monitorizar códigos HTTP: buscar aumentos de 499, 502, 503 y 504.

Comandos de revisión periódica

grep "max_children" /var/log/php8.1-fpm.log
tail -100 /var/log/php8.1-fpm-slow.log
systemctl status php8.1-fpm --no-pager
free -h
ps aux --sort=-%mem | head

Comprobar solo los eventos posteriores a un cambio

journalctl -u php8.1-fpm --since "today" --no-pager

Después de ampliar el pool, conviene observar durante varios días si vuelve a alcanzarse el límite y si aparecen trazas lentas. La ausencia de nuevos 504 no basta para saber si la causa original ha desaparecido o simplemente dispone de más margen.

Conclusión

Un error 504 Gateway Timeout no implica necesariamente que Linux, Nginx o MariaDB hayan dejado de funcionar. En un servidor WordPress, PHP-FPM puede estar activo y, al mismo tiempo, haber agotado todos los procesos disponibles.

La combinación de un estado active: 5, idle: 0, un límite pm.max_children = 5 y el aviso server reached pm.max_children setting permite identificar con bastante precisión la saturación del pool.

La solución inmediata consiste en ampliar prudentemente el número máximo de trabajadores, validar la configuración y reiniciar PHP-FPM. La solución técnica completa requiere además activar el slowlog, observar qué peticiones superan el tiempo previsto y revisar bots, plugins, tareas AJAX, WP-Cron, consultas a MariaDB y llamadas externas.

En servidores con varios WordPress, todos los sitios pueden competir por el mismo conjunto de procesos. Por eso conviene evaluar tanto el tamaño global del pool como la posibilidad de crear pools independientes cuando sea necesario aislar cargas y evitar que una única web afecte al resto.

Preguntas frecuentes