Ошибка 502 Bad Gateway

Что значит 502 Bad Gateway

502 Bad Gateway — это HTTP-код категории 5xx (server error), означающий «прокси-сервер получил невалидный ответ от upstream-приложения». Понять этот код можно, представив архитектуру современного веб-приложения.

Типичная схема: Пользователь → Cloudflare CDN → Nginx (прокси) → Приложение (Node.js / Python / PHP) → База данных. Когда любое звено в цепи ломается, ошибка появляется на уровне прокси:

• Если приложение УПАЛО — прокси получает «connection refused» → возвращает 502.
• Если приложение ОТВЕЧАЕТ мусором — прокси получает невалидный HTTP → 502.
• Если приложение НЕ ОТВЕЧАЕТ за лимит — прокси возвращает 504 (не 502, это разные коды).

Причины 502

• Приложение упало. Необработанное исключение, OOM kill, segfault. Самая частая причина.
• Перезапуск без graceful. Деплой убил старые процессы, новые ещё не стартовали — окно пустоты 1-30 секунд.
• Memory leak. Приложение медленно ест память, OOM-killer убивает процесс. После рестарта — снова начинает течь.
• Connection pool exhausted. Соединения с БД исчерпаны, новые запросы блокируются на бесконечное ожидание.
• Long-running query / deadlock. Один SQL-запрос держит таблицу 5 минут, остальные запросы ждут — worker pool забивается.
• Перегрузка. Резкий пик трафика — приложение не справляется, начинает отвечать медленно или с ошибками.
• Конфигурация прокси. nginx upstream настроен на неправильный порт / IP — приложение «не там».
• SSL handshake failed. Если upstream — HTTPS, и сертификат истёк или не доверяется.

502 Bad Gateway is returned when the server, while acting as a gateway or proxy, received an invalid response from the upstream server. This typically indicates the upstream server is down, unreachable, or returning malformed responses.— Nginx documentation, error codes

Как диагностировать 502

1. Проверьте status приложения.

   # systemd
   systemctl status myapp
   
   # Docker
   docker ps | grep myapp
   docker logs --tail 100 myapp
   
   # Kubernetes
   kubectl get pods -n production
   kubectl logs <pod-name> --tail=100

2. Логи Nginx.

   tail -f /var/log/nginx/error.log
   
   # Смотрим на:
   # connect() failed (111: Connection refused)  → приложение не запущено
   # upstream timed out (110: Connection timed out) → приложение медленное / зависло
   # upstream prematurely closed connection → приложение упало во время ответа

3. Проверьте порт.

   netstat -tlnp | grep :3000
   ss -tlnp | grep :3000
   
   # Если порт не слушает — приложение упало.

4. Память и OOM.

   free -h
   dmesg | grep -i "killed process"
   journalctl -u myapp --since "1 hour ago" | grep -i memory

5. Health endpoint. Сделайте запрос на /health — если 200 OK значит приложение работает, проблема между прокси и приложением.

Как предотвратить 502

• Auto-restart. Docker `restart: always`, systemd `Restart=on-failure`, Kubernetes `restartPolicy: Always`. Упало — само поднялось через 5 секунд.
• Multiple workers. Gunicorn / PM2 запускают 4+ воркеров. Один упал — остальные работают, без пропуска запросов.
• Graceful shutdown. Принимайте SIGTERM, обрабатывайте in-flight запросы, потом завершайтесь. Не убивайте сразу через SIGKILL.
• Health check endpoint. /health возвращает 200 если БД, кэш, очереди доступны. 503 если что-то не так.
• Mониторинг 5xx. Datadog / Grafana / Yandex.Cloud Monitoring — алерт при error rate > 1%.
• Rate limiting на прокси. Защита от DDoS и неадекватных клиентов.
• Connection pool sizing. Лимиты соединений с БД, таймауты, retry с экспоненциальным backoff.
• Blue-green deployment. Развернуть новую версию параллельно, переключить трафик когда новая прогрелась. Без 502.
• Memory limit + alert. Если приложение ест >80% RAM — алерт. Время разобраться до OOM-kill.