Перейти к основному содержимому

Интеграция с CyberPanel

В этом руководстве объясняется, как настроить интеграцию Ultimate Multisite с CyberPanel, чтобы домены, привязанные в вашей сети, автоматически добавлялись (и удалялись) в CyberPanel в качестве виртуальных хостов, с возможностью автоматического предоставления SSL-сертификатов через Let's Encrypt.

Что это делает​

  • Когда домен привязывается в Ultimate Multisite, интеграция обращается к API CyberPanel, чтобы создать виртуальный хост для этого домена.
  • Когда привязка домена удаляется, интеграция вызывает API для удаления соответствующего виртуального хоста.
  • Если включен автоматический SSL, интеграция немедленно инициирует выдачу сертификата Let's Encrypt после создания виртуального хоста.
  • Опционально добавляет/удаляет псевдоним www. в зависимости от настройки «Автоматическое создание поддомена www» в настройках привязки домена.

Предварительные требования​

  • Работающий экземпляр CyberPanel (рекомендуется v2.3 или новее), доступный с вашего сервера WordPress.
  • Существующий сайт в CyberPanel, который уже обслуживает корневую папку вашей сети WordPress. Интеграция прикрепляет новые виртуальные хосты к этому серверу.
  • Включенный доступ к API CyberPanel. Для аутентификации используются имя пользователя и пароль администратора CyberPanel.
  • Ваши DNS-записи для привязанных доменов должны уже указывать на IP-адрес вашего сервера, прежде чем автоматический SSL сможет выдать действительный сертификат.

Требования​

В файле wp-config.php должны быть определены следующие константы:

define('WU_CYBERPANEL_HOST', 'https://your-cyberpanel-host:8090');
define('WU_CYBERPANEL_USERNAME', 'your_admin_username');
define('WU_CYBERPANEL_PASSWORD', 'your_admin_password');
define('WU_CYBERPANEL_PACKAGE', 'Default');

Опционально вы также можете определить:

define('WU_CYBERPANEL_AUTO_SSL', true);          // По умолчанию: true — выдает SSL Let's Encrypt после создания домена
define('WU_CYBERPANEL_PHP_VERSION', 'PHP 8.2');  // По умолчанию: PHP 8.2
define('WU_CYBERPANEL_EMAIL', '[email protected]'); // Используется для контакта при регистрации SSL-сертификата

Инструкции по настройке​

1. Включение API CyberPanel​

  1. Войдите в панель управления CyberPanel в качестве администратора.
  2. Перейдите в Security > SSL и убедитесь, что SSL активен на самой панели CyberPanel (это необходимо для безопасных вызовов API).
  3. API CyberPanel по умолчанию доступен по адресу https://your-server-ip:8090/api/. Для включения дополнительных шагов не требуется — он включен по умолчанию для административных пользователей.

2. Добавление констант в wp-config.php​

Добавьте следующие константы в файл wp-config.php перед строкой /* That's all, stop editing! */:

define('WU_CYBERPANEL_HOST', 'https://your-cyberpanel-host:8090');
define('WU_CYBERPANEL_USERNAME', 'admin');
define('WU_CYBERPANEL_PASSWORD', 'your_secure_password');
define('WU_CYBERPANEL_PACKAGE', 'Default');

Чтобы включить автоматический SSL (рекомендуется):

define('WU_CYBERPANEL_AUTO_SSL', true);
define('WU_CYBERPANEL_EMAIL', '[email protected]');

3. Включение интеграции​

  1. В административной панели сети WordPress перейдите в Ultimate Multisite > Settings.
  2. Перейдите на вкладку Domain Mapping.
  3. Прокрутите вниз до Host Integrations.
  4. Включите интеграцию CyberPanel.
  5. Нажмите Save Changes.

4. Проверка подключения​

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

  1. Перейдите в Ultimate Multisite > Settings > Domain Mapping > Host Integrations > CyberPanel.
  2. Нажмите Test Connection.
  3. Сообщение об успехе подтверждает, что плагин может получить доступ к API CyberPanel и правильно пройти аутентификацию.

Как это работает​

Привязка домена (Domain Mapping)​

Когда домен привязывается в Ultimate Multisite:

  1. Интеграция отправляет POST-запрос на /api/createWebsite на ваш хост CyberPanel.
  2. CyberPanel создает новый виртуальный хост для домена в рамках настроенного пакета.
  3. Корневая директория устанавливается так, чтобы указывать на корневую папку вашей сети WordPress.
  4. Когда привязка домена удаляется, интеграция вызывает /api/deleteWebsite, чтобы очистить виртуальный хост.

Автоматический SSL (Auto-SSL)​

Когда WU_CYBERPANEL_AUTO_SSL установлено в true:

  1. После создания виртуального хоста интеграция вызывает /api/issueSSL для домена.
  2. CyberPanel запрашивает сертификат Let's Encrypt, используя проверку ACME HTTP-01.
  3. Сертификат автоматически продлевается CyberPanel до истечения срока действия.

Важно: DNS должен быть полностью пропэгатирован до IP-адреса вашего сервера, прежде чем Let's Encrypt сможет проверить домен. Если выдача SSL не удалась сразу после привязки, подождите, пока произойдет пропэгация DNS, и повторно запустите SSL из панели CyberPanel в разделе SSL > Manage SSL.

Поддомен www​

Если в настройках привязки домена включено Auto-create www subdomain, интеграция также создает виртуальный хост-псевдоним для www.<домен> и, если включен автоматический SSL, выдает сертификат, покрывающий как основной домен (apex), так и вариант www.

Пересыльщики электронной почты (Email Forwarders)​

Когда активен аддон Ultimate Multisite: Emails, CyberPanel также может предоставлять пересыльщики электронной почты для клиентов. Пересыльщики маршрутизируют сообщения с адреса домена на другой почтовый ящик без создания полноценного почтового ящика, что полезно для псевдонимов типа [email protected] или [email protected].

Перед включением пересыльщиков для клиентов:

  1. Убедитесь, что константы CyberPanel выше настроены и тест подключения пройден.
  2. В настройках аддона Emails включите поставщика электронной почты CyberPanel.
  3. Убедитесь, что домен клиента уже существует в CyberPanel, прежде чем создавать пересыльщик.
  4. Создайте тестовый пересыльщик и отправьте через него сообщение, прежде чем предлагать эту функцию на рабочих планах.

Если создание пересыльщика не удалось, сначала проверьте журналы активности Ultimate Multisite, а затем убедитесь в CyberPanel, что исходный домен существует и что пользователь API имеет права на управление электронной почтой.

Справочник конфигурации​

КонстантаТребуетсяПо умолчаниюОписание
WU_CYBERPANEL_HOSTДа—Полный URL вашего экземпляра CyberPanel, включая порт, например, https://cp.example.com:8090
WU_CYBERPANEL_USERNAMEДа—Имя пользователя администратора CyberPanel
WU_CYBERPANEL_PASSWORDДа—Пароль администратора CyberPanel
WU_CYBERPANEL_PACKAGEДаDefaultПакет хостинга CyberPanel, который будет назначен новым виртуальным хостам
WU_CYBERPANEL_AUTO_SSLНетtrueВыдавать SSL-сертификат Let's Encrypt после создания домена
WU_CYBERPANEL_PHP_VERSIONНетPHP 8.2Версия PHP для новых виртуальных хостов (должна соответствовать версии, установленной в CyberPanel)
WU_CYBERPANEL_EMAILНет—Контактный email для регистрации SSL-сертификата

Важные примечания​

  • API CyberPanel использует аутентификацию токенов на основе сессий. Интеграция автоматически обрабатывает получение токенов при каждом вызове API.
  • Ваша учетная запись администратора CyberPanel должна иметь права на создание и удаление сайтов.
  • CyberPanel по умолчанию работает на порту 8090. Если ваш сервер использует брандмауэр, убедитесь, что этот порт доступен с сервера приложения WordPress.
  • Интеграция не управляет DNS-записями. Вы должны указать DNS домена на IP-адрес вашего сервера, прежде чем привязывать домен в Ultimate Multisite.
  • Если вы используете OpenLiteSpeed (OLS), после изменений виртуального хоста автоматически запускается мягкая перезагрузка. Ручное вмешательство не требуется.

Устранение неполадок​

Отказано в подключении к API (API Connection Refused)​

  • Убедитесь, что порт 8090 открыт в брандмауэре вашего сервера.
  • Подтвердите, что значение WU_CYBERPANEL_HOST включает правильный протокол (https://) и порт.
  • Проверьте, что ваш SSL-сертификат CyberPanel действителен; самоподписанные сертификаты могут вызвать сбои проверки TLS. Устанавливайте WU_CYBERPANEL_VERIFY_SSL в false только в доверенных частных сетевых средах.

Ошибки аутентификации (Authentication Errors)​

  • Подтвердите, что ваши WU_CYBERPANEL_USERNAME и WU_CYBERPANEL_PASSWORD верны, войдя в CyberPanel напрямую.
  • CyberPanel блокирует учетные записи после нескольких неудачных попыток входа. Проверьте Security > Brute Force Monitor в CyberPanel, если происходит блокировка.

Домен не создан (Domain Not Created)​

  • Проверьте журнал активности Ultimate Multisite (Ultimate Multisite > Activity Logs) на наличие сообщений об ошибках API.
  • Убедитесь, что пакет, указанный в WU_CYBERPANEL_PACKAGE, существует в CyberPanel (Packages > List Packages).
  • Убедитесь, что домен не зарегистрирован уже как сайт в CyberPanel — попытка создания дублирующего сайта вернет ошибку.

SSL-сертификат не выдан (SSL Certificate Not Issued)​

  • Подтвердите, что DNS полностью пропэгатирован: dig +short your-domain.com должен вернуть IP-адрес вашего сервера.
  • Let's Encrypt ограничивает количество запросов. Если вы недавно выдавали несколько сертификатов для одного и того же домена, подождите, прежде чем повторять попытку.
  • Проверьте журналы SSL CyberPanel в разделе Logs > Error Logs для получения подробной информации о сбоях выдачи сертификата.
  • В качестве запасного варианта вы можете выдать SSL вручную из CyberPanel: SSL > Manage SSL > выбрать домен > Issue SSL.

Ссылки​