Базовый конфиг nginx.conf в 2026: разбор директив блока за блоком | AdminWiki

Базовый конфиг nginx.conf в 2026: разбор директив блока за блоком

08 ноября 2026 13 мин. чтения

Зачем разбирать nginx.conf, а не копировать шаблон

Nginx — распространённый reverse proxy: он стоит перед веб-серверами, пересылает запросы клиентов и часто закрывает SSL-терминацию, кэширование и балансировку нагрузки (глоссарий веб-инфраструктуры и терминов аптайма). Файл /etc/nginx/nginx.conf управляет всем этим слоем: под каким пользователем работают воркеры, сколько соединений они держат, куда уходит запрос и что клиент увидит при ошибке бэкенда.

Копия чужого шаблона ломается на первом же сервере с другой структурой каталогов. Типичные последствия: duplicate directive при повторной директиве в одном контексте, unknown directive после строки из модуля, которого нет в вашей сборке, и тихое переопределение настроек, когда подключённый файл перебивает родительский блок. Отладка такого конфига занимает больше времени, чем чтение собственных 60 строк.

Идём по файлу сверху вниз: main, events, http, server, location, логика include. По ходу собираем минимальный рабочий конфиг для статики и reverse proxy, разбираем проверку через nginx -t и безопасную перезагрузку. Примеры соответствуют практике 2026 года и актуальной стабильной ветке nginx; каждую строку перед выкаткой в прод проверяйте на стенде через nginx -t.

Структура nginx.conf: контексты директив и их иерархия

Конфиг nginx — дерево контекстов. Директива работает только в своём контексте, иначе nginx -t вернёт ошибку "directive is not allowed here". Карта блоков выглядит так:

  • main: всё, что вне блоков, глобальные параметры процесса;
  • events: как воркер обрабатывает соединения;
  • http: настройки по умолчанию для всех сайтов, MIME-типы, логи, сжатие;
  • server: один виртуальный хост, привязан к listen и server_name;
  • location: правило маршрутизации внутри server;
  • upstream: группа бэкендов, вкладывается в http.
КонтекстТипичные директивыЧто настраивает
mainuser, worker_processes, pid, error_logпараметры мастер-процесса и воркеров
eventsworker_connections, use, multi_acceptобработку сетевых соединений
httpinclude mime.types, sendfile, keepalive_timeout, log_formatзначения по умолчанию для всех server
serverlisten, server_name, root, ssl_certificateвиртуальный хост и его порт
locationtry_files, proxy_pass, alias, returnмаршрутизацию URI внутри хоста
upstreamserver, keepalive, least_connпул бэкендов и метод балансировки

Наследование идёт сверху вниз: location, затем server, затем http, затем main. Если директива не задана в location, берётся значение из server; нет в server — из http. Поэтому keepalive_timeout, заданный один раз в http, работает для всех сайтов, пока его не переопределят.

Протоколы на уровне server: HTTP работает на порту 80, HTTPS на 443 (определения протоколов в глоссарии). HTTP/2 позволяет несколько параллельных запросов по одному соединению, HTTP/3 строится на QUIC поверх UDP вместо TCP. Для типового конфига в 2026 году достаточно HTTPS с HTTP/2; HTTP/3 включают, когда CDN и клиентские сети его поддерживают, и это отдельная тема.

Main-контекст: user, worker_processes, pid

Минимальный набор глобальных директив:

user www-data;
worker_processes auto;
pid /run/nginx.pid;
error_log /var/log/nginx/error.log warn;

user задаёт пользователя, под которым работают воркеры. Мастер-процесс стартует от root, чтобы занять порты 80 и 443 и сменить uid, а воркеры обрабатывают внешний трафик уже без привилегий. Воркеры от root превращают любую уязвимость в разборе запроса в контроль над хостом. В Debian и Ubuntu пакет создаёт пользователя www-data, в RHEL-совместимых дистрибутивах — nginx; значение должно совпадать с владельцем каталогов сайта, иначе статика вернёт 403.

worker_processes auto выставляет число воркеров по количеству доступных CPU. Каждый воркер однопоточный, отдельный процесс под каждое ядро даёт предсказуемое распределение нагрузки без блокировок. Значение 1 имеет смысл на контейнере с лимитом в одно ядро, ручное число вроде 4 при 16 ядрах оставляет железо недогруженным.

pid указывает, куда писать идентификатор мастер-процесса; по этому файлу systemd и утилита nginx -s находят процесс для сигналов. error_log с уровнем warn пишет предупреждения и ошибки, но не засоряет диск отладочными сообщениями.

Контекст events: worker_connections

Пример блока:

events {
  worker_connections 1024;
  use epoll;
  multi_accept on;
}

worker_connections задаёт максимальное число одновременных соединений, которые может открыть каждый воркер. Важно: в этот лимит входят все соединения, включая соединения с проксируемыми серверами, а не только клиентские (обсуждение worker_connections на Server Fault). Поэтому потолок параллельных клиентов оценивают как worker_processes × worker_connections минус дескрипторы, занятые соединениями к upstream (разбор лимитов nginx на Хабре). При 2 воркерах и 1024 соединениях грубая оценка ёмкости — около 2048 соединений всего, из которых часть уйдёт на бэкенды; точное число зависит от того, сколько соединений к приложению держит каждый запрос.

use epoll выбирает механизм мультиплексирования для Linux; на современных сборках epoll используется по умолчанию, явная строка полезна для читаемости конфига на старых системах. multi_accept on забирает все новые соединения из очереди за один проход цикла.

Завышать worker_connections без запаса файловых дескрипторов бесполезно: упрётесь в лимит ОС. Проверьте ulimit -n, при необходимости задайте worker_rlimit_nofile в main и LimitNOFILE в unit-файле systemd. Симптом нехватки дескрипторов — сообщения "worker_connections are not enough" или "Too many open files" в error.log.

Блок http: общие настройки, MIME-типы и include

Рабочий блок http для типового сайта:

http {
  include /etc/nginx/mime.types;
  default_type application/octet-stream;
  sendfile on;
  tcp_nopush on;
  keepalive_timeout 65;
  types_hash_max_size 2048;
  server_tokens off;
  client_max_body_size 10m;
  gzip on;
  gzip_min_length 1024;
  gzip_types text/css application/javascript application/json image/svg+xml;
  log_format main '$remote_addr [$time_local] "$request" $status $body_bytes_sent rt=$request_time';
  access_log /var/log/nginx/access.log main;
  include /etc/nginx/conf.d/*.conf;
  include /etc/nginx/sites-enabled/*;
}

include mime.types подтягивает таблицу соответствия расширений и Content-Type. Без неё CSS уедет как text/plain, а браузер заблокирует применение стилей из-за строгой проверки MIME. default_type задаёт тип для файлов, которых нет в таблице.

sendfile on отдаёт файл из page cache в сокет без промежуточной копии в память процесса. tcp_nopush on собирает заголовки и начало файла в один пакет, что заметно на мелких ответах. keepalive_timeout 65 держит соединение открытым 65 секунд: TLS-рукопожатие добавляет один или два дополнительных round trip, и на повторных запросах эта задержка не платится, что напрямую снижает TTFB, время до прихода первого байта ответа (глоссарий по метрикам и протоколам).

server_tokens off убирает версию nginx из заголовка Server и со страниц ошибок. client_max_body_size 10m меняет дефолтный 1 МБ; без этого загрузка файла вернёт 413. gzip_min_length 1024 отключает сжатие для мелких ответов, где экономия меньше накладных расходов, а gzip_types перечисляет типы, которые сжимать безопасно и полезно.

Логика include и порядок переопределения настроек

include вставляет содержимое другого файла или файлов, подходящих под glob-паттерн, в текущую позицию конфига, и nginx разрешает её на этапе загрузки конфигурации (разбор структуры конфигов nginx). Практический вывод: файлы из conf.d/*.conf и sites-enabled/* попадают в дерево конфига до его полного разбора, поэтому итоговую картину всегда смотрите через nginx -T с маркерами файлов, а не по отдельным файлам. Порядок префиксных location в конфиге не важен, а порядок regex-location важен: побеждает первое совпавшее регулярное выражение в порядке появления в конфиге. Это же правило действует и для блоков, пришедших из include: если два файла задают конкурирующие regex-location, результат зависит от того, в каком порядке они оказались в итоговом конфиге, поэтому проверяйте фактический порядок через nginx -T.

Наследование работает только при отсутствии своей директивы в дочернем контексте. Директивы add_header наследуются с верхнего уровня только если на текущем уровне нет ни одной собственной директивы add_header: объявили в location хотя бы один add_header, и все add_header из server и http в этом location перестают действовать (разбор наследования add_header в nginx). Это самая частая причина, по которой HSTS или заголовки безопасности пропадают на отдельных маршрутах: добавили локальный заголовок — и унаследованный набор родителя отброшен, поэтому нужные security-заголовки приходится повторять в этом location (пример сохранения security-заголовков в nginx). Для proxy_set_header в материалах отдельного подтверждения идентичной логики нет, но правило "своя директива в дочернем контексте отменяет наследование" стоит держать в голове и проверять на стенде.

Директивы-одиночки нельзя дублировать в одном контексте: второй worker_processes на уровне main или второй default_type в http дадут "directive is duplicate". Чек-лист проверки конфликтов:

  1. Найдите все вхождения директивы: grep -R "worker_processes\|server_tokens\|client_max_body_size" /etc/nginx.
  2. Выведите итоговый конфиг с маркерами файлов: nginx -T | less.
  3. Найдите в выводе строку "# configuration file /etc/nginx/..." перед нужной директивой и правьте именно этот файл.
  4. После правки запустите nginx -t, только потом reload.

Блок server: виртуальные хосты, порты и HTTPS

Server описывает один хост: listen задаёт адрес и порт, server_name — домены, которые сюда приходят. Хост с флагом default_server принимает запросы с неизвестным Host, поэтому на порту 80 его лучше отдавать под редирект на HTTPS, а не под чужой шаблон.

С версии 1.25.1 параметр http2 в директиве listen объявлен устаревшим: при перезапуске nginx выводит предупреждение "the \"listen ... http2\" directive is deprecated, use the \"http2\" directive instead" (обсуждение на форуме Hestia). Вместо старой записи listen 443 ssl http2; в блоке server используется отдельная директива http2 on;; после замены старого синтаксиса на новый конфигурация работает корректно (пример на Stack Overflow). Сертификаты задаются через ssl_certificate и ssl_certificate_key, протоколы ограничиваются TLSv1.2 и TLSv1.3. Заголовок HSTS (Strict-Transport-Security) предписывает браузеру всегда открывать домен по HTTPS: после первого ответа с этим заголовком клиент сам переписывает http:// на https:// и делает это в течение срока из max-age.

Каркас HTTPS-хоста и редиректа:

server {
  listen 80;
  server_name example.com www.example.com;
  return 301 https://$host$request_uri;
}

server {
  listen 443 ssl;
  http2 on;
  server_name example.com www.example.com;
  ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
  ssl_protocols TLSv1.2 TLSv1.3;
  add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
  root /var/www/example.com;
  index index.html;
  location / { try_files $uri $uri/ =404; }
}

Минимальный server для статики

Разбор строк: root задаёт корень файлов, к которому приклеивается URI запроса. index index.html указывает файл для запроса каталога. try_files $uri $uri/ =404 проверяет файл по точному пути, затем каталог и только потом отдаёт 404; без этой строки запрос к несуществующему адресу может уйти в лишнюю обработку или отдать листинг каталога при включённом autoindex.

Проверка после reload: curl -I https://example.com/ показывает код класса 2xx, curl -I https://example.com/no-such-page вернёт 404. Классы кодов помогают читать диагностику: 2xx — успех, 3xx — редирект, 4xx — ошибка клиента, 5xx — ошибка сервера (классификация кодов ответа в глоссарии). Подробные ошибки 403 и 404 из-за прав, симлинков и SELinux разобраны в гайде по раздаче статического контента через nginx.

Минимальный server для reverse proxy

Проксирование на локальное приложение:

location / {
  proxy_pass http://127.0.0.1:3000;
  proxy_http_version 1.1;
  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 без URI в конце передаёт исходный путь целиком; вариант proxy_pass http://127.0.0.1:3000/api/ заменит совпавшую часть адреса на /api/. Путаница между этими формами даёт 404 на бэкенде при формально корректном nginx -t.

Host $host сохраняет домен, по которому пришёл клиент, иначе приложение увидит 127.0.0.1 и сгенерирует неверные абсолютные ссылки или отклонит запрос по проверке хоста. X-Real-IP и X-Forwarded-For передают адрес клиента, без них в логах приложения будут только адреса прокси. X-Forwarded-Proto сообщает схему, чтобы приложение не редиректило на http://.

Коды отказов: 502 означает, что прокси слишком долго ждал ответа от origin-сервера, обычно из-за падения или перегрузки бэкенда; 503 говорит о временной неспособности сервера обработать запрос (пояснения кодов 502 и 503 в глоссарии). Для нескольких инстансов приложения бэкенды выносятся в upstream с директивой keepalive, иначе каждое проксирование открывает новое TCP-соединение к приложению.

Блок location: маршрутизация и приоритеты

location выбирает, какой обработчик получит URI. Типов пять, и порядок проверки не совпадает с порядком строк в файле.

ТипПримерКогда срабатывает
Точное совпадениеlocation = /favicon.icoпервым, при полном совпадении пути
Префикс с приоритетомlocation ^~ /static/если это самый длинный префикс, регулярные выражения уже не проверяются
Регулярное выражениеlocation ~* \.(png|jpg|webp)$после префиксов, первое совпадение в порядке появления
Обычный префиксlocation /api/если регулярные выражения не совпали, побеждает самый длинный
Именованныйlocation @appтолько по внутреннему переходу через try_files или error_page

Практическая последовательность: сначала ищется точное совпадение с "=", и при совпадении поиск сразу прекращается. Затем сканируются все префиксные location и запоминается самое длинное совпадение; если у него модификатор ^~, используется оно, а регулярные выражения не проверяются. Иначе nginx перебирает регулярные выражения в порядке появления в конфиге и берёт первое совпадение. Если ни одно не совпало, работает самый длинный префикс (описание path matching в документации NGINX).

Отсюда классическая ошибка: location ~ \.php$ перехватывает запрос раньше, чем префикс /api/, потому что регулярные выражения проверяются до обычных префиксов. Лечится либо ^~ на префиксе, либо переносом правила в отдельный server.

Разница root и alias: root приклеивает URI к пути (root /var/www/site при запросе /img/a.png отдаст /var/www/site/img/a.png), alias подменяет совпавшую часть (location /img/ { alias /data/images/; } при том же запросе отдаст /data/images/a.png). Пропущенный слеш в конце alias даёт 404, потому что путь склеивается как /data/imagesa.png.

Проверка конфигурации и безопасная перезагрузка

nginx -t проверяет синтаксис, допустимость директив в контекстах и доступность файлов сертификатов. Ошибка печатается с файлом и номером строки: "nginx: [emerg] unknown directive \"proxy_passs\" in /etc/nginx/sites-enabled/api.conf:12". Флаг nginx -T дополнительно выводит весь итоговый конфиг с включёнными файлами, что снимает вопрос "почему мои правки не применяются".

Применение без простоя: nginx -s reload или systemctl reload nginx. Мастер-процесс перечитывает конфиг, запускает новые воркеры и мягко гасит старые после обработки текущих запросов, соединения не рвутся. Если конфиг битый, мастер оставит прежнюю версию, поэтому nginx -t перед reload обязателен. Механика сигналов и откат при неудачном деплое подробно разобраны в материале про безопасную перезагрузку конфигурации nginx.

Порядок действий после reload: curl -I на основной домен, curl -I -H "Host: example.com" http://127.0.0.1 на локальный порт, затем tail -f /var/log/nginx/error.log в отдельном терминале. Перед крупной правкой сохраните снимок: nginx -T > /root/nginx-conf-$(date +%F).bak, вместе с копией каталога /etc/nginx. Процедура бэкапа и восстановления описана в чек-листе по резервному копированию конфигурации nginx.

Типичные ошибки новичка и как их диагностировать

  • duplicate directive: директива задана дважды в одном контексте, например sendfile в http и в подключённом conf.d/base.conf. Найдите второе вхождение через nginx -T.
  • unknown directive: опечатка или модуль отсутствует в сборке. nginx -V покажет флаги компиляции; для пакетных сборок проверьте, установлен ли нужный пакет модулей.
  • directive is not allowed here: директива попала в чужой контекст, например proxy_pass на уровне http или user внутри server. Перенесите строку в location или main.
  • Правки не применяются: файл лежит в sites-available без симлинка в sites-enabled либо конфиг подключён другим include. Сверяйтесь с маркерами файлов в выводе nginx -T.
  • Конфликт server_name: два хоста с одинаковым listen и server_name, запрос уходит в первый по порядку include. Оставьте один default_server и разнесите имена по файлам.
  • Порядок location: регулярное выражение перебивает префикс. Проверьте приоритеты и добавьте ^~ там, где нужен префиксный блок.
  • root вместо alias: путь собирается с лишним каталогом, в логах 404 при существующем файле. Сравните итоговый путь в error.log.
  • 403 на статике: нет index-файла, каталог закрыт правами или SELinux. Проверьте владельца файлов относительно директивы user.
  • Пропавшие заголовки: свой add_header в location отменил наследование из server. Повторите нужные заголовки внутри location или используйте include с общим набором.

Разбор конфигурации по шагам и готовые варианты под HTTPS, API и статику есть в материале полный разбор структуры nginx.conf с примерами для DevOps.

Чек-лист базового nginx.conf на 2026 год

  • Каждая директива в своём контексте: main, events, http, server, location. Проверка — nginx -t.
  • user указывает на непривилегированного пользователя, совпадающего с владельцем каталогов сайта.
  • worker_processes auto, worker_connections согласованы с ulimit -n и LimitNOFILE в systemd.
  • include /etc/nginx/mime.types присутствует, default_type задан.
  • sendfile on, keepalive_timeout в пределах 30–75 секунд, gzip с gzip_min_length.
  • server_tokens off, client_max_body_size под размер загружаемых файлов.
  • Отдельные server для HTTP и HTTPS, на порту 80 редирект 301 на https://$host$request_uri.
  • listen 443 ssl с отдельной директивой http2 on, ssl_protocols TLSv1.2 и TLSv1.3, HSTS с max-age и includeSubDomains.
  • try_files $uri $uri/ =404 для статики, root без лишних вложенных каталогов.
  • proxy_set_header Host, X-Real-IP, X-Forwarded-For, X-Forwarded-Proto в каждом проксирующем location.
  • Порядок include и приоритеты location проверены через nginx -T.
  • Последовательность выкатки: правка, nginx -t, nginx -T, reload, curl -I, просмотр error.log.

Возьмите свой текущий nginx.conf, прогоните его через nginx -T и сверьте каждый блок с этим списком. Расхождения покажут строки, которые вы унаследовали от шаблона и не понимаете: именно их стоит переписать осознанно, начиная с main и events, затем http, затем server и location.

Поделиться: