Зачем разбирать 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.
| Контекст | Типичные директивы | Что настраивает |
|---|---|---|
| main | user, worker_processes, pid, error_log | параметры мастер-процесса и воркеров |
| events | worker_connections, use, multi_accept | обработку сетевых соединений |
| http | include mime.types, sendfile, keepalive_timeout, log_format | значения по умолчанию для всех server |
| server | listen, server_name, root, ssl_certificate | виртуальный хост и его порт |
| location | try_files, proxy_pass, alias, return | маршрутизацию URI внутри хоста |
| upstream | server, 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". Чек-лист проверки конфликтов:
- Найдите все вхождения директивы: grep -R "worker_processes\|server_tokens\|client_max_body_size" /etc/nginx.
- Выведите итоговый конфиг с маркерами файлов: nginx -T | less.
- Найдите в выводе строку "# configuration file /etc/nginx/..." перед нужной директивой и правьте именно этот файл.
- После правки запустите 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.