502 Bad Gateway: причини и как да я поправите

Какво означава грешката

502 е отговор от сървър, който работи. Уеб сървърът отпред (nginx, Apache, балансьор на натоварването или CDN като Cloudflare) е получил заявката, предал я е на приложението зад него (PHP-FPM, процес на Node.js или Python, бекенд сървър) и не е получил използваем отговор: връзката е била отказана, прекъсната или е върнала боклук. „Gateway“ е сървърът отпред; „bad“ е това, което е дошло отзад.

Така 502 Ви казва две неща едновременно: отпред работи, отзад не работи или е повредено. Това стеснява търсенето значително.

Чести причини

1. Процесът на приложението не работи. PHP-FPM е забил или е спрян, процесът на Node.js е умрял, контейнерът е излязъл. Отпред изобщо не може да се свърже.
2. Приложението е претоварено. Всички PHP-FPM работници са заети, опашката е пълна, новите връзки се отказват. Често след скок на трафика или бавна заявка към базата данни, която блокира всеки работник.
3. Грешен сокет или порт в конфигурацията. След актуализация или смяна на версията на PHP nginx още сочи към php8.2-fpm.sock, докато новият пул слуша на php8.4-fpm.sock.
4. Твърде кратки времена за изчакване. Бекендът отговаря, но по-късно, отколкото отпред е склонен да чака. Някои конфигурации го отчитат като 502, други като 504 Gateway Timeout.
5. Бекендът изпраща прекалено голяма заглавна част или невалиден отговор. Типично за рамки, които слагат много в бисквитките; nginx тогава записва „upstream sent too big header“.
6. CDN не може да достигне Вашия сървър. При Cloudflare отпред страница 502 с логото на Cloudflare означава, че Cloudflare не е получил нищо от Вашия оригинален сървър: защитна стена, грешен IP след преместване или сървърът просто не работи.

Ако сте посетител

Не можете да поправите 502 на чужд сайт. Презаредете веднъж след минута; ако продължава, собственикът на сайта трябва да действа. За собствения си сайт продължете да четете.

Ако е Вашият сайт: проверете първо

Не работи ли за всички? Пуснете проверката дали сайтът не работи. Тя показва кода на състоянието отвън и дали е отговорил CDN, или оригиналният сървър.

Споделен хостинг или конструктор на сайтове? 502 там е почти винаги проблем на хостинга (претоварен PHP пул на споделен възел). Преминете към съобщението за хостинга си по-долу.

Вашият собствен сървър: влезте по SSH и попитайте уеб сървъра какво е станало.

# nginx: the last errors, newest at the bottom
sudo tail -n 50 /var/log/nginx/error.log

# Apache (Debian/Ubuntu)
sudo tail -n 50 /var/log/apache2/error.log

Типични редове и какво значат:

• connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory): PHP-FPM не работи или пътят до сокета е грешен.
• connect() failed (111: Connection refused) while connecting to upstream: портът на бекенда не слуша.
• upstream prematurely closed connection: процесът на бекенда е забил, докато е отговарял, често фатална грешка на PHP или недостиг на памет.
• upstream sent too big header: увеличете буферите (вижте по-долу).
• (11: Resource temporarily unavailable): всички PHP-FPM работници са заети.

Поправки на Вашия собствен сървър

1. Стартирайте спряната услуга

# find the PHP-FPM version you use
systemctl list-units --type=service | grep -E 'php|fpm'

systemctl status php8.3-fpm
sudo systemctl start php8.3-fpm

# Node.js or Python apps managed by systemd
sudo systemctl restart myapp

Ако услугата отказва да стартира, причината е в journalctl -u php8.3-fpm -n 50. Най-честата е пълен диск (df -h), втората е синтактична грешка в конфигурация на пул (sudo php-fpm8.3 -t).

2. Поправете сокета или порта

Сравнете към какво се свързва nginx с това, на което слуша PHP-FPM:

grep -r fastcgi_pass /etc/nginx/sites-enabled/
grep -r '^listen' /etc/php/*/fpm/pool.d/

Двете трябва да съвпадат. След промяна винаги тествайте конфигурацията, преди да презаредите:

sudo nginx -t && sudo systemctl reload nginx

При Apache и PHP-FPM през mod_proxy_fcgi същата проверка важи за реда SetHandler "proxy:unix:/run/php/php8.3-fpm.sock|fcgi://localhost"; тествайте със sudo apachectl configtest.

3. Дайте място на PHP-FPM

Ако логът за грешки казва, че работниците са заети, или server reached pm.max_children, повишете ограничението във файла на пула (/etc/php/8.3/fpm/pool.d/www.conf):

pm = dynamic
pm.max_children = 20
pm.start_servers = 4
pm.min_spare_servers = 2
pm.max_spare_servers = 6

Всеки работник се нуждае от памет (често от 30 до 80 MB за WordPress); проверете free -m, преди да повишите числото, и потърсете бавната заявка или плъгина, който държи работниците заети от самото начало.

4. Повишете буферите за големи заглавни части

В server блока на nginx:

fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;
proxy_buffers 8 16k;
proxy_buffer_size 32k;

5. Особености на WordPress

502 веднага след актуализация на плъгин или тема обикновено означава, че на PHP му свършва паметта или удря фатална грешка при всяка заявка. Преименувайте папката на плъгина през SFTP или SSH, за да го изключите (wp-content/plugins/plugin-name на plugin-name.off), после презаредете сайта. Повишете memory_limit в пула или php.ini, ако journalctl показва „Allowed memory size exhausted“. Ако ползвате WP-CLI: wp plugin deactivate plugin-name.

6. Зад Cloudflare

Проверете дали оригиналният сървър отговаря директно: curl -I https://YOUR-SERVER-IP -H 'Host: example.com' -k. Ако това работи, защитната стена на сървъра може да блокира адресните диапазони на Cloudflare или DNS записът в Cloudflare да сочи към стар IP.

Когато е проблем на Вашия хостинг

При споделен хостинг не можете да рестартирате PHP-FPM. Изпратете на хостинга си това, с часа и точната грешка:

Здравейте, сайтът ми example.com връща „502 Bad Gateway“ от около 14:30 UTC. Външна проверка го потвърждава; не съм променял нищо от моя страна. Моля, проверете PHP процесите и уеб сървъра на моя хостинг акаунт и ми кажете, когато работи отново.

Как да предотвратите следващата

502 е почти винаги спрян или претоварен бекенд и двете се виждат, преди посетителите да забележат: PHP-FPM услуга, която е спряла, свършваща памет, пълнещ се диск. Мониторингът на сървъри с агента отчита точно това отвътре на сървъра, а проверките на сайта отвън хващат 502 в момента, в който се появи. На Ваш собствен сървър Quick Fix може да рестартира спряната услуга, след като тестът на конфигурацията е успешен; ако причината е по-дълбока, Deep Fix поема денонощно.