Агенты в Битрикс: чек-лист, который убережёт от тихих сбоев

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

Материал написан для «1С-Битрикс: Управление сайтом» с главным модулем main 23.x и новее и PHP 8.x. Версию main смотрите в админке, в разделе обновлений. Названия опций в интерфейсе могут отличаться, поэтому сверяйтесь с документацией своей версии. Очереди, обмен с 1С и роботы Битрикс24 здесь не разбираются, речь только о классических агентах (класс CAgent).

Хиты или cron: первое решение

От режима запуска зависит всё остальное. Агенты на хитах работают как псевдокрон, а cron запускает их из консоли по расписанию.

Пояснение к термину. Псевдокрон — это имитация планировщика: вместо системного cron движок проверяет список задач при обработке обычных запросов посетителей и выполняет те, чей срок наступил.

Цена первого варианта в том, что работа агента попадает в чужой запрос. Цена второго в том, что у вас появляется ещё одна точка отказа, о которой надо помнить.

Чек-лист: восемь проверок до включения агента

1. Функция возвращает строку собственного вызова. Например, 'RecalcPricesAgent();', обязательно с точкой с запятой. Если вернуть пустое значение или забыть return, Битрикс решит, что агент отработал своё, и удалит его. Это самая частая причина жалобы «агент выполнился один раз и пропал».
2. Исключения пойманы, а return стоит после блока catch. Необработанная ошибка может оставить агента в состоянии «выполняется», и следующих запусков не будет. Как это выглядит у вас, проверьте в списке агентов в админке на своей версии.
3. За запуск делается одна порция работы. Весь объём за раз на хитах упрётся в max_execution_time веб-PHP. В CLI лимита обычно нет, но тот же агент в хитовом режиме оборвётся посреди работы.
4. Период и интервал выбраны осознанно. При периоде N интервал отсчитывается от завершения запуска, при Y расписание привязано к плановому времени. Точные правила для вашей версии смотрите в описании CAgent::AddAgent в документации.
5. Агент не опирается на контекст запроса. В cron нет текущего пользователя и HTTP-хоста, а на многосайтовой установке может быть не определён SITE_ID. Адреса берите из настроек сайта или модуля.
6. Нужные модули подключены внутри функции. Для iblock, catalog и sale вызывайте Loader::includeModule и проверяйте результат.
7. Ошибки пишутся в лог. AddMessage2Log сохраняет сообщения только при заданной константе LOG_FILENAME. Файл держите вне корня сайта, иначе лог можно открыть по прямой ссылке.
8. Агент регистрируется один раз. AddAgent не место в init.php: он вызовется на каждом хите. Регистрируйте при установке модуля или разовым скриптом, а потом убедитесь, что в списке одна запись.

Как выглядит агент, который проходит чек-лист

Ниже схематичный шаблон: RecalcPricesBatch — ваша функция, которая обрабатывает ограниченную порцию данных. Код лежит в init.php проекта (в /local/php_interface/ или /bitrix/php_interface/, смотря что используется у вас).

<?php
// Битрикс main 23.x+, PHP 8.x
function RecalcPricesAgent()
{
    try {
        if (!\Bitrix\Main\Loader::includeModule('catalog')) {
            AddMessage2Log('Модуль catalog недоступен', 'RecalcPricesAgent');
            return 'RecalcPricesAgent();';
        }

        // Схематично: ваша функция, не больше 200 товаров за запуск
        RecalcPricesBatch(200);
    } catch (\Throwable $e) {
        AddMessage2Log($e->getMessage(), 'RecalcPricesAgent');
    }

    // Строка собственного вызова обязательна: пустой ответ удалит агента
    return 'RecalcPricesAgent();';
}

Регистрация выполняется один раз, отдельным скриптом или при установке модуля:

<?php
CAgent::AddAgent(
    'RecalcPricesAgent();', // строка вызова
    '',                     // модуль не указан: функция лежит в init.php
    'N',                    // интервал считается от завершения запуска
    3600                    // интервал в секундах
);

Агент, который не умеет сообщить об ошибке, ломается молча. О сбое вы узнаете по жалобам пользователей, а не по логам.

Перенос агентов на cron

Добавьте в /bitrix/php_interface/dbconn.php две строки. Первая переводит запуск агентов на cron, вторая включает файл лога:

define('BX_CRONTAB_SUPPORT', true);
define('LOG_FILENAME', '/var/log/bitrix/agents.log'); // каталог создайте заранее, дайте права пользователю PHP

Затем добавьте задачу в crontab пользователя, от которого работает веб-сервер. Пути ниже заглушки, подставьте свои:

* * * * * /usr/bin/php -f /var/www/example.ru/bitrix/modules/main/tools/cron_events.php

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

• Запустите команду из crontab вручную под тем же пользователем и убедитесь, что она завершается без ошибок.
• Проверьте версию php-CLI командой php -v. Она должна совпадать с версией, под которой работает сайт.
• У CLI свой php.ini. Расширения и memory_limit там могут отличаться от настроек php-fpm.

Что ломается

• Cron не работает, а хиты отключены. Агенты останавливаются все разом. Признак: у всех активных агентов дата «Следующий запуск» в прошлом.
• Cron запущен от root. Файлы кеша и загрузок, созданные в таком запуске, принадлежат root, и сайт потом не может их перезаписать.
• CLI и веб на разных версиях PHP. Агент работает в браузерной проверке и падает в cron из-за недостающего расширения или другой версии.
• Дубли агентов. Причина обычно в повторной установке модуля или в AddAgent, вызванном на каждом хите. Каждый дубль запускает ту же работу ещё раз.
• Тяжёлый агент на хитах. Случайный посетитель получает страницу с задержкой, равной времени работы агента.
• Кластер. Cron, включённый на каждом узле, может запускать одни и те же агенты несколько раз. Включайте его на одном узле, если документация вашей схемы не говорит иного.

Когда что выбирать

• Хиты: у сайта стабильный трафик, агенты отрабатывают за секунды, точность в пределах минут не важна, или доступа к cron просто нет.
• Агенты + cron: стандарт для прода. Выбирайте его для рассылок, выгрузок, пересчётов и всего, что должно идти по расписанию.
• Свой скрипт: задача регулярно длится дольше минуты (это минимальный шаг cron) или нужна собственная блокировка от параллельных запусков.

Что делать дальше

Добавьте в каждый агент две записи в лог: начало и конец работы. По ним видно реальную длительность запуска. Затем раз в день сравнивайте «Следующий запуск» в списке агентов с текущим временем. Если отставание у активного агента больше интервала cron, значит, где-то остановилась очередь, и пора смотреть crontab и состояние агента. Параметры CAgent::AddAgent и настройку cron сверьте с документацией разработчика для вашей версии.