nginx 502 после рестарта Docker контейнера

Когда контейнер за nginx-прокси перезапускается (docker compose up -d, рестарт самого Docker, новая версия образа) — он получает новый IP в Docker network. nginx, который резолвил DNS-имя upstream’а только при старте, продолжает слать запросы на старый IP → 502 Bad Gateway.

Воспроизведение

docker compose up -d immich_server  # ← новый IP в Docker bridge
curl https://photo.example/         # → 502 Bad Gateway
docker restart nginx                # ← перерезолвит имена
curl https://photo.example/         # → 200 OK

Почему так

В типичном nginx-конфиге:

upstream immich {
  server immich_server:2283;
}

nginx резолвит immich_server → IP один раз при старте и кеширует навсегда (пока процесс жив). Docker DNS даёт правильный IP в момент резолва, но если контейнер потом пересоздаётся — IP меняется, nginx про это не знает.

Решения

Простое — рестарт nginx после изменений

docker restart nginx

Подходит для редких ручных операций.

Авто-фикс при boot

systemd unit который ждёт пока зависимые контейнеры станут healthy, потом делает docker restart nginx. Выполняется один раз при boot.

Правильный — resolver в nginx

Заставить nginx переразрешать DNS на каждый запрос через переменные в proxy_pass:

server {
  resolver 127.0.0.11 valid=10s ipv6=off;  # Docker embedded DNS
 
  location / {
    set $upstream "immich_server:2283";
    proxy_pass http://$upstream;
  }
}

Ключевые моменты:

• 127.0.0.11 — Docker’s встроенный DNS (доступен из любого контейнера в bridge network)
• valid=10s — TTL кеша резолва
• set $upstream + переменная в proxy_pass отключает один-раз-при-старте резолв и заставляет per-request lookup
• НЕ работает с upstream блоком без commercial-only фичи nginx plus

Trade-off: при использовании переменных теряется keepalive upstream connection pool (open-source nginx).

Когда какое решение использовать

Связано

• systemd unit для рестарта после Docker healthcheck

Мета

Область:: 00 Nginx