Агенты 1С-Битрикс на cron: как настроить и проверить

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

На практике фоновые задачи лучше выносить на cron. Так выполнение становится предсказуемее, а пользовательские запросы не ждут служебную работу.

Что обычно выполняют агенты

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

SELECT ID, NAME, ACTIVE, NEXT_EXEC, LAST_EXEC
FROM b_agent
ORDER BY NEXT_EXEC ASC;

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

Проверка вручную

Перед настройкой cron полезно запустить проверку агентов вручную из консоли. Обычно используется файл check_agents.php.

cd /var/www/site.ru
php -f bitrix/modules/main/tools/check_agents.php

Если команда падает вручную, cron тоже не поможет. Нужно смотреть ошибку PHP, права, версию PHP и подключение к базе.

Версия PHP

Сайт может работать на одной версии PHP, а консоль использовать другую. Для Битрикс это частая причина странных ошибок: в вебе всё нормально, а cron падает.

php -v
which php

В crontab лучше указывать полный путь к нужному PHP:

* * * * * cd /var/www/site.ru && /usr/bin/php8.2 -f bitrix/modules/main/tools/check_agents.php >> bitrix/php_interface/cron_agents.log 2>&1

Путь к PHP зависит от сервера. На хостингах он может называться php82 или лежать в нестандартной директории.

Отключить запуск агентов на хитах

После переноса на cron обычно отключают запуск агентов на пользовательских хитах. В dbconn.php или другом конфиге проекта может использоваться константа:

define('BX_CRONTAB_SUPPORT', true);

Для запуска cron-задачи также часто указывают:

define('BX_CRONTAB', true);

Настройка зависит от версии проекта и окружения. После изменения нужно проверить, что агенты действительно выполняются через cron, а не перестали выполняться вообще.

Логирование cron

Без логов cron превращается в догадки. В команду нужно добавить вывод stdout и stderr в файл.

* * * * * cd /var/www/site.ru && /usr/bin/php -f bitrix/modules/main/tools/check_agents.php >> local/logs/agents.log 2>&1

Директория для логов должна существовать и быть доступна на запись пользователю cron.

mkdir -p local/logs
touch local/logs/agents.log
ls -la local/logs

Права и пользователь

Если cron запускается от другого пользователя, могут появиться ошибки записи в cache, upload, tmp или логи. Нужно проверить владельца файлов и права на рабочие директории.

whoami
ls -la bitrix/cache
ls -la bitrix/managed_cache
ls -la upload

Не стоит решать проблему правами 777 на весь проект. Лучше настроить владельца и группы под веб-сервер и пользователя cron.

Зависшие агенты

Если агент выполняется слишком долго или падает, он может мешать очереди задач. Нужно смотреть LAST_EXEC, NEXT_EXEC и логи. Для тяжёлых задач полезно добавлять собственное логирование.

\Bitrix\Main\Diag\Debug::writeToFile(
    ['message' => 'agent started'],
    'agent',
    '/local/logs/custom_agent.log'
);

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

Чек-лист настройки

1. Посмотреть список активных агентов в b_agent.
2. Запустить check_agents.php вручную.
3. Проверить версию PHP в консоли.
4. Добавить cron с полным путём к PHP.
5. Настроить логирование вывода cron.
6. Проверить права на cache, managed_cache, upload и logs.
7. Отключить запуск агентов на хитах только после проверки cron.
8. Проверить выполнение задач через несколько минут.

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