Справочник: что ещё есть в стандартной сборке

Это карта, а не урок про одну мысль: читай оглавление, запоминай, что существует. Разборы про json_set и про содержимое официального образа стоит прочитать целиком.

Понадобилось уменьшать картинки на лету. Строка из документации, официальный образ nginx:alpine. Что скажет nginx -t?

image_filter resize 200 -;   # 200 - ширина, прочерк - «высоту подобрать по пропорции»

nginx: [emerg] unknown directive "image_filter"

Модуль есть в документации, описан на сайте nginx, и его нет в твоём nginx. Список того, что документация называет стандартным, и список того, что собрано у тебя, - разные списки.

На что это похоже

Справочник по модулям - это аптечка, а не учебник. Наизусть дозировки никто не помнит; помнят, что в аптечке лежит жгут, и где он лежит. Половина времени, потраченного на «напишу-ка я для этого сервис», уходит зря именно потому, что человек не знал: жгут уже есть.

Поэтому читать этот урок надо один раз целиком, а возвращаться - по оглавлению.

Как это устроено: три состояния модуля

Правило

Перед тем как писать директиву из документации, спроси свою сборку:

nginx -V 2>&1 | tr ' ' '\n' | grep -E "with-|module"

Модули со звёздочкой в документации собираются только явно (--with-http_image_filter_module), в пакетах дистрибутивов часть вынесена в отдельные файлы (nginx-module-njs, nginx-module-image-filter), и тогда нужна строка load_module в самом верху конфига (.so - файл собранного модуля, load_module подключает его до всех блоков).

Разбор: что реально лежит в официальном образе

Прогон по образу nginx:alpine 1.31.5 - каждая директива проверена на unknown directive:

В debian-образе те же image_filter и xslt лежат отдельными файлами в /etc/nginx/modules/ - то есть там они есть, но молчат, пока не написан load_module. Один и тот же «официальный nginx» ведёт себя по-разному в двух официальных образах, и это стоит проверить до того, как под фичу заведена задача.

Разбор: json_set и путь, который молча ничего не находит

Свежий модуль стандартной сборки, которого нет в старых руководствах: ngx_http_json_module. Он достаёт значение из JSON прямо в конфиге - без njs и без похода в приложение.

json_set $user_name $request_body user.name;
json_max_depth 8;

Путь пишется точками. И вот тут ловушка: похожие на JSON Pointer записи проверку проходят, а значения не дают. Один и тот же заголовок {"user":{"name":"бобр"},"items":["раз","два"]}, разные пути:

Битый JSON тоже даёт пустое значение и ни строки в логе. То есть все ошибки здесь выглядят одинаково - пустая переменная, - и различать их придётся прогоном, а не чтением конфига.

Вторая тонкость: $request_body заполняется, только когда тело реально прочитано. С return в том же location переменная пуста, с proxy_pass - работает:

proxy_set_header X-User $user_name;
proxy_pass http://app:8000;

Другие способы дойти до приложения

grpc_pass стоит запомнить отдельно: gRPC внутри - это HTTP/2, поэтому обычный proxy_pass для него не годится, а на порту нужен http2 on.

Правка ответа на лету

sub_filter заменяет текст в теле - спасает при переезде домена, когда в вёрстке остались абсолютные ссылки, а править приложение нельзя:

sub_filter 'http://old.shop.local' 'https://shop.local';
sub_filter_once off;
sub_filter_types text/html text/css;

Плата - разбор тела каждого ответа, поэтому это временная мера, а не архитектура. Рядом: ssi собирает страницу из кусков прямо в nginx, addition приклеивает ответ подзапроса до или после основного без разбора тела, gunzip распаковывает ответ бэкенда для клиента, который сжатия не понимает.

Файлы, картинки и мелочи

• image_filter - изменить размер, повернуть, обрезать картинку на лету; прожорлив по процессору, результат обязательно кешировать.
• dav - загрузка и удаление файлами методами PUT, DELETE, MKCOL. Включать только с ограничением доступа: помни CVE-2026-27654 из двенадцатого раздела.
• mp4 и flv - перемотка видео по времени без скачивания всего файла; slice режет большой файл на куски для кеша.
• userid ставит клиенту cookie-идентификатор ($uid_got, $uid_set), charset дописывает и перекодирует кодировку, empty_gif отдаёт однопиксельный gif из памяти, random_index выдаёт случайный файл каталога.

Совсем другой мир: почта

Кроме http и stream есть третий корневой блок - mail: прокси для IMAP, POP3 и SMTP с терминацией TLS и внешней авторизацией.

mail {
    server_name mail.shop.local;
    auth_http   http://app:8000/mail/auth;

    server {
        listen 993 ssl;
        protocol imap;
        proxy_pass_error_message on;
    }
}

nginx принимает соединение, спрашивает у твоего http-сервиса, куда направить пользователя, и соединяет его с нужным почтовым сервером. Задача узкая, но если она твоя - отдельный прокси заводить не нужно.

Что ломается без этого

Дважды написанная логика. Приложение, которое парсит JSON только затем, чтобы положить поле в заголовок, - это json_set. Скрипт, склеивающий страницу из двух кусков, - это ssi или addition. Сервис, распаковывающий ответ соседа, - это gunzip. Каждая такая замена стоит своего процесса, своего деплоя и своего дежурства.

Обратная ошибка тоже дорогая: sub_filter на всех ответах и image_filter без кеша выглядят как экономия, а стоят процессорного времени на каждом запросе. Оба модуля - временная мера, у которой должен быть срок.

Зачем это в работе

На разборе инцидента полезнее всего помнить не синтаксис, а список существующего. «Нам нужен сервис, который подменит домен в html» - это одна строка конфига и пятнадцать минут. «Нам нужно вытащить поле из тела запроса для маршрутизации» - json_set вместо njs, то есть без кода в рабочем процессе.

И обратная сторона: nginx -V стоит смотреть первым делом на чужом сервере. Половина «у нас это не работает» объясняется тем, что модуля там просто нет.

Теперь сам

В конфиг добавили строку image_filter resize 200 -;, nginx -t ругается unknown directive. Коллега советует пересобрать nginx из исходников. Что проверить до этого?