Установка модулей Nginx через APT и YUM: полное пошаговое руководство | AdminWiki
Logo

Установка модулей Nginx через APT и YUM: полное пошаговое руководство

26 июля 2026 9 мин. чтения
Содержание статьи

Чтобы установить дополнительный модуль Nginx через пакетный менеджер, нужно подключить официальный репозиторий проекта, выполнить поиск нужного пакета командой apt search nginx-module (Debian/Ubuntu) или yum search nginx-module (CentOS/Rocky), проверить совместимость версий и запустить установку. После этого модуль подключается директивой load_module в конфигурации, а результат проверяется через nginx -T.

Этот подход исключает ручную компиляцию и гарантирует, что модуль собран под ту же версию Nginx, что установлена в системе. Вы получаете готовый бинарник, который достаточно активировать в конфигурационном файле. Руководство охватывает два семейства дистрибутивов: Debian/Ubuntu с пакетным менеджером APT и CentOS/Rocky Linux с YUM/DNF. Для каждого шага приведены проверенные команды, которые можно копировать и выполнять без изменений.

Материал построен на практике работы с продакшн-средами. Все примеры протестированы на Ubuntu 22.04/24.04 LTS и Rocky Linux 9. Если вы ранее собирали Nginx из исходников ради одного модуля, после прочтения вы сможете получать ту же функциональность через штатный пакетный менеджер за считанные минуты. О том, как проверить, какие модули уже скомпилированы в вашу сборку, читайте в отдельном руководстве по просмотру установленных модулей Nginx.

Подготовка: настройка репозиториев для актуальных модулей Nginx

Стандартные репозитории Debian и CentOS содержат устаревшие версии Nginx. Например, Ubuntu 22.04 LTS из коробки предлагает Nginx 1.18, тогда как актуальная стабильная ветка на июль 2026 года - 1.26.x или 1.27.x. Модули из разных веток несовместимы: попытка установить пакет nginx-module-geoip из официального репозитория Nginx для версии 1.26 на систему с Nginx 1.18 из репозитория Ubuntu приведёт к ошибке разрешения зависимостей. Поэтому первый шаг - подключение официального репозитория nginx.org, который содержит согласованные версии ядра и модулей.

Для модулей, которых нет в официальном репозитории (например, Brotli), потребуется сторонний источник. Наиболее стабильный вариант - репозиторий nginx-module от сообщества, который поддерживает сборки для популярных дистрибутивов. Ниже разобраны оба случая.

Debian/Ubuntu: добавление официального репозитория Nginx

Выполните следующие шаги для подключения репозитория. Команды требуют прав суперпользователя.

Шаг 1. Установите пакеты для работы с HTTPS-репозиториями и управления ключами:

sudo apt update
sudo apt install curl gnupg2 ca-certificates lsb-release debian-archive-keyring

Шаг 2. Добавьте официальный ключ подписи Nginx:

curl -fsSL https://nginx.org/keys/nginx_signing.key | sudo gpg --dearmor -o /usr/share/keyrings/nginx-archive-keyring.gpg

Шаг 3. Создайте файл репозитория:

echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] http://nginx.org/packages/mainline/ubuntu $(lsb_release -cs) nginx" | sudo tee /etc/apt/sources.list.d/nginx.list

Для стабильной ветки замените mainline на stable. Администраторам, которые предпочитают проверенные временем версии, рекомендуем стабильную ветку. Тем, кому нужны самые новые возможности - mainline.

Шаг 4. Обновите индекс пакетов:

sudo apt update

После обновления проверьте доступность пакетов:

apt policy nginx

Вывод покажет кандидата на установку из добавленного репозитория. Если приоритет ниже, чем у системного пакета, настройте пиннинг через файл /etc/apt/preferences.d/nginx.

CentOS/Rocky Linux: настройка репозитория через YUM/DNF

Для RPM-дистрибутивов процесс аналогичен, но синтаксис команд отличается.

Шаг 1. Установите утилиты для управления репозиториями:

sudo dnf install yum-utils

Шаг 2. Создайте файл репозитория:

sudo tee /etc/yum.repos.d/nginx.repo <<EOF
[nginx-stable]
name=nginx stable repo
baseurl=http://nginx.org/packages/centos/\$releasever/\$basearch/
gpgcheck=1
enabled=1
gpgkey=https://nginx.org/keys/nginx_signing.key
module_hotfixes=true
EOF

Для Rocky Linux 9 укажите \$releasever - он автоматически подставит нужную версию (9). Для CentOS 7 замените centos на rhel в baseurl.

Шаг 3. Очистите кэш и проверьте доступность пакетов:

sudo dnf clean all
sudo dnf makecache
dnf list available nginx\*

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

sudo dnf remove nginx
sudo dnf install nginx

Поиск доступных модулей Nginx в репозиториях

После подключения репозитория вы получаете доступ к десяткам модулей. Точный список зависит от версии Nginx и дистрибутива. Для поиска используйте штатные команды пакетного менеджера с фильтрацией по имени.

Debian/Ubuntu (APT):

apt search nginx-module

Вывод показывает все пакеты, в имени которых есть nginx-module. Для фильтрации по конкретной функциональности используйте grep:

apt search nginx-module | grep -i geo

CentOS/Rocky (YUM/DNF):

dnf search nginx-module

Для просмотра подробной информации о конкретном пакете:

apt show nginx-module-geoip        # Debian/Ubuntu
dnf info nginx-module-geoip         # CentOS/Rocky

В описании пакета указаны: версия модуля, для какой версии Nginx он собран, список зависимостей и краткое описание функциональности. Популярные модули, доступные в официальном репозитории: nginx-module-geoip, nginx-module-image-filter, nginx-module-njs, nginx-module-perl, nginx-module-xslt.

Модуль Brotli отсутствует в официальном репозитории. Для его установки подключите сторонний репозиторий:

sudo add-apt-repository ppa:hda-me/nginx-stable    # Ubuntu
sudo apt update

После этого пакет libnginx-mod-brotli станет доступен для установки. На CentOS/Rocky аналогичный пакет предоставляется репозиторием GetPageSpeed:

sudo dnf install https://extras.getpagespeed.com/release-latest.rpm
sudo dnf install nginx-module-brotli

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

Установка модуля, собранного для другой версии Nginx, приведёт к ошибке при загрузке. Сервер либо откажется стартовать, либо проигнорирует модуль. Проверка совместимости занимает меньше минуты и предотвращает простой.

Шаг 1. Узнайте точную версию установленного Nginx:

nginx -v

Вывод содержит строку вида nginx/1.26.2. Запомните номер версии.

Шаг 2. Проверьте, для какой версии собран модуль:

apt show nginx-module-geoip | grep -E "Version|Depends"    # APT
dnf info nginx-module-geoip | grep -E "Version|Requires"   # DNF

В зависимостях пакета указана требуемая версия Nginx, например nginx (= 1.26.2). Если версии совпадают, можно устанавливать. Если нет - ищите альтернативы.

Шаг 3. Действия при несовпадении версий:

  • Обновите Nginx до версии, для которой собран модуль: sudo apt install nginx=1.26.2
  • Найдите модуль в другом репозитории, который поддерживает вашу версию
  • Соберите модуль из исходников - процесс описан в руководстве по сборке динамических модулей Nginx

Разрешение конфликтов зависимостей при установке

Пакетный менеджер может отказаться устанавливать модуль с ошибкой вроде nginx-module-geoip : Depends: nginx (= 1.26.2) but 1.27.0 is to be installed. Это означает, что версия Nginx в системе новее, чем требуется модулю. Решения:

  • Понизить версию Nginx до требуемой модулем: sudo apt install nginx=1.26.2 nginx-module-geoip
  • Использовать флаг --no-install-recommends (APT), чтобы избежать подтягивания дополнительных пакетов, усугубляющих конфликт
  • Установить модуль из того же репозитория и той же версии, что и Nginx - это основная рекомендация, которая решает 95% проблем
  • Для YUM/DNF: флаг --skip-broken позволяет пропустить проблемный пакет и установить остальные, но для модуля это не подходит - он просто не будет установлен. Вместо этого используйте dnf module reset nginx и явно укажите версию

Установка модуля: пошаговые команды для APT и YUM/DNF

Синтаксис установки универсален: имя пакета формируется по шаблону nginx-module-<имя_модуля>. После установки модуль размещается в директории /etc/nginx/modules (Debian/Ubuntu) или /usr/lib64/nginx/modules (CentOS/Rocky). Для активации добавьте директиву load_module в конфигурационный файл /etc/nginx/nginx.conf в секцию над блоками events и http.

load_module modules/ngx_http_geoip_module.so;

events {
    worker_connections 1024;
}

http {
    ...
}

После изменения конфигурации проверьте её корректность и перезагрузите Nginx:

sudo nginx -t
sudo systemctl reload nginx

Установка модуля GeoIP для геолокации

Модуль GeoIP определяет страну, регион и город посетителя по IP-адресу. Данные используются для блокировки трафика из определённых стран, маршрутизации на языковые версии сайта или сбора статистики.

Установка:

# Debian/Ubuntu
sudo apt install nginx-module-geoip geoip-database

# CentOS/Rocky
sudo dnf install nginx-module-geoip geoip geoip-devel

Базовая конфигурация в nginx.conf:

load_module modules/ngx_http_geoip_module.so;

http {
    geoip_country /usr/share/GeoIP/GeoIP.dat;
    geoip_city /usr/share/GeoIP/GeoIPCity.dat;

    server {
        location / {
            if ($geoip_country_code = RU) {
                return 302 /ru/;
            }
        }
    }
}

Проверка работы: выполните запрос к серверу и проверьте заголовки или переменные. Самый быстрый способ - добавить кастомный заголовок с геоданными во время отладки:

add_header X-Geo-Country $geoip_country_code;

После перезагрузки Nginx отправьте тестовый запрос:

curl -I http://localhost | grep X-Geo-Country

Вывод X-Geo-Country: RU подтверждает, что модуль загружен и работает.

Установка модуля Brotli для сжатия

Brotli сжимает текстовые ресурсы на 15-25% эффективнее, чем gzip, при сопоставимой скорости. Модуль не входит в официальный репозиторий Nginx, поэтому используйте сторонний источник.

Ubuntu - установка из PPA:

sudo add-apt-repository ppa:hda-me/nginx-stable
sudo apt update
sudo apt install libnginx-mod-brotli

CentOS/Rocky - установка из GetPageSpeed:

sudo dnf install https://extras.getpagespeed.com/release-latest.rpm
sudo dnf install nginx-module-brotli

Конфигурация:

load_module modules/ngx_http_brotli_filter_module.so;
load_module modules/ngx_http_brotli_static_module.so;

http {
    brotli on;
    brotli_comp_level 6;
    brotli_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
}

Проверка работы:

curl -H "Accept-Encoding: br" -I http://localhost | grep Content-Encoding

Вывод Content-Encoding: br означает, что сжатие Brotli активно.

Проверка загрузки и работы модуля

После установки и настройки убедитесь, что модуль действительно загружен и функционирует. Двухэтапная проверка исключает ситуацию, когда конфигурация написана, но модуль не активен.

Этап 1. Проверка загрузки модуля:

nginx -T 2>&1 | grep load_module

Команда выводит полную конфигурацию, включая все активные директивы load_module. Каждая строка соответствует одному загруженному динамическому модулю. Отсутствие вывода означает, что модуль не загружен - проверьте наличие директивы в конфигурации и правильность пути к .so-файлу.

Для статических модулей, вкомпилированных в ядро, используйте:

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

Статические модули отображаются с префиксом --with-http_, динамические - с --with-...=dynamic. Подробный разбор вывода команды nginx -V и методов аудита модулей приведён в статье о просмотре установленных модулей Nginx.

Этап 2. Функциональное тестирование:

Для каждого модуля тест индивидуален. Принцип: создать конфигурацию, которая использует возможности модуля, и проверить ожидаемое поведение. Примеры:

  • GeoIP: настройте add_header X-Geo-Country $geoip_country_code; и проверьте заголовок в ответе сервера
  • Brotli: запросите ресурс с заголовком Accept-Encoding: br и проверьте Content-Encoding: br
  • Image Filter: настройте image_filter resize 100 100; и запросите изображение - размер должен измениться
  • Auth LDAP: настройте аутентификацию и попробуйте зайти на защищённый ресурс с корректными и некорректными учётными данными

Если функциональный тест не проходит, а модуль загружен, проверьте логи ошибок:

sudo tail -f /var/log/nginx/error.log

Типичные причины: отсутствие необходимых библиотек, неверные пути к базам данных (GeoIP), синтаксические ошибки в директивах модуля.

Типичные проблемы и их решение

Модуль не загружается после установки. Самая частая причина - отсутствие директивы load_module в конфигурации. Установка пакета копирует .so-файл на диск, но не активирует модуль автоматически. Добавьте директиву в /etc/nginx/nginx.conf вручную. Проверьте, что путь к файлу корректен: для Debian/Ubuntu это modules/ngx_http_geoip_module.so, для CentOS/Rocky - /usr/lib64/nginx/modules/ngx_http_geoip_module.so.

Ошибка version mismatch. Nginx отказывается загружать модуль с сообщением module was built for version 1.26.2, but this is 1.27.0. Решение: установите модуль и Nginx из одного репозитория одной командой:

sudo apt install nginx=1.26.2 nginx-module-geoip

Если нужна конкретная версия Nginx, сначала удалите текущую, затем установите требуемую вместе с модулем. На CentOS/Rocky используйте dnf module reset nginx перед установкой.

Модуль отсутствует в репозитории. Не все модули пакетированы. Если нужного модуля нет ни в официальном, ни в сторонних репозиториях, остаётся сборка из исходников. Процесс включает компиляцию динамического модуля с флагом --add-dynamic-module и копирование полученного .so-файла в директорию модулей. Детальная инструкция - в руководстве по сборке и подключению динамических модулей Nginx.

Ошибка загрузки модуля из-за отсутствующих библиотек. Сообщение в логах: cannot open shared object file: No such file or directory. Проверьте зависимости модуля:

ldd /etc/nginx/modules/ngx_http_geoip_module.so    # Debian/Ubuntu
ldd /usr/lib64/nginx/modules/ngx_http_geoip_module.so  # CentOS/Rocky

Вывод покажет отсутствующие библиотеки с пометкой not found. Установите соответствующие пакеты. Для GeoIP это libgeoip1 (Debian) или geoip (CentOS).

Конфигурация валидна, но функциональность не работает. Пример: модуль GeoIP загружен, но переменная $geoip_country_code пуста. Причина - отсутствие базы данных GeoIP. Установите пакет geoip-database (Debian) или geoip (CentOS) и укажите правильный путь к .dat-файлу в директиве geoip_country.

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

Поделиться:
Сохранить гайд? В закладки браузера