Если MODX-сайт перестал открываться, показывает белый экран, ошибку 500 или бесконечную загрузку, не начинайте с переустановки CMS. Сначала нужно определить, отвечает ли веб-сервер, запускается ли PHP, подключается ли MODX к базе и на каком этапе обрывается обработка запроса.

Чаще всего сбой появляется после обновления PHP, изменения .htaccess, установки дополнения, переноса проекта или переполнения диска. Безопасная тактика: сохранить текущее состояние, снять логи, локализовать слой ошибки и только затем менять конфигурацию.

Что проверить в первую очередь

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

  • Снимите HTTP-код через браузер и curl: 403, 404, 500, 502 и 504 указывают на разные уровни сбоя.
  • Проверьте свободное место и inode, доступность базы, срок сертификата и состояние PHP-FPM.
  • Откройте error_log веб-сервера, журнал PHP и core/cache/logs/error.log MODX за время сбоя.
  • Уточните, что изменилось перед проблемой: версия PHP, дополнение, шаблон, DNS, SSL или права файлов.

Почему возникает проблема

У подобных сбоев редко бывает одна универсальная причина. На итог одновременно влияют конфигурация приложения, окружение, данные, кеш, права и внешние сервисы. Проверка должна идти от внешнего симптома к конкретному уровню, на котором впервые появляется неверное состояние.

  • Версия MODX или дополнения несовместима с новой версией PHP.
  • В .htaccess ошибочно настроены rewrite-правила, базовый путь или обработчик PHP.
  • Поврежден кеш, а плагин или сниппет падает при событии, которое выполняется на каждой странице.
  • Изменились реквизиты базы, права пользователя MySQL либо кодировка соединения.
  • Диск заполнен, PHP-FPM исчерпал воркеры или файлы принадлежат другому системному пользователю.

Пошаговая диагностика

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

  • Проверьте простой статический файл и отдельный минимальный PHP-файл, чтобы разделить проблемы Nginx/Apache и PHP.
  • Запустите проверку синтаксиса измененных PHP-файлов и найдите первое исключение в логе, а не последнее вторичное сообщение.
  • Сравните версию PHP в CLI и у сайта: они могут использовать разные конфигурации и наборы расширений.
  • Проверьте подключение к базе теми же реквизитами и убедитесь, что таблицы MODX доступны.
  • Временно переименуйте только каталог кеша после резервной копии; не удаляйте core и пользовательские файлы.

Как отличить сбой MODX от проблемы сервера

MODX формирует страницу после прохождения веб-сервера, PHP, загрузки конфигурации, соединения с базой и событий плагинов. Точка первого отказа определяет правильное действие.

  • Статический файл не открывается — проверяйте DNS, виртуальный хост, TLS, корень сайта и правила веб-сервера.
  • Статика работает, а PHP нет — проверяйте PHP-FPM, сокет, лимиты памяти, расширения и синтаксис.
  • Минимальный PHP работает, но MODX падает — смотрите config.inc.php, базу, кеш и события плагинов.
  • Главная открывается, а внутренние страницы нет — проверяйте friendly URLs, base_url, site_url и rewrite.
  • Менеджер доступен, а фронтенд нет — локализуйте шаблон, сниппеты и плагины конкретного контекста.

Как исправить проблему

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

  • Верните совместимую версию PHP либо обновите MODX и дополнения сначала на тестовой копии.
  • Исправьте виртуальный хост и .htaccess по рабочему эталону, сохранив старый файл для отката.
  • Очистите кеш штатно или удалите только его содержимое при остановленном процессе записи.
  • Отключайте подозрительный плагин точечно через базу лишь при наличии резервной копии и понимании события.
  • Восстановите владельца и минимально необходимые права; не используйте chmod 777 как постоянное решение.

Безопасный порядок внедрения

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

Как проверить результат

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

  • Главная, внутренние ЧПУ, менеджер и сохранение тестового ресурса работают без новых ошибок.
  • После повторной очистки кеша и перезапуска PHP-FPM сайт продолжает открываться.
  • В журнале нет повторяющихся fatal error, предупреждений подключения к базе и циклов редиректа.
  • Проверены формы, поиск, авторизация и задачи cron, связанные с MODX.

Типичные ошибки при исправлении

  • Включать публичный display_errors и показывать посетителям пути, запросы или секреты.
  • Удалять весь core или переустанавливать CMS до сохранения базы и пользовательских файлов.
  • Одновременно менять PHP, .htaccess, права и плагины, после чего невозможно определить причину.
  • Выдавать всем файлам права 777 вместо восстановления владельца и корректных групп.

Как предотвратить повторение

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

  • Фиксируйте версии MODX, PHP и дополнений и проверяйте обновления на staging.
  • Настройте мониторинг HTTP-кодов, диска, PHP-FPM и ошибок приложения.
  • Храните рабочую конфигурацию веб-сервера и .htaccess в системе контроля версий.
  • Проверяйте восстановление резервной копии, а не только факт ее создания.

Что подготовить для разбора

  • Краткое описание ожидаемого и фактического поведения без паролей, токенов и персональных данных.
  • Точное время и последовательность действий, после которых появляется проблема.
  • Версии приложения, окружения и зависимостей, а также перечень последних изменений.
  • Фрагменты журналов с контекстом до и после ошибки; секреты в них необходимо скрыть.
  • Описание уже выполненных проверок и способ безопасно повторить проблему.

Частые вопросы

Можно ли просто очистить кеш MODX?

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

Почему менеджер работает, а сайт нет?

Менеджер и фронтенд используют разные контексты, шаблоны и события. Тогда сервер и база, вероятно, доступны, а искать нужно в теме, сниппетах, friendly URLs и фронтенд-плагинах.

Когда нужна помощь специалиста

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