#Симптом и границы применимости
После обновления Nginx или динамического модуля лишь некоторые URL дают 502, тогда как главная страница продолжает открываться. Код 502 означает проблему обмена с вышестоящим сервером; сам модуль может быть лишь косвенной причиной.
#Возможные причины и как их отличить
| Возможная причина | Как узнать | Что делать |
|---|---|---|
| Отличается маршрут locationДля отдельных путей может использоваться другой upstream. | 502 появляется только у /api/ или /admin/ | Сопоставить location и proxy_pass/fastcgi_pass |
| Несовместимость модуля или фильтраДинамические модули требуют совместимости с установленным Nginx. | Сбой начинается после обновления на определённых ответах | Сравнить журналы и версию сборки |
| Падают отдельные процессы приложенияОтвет 502 может появляться только при выполнении тяжёлых обработчиков. | В журнале connection refused / upstream prematurely closed | Проверить журналы конкретного backend |
#Пошаговая диагностика и исправление
- Зафиксируйте воспроизводимые путиВ браузере соберите два адреса на одном домене: исправный и дающий 502. Запишите время, URL без секретных параметров и разницу GET/POST. Не передавайте cookies или токены. Проверьте каждый URL без повторной отправки опасных POST-запросов.
- Сравните ответы с сервераНа своём компьютере выполните curl -I для обеих публичных страниц; если API требует GET или HEAD не поддерживает, используйте безопасный GET на тестовом маршруте. Если ошибка только на динамических запросах, переходите к upstream, а не к TLS.Linux · Терминал (Bash)КомандаЗамените /api/health на существующий безопасный адрес; 405 на HEAD не означает сбоя.
curl -I https://example.com/curl -I https://example.com/api/health
- Найдите соответствующую ошибку в журналеВ SSH найдите путь error_log и откройте последние записи в момент проблемы. Строки connect() failed, upstream sent invalid header, upstream prematurely closed connection имеют разные причины. Не повышайте уровень логирования на весь сайт без оценки объёма и персональных данных.
- Логи могут содержать URL и личные данные; обезличьте ихLinux · Терминал (Bash)КомандаНужен sudoЛоги могут содержать URL и личные данные; обезличьте их.
sudo nginx -T 2>&1 | grep -nE "error_log|proxy_pass|fastcgi_pass|load_module"sudo journalctl -u nginx -n 80 --no-pager
- Проверьте состояние вышестоящего приложенияПо строке upstream в журнале определите адрес или Unix-сокет. Для TCP-порта посмотрите ss; для PHP-FPM — состояние службы и соответствующий пул; для другого приложения — его отдельный журнал. Если ошибка только в одном обработчике, проверьте его зависимости и время выполнения, не меняя общие тайм-ауты.
- Не изменяет систему; для Unix-сокетов дополнительно используйте ss -lxnpLinux · Терминал (Bash)КомандаНужен sudoНе изменяет систему; для Unix-сокетов дополнительно используйте ss -lxnp.
sudo ss -lntp
- Проверьте версию и модуль после обновленияСравните вывод nginx -V и пакетный журнал обновления. В конфигурации найдите load_module; проверьте, что Nginx действительно стартовал без ошибок загрузки. Не копируйте бинарный модуль из другой версии и не отключайте проверку подписи или защиту ради теста.Linux · Терминал (Bash)КомандаВыводит опции сборки и расположения настроек.
nginx -V 2>&1
- Откатите только подтверждённую несовместимостьЕсли по журналу доказан сбой нового модуля, согласуйте окно обслуживания. Сохраните текущие конфиги и список пакетов; отключите необязательный модуль в тестовом окружении или вернитесь к совместимой версии из надёжного репозитория. После nginx -t выполните контролируемое перечитывание и проверьте проблемные пути.Linux · Терминал (Bash)С осторожностьюНужен sudoПеред изменениями требуется резервная копия; обновление модулей может потребовать перезапуска.
sudo nginx -tКоманда может изменить состояние системы или её настройки. Проверьте параметры и последствия перед запуском.
#Как проверить результат
Два исходных адреса должны стабильно возвращать ожидаемые ответы. В error_log перестали появляться ошибки upstream в том же сценарии; сравните сообщения при повторном безопасном запросе.
#Если проблема не устранена
Если 502 сохраняется только при определённом POST/нагрузке, исследуйте запрос и журнал приложения вместе с upstream_addr и upstream_status; не маскируйте падение увеличением proxy_read_timeout без понимания причины.