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

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

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

Разбор четырёх частых отказов: панель не запускается, сайт отвечает 502 или 404, сертификат не выпускается и агент недоступен.

В каждом сценарии ниже три части: симптомы, которые вы видите, проверки, отличающие причины друг от друга, и исправления. Все команды выполняйте на самом сервере от root. Два инструмента помогают во всех четырёх случаях: maran status показывает, какие службы работают, даже когда панель не отвечает, а maran collect-diagnostics собирает архив с вычищенными секретами для того, кто вам помогает (оба описаны в разделе Восстановление и диагностика).

bash
sudo /usr/local/sbin/maran status

Службы называются maran-api (панель), maran-agent (демон от root, выполняющий привилегированные операции), postgresql и nginx; после включения передачи файлов в списке появляется и maran-ftps. Их журналы находятся в журнале systemd.

Панель не запускается

Симптомы. Браузер не открывает панель на порту 8443, либо открывает, но каждый вызов отвечает 502. В maran status служба maran-api.service в состоянии failed или activating, либо раздел Panel сообщает, что собственный отчёт панели недоступен.

Проверки.

bash
sudo systemctl status maran-api.service --no-pager
sudo journalctl -u maran-api.service -n 50 --no-pager
ls -l /run/maran-api/api.sock
  • Когда панель отказывается запускаться, причина названа в журнале: ключ шифрования или подписи в /etc/maran/panel.env отсутствует, совпадает с опубликованным ключом для разработки или имеет неверный формат, либо не задан ReverseProxy__PeerUid (идентификатор пользователя веб-сервера, который записывает установщик).
  • Панель подключается к PostgreSQL через локальный сокет, поэтому в maran status посмотрите и postgresql.service.
  • У исправной панели есть сокет /run/maran-api/api.sock с правами 660. Если его нет, панель его так и не создала; если права или группа другие, nginx не может его открыть и каждый вызов отвечает 502.
  • Служба сдаётся после пяти запусков за шестьдесят секунд. Если в журнале видно именно это, причина находится выше по журналу, а не в последней строке.

Исправления.

  1. Исправьте то, что названо в журнале, например строку в /etc/maran/panel.env. Не заменяйте ключ шифрования вручную, если об этом не говорит сообщение об отказе: после замены сохранённые секреты становятся нечитаемыми.
  2. Если PostgreSQL был остановлен, сначала запустите его: sudo systemctl start postgresql.service.
  3. Сбросьте счётчик запусков и запустите панель:
    bash
    sudo systemctl reset-failed maran-api.service
    sudo systemctl restart maran-api.service
    
  4. Если сами файлы повреждены, запустите установщик ещё раз: это безопасно (см. Установка). Если не работает только вход в панель, см. Восстановление и диагностика.

Сайт отвечает 502 или 404

Симптомы. Размещённый сайт отвечает 502 Bad Gateway или 404 Not Found, а сама панель работает.

Проверки.

bash
sudo nginx -t
sudo systemctl status nginx.service --no-pager
ls /etc/maran/nginx/sites/
ls -l /run/maran-php/
sudo tail -n 50 /var/log/maran/sites/<account>/*.log
  • nginx -t должен проходить. У каждого сайта свой файл конфигурации в /etc/maran/nginx/sites/, подключаемый через /etc/nginx/conf.d/maran-sites.conf. Сайт без файла там nginx неизвестен, и его имя отвечает как другой сайт или как сайт по умолчанию.
  • 502 на PHP-сайте означает, что nginx не достучался до PHP-пула сайта: его сокет лежит в /run/maran-php. 502 на сайте-обратном прокси означает, что служба, на которую вы его направили, не запущена или не слушает.
  • 404 означает, что nginx ответил, но ничего не нашёл: домена нет среди доменных имён и алиасов сайта, сайт приостановлен или отключён, DNS-имя указывает на другой сервер или в корневом каталоге нет индексного файла. См. Сайты и PHP.
  • Журналы доступа и ошибок самого сайта лежат в /var/log/maran/sites/<account>/, вне домашнего каталога клиента; панель также показывает их потоком на странице сайта. Журналы веб-сервера самой панели: /var/log/maran/nginx-access.log и /var/log/maran/nginx-error.log.

Исправления.

  1. Исправьте домен, алиасы или корневой каталог в панели либо снова включите сайт и проверьте DNS-запись.
  2. Для сайта-обратного прокси запустите службу, на которую он смотрит.
  3. Если нет PHP-сокета или сайт создан более ранним выпуском, перезапустите панель: sudo systemctl restart maran-api.service. При запуске она просит агента привести пул и конфигурацию веб-сервера каждого PHP-сайта в порядок.
  4. Запись конфигурации проверяется собственным валидатором веб-сервера и откатывается при ошибке, поэтому один сайт обычно не ломает остальные. Если nginx -t падает на файле, который не относится к Maran, сначала исправьте его: из-за него не проходит перезагрузка конфигурации для всех сайтов.

Сертификат не выпускается

Симптомы. Заказ сертификата для сайта или доверенного сертификата для панели завершается ошибкой. Это одна из AcmeValidationFailed, AcmeValidationTimedOut, AcmeAuthorityUnreachable, AcmeChallengeWriteFailed, PanelHostNameNotConfigured, PanelChallengeWriteFailed или AgentBelowFreeSpaceFloor (все перечислены в разделе Коды ошибок API).

Проверки.

  • Сертификаты выпускаются по проверке ACME HTTP-01, поэтому центр сертификации должен достучаться до вашего сервера по обычному HTTP на порту 80. Домен должен указывать на этот сервер, а порт 80 не должен блокироваться ни межсетевым экраном перед машиной, ни правилами самого сервера:
    bash
    sudo nft list ruleset
    curl -I http://example.com/.well-known/acme-challenge/test
    

    Ответ 404 на вторую команду нормален: он доказывает, что порт 80 отвечает для этого имени.
  • Проверочный файл сайта отдаётся из его собственного корневого каталога, поэтому сайт должен существовать, быть включён и отвечать на заказываемое имя. Имя, которое панель резервирует (IP-адрес, localhost, .local и подобные или собственное имя панели), отклоняется до любого запроса.
  • Для сертификата панели Panel__HostName в /etc/maran/panel.env должно быть настоящим именем, указывающим на этот сервер. Проверочный файл отдаётся из /var/lib/maran-acme блоком порта 80 в конфигурации веб-сервера панели; сервер, установленный до появления этого блока, требует повторного запуска установщика. См. Сертификат панели.
  • Свободное место: df -h. Ниже порога свободного места (1 ГиБ, если не изменён) запись отклоняется.

Исправления.

  1. Направьте DNS-запись на этот сервер, откройте порт 80 и закажите сертификат снова. Неудачный заказ ничего не заменяет: уже используемый сертификат остаётся на месте.
  2. Задайте Panel__HostName, если его нет, перезапустите панель и закажите снова; если нет блока порта 80, запустите установщик ещё раз.
  3. Освободите место на диске, если ошибка называется AgentBelowFreeSpaceFloor.
  4. Подстановочные имена и DNS-01 не поддерживаются, поэтому имя вида *.example.com заказать нельзя. Как устроены заказ и продление, описано в разделе SSL-сертификаты.

Агент недоступен

Симптомы. Действия, меняющие сервер (создание учётной записи или сайта, заказ сертификата, резервная копия), завершаются ошибкой агента, например AgentIncompatible, а страницы, которые только читают данные панели, открываются. Отчёт о состоянии панели показывает агента как недоступного, а maran status показывает maran-agent.service не в состоянии active.

Проверки.

bash
sudo systemctl status maran-agent.service --no-pager
sudo journalctl -u maran-agent.service -n 50 --no-pager
ls -l /run/maran/agent.sock
cat /etc/maran/agent.env
  • Агент слушает unix-сокет /run/maran/agent.sock: права 660, владелец root, группа панели. Никто другой подключиться не может, а сам агент принимает только идентификатор пользователя из MARAN_AGENT_ALLOW_UID в /etc/maran/agent.env.
  • MARAN_AGENT_FREE_SPACE_FLOOR_MIB в том же файле должен быть целым числом от 1: иначе агент отказывается запускаться (порог свободного места описан в разделе Восстановление и диагностика).
  • AgentIncompatible означает, что панель и агент разных версий, например во время обновления. Их нужно обновлять вместе.
  • Панель запускается без агента и лишь пишет предупреждение, поэтому то, что панель работает, ничего не говорит об агенте.

Исправления.

  1. Перезапустите агента, затем панель, именно в таком порядке:
    bash
    sudo systemctl restart maran-agent.service
    sudo systemctl restart maran-api.service
    
  2. Если служба продолжает падать, исправьте то, что названо в её журнале (например, значение порога), и перед перезапуском выполните sudo systemctl reset-failed maran-agent.service.
  3. Если версии различаются, запустите установщик ещё раз, чтобы обе части были из одного выпуска.
  4. Если не помогло, выполните sudo /usr/local/sbin/maran collect-diagnostics, прочитайте архив и отправьте его тому, кто вам помогает.