Агенты и очереди в Битрикс: типичные ошибки и решения

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

Сначала разделите агента и очередь

Агент — механизм периодического запуска PHP-функции в 1С-Битрикс: Управление сайтом. Очередь — способ хранить задания, которые нужно обработать позже, например отправить уведомления или пересчитать данные. Агент может забирать задания из очереди, но сам по себе очередью не становится.

Рекомендации ниже относятся к типовой установке 1С-Битрикс: Управление сайтом, включая ветки 24.x и 25.x. Точные названия пунктов административного интерфейса и поведение настроек зависят от редакции и конфигурации. Перед изменением расписания сверяйтесь с документацией именно вашей версии.

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

Четыре ошибки, которые ломают обработку

1. Долгую работу запускают на хите

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

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

2. Агент обрабатывает всю очередь за один запуск

Сотни или тысячи записей в одном вызове — риск упереться в лимит времени PHP и оборвать обработку посередине. Разбивайте работу на небольшие порции. Один запуск выбирает ограниченное число доступных заданий, обрабатывает их и завершается; следующий продолжает очередь.

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

3. Повторный запуск создаёт дубликаты

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

Сделайте обработчик идемпотентным¹: повторная обработка того же задания не должна повторно создавать заказ, списывать деньги или отправлять дублирующее уведомление. Используйте устойчивый идентификатор задания и фиксируйте результат обработки. Для внешнего API проверьте, поддерживает ли он ключ идемпотентности; не выдумывайте его формат — смотрите документацию конкретного сервиса.

4. Ошибка превращает задание в бесконечный цикл

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

Храните число попыток, время последней ошибки и понятное описание причины. После установленного числа неудач переводите запись в отдельное состояние для разбора, а не гоняйте её без конца. Конкретный предел выбирайте с учётом стоимости операции и доступности сервиса.

Сравнение подходов к очереди

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

Очередь надёжна не потому, что задания лежат в таблице. Надёжность появляется, когда повтор безопасен, ошибка видна, а незавершённая работа не исчезает молча.

Что проверять после изменения

1. Режим запуска. Убедитесь, что выбран один согласованный способ выполнения — по cron или на хитах. Проверьте расписание и владельца процесса на сервере.
2. Длительность. Замерьте время одного запуска и время обработки порции. Если выполнение подходит к лимиту PHP или хостинга, уменьшите порцию либо вынесите обработку отдельно.
3. Параллельность. Запустите проверку при возможном одновременном старте двух процессов. Одно задание не должно обрабатываться конкурентно без защиты от захвата двумя исполнителями.
4. Повтор после сбоя. Прервите тестовую обработку в безопасной среде и проверьте, что повтор не создаёт дубль, а задание не теряется.
5. Наблюдаемость. Убедитесь, что видны число ожидающих заданий, возраст самого старого задания, ошибки и количество попыток. Растущая очередь — повод искать причину, даже если сам агент формально запускается.

Где подход ломается

Таблица в базе Битрикс не заменяет брокер сообщений, если обработку нужно масштабировать на много независимых исполнителей. И наоборот: подключать отдельную очередь ради нескольких коротких задач часто дороже, чем поддерживать. Граница проходит по требованиям к объёму, времени реакции, повторной доставке и восстановлению после отказа.

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

¹ Идемпотентность — свойство операции, при котором повтор одного и того же запроса не приводит к повторному побочному эффекту.

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

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