Nginx. Как настроить правила (location) для виртуального хоста

Правила (locations) задают, как Nginx обрабатывает запросы по разным URL-путям виртуального хоста. Через них можно подключить PHP, настроить проксирование на другой сервис, ограничить доступ по IP, переопределить корневую папку для подпути и задать другие параметры. Статья — для тех, кто уже создал виртуальный хост по статье Nginx. Работа с виртуальными хостами и хочет настроить блок «Дополнительные опции» в форме конструктора. Если форма не покрывает нужный сценарий (например, директивы rewrite, if, map), используйте режим эксперта.

Где находятся правила

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

Шаблоны правил

При добавлении правила выбирается один из шаблонов. Шаблон определяет, какие специальные поля появятся в карточке и какие директивы Nginx попадут в итоговый блок location. Корневое правило всегда присутствует в хосте и создаётся автоматически — его шаблон поменять нельзя; для остальных правил шаблон выбирается вручную.

Корневое правило

Корневое правило — это блок location / в конфиге Nginx. Через него идут все запросы, которые не подошли под более специфичные правила. Карточка корневого правила всегда первая в форме; путь зафиксирован на /, селектор шаблона не показывается, кнопки удаления нет. Доступны только переключатель «Включено / Выключено» и универсальные параметры.

По умолчанию в корневом правиле уже заданы параметры:

• «Файлы (try_files)» = $uri $uri/ =404 — стандартная схема отдачи статики: Nginx сначала ищет файл по запросу, потом папку, иначе отвечает 404.
• «Макс. размер запроса» = 10m — лимит на размер тела запроса.

Любой из дефолтных параметров можно изменить или удалить, остальные универсальные параметры добавляются обычным способом. Само корневое правило тоже можно выключить переключателем (см. Включение и выключение правила) — например, чтобы полностью описать обработку корня через отдельные правила или универсальные параметры.

Простой

Шаблон «Простой» — это пустой блок location с произвольным «путём» и набором универсальных параметров. Специальных полей у него нет — поведение настраивается через добавление параметров. Типичные сценарии:

• ограничить доступ по IP к каталогу /admin/;
• переопределить корневую папку для /static/;
• задать долгий expires на ассеты;
• закрыть доступ к служебным файлам вроде .git.

Развёрнутый пример: правило для каталога со статикой

Допустим, в форме «Простого» правила задан путь /static/, через «Добавить параметр» добавлены «Время кэша (expires)» = 30d, «Макс. размер запроса» = 10m и «Разрешить доступ (allow)» = all. В итоговый *.conf-файл попадёт примерно такой блок:

location /static/ {
    expires 30d;
    client_max_body_size 10m;
    allow all;
}

Шаблон «Простой» сам по себе не добавляет в блок никаких директив — на выходе только то, что вы задали в параметрах.

PHP (FastCGI)

Шаблон «PHP (FastCGI)» настраивает передачу запросов в PHP-FPM — обычный сценарий для WordPress, Laravel и других PHP-приложений. При выборе шаблона поле «Путь» автоматически заполняется регулярным выражением ~ \.php$ — оно совпадает со всеми запросами, которые оканчиваются на .php. В большинстве случаев менять это значение не нужно.

Если хотя бы одно правило в хосте использует шаблон PHP (FastCGI), BeAdmin автоматически добавляет index.php первым в общий список index-файлов хоста. При удалении такого правила index.php так же автоматически убирается из списка.

Версия PHP

Версия PHP — специфичное поле этого шаблона. По выбранной версии BeAdmin подставляет в конфиг путь к нужному FPM-сокету: unix:/var/run/php/php<X.Y>-fpm.sock. Если выбранной версии в системе ещё нет, прямо отсюда можно её установить — отдельно ходить в раздел «PHP» не нужно.

💡 Что добавляет панель помимо ваших параметров

Кроме fastcgi_pass для выбранной версии PHP, BeAdmin сам добавляет в блок стандартный набор FastCGI-директив: fastcgi_split_path_info, try_files $fastcgi_script_name =404, include fastcgi_params и базовые fastcgi_param. Поскольку try_files фиксирован, пользовательский параметр «Файлы (try_files)» в шаблоне PHP игнорируется — задавать его смысла нет.

Развёрнутый пример: PHP-правило в итоговом конфиге

Допустим, в форме PHP-правила задан путь ~ \.php$, выбрана PHP 8.3, через «Добавить параметр» добавлены «Макс. размер запроса» = 64m и «Время кэша (expires)» = 1h. В итоговый *.conf-файл попадёт примерно такой блок:

location ~ \.php$ {
    # Параметры из формы
    client_max_body_size 64m;
    expires 1h;

    # Сокет PHP-FPM выбранной версии
    fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;

    # Стандартный FastCGI-обвес от BeAdmin
    fastcgi_split_path_info ^(.+?\.php)(/.*)$;
    try_files $fastcgi_script_name =404;
    set $path_info $fastcgi_path_info;
    include fastcgi_params;

    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param PATH_INFO       $path_info;
    fastcgi_param PATH_TRANSLATED $document_root$path_info;
    fastcgi_param HTTP_PROXY      "";
}

Первые две директивы — это параметры, которые вы добавили в форме. Всё остальное BeAdmin подставляет сам по выбранной версии PHP и стандартному шаблону FastCGI-обработки.

Проксирование

Шаблон «Проксирование» превращает блок location в обратный прокси: запросы по выбранному пути уходят на внутренний бэкенд (другой Nginx, Apache на 127.0.0.1:8808, Node-приложение, Docker-контейнер). Поле «Путь» при выборе шаблона очищается — задайте его сами: чаще всего это /, /api или ^~ /api/.

Проксировать на (proxy_pass)

В поле «Проксировать на (proxy_pass)» указывается URL бэкенда — например, http://127.0.0.1:8080 или https://api.internal.example.com/v2. Это значение попадает в директиву proxy_pass. Поле обязательное, без него правило не сохранится.

Заголовки

В подсекции «Заголовки» задаются дополнительные HTTP-заголовки, которые Nginx передаёт бэкенду через proxy_set_header. По кнопке «Добавить заголовок» добавляется пара «имя — значение». Имя выбирается из заранее заданного списка: Host, X-Real-IP, X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port, Connection, Upgrade, Accept-Encoding, Accept-Language, Authorization, Content-Type, Content-Length, User-Agent, Referer, Origin, Cache-Control, Cookie, Set-Cookie. Если нужного заголовка в списке нет, единственный путь — режим эксперта.

Типичный набор для связки Nginx + Apache: Host = $host, X-Real-IP = $remote_addr, X-Forwarded-For = $proxy_add_x_forwarded_for, X-Forwarded-Proto = $scheme.

Развёрнутый пример: проксирование на локальное Node-приложение

Допустим, в форме «Проксирования» задан путь /, в «Проксировать на (proxy_pass)» — http://127.0.0.1:8080, и через «Добавить заголовок» добавлены пары Host = $host и X-Real-IP = $remote_addr. В итоговый *.conf-файл попадёт примерно такой блок:

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

Шаблон «Проксирование» добавляет в блок только proxy_pass и proxy_set_header для перечисленных заголовков; всё остальное настраивается универсальными параметрами или режимом эксперта.

Универсальные параметры

У всех шаблонов есть общая подсекция «Параметры» с одинаковым набором ключей. По кнопке «Добавить параметр» ключ выбирается из списка; повторно добавить тот же ключ в одну карточку нельзя. В таблице — что каждый параметр означает в конфиге Nginx и как его проверяет форма.

Параметр в форме	В *.conf	Что задаёт и как проверяется
«Разрешить доступ (allow)»	allow <значение>;	Список адресов, которым разрешён доступ. Каждое значение — IPv4 (192.168.1.100), CIDR-сеть (192.168.1.0/24, маска от 0 до 32) или ключевое слово all. Несколько значений вводятся подряд через выпадающий список.
«Запретить доступ (deny)»	deny <значение>;	То же самое, но запрещает доступ. Обычная связка — несколько allow для своих сетей и deny all в конце.
«Макс. размер запроса»	client_max_body_size <значение>;	Лимит на размер тела запроса. Формат — число с опциональным суффиксом k, m или g: 100m, 10k, 1g, 0.
«Время кэша (expires)»	expires <значение>;	Заголовок Expires для кэша на стороне браузера. В выпадающем списке — пресеты off, 1m, 30m, 1h, 24h, 7d, 30d, 1y; можно ввести своё значение, например -1h или max.
«Логировать 404 ошибки»	log_not_found on/off;	Переключатель: писать ли в лог Nginx сообщения о ненайденных файлах.
«Корневая папка (root_dir)»	root <значение>;	Корневая папка для этого правила — переопределяет общую root хоста на конкретный путь. Поле должно быть непустым.
«Файлы (try_files)»	try_files <значение>;	Полная строка аргументов директивы try_files, например $uri $uri/ =404 или $uri /index.php?$query_string. В шаблоне PHP (FastCGI) этот параметр игнорируется — try_files там фиксирован.

⚠️ IPv6 в «Разрешить доступ» и «Запретить доступ»

В форме принимаются только IPv4-адреса и IPv4-CIDR-сети. Для ограничений по IPv6 нужен режим эксперта — там allow и deny пишутся напрямую в конфиг и поддерживают любой синтаксис Nginx.

Включение и выключение правила

Каждое правило, включая корневое, можно временно выключить переключателем «Включено» / «Выключено». Настройки выключенного правила сохраняются в форме, но в итоговый *.conf для Nginx оно не попадает — удобно, когда нужно отключить кусок конфигурации, не теряя его. Заодно с выключенного правила снимается проверка на дублирующийся «Путь»: можно выключить старое правило с путём /api и создать новое с тем же путём — сохранение пройдёт.

Полезные ссылки

• Nginx. Работа с виртуальными хостами
• Nginx. Виртуальные хосты в режиме эксперта
• Решение ошибок ACME при выпуске SSL-сертификата
• Официальная документация Nginx — директива location