Битрикс упал после обновления: обходим CacheEngine TypeError

После нажатия «Обновить» сайт отвечает TypeError, а исправление предлагают установить через уже недоступную админку. Я начинаю с точной диагностики и временного переключения кеша на файлы: если сбой происходит в Redis-обработчике, это позволяет снова запустить ядро и завершить обновление штатным способом. Я — Семёнов Евгений Сергеевич, директор ООО «АйТи-Фреш». Покажу, как найти действующую конфигурацию, не перепутать ошибку RedisCluster с отсутствующим соединением, избежать опасного частичного отката и вернуть Redis только после проверки системы.

Что именно сломалось: RedisCluster и null требуют разных проверок

Сначала я сохраняю полный текст исключения и читаю его буквально. Сообщение Cannot assign null to property Bitrix\Main\Data\CacheEngine::$engine of type Redis|Memcache|Memcached означает, что код попытался записать null в типизированное свойство, которое такого значения не допускает. Это ещё не доказывает, что сервер Redis остановлен. Причиной может быть отсутствующее расширение PHP, неудачное подключение, неполная конфигурация, неподходящий обработчик или промежуточное состояние файлов во время обновления. Поэтому к первой строке обязательно добавляю стек вызовов и время возникновения ошибки.

Если PHP сообщает о попытке присвоить объект RedisCluster, проверка другая. В расширении phpredis RedisCluster объявлен самостоятельным классом, а не наследником Redis. Объект одного класса нельзя записать в свойство, тип которого разрешает только Redis, Memcache или Memcached. Сходство названий здесь ничего не меняет: PHP сопоставляет фактический класс с декларацией типа. Это видно в stub-файле phpredis 6.1.0 и согласуется с правилами декларации типов PHP.

Для исторического сбоя есть подтверждённая контрольная точка: в журнале главного модуля версия main 25.100.100 датирована 12 марта 2025 года, а среди изменений прямо указано исправление кеширования при использовании \RedisCluster. На официальном форуме администратор «1С-Битрикс» 17 марта 2025 года сообщил, что исправление уже доступно в системе обновлений. Это две разные даты: первая относится к записи в истории версии, вторая — к сообщению о доступности пакета. Проверить их можно в истории main и теме форума № 161158.

Я не превращаю main 25.100.100 в универсальный рецепт. Если установлен более новый модуль, а исключение всё равно возникает, нужно проверить фактически загруженный файл, завершённость обновления, действующую секцию cache, расширение PHP и новый стек. Версия в bitrix/modules/main/install/version.php показывает значение из одного файла, но сама по себе не подтверждает, что все установочные действия и преобразования базы завершились успешно.

Административная часть падает вместе с публичной, потому что использует то же ядро. Когда исключение возникает на раннем этапе создания кеша, запрос не доходит даже до формы авторизации или страницы обновлений. В такой ситуации я временно исключаю проблемный кеш-обработчик из загрузки. Если же стек ведёт в обработчик сессий, пользовательский модуль или прямое создание RedisCluster, переключение общей секции cache не решит исходную проблему — потребуется отдельная диагностика соответствующего компонента.

• Сохранить дословное сообщение TypeError и полный стек вызовов.
• Различить присваивание `null` и присваивание объекта `RedisCluster`.
• Проверить фактическую версию main, но не считать один файл доказательством завершённого обновления.
• Установить, относится ли сбой к общему кешу, сессиям или пользовательскому коду.

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

Первым делом я ограничиваю публичный трафик на уровне балансировщика или веб-сервера. Заглушка, реализованная внутри Битрикса, может упасть вместе с приложением. Затем приостанавливаю импорты, обмены с учётными системами, почтовые задания и другие процессы, которые изменяют данные. Отдельно проверяю, не работает ли уже запущенный процесс обновления: второй экземпляр обновлятора в соседней вкладке способен только усложнить восстановление.

Дальше сохраняю журналы, действующие конфигурационные файлы и аварийное состояние файлов с базой данных. Аварийный снимок и резервная копия до обновления решают разные задачи. Первый нужен, чтобы разобрать происшествие и отменить собственные неудачные действия; второй — чтобы при необходимости вернуть заведомо согласованную систему. Если база находится на отдельном сервере, снимок одной веб-машины её не включает. Копии конфигурации и дампы я не оставляю в каталоге, доступном по HTTP.

Минимальную инвентаризацию типовой установки начинаю так. /home/bitrix/www — распространённый, но не обязательный корень сайта; перед запуском его нужно заменить фактическим путём проекта.

cd -- /home/bitrix/www
php -v
php --ri redis
sed -n '1,80p' bitrix/modules/main/install/version.php
df -h .
df -i .

Опция PHP --ri redis выводит сведения о загруженном расширении redis. У sed сочетание -n и адреса 1,80p отключает обычный вывод и печатает первые 80 строк. df -h показывает занятое место в читаемом виде, а df -i — использование inode. Синтаксис сверяется с руководством PHP CLI, GNU sed и GNU Coreutils.

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

Вывод CLI обязательно сопоставляю с PHP, который обслуживает веб-запросы. На сервере могут одновременно работать несколько версий интерпретатора, разные php.ini, разные каталоги расширений и несколько пулов PHP-FPM. Успешный php --ri redis в SSH подтверждает только окружение конкретного CLI-бинарника. Версию и расширения веб-пула проверяю по его конфигурации, журналу запуска и контролируемому диагностическому запросу, который после проверки удаляю или закрываю от публичного доступа.

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

• Зафиксировать время ошибки, URL запроса, стек и этап установки обновлений.
• Сохранить оригиналы изменяемых файлов, их контрольные суммы, владельцев и права.
• Проверить наличие согласованной резервной копии файлов и БД до обновления.
• Остановить фоновые задания и убедиться, что другой обновлятор не продолжает работу.
• Сопоставить CLI PHP с реальным пулом PHP-FPM или модулем веб-сервера.

Нахожу действующую конфигурацию и включаю файловый кеш

Базовые настройки D7 обычно находятся в /bitrix/.settings.php, а динамические дополнения — в /bitrix/.settings_extra.php. Начиная с main 24.100.0 файлы .settings.php и .settings_extra.php разрешено размещать также в /local/. Если одноимённые файлы присутствуют и в /local/, и в /bitrix/, приоритет имеет вариант из /local/. Дополнительный файл объединяется с основным, поэтому он тоже может изменить итоговую секцию cache. Эти правила описаны в документации конфигурации ядра и структуре директорий.

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

В существующей секции cache, внутри value, я целиком заменяю значение type на штатный файловый обработчик:

'type' => [
    'class_name' => '\\Bitrix\\Main\\Data\\CacheEngineFiles',
],

Это фрагмент массива, а не полный файл .settings.php. Остальные параметры секции, включая существующий sid и корректно настроенный root_directory, сохраняю. Из нового type удаляю поля extension, required_file и required_remote_file, если они относились только к прежнему Redis-обработчику. Класс и структура примера приведены в официальном разделе «Конфигурация кеша».

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

'cache' => [
    'value' => [
        'type' => [
            'class_name' => '\\Bitrix\\Main\\Data\\CacheEngineFiles',
        ],
        'root_directory' => '/bitrix/cache/',
        'sid' => $_SERVER['DOCUMENT_ROOT'] . '#01',
    ],
],

В документации /bitrix/cache/ указан как каталог файлового кеша по умолчанию; с main 24.100.0 параметром root_directory можно задать другой каталог. Суффикс #01 — пример, а не обязательное значение: действующий sid проекта без причины не меняю.

Подготовленный файл проверяю тем бинарником PHP, который соответствует веб-пулу. Опция -l выполняет проверку синтаксиса без запуска файла:

php -l /home/bitrix/www/bitrix/.settings.php
php -l /home/bitrix/www/bitrix/.settings_extra.php

Если активная конфигурация лежит в /local/, в командах указываю её фактические пути. Проверка ловит пропущенную запятую или кавычку, но не подтверждает, что выбран правильный файл, существует класс обработчика и каталог доступен пользователю PHP.

После установки файла я проверяю права на каталог файлового кеша и наличие свободных ресурсов. Старые кеш-файлы очищаю только адресно, при остановленных писателях и после определения реального root_directory. Не удаляю вслепую весь /bitrix/cache/: в конкретной установке там могут находиться защитные и служебные файлы, которые следует сохранить. Если проект использует несколько веб-узлов, локальные файловые кеши каждого узла не становятся общими от одинакового sid.

Секции connections и session при этом не трогаю. Общий кеш и PHP-сессии настраиваются отдельно. По документации Bitrix Framework секция session поддерживает файловый обработчик, Redis, базу данных и Memcache; отсутствие секции означает файловое хранение по умолчанию. Поэтому переключение cache не переносит пользовательские сессии из Redis. Если следующий стек падает уже в сессионном обработчике, я разбираю его отдельно по документации сессий.

• Проверить `.settings.php` и `.settings_extra.php` как в `/local/`, так и в `/bitrix/`.
• Изменить только действующее значение `cache.value.type`.
• Сохранить параметры `sid` и `root_directory`, если они корректны.
• Проверить синтаксис нужной версией PHP и восстановить исходные права файла.
• Не смешивать настройку общего кеша с настройкой сессий.

Обновляю состояние PHP и завершаю штатное обновление

После изменения конфигурации я открываю административную страницу и одновременно слежу за свежими записями журнала веб-сервера и PHP. Если возвращается буквально прежнее исключение с прежней строкой, сначала перепроверяю путь к активному конфигу и состояние OPcache. При opcache.validate_timestamps=0 PHP не проверяет изменения файлов по времени на каждом запросе: для применения новой версии требуется адресная инвалидация, сброс OPcache или перезапуск обслуживающего процесса. Простая перезагрузка страницы браузера этого не обеспечивает.

Руководство PHP прямо указывает, что при отключённом opcache.validate_timestamps изменения файлов вступают в силу после opcache_reset(), opcache_invalidate() либо перезапуска веб-сервера. В архитектуре с отдельным PHP-FPM практически значим именно процесс FPM, который исполняет PHP. Перезапуск одного Nginx его разделяемую память не очищает. Подробности есть в настройках OPcache.

Имя службы не угадываю. В разных системах это может быть версионный unit, отдельный пул в контейнере или собственный сервис. Перед перезапуском устанавливаю, какой процесс обслуживает сайт, проверяю его конфигурацию и убеждаюсь, что обновлятор не выполняет запись. Вызов opcache_reset() из обычного CLI тоже не считаю доказательством: CLI и FPM обычно используют разные процессы и области памяти. Итоговая проверка — успешный запрос через настоящий веб-тракт.

Когда административная часть открылась, я авторизуюсь и перехожу в систему обновлений. Там смотрю журнал: какой пакет загружался, какие этапы завершены и где зафиксирована ошибка. Официальная справка подтверждает, что журнал содержит статусы и ошибки установки. Штатная страница описана в разделе «Система обновлений».

Далее продолжаю установку штатным механизмом и устанавливаю требуемые пакеты вместе с зависимостями. main 25.100.100 использую только как историческую контрольную точку исправления RedisCluster. Если доступна более новая совместимая цепочка, целевую версию выбираю по состоянию конкретной лицензированной установки и журналу обновлений. Включать бета-версии на работающем проекте ради аварийного восстановления не следует: документация системы обновлений отдельно предупреждает об их возможном негативном влиянии.

Файловый кеш оставляю активным до завершения всей согласованной цепочки. Возвращать Redis после первой открывшейся страницы рано: последующие пакеты ещё могут менять связанные классы и настройки. Если обновление снова останавливается, сохраняю новый стек и журнал, не затирая предыдущие свидетельства. Особенно внимательно проверяю случай, когда version.php уже содержит новую версию, но журнал сообщает об ошибке установочных действий.

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

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

Когда ручная правка ядра оправданна и почему частичный откат опасен

Я не называю любую ручную правку ядра безусловной катастрофой. Узкий временный патч может потребоваться, если конфигурационный обход не сработал, причина точно подтверждена, есть резервная копия и известна корректная декларация для установленной версии. Но это запасной путь. До него я доказываю, что файловый обработчик действительно выбран, а старый класс не создаётся напрямую пользовательским модулем, init.php или дополнительным конфигом.

Добавление RedisCluster в union type исправляет конкретную несовместимость объекта с декларацией свойства. Добавление null разрешает присваивание отсутствующего объекта. Это разные изменения. Во втором случае причина, по которой соединение или обработчик не были получены, может остаться и проявиться на следующем обращении. Именно поэтому совет «замените строку 13» без сравнения текущего файла, версии main и фактического TypeError я не использую.

Если временная правка всё-таки необходима, сохраняю оригинал, контрольную сумму, точный diff, время изменения и ссылку на основание. Не копирую целиком cacheengine.php из неизвестной установки и не переношу строку между разными выпусками main. После получения доступа запускаю штатное обновление, а затем сравниваю файл с поставкой производителя. Временный патч должен быть удалён официальным кодом, а не остаться незадокументированной частью проекта.

Производитель предупреждает, что самостоятельное изменение файла ядра или структуры базы может дать непредсказуемый результат при автоматическом обновлении. Там же ядром названы /bitrix/modules/ и системные компоненты, а /bitrix/updates/ выделен как каталог самой системы обновлений. Эти определения и требование резервной копии приведены в официальном уроке о системе обновлений.

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

С откатом правило ещё строже. Возврат старой папки /bitrix/ не отменяет запросы к базе и преобразования схемы, которые обновлятор уже успел выполнить. Надёжный откат восстанавливает согласованную точку файлов и БД, предварительно проверенную на отдельной площадке. Если после создания копии появились заказы, оплаты или изменения каталога, отдельно планирую их сохранение и повторное внесение. Даже двадцать минут потери данных для интернет-магазина могут быть существенными.

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

• Править ядро только после подтверждения точной причины и версии файла.
• Хранить оригинал, контрольную сумму и воспроизводимый diff временного патча.
• После обновления сверить файл с официальной поставкой и убрать временную правку.
• Для отката восстанавливать согласованную пару файлов и БД.
• Отдельно решить судьбу бизнес-данных, появившихся после резервной копии.

Разбор на стенде: торговый дом «Электрокомплект», 45 РМ

Для предметного разбора беру учебную реконструкцию: торговый дом «Электрокомплект», 45 РМ. Это модельный сценарий, а не отчёт о реальном клиентском инциденте и не обещание нормативного времени восстановления. Архивный стенд состоит из одной веб-ВМ с 4 vCPU, 8 ГБ RAM и диском 100 ГБ. На нём установлены PHP-FPM 8.2.28, расширение phpredis 6.1.0 и Redis 7.2.7. Исходная версия main — 25.100.0, историческая контрольная точка исправления — main 25.100.100.

Все названные версии реально выпускались. PHP 8.2.28 опубликован как security-релиз на php.net, phpredis 6.1.0 присутствует в официальных релизах расширения, а Redis 7.2.7 — в релизах Redis. Они нужны для воспроизводимости исторического упражнения, а не как рекомендация разворачивать новый рабочий проект на этих патч-релизах.

Лабораторный Redis Cluster состоит из трёх master-процессов на портах 7000–7002 одного хоста, без реплик. Официальная документация называет три master-узла минимальным работающим кластером, а для развёртывания рекомендует шесть узлов — три master и три replica. Поэтому стенд годится для проверки кластерного клиента, распределения слотов и ошибки типов, но не моделирует отказоустойчивую эксплуатацию. Требования и пример топологии опубликованы в руководстве Scale with Redis Cluster.

В исходных данных сценария сессии хранятся в файлах, каталог содержит 30 тысяч товаров, на диске свободно 35 ГБ. Эти числа описывают учебную нагрузку, а не системные требования Битрикса. Перед аварийным упражнением я проверяю, что кластер покрывает все 16 384 hash slot, но в самой статье не выдаю лабораторную топологию за пригодную для production. Один физический хост остаётся единой точкой отказа независимо от количества процессов.

Авария воспроизводится так: во время обновления запрос доходит до создания кеш-движка и завершается TypeError, связанным с декларацией CacheEngine::$engine и RedisCluster. Действующая секция cache определена в /bitrix/.settings_extra.php, а у веб-пула установлено opcache.validate_timestamps=0. Получаются две последовательные ловушки: изменение /bitrix/.settings.php не перекрывает фактическое значение из extra, а правильно изменённый extra продолжает исполняться из старого байткода, пока не обновлено состояние FPM.

Я сохраняю оба конфигурационных файла и метаданные, меняю cache.value.type в действующем /bitrix/.settings_extra.php на CacheEngineFiles, проверяю файл опцией php -l, восстанавливаю владельца и права, затем контролируемо перезапускаю именно тот PHP-FPM, который обслуживает сайт. Секции сессий и подключений к БД остаются неизменными. После этого проверяю новый запрос и убеждаюсь по стеку, что прежний Redis-обработчик больше не создаётся на раннем этапе.

Дальнейшая развязка модели такая: административная часть загружается с файловым кешем, штатный обновлятор продолжает цепочку и завершает установку пакета с исправлением. Файлы ядра вручную не меняются. Redis возвращаю только после завершённого журнала обновлений и очистки именно кеш-пространства проекта. Если определить принадлежность ключей нельзя, создаю на стенде проверенное отдельное пространство с согласованным sid, а не удаляю данные общего экземпляра.

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

• Одна веб-ВМ: 4 vCPU, 8 ГБ RAM, диск 100 ГБ.
• PHP-FPM 8.2.28, phpredis 6.1.0, Redis 7.2.7.
• Три master-процесса Redis Cluster на портах 7000–7002 без реплик.
• Каталог на 30 тысяч товаров, 35 ГБ свободного места.
• Приёмка: 5 авторизаций, 100 динамических запросов, изменение товара и тестовый обмен.

Возвращаю Redis без устаревших данных и повторного простоя

Пока приложение работало с файловым кешем, прежние записи Redis могли не получать инвалидацию. Поэтому простое возвращение старого конфига способно снова показать устаревшие цены, остатки или настройки. Я оставляю ограничение трафика, восстанавливаю проверенную конфигурацию Redis и адресно очищаю кеш-пространство проекта до открытия сайта. Альтернативный путь — заранее протестированное новое пространство, согласованное через одинаковый sid на всех веб-узлах.

Параметр sid предназначен для уникальной идентификации кеша сайта. Официальный пример формирует его из $_SERVER['DOCUMENT_ROOT'] и уникального суффикса; при изменении формата документация предписывает очистить старый кеш, поскольку система больше не сможет его использовать. Поэтому sid нельзя менять на одном узле или генерировать случайно при каждом запросе. Его назначение и примеры описаны в документации кеширования Bitrix Framework.

Команду FLUSHALL для обычного возврата проекта я не использую. Она удаляет все ключи из всех баз экземпляра Redis, а её синтаксис имеет вид FLUSHALL [ASYNC | SYNC]. В общем экземпляре под удаление могут попасть сессии, очереди и данные других приложений. Команда также помечена как опасная в ACL-категориях Redis. Точное поведение приведено в официальном описании FLUSHALL.

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

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

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

Приёмку начинаю с динамических страниц, чтобы готовый HTML не скрыл ошибку. Проверяю вход в админку, сохранение настроек, карточку товара, корзину, оформление тестового заказа, обмен и фоновые задания. Данные специально изменяю и убеждаюсь, что новое значение появляется у пользователя. Одновременно слежу за журналами PHP, веб-сервера, Redis, нагрузкой на БД и задержками диска.

После аварии обновляю эксплуатационную инструкцию: где лежат активные .settings.php и .settings_extra.php, какой PHP-пул обслуживает сайт, как временно включается файловый кеш, кто останавливает обмены и по каким критериям принимается восстановление. Отдельным окном планирую обновление окружения. Ветка PHP 8.2 получает только критические исправления безопасности до 31 декабря 2026 года, после чего достигает конца поддержки; актуальные сроки опубликованы на странице Supported PHP Versions. Наличие поддержки ветки до этой даты не делает старый PHP 8.2.28 актуальным патч-релизом.

Авария считается завершённой, когда журнал обновлений не содержит незавершённых действий, бизнес-операции работают, фоновые процессы возвращены под наблюдением, а итоговая конфигурация записана в документацию. Один ответ HTTP 200 этого не доказывает: его может отдать статическая заглушка, прокси или старый кеш.

• Проверить авторизацию, сохранение настроек и отсутствие новых CacheEngine TypeError.
• Проверить динамические страницы, чтобы HTML-кеш не скрыл сбой.
• Изменить тестовые данные и подтвердить отображение нового результата.
• Возобновлять обмены, задания и веб-узлы поэтапно, наблюдая за ошибками и нагрузкой.
• Зафиксировать итоговые версии, конфигурацию и удалить только подтверждённые временные изменения.
• Запланировать переход с PHP 8.2 до окончания security-поддержки 31 декабря 2026 года.

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