Готовый конфиг Nginx как reverse proxy для Next.js 15 (релиз 2025) с TLS, кешированием и поддержкой WebSocket за 30–60 минут. Пошаговое руководство с командами, проверкой и типичными ошибками.
Статья была полезной?
К концу вы получите рабочий файл конфигурации Nginx для проксирования приложений Next.js 15 (релиз 2025) с TLS и кешем, готовый к развёртыванию на Ubuntu 22.04 или в Docker. Весь процесс обычно занимает 30–60 минут при стабильном подключении к интернету.
nginx:1.26.0 (~23 MB compressed).localhost:3000 или контейнере с пробросом порта 3000.Upgrade.Nginx как reverse proxy решает несколько задач: TLS-терминация, балансировка, сжатие, кеширование статического и динамического контента, маршрутизация путей и защита. Для Next.js 15 (релиз 2025) актуально разграничение ответственности: Nginx обслуживает TLS/HTTP/2 и кеш, Next.js — рендер и API. Преимущества: снижение нагрузки на Node-процесс, возможность централизованного кеширования и быстрая отдача ассетов через HTTP/2 или gzip/ brotli.
Рекомендованный быстрый способ — запустить официальный образ Nginx 1.26. Команда ниже создаст контейнер и пробросит порты 80/443.
docker run -d --name nginx-proxy -p 80:80 -p 443:443 nginx:1.26.0Пояснение: используем официальный образ nginx:1.26.0 (релиз 2024). Размер образа ~23 MB (compressed). Время выполнения: ~5–15 секунд на современном хосте при хорошем интернете.
Ожидаемый вывод:
f2a1b3c4d5e6f7g8h9i0jklmnopqrstuvТипичная ошибка и её фикс:
Ошибка: "Cannot connect to the Docker daemon" или "permission denied".
Фикс: запустите Docker daemon: sudo systemctl start docker и повторите команду. Если проблема с правами, используйте sudo docker run ... или добавьте пользователя в группу docker.Создайте файл конфигурации. Пример для сервера на localhost:3000 с TLS-терминацией (сертификаты будут добавлены в шаге 3):
/etc/nginx/conf.d/nextjs.conf
server {
listen 80;
listen [::]:80;
server_name example.com www.example.com;
# Перенаправляем HTTP на HTTPS
return 301 https://$host$request_uri;
}
server {
listen 443 ssl http2;
listen [::]:443 ssl http2;
server_name example.com www.example.com;
ssl_certificate /etc/ssl/certs/example.crt;
ssl_certificate_key /etc/ssl/private/example.key;
ssl_protocols TLSv1.3;
ssl_prefer_server_ciphers on;
# Static files
location /_next/static/ {
alias /var/www/next/.next/static/;
access_log off;
expires max;
}
# Proxy to Next.js
location / {
proxy_pass http://127.0.0.1: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_buffer_size 16k;
proxy_buffers 4 32k;
proxy_busy_buffers_size 64k;
proxy_cache my_cache;
proxy_cache_bypass $http_cache_control;
proxy_cache_valid 200 302 10m;
proxy_cache_valid 404 1m;
}
}
# Cache path (см. шаг 5)
proxy_cache_path /var/cache/nginx/next levels=1:2 keys_zone=my_cache:100m max_size=1g inactive=60m use_temp_path=off;Пояснение: конфиг разделяет статику и проксирование. Опция http2 включена для производительности. Время на редактирование файла: 5–10 минут.
Проверка конфигурации и ожидаемый вывод:
sudo nginx -t
Конфигурация nginx: тест успешно
nginx: configuration file /etc/nginx/nginx.conf test is successfulТипичная ошибка и её фикс:
Ошибка: "nginx: [emerg] unknown directive \"proxy_cache\"".
Фикс: убедитесь, что конфигурация не размещена в контексте http и что модуль proxy включён (обычно стандартный). Проверьте файл на опечатки и используйте nginx -t для получения номера строки.Для тестовой среды быстро сгенерируйте self-signed сертификат. В продакшн используйте certbot или ACME. Self-signed команда:
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout /etc/ssl/private/example.key \
-out /etc/ssl/certs/example.crt \
-subj "/C=US/ST=State/L=City/O=Org/OU=Dev/CN=example.com"
Время выполнения: ~1–3 секунды на генерацию ключа.Ожидаемый вывод (часть):
Generating RSA private key, 2048 bit long modulus (2 primes)
..................................+++...
writing RSA key
-----Типичная ошибка и её фикс:
Ошибка: Permission denied при записи в /etc/ssl/private.
Фикс: запускайте команду с sudo или создайте директорию с правильными правами: sudo mkdir -p /etc/ssl/private && sudo chown root:root /etc/ssl/private && sudo chmod 700 /etc/ssl/private.Если установлен system nginx:
sudo systemctl restart nginx
sudo systemctl status nginx --no-pagerОжидаемый вывод (часть):
● nginx.service - A high performance web server and a reverse proxy server
Loaded: loaded (/lib/systemd/system/nginx.service; enabled)
Active: active (running) since Mon 2026-02-01 12:34:56 UTC; 10s agoЕсли используете Docker, перезагрузите контейнер с монтированным конфигом:
docker cp ./nextjs.conf nginx-proxy:/etc/nginx/conf.d/nextjs.conf
docker exec nginx-proxy nginx -s reloadТипичная ошибка и её фикс:
Ошибка: "Job for nginx.service failed because the control process exited with error code".
Фикс: выполните sudo journalctl -u nginx -b --no-pager и nginx -t, исправьте синтаксис, проверьте занятые порты: sudo ss -ltnp | grep :80.Кеширование снижает время ответа и нагрузку на Node. Пример конфигурации см. в шаге 2: директива proxy_cache_path и использование proxy_cache my_cache;. Разберём параметры подробнее.
proxy_cache_path /var/cache/nginx/next levels=1:2 keys_zone=my_cache:100m max_size=1g inactive=60m use_temp_path=off;
# В server/location:
proxy_cache my_cache;
proxy_cache_key "$scheme://$host$request_uri";
proxy_cache_valid 200 302 10m;
proxy_cache_valid 404 1m;
add_header X-Proxy-Cache $upstream_cache_status;Пояснение параметров:
keys_zone=my_cache:100m — зона хранилища в памяти, 100 MB достаточно для большого количества ключей; можно уменьшить до 10–20 MB для малых сайтов.max_size=1g — верхняя граница кеша; при достижении Nginx начнёт удалять старые объекты.inactive=60m — если элемент не запрашивали 60 минут, он удаляется.Проверка кеша через curl (ожидаемый вывод):
curl -I -H "Cache-Control: max-age=0" https://example.com/
HTTP/2 200
x-proxy-cache: MISS
...
# Повторный запрос
curl -I https://example.com/
HTTP/2 200
x-proxy-cache: HITТипичная ошибка и её фикс:
Ошибка: "upstream_cache_status" возвращает "MISS" всегда.
Фикс: проверьте, что add_header X-Proxy-Cache $upstream_cache_status; находится в том же context (server/location) и что ответы Next.js имеют релевантные заголовки (например, отсутствие Set-Cookie для кешируемых ответов). Также убедитесь, что директория кеша существует и права верные: sudo mkdir -p /var/cache/nginx/next && sudo chown -R www-data:www-data /var/cache/nginx/next.Next.js 15 может использовать API-роуты и WebSocket-подключения. Для проксирования WebSocket добавьте важные заголовки и версию HTTP:
location /socket/ {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
proxy_set_header Host $host;
proxy_read_timeout 3600s;
}Пояснение: proxy_http_version 1.1 и заголовки Upgrade/Connection обязаны для WebSocket. Тестирование можно выполнить утилитой wscat или браузерным клиентом.
Ожидаемый вывод теста (wscat):
Connected (press CTRL+C to quit)
> ping
< pongТипичная ошибка и её фикс:
Ошибка: WebSocket сразу закрывается с кодом 1006.
Фикс: проверьте, что Nginx пропускает заголовок Upgrade и что backend действительно обрабатывает WebSocket на соответствующем пути. Убедитесь, что прокси не удаляет заголовки и что таймауты достаточно длинные.
Скриншот файла конфигурации Nginx для reverse proxy Next.js 15
Полезные команды для быстрой диагностики:
nginx -t — проверка синтаксиса конфига (обычно <1 секунда).sudo tail -n 200 /var/log/nginx/error.log — ошибки Nginx.curl -I https://example.com/ — проверить заголовки, статус и X-Proxy-Cache.ss -ltnp | grep LISTEN — увидеть занятые порты (быстро, ~0.1 сек.).Если встречаете проблемы с производительностью, профилируйте Node/Next.js приложение отдельно и убедитесь, что Nginx не ограничивает буферы.
Скриншот вывода curl с заголовком X-Proxy-Cache: HIT для Next.js 15
certbot --nginx -d example.com (рекомендация 2025–2026).Используйте curl для заголовков: curl -I https://example.com/ и смотрите заголовок X-Proxy-Cache или x-cache, который вы добавили конфигурацией. При первом запросе ожидается MISS, при повторном — HIT. Если всегда MISS, проверьте отсутствие Set-Cookie в ответах, корректность ключа кеша и права на директорию кеша.
Команда nginx -t укажет файл и номер строки с ошибкой. Откройте файл, проверьте контексты (server/location/http) и отсутствующие точки с запятой. Частая ошибка — директивы, размещённые не в том блоке (например, proxy_cache_path должен быть в контексте http, а не внутри server).
Проверьте, что в конфигурации указаны proxy_http_version 1.1, proxy_set_header Upgrade $http_upgrade; и proxy_set_header Connection "Upgrade";. Также убедитесь, что backend слушает на нужном пути и что таймауты достаточно длинные. Неправильные заголовки или использование HTTP/1.0 приведут к немедленному закрытию соединения.
Зависит от трафика и размера ассетов. Для малого проекта начните с keys_zone=my_cache:100m и max_size=1g. Это подходит для сайтов со средней статикой. Для крупных проектов планируйте 10–100+ GB и используйте отдельный диск или распределённый кэш (CDN) вместо локального кеша.
В Docker вы монтируете конфиги внутрь контейнера и перезагружаете контейнер или отправляете сигнал nginx -s reload. В systemd-сценарии управляете сервисом через systemctl. В обоих случаях важны корректные пути к сертификатам и правам доступа; в Docker удобно изолировать Nginx, но нужно управлять volume и персистентным кешем.
Комментарии (0)
Войдите или зарегистрируйтесь, чтобы оставить комментарий
Загрузка комментариев…