Модули Nginx: Полный гид по стандартным и сторонним сборкам в 2026

Модули Nginx - это разделяемые библиотеки, которые добавляют в веб-сервер конкретную функциональность: от сжатия Brotli до скриптинга на Lua. Вы можете использовать только то, что нужно вашему проекту, и отключить всё лишнее. В этом руководстве разобрана архитектура модулей, полный список стандартных компонентов, пошаговая инструкция по добавлению сторонних решений и рекомендации по безопасности. Материал построен так, чтобы вы могли сразу применить инструкции в своей среде.

На практике администратор сталкивается с модулями в трёх ситуациях: нужно понять, что уже скомпилировано в текущей сборке, требуется добавить специфическую возможность вроде стриминга или геолокации, либо необходимо собрать минималистичный образ без лишнего кода. Каждый из этих сценариев детально рассмотрен ниже.

Как устроена модульная архитектура Nginx

Ядро Nginx обрабатывает события, управляет соединениями и диспетчеризует запросы. Все остальные возможности - от парсинга HTTP-заголовков до проксирования FastCGI - вынесены в модули. Такой подход сохраняет ядро компактным и быстрым, а администратор получает точный контроль над функциональностью сервера.

Модули компилируются либо статически (встраиваются в бинарный файл nginx), либо динамически (остаются отдельными .so файлами). Динамическая загрузка появилась в версии 1.9.11 и с тех пор стала стандартом де-факто для сторонних расширений. Производительность статического и динамического модуля идентична после загрузки - разница только в этапе запуска и удобстве обновления.

Проверить, какие модули уже установлены, можно одной командой. Подробный разбор вывода nginx -V и методов аудита описан в статье просмотр установленных модулей Nginx.

Статические модули: когда пересборка оправдана

Статический модуль компилируется прямо в бинарный файл nginx на этапе сборки через флаг --add-module. После этого он становится неотъемлемой частью сервера - вы не сможете отключить его без полной перекомпиляции.

Ключевые сценарии для статической компиляции:

Создание минималистичного Docker-образа, где каждый мегабайт на счету, а динамический загрузчик не нужен.
Сборка критически важного модуля, который должен быть доступен сразу при старте, без риска отсутствия .so файла.
Гарантированная совместимость - модуль компилируется с той же версией ядра и теми же опциями.

Пример: ngx_http_ssl_module в большинстве дистрибутивов вкомпилирован статически, потому что без HTTPS современный веб-сервер не имеет смысла. Отключать его не предполагается.

Процесс сборки со статическим модулем:

./configure --add-module=../path/to/module
make
make install

Недостаток очевиден: для удаления модуля потребуется пересборка всего Nginx. В продакшн-среде это означает либо простой, либо сложную процедуру замены бинарника на лету.

Динамические модули: гибкость без перекомпиляции

Динамический модуль компилируется отдельно через --add-dynamic-module и загружается директивой load_module в конфигурации nginx.conf. Файлы модулей обычно располагаются в /etc/nginx/modules/ или /usr/lib/nginx/modules/.

Преимущества динамической загрузки:

Добавление и удаление функциональности без пересборки ядра.
Поставка модулей через пакетный менеджер (nginx-module-* в Debian/Ubuntu).
Изоляция: если модуль содержит ошибку, она не влияет на компиляцию остальных компонентов.

Пример загрузки динамического модуля:

load_module modules/ngx_http_headers_more_filter_module.so;

Проверить, какие динамические модули загружены в текущей конфигурации, можно командой nginx -T - она выведет полный конфиг со всеми включёнными файлами. Подробная инструкция по сборке динамических модулей с примерами для типовых задач разобрана в материале динамические модули Nginx: сборка, подключение и управление.

Критическое требование: версия модуля должна точно совпадать с версией ядра Nginx. При несовпадении вы получите ошибку загрузки вида module version mismatch. Всегда проверяйте вывод nginx -V перед сборкой.

Обзор стандартных модулей Nginx: полный список

Стандартная поставка Nginx включает несколько десятков модулей. Их точный состав зависит от опций, переданных при сборке. Получить список того, что скомпилировано в вашем экземпляре, можно командой:

nginx -V 2>&1 | grep -o 'with-http_[a-z_]*_module'

Ниже - структурированный обзор ключевых групп модулей с практическими директивами, которые вы будете использовать ежедневно.

Модули для работы с HTTP-запросами

Эта группа отвечает за маршрутизацию, модификацию заголовков и управление переменными. Три модуля, которые покрывают 90% задач администратора:

ngx_http_rewrite_module - изменение URI, редиректы и условные переходы. Основные директивы: if, return, rewrite, set. Пример принудительного HTTPS-редиректа:

if ($scheme != "https") {
    return 301 https://$host$request_uri;
}

ngx_http_headers_module - добавление и модификация HTTP-заголовков в ответах. Директивы add_header и expires используются для управления кэшированием и безопасностью. Пример установки заголовка Content-Security-Policy:

add_header Content-Security-Policy "default-src 'self'" always;

ngx_http_map_module - создание динамических переменных на основе значений других переменных. Удобен для маршрутизации по доменам или User-Agent без дублирования конфигураций. Пример маппинга доменов на бэкенды:

map $host $backend {
    api.example.com     backend_api;
    admin.example.com   backend_admin;
    default             backend_default;
}

Модули для безопасности и SSL/TLS

Шифрование трафика и аутентификация пользователей - базовые требования любой production-среды.

ngx_http_ssl_module - поддержка HTTPS. Ключевые директивы: ssl_certificate, ssl_certificate_key, ssl_protocols, ssl_ciphers. Модуль поддерживает TLS 1.3, который сокращает время рукопожатия на один round-trip по сравнению с TLS 1.2. Пример минимальной конфигурации:

ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
ssl_certificate /etc/nginx/ssl/example.crt;
ssl_certificate_key /etc/nginx/ssl/example.key;

ngx_http_v2_module - включает HTTP/2, который мультиплексирует запросы в рамках одного TCP-соединения. Для работы требует TLS (ALPN). Включается одной директивой http2 в блоке listen.

ngx_http_auth_basic_module - базовая HTTP-аутентификация через файл .htpasswd. Подходит для закрытия служебных зон (staging, админки).

ngx_http_secure_link_module - защита ссылок от несанкционированного доступа через проверку хеша и срока действия. Применяется для платного контента и временных загрузок.

Расширенные меры защиты, включая WAF на базе ModSecurity и rate limiting, описаны в руководстве продвинутая безопасность Nginx для production-сред.

Модули для проксирования и балансировки

Nginx в роли reverse proxy - один из самых распространённых сценариев использования. Модули этой группы передают запросы на бэкенды и распределяют нагрузку.

ngx_http_proxy_module - проксирование HTTP-запросов. Основные директивы: proxy_pass, proxy_set_header, proxy_buffering. Пример передачи реального IP клиента на бэкенд:

location / {
    proxy_pass http://backend;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

ngx_http_fastcgi_module - проксирование на FastCGI-серверы (PHP-FPM). Использует директиву fastcgi_pass и переменные $fastcgi_script_name, $document_root.

ngx_http_upstream_module - определение групп бэкендов для балансировки. Поддерживает методы: round-robin (по умолчанию), least_conn (наименьшее число соединений), ip_hash (привязка сессии по IP), hash (произвольный ключ). Пример upstream с least_conn:

upstream backend {
    least_conn;
    server 10.0.0.1:8080 weight=3;
    server 10.0.0.2:8080;
    server 10.0.0.3:8080 backup;
}

Готовые конфигурационные блоки для проксирования, раздачи статики и SSL собраны в статье рабочие конфигурации Nginx для стандартных задач.

Как добавить сторонний модуль в Nginx: пошаговое руководство

Когда стандартного функционала не хватает, вы подключаете сторонний модуль. Есть два пути: использовать готовый пакет из репозитория дистрибутива (быстро, но версия может быть старой) или собрать из исходников (полный контроль, но требует аккуратности).

Пошаговый алгоритм сборки из исходников:

Определите текущую версию Nginx и опции сборки: nginx -V. Скопируйте все флаги configure - они понадобятся для совместимости.
Скачайте исходники Nginx той же версии с nginx.org.
Скачайте исходники модуля (обычно из GitHub-репозитория).
Сконфигурируйте сборку с флагом --add-dynamic-module=../path/to/module, добавив все скопированные на шаге 1 флаги.
Выполните make modules - соберутся только модули, без перекомпиляции ядра.
Скопируйте полученный .so файл в директорию модулей: cp objs/ngx_http_*.so /etc/nginx/modules/.
Добавьте load_module в nginx.conf и проверьте конфигурацию: nginx -t.
Перезагрузите Nginx: nginx -s reload.

Полный чек-лист сборки Nginx с дополнительными модулями, включая stream, RTMP и Lua, с разбором зависимостей и systemd unit-файлом изложен в материале сборка Nginx с дополнительными модулями: пошаговое руководство.

Проверка совместимости модуля с вашей версией Nginx

Несовместимость версий - причина номер один падения сервера после добавления модуля. Модуль должен быть собран под ту же мажорную версию Nginx и с теми же опциями компиляции.

Проверка сигнатур в .so файле выполняется командой:

strings ngx_http_example_module.so | grep -E 'nginx_version|NGINX_VERSION'

Если версии не совпадают, Nginx откажется загружать модуль с ошибкой module is not binary compatible. Решение одно: пересобрать модуль под вашу версию ядра. Перед внедрением в production всегда тестируйте сборку в staging-окружении, идентичном боевому.

Типичные ошибки при сборке и их решение

Ошибка missing dependencies возникает, когда не установлены dev-пакеты. Для Debian/Ubuntu минимальный набор зависимостей:

apt install build-essential libpcre3-dev libssl-dev zlib1g-dev

Ошибка conflicting symbols сигнализирует, что два модуля экспортируют функции с одинаковыми именами. Решение: отключить один из конфликтующих модулей или собрать их статически в рамках одной компиляции.

Ошибка unknown directive после загрузки модуля означает, что модуль загружен, но его директива не распознана в текущем контексте (например, директива уровня server использована в блоке http). Проверьте документацию модуля на допустимый контекст директив.

Рекомендованные сторонние модули для Nginx в 2026 году

Из десятков доступных сторонних модулей выделим семь, которые решают конкретные задачи в production-средах. Каждый проверен на совместимость с актуальными версиями Nginx и имеет активное сообщество.

nginx-module-vts - расширенный мониторинг и экспорт метрик. В отличие от встроенного stub_status, выдаёт детальную статистику по виртуальным хостам, зонам upstream и кодам ответов. Настройка экспорта в Prometheus:

vhost_traffic_status_zone;
server {
    location /metrics {
        vhost_traffic_status_display;
        vhost_traffic_status_display_format prometheus;
    }
}

ngx_brotli - сжатие Brotli, которое даёт на 20-30% лучшее сжатие текстовых ресурсов по сравнению с gzip при сопоставимой скорости. Поддерживается всеми современными браузерами. Требует сборки с библиотекой libbrotli-dev.

nginx-rtmp-module - стриминг видео и аудио через протокол RTMP. Поддерживает HLS и DASH для доставки контента на мобильные устройства. Незаменим для организации прямых трансляций.

lua-nginx-module - встраивание скриптов Lua непосредственно в конфигурацию Nginx. Позволяет реализовать сложную логику балансировки, динамическую аутентификацию и модификацию ответов без внешних сервисов. Требует установки OpenResty или сборки с LuaJIT.

ngx_http_geoip2_module - определение страны, города и провайдера по IP-адресу с использованием баз MaxMind GeoIP2. Применяется для геотаргетинга и блокировки трафика из определённых регионов.

njs - официальный модуль Nginx для выполнения JavaScript на серверной стороне. Более легковесная альтернатива Lua для задач модификации запросов и ответов. Поддерживает ES6 и асинхронные операции.

ngx_http_headers_more_module - точное управление заголовками: удаление, замена и добавление на всех этапах обработки ответа. Решает проблему, когда стандартный add_header переопределяет заголовки на разных уровнях конфигурации.

Модули для мониторинга и метрик

Выбор между nginx-module-vts и ngx_http_stub_status_module зависит от потребностей. Stub_status даёт минимальную статистику: число принятых соединений, обработанных запросов, активных соединений и чтений/записей. Этого достаточно для базового мониторинга через Zabbix или Nagios.

VTS предоставляет детализацию по каждому server и location, включая гистограммы времени ответа, распределение по кодам HTTP и статистику по upstream-серверам. Для интеграции с Prometheus и Grafana VTS - стандартный выбор. Настройка сводится к добавлению зоны и location для экспорта метрик, как показано выше.

Модули для оптимизации производительности

ngx_brotli даёт выигрыш на текстовом контенте: HTML, CSS, JavaScript, SVG. На изображениях и видео эффекта нет - там применяются свои кодеки. При раздаче статики используйте статически сжатые файлы (.br) вместе с ngx_http_gzip_static_module для минимальной нагрузки на CPU.

ngx_http_slice_module позволяет отдавать большие файлы (видео, ISO-образы) частями, что критично для CDN и медленных клиентов. Модуль нарезает ответ на слайсы заданного размера и кэширует их по отдельности.

ngx_pagespeed (mod_pagespeed) автоматически оптимизирует ресурсы фронтенда: минифицирует CSS/JS, конвертирует изображения в WebP, откладывает загрузку некритичных ресурсов. Однако модуль потребляет значительные ресурсы CPU и RAM, поэтому его применение оправдано только при наличии выделенного сервера оптимизации.

Безопасность модулей Nginx: как минимизировать риски

Каждый модуль увеличивает поверхность атаки - это аксиома. Модуль, обрабатывающий пользовательский ввод (например, парсер MP4 или GeoIP), потенциально содержит уязвимости, которые могут привести к выполнению кода или отказу в обслуживании.

Правила минимизации рисков:

Загружайте только те модули, которые реально используются. Проверьте конфигурацию на наличие неиспользуемых load_module.
Отдавайте предпочтение динамической загрузке - скомпрометированный динамический модуль проще изолировать и заменить.
Обновляйте Nginx и модули из одного репозитория, чтобы гарантировать совместимость и своевременное получение патчей.
Запускайте Nginx от непривилегированного пользователя (www-data, nginx), а не от root.

Пример: уязвимость CVE-2022-41741 в модуле ngx_http_mp4_module позволяла вызвать отказ в обслуживании или потенциально выполнить код при обработке специально сформированного MP4-файла. Патч был выпущен в течение недели, но администраторы, не обновившие Nginx вовремя, оставались уязвимы.

Как отслеживать уязвимости в модулях Nginx

Источники информации об уязвимостях:

Официальная рассылка nginx-announce - обязательная подписка для администраторов.
База CVE (National Vulnerability Database) - поиск по ключевым словам "nginx module".
Автоматические сканеры образов: Trivy, Clair, Docker Scout - проверяют контейнеры на известные уязвимости в пакетах.

Интеграция сканера в CI/CD пайплайн позволяет блокировать деплой образов с критическими CVE. Настройка Trivy для проверки Docker-образа с Nginx:

trivy image --severity HIGH,CRITICAL nginx:1.27

Принцип минимальных привилегий для модулей

Динамические модули можно загружать выборочно, комментируя ненужные load_module. Это уменьшает количество активного кода в рантайме.

Дополнительные меры изоляции:

Запуск Nginx в chroot-окружении ограничивает доступ модуля к файловой системе.
Seccomp-профили ограничивают набор доступных системных вызовов. Например, модулю сжатия не нужен вызов socket().
AppArmor или SELinux создают мандатные политики доступа для процессов Nginx.

Для критичных сред рассмотрите ngx_http_modsecurity_module - WAF на уровне веб-сервера, который блокирует атаки на уровне HTTP-запросов до их обработки модулями. ModSecurity использует сигнатурный анализ и набор правил OWASP Core Rule Set.

Практика показывает: сервер, собранный с десятком непроверенных сторонних модулей, представляет большую угрозу, чем сервер со стандартным набором и одним тщательно проверенным расширением. Каждый модуль перед установкой должен пройти оценку: активность репозитория, частота коммитов, число открытых issues с тегом security, наличие мейнтейнера.