Nginx в Docker: поднимаем реверс-прокси для всех домашних сервисов

Nginx Proxy Manager (NPM) — полноценный веб-интерфейс для управления реверс-прокси. Не нужно править конфиги вообще: добавляешь хосты через браузер, настраиваешь SSL в пару кликов, управляешь перенаправлениями. Под капотом — тот же Nginx.

По статистике запросов — один из самых популярных вариантов для домашних серверов. И понятно почему: порог входа минимальный. Но гибкость ниже, чем у ручной конфигурации. Сложные правила проксирования, нестандартные заголовки, тонкая настройка кеширования — тут NPM начинает мешать.

nginx:alpine-slim

Образ: nginx:alpine-slim

Ещё более урезанная версия Alpine-сборки. Убраны некоторые модули, минимизирован размер. Для реверс-прокси с базовой конфигурацией — достаточен.

bitnami/nginx

Образ: bitnami/nginx

От Bitnami (VMware/Broadcom). Работает от непривилегированного пользователя из коробки (не root). Удобно в средах с жёсткими требованиями безопасности. Структура конфигов отличается от стандартной — /opt/bitnami/nginx/conf/ вместо /etc/nginx/.

nginx-unprivileged

Образ: nginxinc/nginx-unprivileged

Официальный образ от Nginx Inc., запускающийся без root-привилегий. Слушает порт 8080 вместо 80. Хороший выбор для Kubernetes (система оркестрации контейнеров) и сред, где root в контейнере нежелателен.

Если честно, для домашнего реверс-прокси в 80% случаев хватает двух вариантов: nginx:alpine — если хочешь контроль и понимание, или jc21/nginx-proxy-manager — если хочешь GUI и не лезть в конфиги. Остальные образы — для специфических задач.

Поднимаем Nginx как реверс-прокси: Docker Compose

Дальше — практика. Берём nginx:alpine и настраиваем руками. Это длиннее, чем NPM, зато ты понимаешь каждую строчку.

Структура проекта:

Копироватьnginx-proxy/
├── docker-compose.yml
├── nginx.conf
├── conf.d/
│   ├── nextcloud.conf
│   ├── grafana.conf
│   └── jellyfin.conf
└── certs/

docker-compose.yml

yamlКопироватьservices:
  nginx:
    image: nginx:alpine
    container_name: nginx-proxy
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./conf.d:/etc/nginx/conf.d:ro
      - ./certs:/etc/nginx/certs:ro
    restart: unless-stopped
    networks:
      - proxy-network

networks:
  proxy-network:
    external: true

Сеть proxy-network — внешняя. Создай её заранее:

bashКопироватьdocker network create proxy-network

Зачем внешняя сеть? Потому что Nginx должен видеть контейнеры из других docker-compose.yml файлов. Если каждый сервис живёт в своём Compose-файле (а так обычно и бывает), они по умолчанию в разных сетях и не видят друг друга. Общая внешняя сеть решает проблему.

В каждый docker-compose.yml сервиса добавляешь:

yamlКопироватьservices:
  grafana:
    image: grafana/grafana
    # ... остальные настройки ...
    networks:
      - proxy-network
      - default

networks:
  proxy-network:
    external: true

nginx.conf — основной конфиг

nginxКопироватьworker_processes auto;
error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;

events {
    worker_connections 1024;
}

http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    # Логирование
    log_format main '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    '"$http_referer" "$http_user_agent"';
    access_log /var/log/nginx/access.log main;

    sendfile on;
    tcp_nopush on;
    keepalive_timeout 65;
    client_max_body_size 100m; # Для загрузки файлов в Nextcloud

    # Подключаем конфиги сервисов
    include /etc/nginx/conf.d/*.conf;
}

Тут ничего необычного. Единственное — client_max_body_size. По умолчанию Nginx ограничивает тело запроса одним мегабайтом. Для Nextcloud (облачное хранилище) или Jellyfin (медиасервер) этого мало.

Конфиг для отдельного сервиса

Файл conf.d/grafana.conf:

nginxКопироватьserver {
    listen 80;
    server_name grafana.home.local;

    location / {
        proxy_pass http://grafana:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Обрати внимание: proxy_pass http://grafana:3000 — здесь grafana — это имя контейнера (или имя сервиса в Docker Compose). Docker DNS (система доменных имён) внутри общей сети резолвит его в IP контейнера. Не нужно знать адрес — достаточно имени.

Заголовки X-Real-IP и X-Forwarded-For — чтобы сервис за прокси видел реальный IP клиента, а не IP контейнера Nginx. Без них в логах Grafana все запросы будут от 172.18.0.x — внутреннего адреса Docker-сети.

Конфиг для WebSocket-сервисов

Некоторые сервисы (Home Assistant, Nextcloud Talk, Portainer) используют WebSocket (протокол двусторонней связи в реальном времени). Стандартный proxy_pass их не пробросит — нужны дополнительные заголовки:

nginxКопироватьserver {
    listen 80;
    server_name ha.home.local;

    location / {
        proxy_pass http://homeassistant:8123;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Без блока WebSocket Home Assistant будет открываться, но интерфейс начнёт терять соединение, виджеты перестанут обновляться в реальном времени. Классический симптом: «всё вроде работает, но что-то периодически отваливается».

SSL: Let's Encrypt через Certbot

HTTP — это, конечно, работает. Но браузеры ругаются, пароли летят открытым текстом, а если выставляешь сервис наружу через VPN (виртуальная частная сеть) или Cloudflare Tunnel — HTTPS обязателен.

Для локальной сети с внутренними доменами (.home.local) Let's Encrypt не подойдёт — нужен реальный домен. Но если у тебя есть свой домен и DNS-провайдер поддерживает API — всё решаемо.

Certbot как Docker-контейнер

Дополняем docker-compose.yml:

yamlКопироватьservices:
  nginx:
    image: nginx:alpine
    container_name: nginx-proxy
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./conf.d:/etc/nginx/conf.d:ro
      - ./certs/live:/etc/nginx/certs:ro
      - ./certbot/www:/var/www/certbot:ro
    restart: unless-stopped
    networks:
      - proxy-network

  certbot:
    image: certbot/certbot
    volumes:
      - ./certs:/etc/letsencrypt
      - ./certbot/www:/var/www/certbot
    entrypoint: "/bin/sh -c 'trap exit TERM; while :; do certbot renew; sleep 12h & wait $${!}; done;'"
    networks:
      - proxy-network

networks:
  proxy-network:
    external: true

Certbot (утилита для автоматического получения SSL-сертификатов) будет проверять необходимость обновления каждые 12 часов. Сертификаты сохраняются в ./certs, откуда Nginx их читает.

В конфиге Nginx добавляем обработку challenge-запросов от Let's Encrypt:

nginxКопироватьserver {
    listen 80;
    server_name grafana.example.com;

    # Для Certbot
    location /.well-known/acme-challenge/ {
        root /var/www/certbot;
    }

    # Всё остальное — редирект на HTTPS
    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl;
    server_name grafana.example.com;

    # ⚠️ Проверь путь к сертификатам! Зависит от домена
    ssl_certificate /etc/nginx/certs/grafana.example.com/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/grafana.example.com/privkey.pem;

    location / {
        proxy_pass http://grafana:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Первичное получение сертификата:

bashКопироватьdocker compose run --rm certbot certonly \
  --webroot \
  --webroot-path=/var/www/certbot \
  -d grafana.example.com \
  --email YOUR_EMAIL_HERE \
  --agree-tos

После получения — перезагрузить Nginx, чтобы подхватил сертификаты:

bashКопироватьdocker compose exec nginx nginx -s reload

Для внутренней сети без реального домена есть альтернатива — самоподписанные сертификаты или собственный CA (удостоверяющий центр). Инструмент mkcert упрощает этот процесс: генерирует корневой сертификат, устанавливает его в доверенные на твоих устройствах, и выпускает сертификаты для любых имён. Браузеры перестают ругаться. Но это тема для отдельной статьи.

Nginx Proxy Manager: для тех, кому конфиги не нужны

Если предыдущие разделы показались слишком многословными — вот радикально другой подход.

yamlКопироватьservices:
  npm:
    image: jc21/nginx-proxy-manager:latest
    container_name: nginx-proxy-manager
    ports:
      - "80:80"
      - "443:443"
      - "81:81" # Веб-интерфейс управления
    volumes:
      - ./npm-data:/data
      - ./npm-letsencrypt:/etc/letsencrypt
    restart: unless-stopped
    networks:
      - proxy-network

networks:
  proxy-network:
    external: true

bashКопироватьdocker compose up -d

Открываешь http://192.168.1.x:81, логин по умолчанию — admin@example.com / changeme. NPM сразу попросит сменить.

Дальше — Proxy Hosts → Add Proxy Host. Заполняешь домен, указываешь IP или hostname контейнера, порт, включаешь SSL в один клик (NPM сам дёрнет Let's Encrypt). Готово.

Почему тогда не все используют NPM? Несколько причин:

• Нестандартные конфигурации (сложные location-блоки, условные редиректы, rate limiting) в GUI делать неудобно или невозможно
• Обновления NPM иногда ломают конфигурацию — на форумах и в issue-трекере жалобы встречаются регулярно
• Это ещё один сервис, который нужно обслуживать и обновлять
• Если NPM упадёт — ляжет доступ ко всем сервисам, а восстановление через GUI может быть дольше, чем правка текстового конфига

Но для быстрого старта — работает отлично.

Типичные проблемы и как их решать

502 Bad Gateway

Самая частая ошибка при настройке реверс-прокси. Означает: Nginx не может достучаться до backend-сервиса.

Причины:

• Контейнер сервиса не в той же Docker-сети, что Nginx. Проверь: docker network inspect proxy-network — оба контейнера должны быть в списке
• Неверное имя хоста в proxy_pass. Используй имя контейнера или имя сервиса из Compose
• Сервис ещё не запустился. Nginx стартует быстрее, чем, скажем, Nextcloud, и в первые секунды будет отдавать 502. Это нормально — подожди

Диагностика:

bashКопировать# Логи Nginx
docker logs nginx-proxy

# Проверить, видит ли Nginx контейнер
docker exec nginx-proxy ping grafana

host not found in upstream

Nginx не может зарезолвить имя из proxy_pass при старте и отказывается запускаться. Бывает, когда проксируемый контейнер ещё не создан.

Решение — использовать переменную и resolver:

nginxКопироватьserver {
    listen 80;
    server_name grafana.home.local;

    resolver 127.0.0.11 valid=30s; # Встроенный DNS Docker

    location / {
        set $upstream http://grafana:3000;
        proxy_pass $upstream;
        # ... заголовки ...
    }
}

С переменной $upstream Nginx не резолвит имя при старте — только при поступлении запроса. Если контейнер недоступен в момент запроса — будет 502, но Nginx хотя бы запустится.

403 Forbidden

Если Nginx отдаёт 403 при обращении к проксируемому сервису — проблема обычно не в Nginx, а в самом сервисе. Некоторые приложения (Nextcloud, Vaultwarden) требуют указания доверенных прокси.

Например, для Nextcloud в config.php:

phpКопировать'trusted_proxies' => ['172.16.0.0/12'], // Подсеть Docker
'overwriteprotocol' => 'https',

Permission denied при монтировании конфигов

Nginx в Alpine-образе работает от пользователя nginx (UID 101). Если конфиг-файлы на хосте принадлежат root и имеют права 600 — Nginx не сможет их прочитать. Режим :ro в volumes не поможет с правами.

Решение: права 644 на файлы конфигурации.

bashКопироватьchmod 644 nginx.conf
chmod -R 644 conf.d/

Полезные мелочи для продвинутой настройки

Логи в stdout — Docker-way

Официальный образ Nginx по умолчанию пишет access.log и error.log в stdout/stderr контейнера. Это значит, что docker logs nginx-proxy покажет всё. Если хочешь хранить логи на диске — пробрось volume:

yamlКопироватьvolumes:
  - ./logs:/var/log/nginx

Но для домашнего сервера stdout обычно достаточно. Логи можно собирать через Loki (система агрегации логов) или Promtail (агент сбора логов), если настроен стек мониторинга.

Проверка конфига перед перезагрузкой

bashКопировать# Проверить синтаксис
docker exec nginx-proxy nginx -t

# Если OK — перезагрузить без даунтайма
docker exec nginx-proxy nginx -s reload

Никогда не делай docker restart nginx-proxy, если нужно просто применить новый конфиг. nginx -s reload подхватывает изменения без обрыва соединений.

Мониторинг

Nginx отдаёт базовую статистику через stub_status:

nginxКопироватьserver {
    listen 8080;
    server_name localhost;

    location /nginx_status {
        stub_status;
        allow 172.16.0.0/12; # Только Docker-сеть
        deny all;
    }
}

Для Prometheus (система мониторинга) есть экспортёр nginx/nginx-prometheus-exporter, который парсит stub_status и отдаёт метрики в формате Prometheus.

Что в итоге получается

Схема для домашнего сервера:

КопироватьИнтернет / LAN
       │
       ▼
  Nginx (порты 80, 443)
       │
       ├── grafana.home.local  → контейнер Grafana:3000
       ├── nc.home.local       → контейнер Nextcloud:8080
       ├── ha.home.local       → контейнер HomeAssistant:8123
       ├── jelly.home.local    → контейнер Jellyfin:8096
       └── portainer.home.local → контейнер Portainer:9000

Один контейнер Nginx, один docker-compose.yml, папка с конфигами — по файлу на сервис. Добавить новый сервис — скопировать конфиг, поменять имя и порт, nginx -s reload. Удалить — обратная операция.

Nginx в Docker-контейнере для реверс-прокси — решение, которое живёт годами. Обновления образа — docker compose pull && docker compose up -d. Бэкап — скопировать папку проекта. Перенос на другой сервер — rsync и docker compose up. Проще не бывает. Ну, почти.

Блог о домашней инфраструктуре: умный дом, серверы, сети. Только реальный опыт и честные рекомендации.