Как добавить собственный модуль Nginx в ISPmanager
Контрольная панель ISPmanager широко используется для управления сайтами, пользователями и серверными службами. Однако ее возможности не ограничиваются функциями, доступными сразу после установки. С помощью механизма плагинов панель можно адаптировать под нестандартные задачи: добавить новые пункты меню, создать формы, подключить отчеты и автоматизировать действия, выполняемые до или после типовых операций.
В качестве практического примера рассмотрим подключение к Nginx расширения `mod_rewrite` - `ngx_http_apache_rewrite_module`. Такой модуль позволяет обрабатывать правила из файла `.htaccess` даже в конфигурации Nginx + PHP-FPM, без Apache. Это особенно полезно при переносе сайтов и CMS, рассчитанных на Apache и его правила перенаправлений.
Задача актуальна для серверов под управлением AlmaLinux 9/10 и совместимых дистрибутивов. Debian и Ubuntu в рассматриваемом сценарии не используются. Цель проекта - подготовить RPM-пакет, который можно установить на сервер с ISPmanager. После установки он должен:
- собрать и подключить модуль `ngx_http_apache_rewrite_module` для текущей версии Nginx;
- отслеживать обновления Nginx и при необходимости автоматически пересобирать расширение;
- добавить в интерфейс ISPmanager формы для включения, отключения и настройки модуля;
- позволить управлять доступностью расширения для отдельных сайтов.
Практическое руководство по подобному расширению панели и работе с конфигурацией можно изучить в материале о том, как выполняется настройка Nginx в ISPmanager. При этом важно разделять несколько разных понятий. Плагин ISPmanager добавляет интерфейс и логику управления. Модуль ISPmanager отображается в разделе "Модули", используется для первичной настройки и удаления расширения. А `mod_rewrite` в данном случае является именно модулем-расширением Nginx.
Почему стандартной настройки ЧПУ недостаточно
Для проверки создается пользователь ISPmanager и тестовый сайт. В качестве режима работы выбирается FastCGI - связка Nginx и PHP-FPM, а в настройках сайта включается параметр "Обработка ЧПУ". В корне сайта размещается файл `.htaccess` с несколькими правилами:
1. перенаправление `index.php` на тот же файл с параметром;
2. обработка URL, начинающихся с `test1/`;
3. обработка адресов с префиксом `test-ok/`;
4. внутреннее перенаправление `test6.php` на `test2.php`;
5. запрет прямого доступа к `test3.php`.
В связке Apache и `mod_rewrite` эти правила работают ожидаемым образом. Но после переключения сайта на Nginx + PHP-FPM ситуация меняется: стандартная галочка ЧПУ не превращает Nginx в полноценный интерпретатор Apache-правил. Часть запросов обрабатывается неправильно, часть перенаправлений не выполняется, а запрет доступа к отдельному файлу может игнорироваться.
Проблему можно решить ручным редактированием блока `server` для конкретного сайта. Однако при использовании панели управления это неудобно: конфигурации генерируются автоматически, могут перезаписываться после изменения параметров сайта или обновления, а повторять операции вручную для нескольких ресурсов неэффективно. Поэтому предпочтительнее использовать собственный плагин и централизованное управление.
Структура плагина ISPmanager
Основой расширения является XML-файл. В нем описываются:
- элементы интерфейса и структура форм;
- события, на которые должен реагировать плагин;
- обработчики, запускаемые при выполнении этих событий;
- параметры, доступные администратору.
Файлы расширения располагаются в стандартных каталогах ISPmanager:
```text
/usr/local/mgr5/etc/xml
/usr/local/mgr5/addon
```
В первом каталоге размещается XML-описание плагина, а во втором - исполняемые обработчики и логика его работы. Такое разделение позволяет отдельно описать интерфейс и реализовать серверные действия.
Для первоначальной настройки создается описание модуля ISPmanager, например:
```text
/usr/local/mgr5/etc/plugins/ispmgr/nginx_mod_rewrite_plugin.xml
```
В XML указывается обработчик настроек:
```xml
```
Именно он запускается при первичной конфигурации. В данном проекте первичная настройка сводится к загрузке исходных файлов, проверке установленной версии Nginx, сборке `mod_rewrite` и подключению полученного модуля.
Как организовать сборку и обновление
Нельзя рассчитывать, что однажды собранное расширение будет работать после любого обновления Nginx. Динамический модуль должен соответствовать версии основного сервера, поэтому RPM-пакет обязан проверять состояние компонентов. При обнаружении новой версии Nginx запускается повторная сборка, после чего конфигурация сервиса обновляется и выполняется проверка успешности загрузки.
Желательно предусмотреть резервное копирование рабочей конфигурации перед изменениями. Если новая сборка окажется несовместимой, автоматический обработчик должен вернуть прежний вариант и записать подробности в журнал. Такой подход делает управление сервером ISPmanager безопаснее и снижает риск простоя сайтов.
При проектировании интерфейса стоит разделить глобальные и локальные параметры. Администратор должен иметь возможность включить или выключить расширение на уровне сервера, а также определить, для каких сайтов разрешена обработка `.htaccess`. Это предотвращает непреднамеренное выполнение правил на ресурсах, где они не тестировались.
Что должен содержать интерфейс
Плагин может включать несколько форм:
- статус установленного модуля;
- текущую версию Nginx и версию собранного расширения;
- кнопку запуска сборки;
- переключатель глобальной активности;
- список сайтов, для которых разрешен `mod_rewrite`;
- состояние последней операции и текст ошибки.
Такая схема удобнее ручной правки конфигурационных файлов. Все основные действия выполняются из панели, а администратор видит, подключен ли модуль, когда он был собран и не возникли ли ошибки при перезапуске Nginx.
В XML также можно описать обработчики событий создания, изменения и удаления сайта. Например, при добавлении ресурса плагин может автоматически подготовить нужный фрагмент конфигурации, а при отключении расширения - удалить его и корректно проверить синтаксис Nginx. Это делает установку модулей Nginx частью стандартного жизненного цикла сайтов.
Проверка результата
После сборки необходимо проверить несколько уровней:
1. успешно ли собрался модуль;
2. видит ли его Nginx;
3. проходит ли проверку синтаксис конфигурации;
4. корректно ли перезапускается служба;
5. выполняются ли все тестовые правила `.htaccess`;
6. сохраняются ли настройки после изменения параметров сайта в ISPmanager.
Отдельно следует протестировать обычные страницы, PHP-скрипты, несуществующие адреса и запрещенные файлы. Важно убедиться, что внутренние перенаправления не превращаются в циклы, а внешние редиректы возвращают правильные HTTP-коды.
Таким образом, собственный плагин решает сразу две задачи: расширяет возможности панели и автоматизирует обслуживание нестандартного модуля Nginx. Корректная настройка Nginx в ISPmanager в этом случае перестает зависеть от ручного редактирования сгенерированных конфигураций. А механизм автоматической пересборки помогает сохранить работоспособность расширения после обновления веб-сервера.
Для администраторов, которым требуется добавить модуль Nginx, особенно важны контроль версий, безопасный откат и проверка конфигурации перед перезапуском. Если эти механизмы заложить в RPM-пакет и обработчики плагина с самого начала, расширение получится пригодным не только для тестового стенда, но и для постоянной эксплуатации.
