У чому різниця між 502 і 504

Обидві помилки означають, що Nginx не зміг отримати нормальну відповідь від бекенду — PHP-FPM, застосунку на Node.js чи іншого проксі-сервера. Але причини різні. 502 Bad Gateway означає, що бекенд відповів некоректно або з'єднання обірвалося. 504 Gateway Timeout означає, що бекенд не відповів за відведений час — він просто занадто довго думає.

Перший крок діагностики завжди один: відкрити /var/log/nginx/error.log і подивитися останні рядки за момент помилки.

Як читати error.log при 502

Типові рядки при 502 і що вони означають:

Рядок у логу	Причина
connect() failed (111: Connection refused)	PHP-FPM або бекенд не запущений або слухає інший сокет
recv() failed (104: Connection reset by peer)	Бекенд впав під час обробки запиту, найчастіше через нестачу пам'яті
upstream sent too big header	Заголовки відповіді бекенду перевищили буфер Nginx

Перевірте, чи взагалі живий процес бекенду: systemctl status php8.3-fpm. Якщо сервіс впав, дивіться його власний лог: /var/log/php8.3-fpm.log.

Як читати error.log при 504

Рядок upstream timed out (110: Connection timed out) while reading response header from upstream означає, що PHP-FPM прийняв запит, але не відповів за час, заданий у proxy_read_timeout чи fastcgi_read_timeout. Зазвичай так стається через довгий SQL-запит, зовнішній виклик API без таймауту або нестачу вільних воркерів PHP-FPM.

Перевірте чергу PHP-FPM: systemctl status php8.3-fpm | grep -A2 active і статус пулу через fpm-status, якщо він увімкнений у конфігурації.

Як налаштувати таймаути правильно

Таймаути потрібно піднімати точково, лише для повільних маршрутів, а не глобально для всього сайту:

location /api/export/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_connect_timeout 5s;
    proxy_send_timeout 60s;
    proxy_read_timeout 60s;
}

Для зв'язки з PHP-FPM аналогічні параметри називаються fastcgi_connect_timeout, fastcgi_send_timeout і fastcgi_read_timeout. Значення за замовчуванням — 60 секунд, піднімати вище 120 секунд майже ніколи не варто: це ознака того, що повільний код краще полагодити, а не маскувати таймаутом.

Що перевірити на боці PHP-FPM

Часта причина і 502, і 504 — вичерпання пулу воркерів PHP-FPM. Перевірте параметри пулу в /etc/php/8.3/fpm/pool.d/www.conf:

pm.max_children — замале значення створює чергу і таймаути під навантаженням
pm.max_requests — періодичний перезапуск воркерів проти витоків пам'яті
лог повільних запитів slowlog і request_slowlog_timeout — показує, який саме код гальмує

Покроковий чек-лист діагностики

Порядок дій при появі 502 чи 504 на проді:

відкрити error.log і знайти точний рядок помилки за час інциденту
перевірити, чи живий процес бекенду: systemctl status
якщо бекенд живий — перевірити чергу та повільні запити через slowlog
якщо проблема в поодинокому повільному маршруті — підняти таймаут точково для нього
якщо проблема системна — збільшити pm.max_children і додати моніторинг пам'яті

Підсумок

502 означає, що бекенд відповів неправильно або впав, 504 — що він не встиг відповісти вчасно. В обох випадках рішення шукають не в Nginx, а в логах і налаштуваннях бекенду. Якщо помилки пов'язані саме зі зв'язкою Nginx і PHP, подивіться статтю Nginx і PHP-FPM: сокети, пули і fastcgi_params, а базові принципи проксі розібрані у статті reverse proxy на Nginx.

502 і 504 у Nginx: як знайти причину і полагодити сайт