Агенты и очереди в Битрикс: чек-лист перед продакшеном

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

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

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

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

* Агент — запланированный вызов функции ядром Битрикс. В зависимости от конфигурации агенты запускаются на хитах сайта или через cron. Хит — обычный запрос к сайту, например открытие страницы посетителем.

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

Выберите способ запуска и зафиксируйте его

У Битрикс есть два распространённых варианта запуска агентов. Режим «на хитах» проще включить, но выполнение зависит от трафика и добавляет работу к запросам. Запуск через cron даёт предсказуемое расписание, но требует настроить системное задание и проверить, что веб-запросы не запускают ту же работу параллельно. Настройки и порядок переключения зависят от версии ядра и конфигурации проекта — не переносите инструкцию с другого сайта без проверки.

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

Чек-лист перед выпуском

1. Запишите версии. Зафиксируйте версию продукта, ядра и PHP на тестовом и рабочем окружениях. Уточните, какой именно режим запуска агентов действует в этой конфигурации. Проверка: команда и расписание запуска отражены в инструкции по развёртыванию.
2. Ограничьте одну порцию. Обработчик не должен выбирать всю накопившуюся очередь за один проход. Задайте конечный размер порции и верхнюю границу времени работы. Проверка: при тестовом запуске обработчик оставляет остальные задачи на следующий проход, а веб-запрос не ждёт всю очередь.
3. Определите состояния задачи. Минимум нужны состояния «ожидает», «в работе», «выполнена» и «ошибка», а также время последней попытки и число попыток. Проверка: по одной записи в хранилище можно понять, что с ней случилось и когда её брали в работу.
4. Защититесь от дублей. Один и тот же элемент могут выбрать два обработчика либо повторно обработать после сбоя. Используйте атомарный захват на уровне хранилища и делайте бизнес-действие идемпотентным^*: повторный вызов не должен дважды списать деньги, создать заказ или отправить уведомление. Проверка: два параллельных тестовых запуска не обрабатывают одну задачу одновременно.
5. Разберите сбой между действием и отметкой. Процесс может завершиться после внешнего вызова, но до записи статуса «выполнена». Проверка: повторная обработка такого задания не создаёт дублирующий побочный эффект; если это невозможно, предусмотрена сверка с внешней системой.
6. Задайте правила повторов. Временная ошибка сети не должна навсегда потерять задачу, а постоянная ошибка не должна гонять её бесконечно. Ограничьте число попыток, храните последнюю ошибку и предусмотрите ручной разбор задач, исчерпавших лимит. Проверка: искусственная ошибка приводит к повтору по заданному правилу, а не к циклу без конца.
7. Проверьте таймауты и нагрузку. Учитывайте ограничения PHP, веб-сервера и внешнего API. Проверка: порция заканчивается до лимита выполнения; обработчик не держит блокировку во время долгого сетевого ожидания.
8. Добавьте наблюдаемость. Считайте длину очереди, возраст самой старой задачи, число ошибок, длительность обработки и число повторов. Проверка: тестовая просроченная задача видна в журнале или панели мониторинга, а ответственный знает, где её искать.

* Идемпотентность — свойство операции, при котором повторное выполнение с теми же данными не создаёт повторного эффекта. Например, повторная попытка не должна создавать второй одинаковый заказ.

Что чаще всего ломается в продакшене

Долгая работа выполняется на хите

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

Одну задачу берут два раза

Простая проверка «статус ещё ожидает» не защищает от гонки: два процесса могут увидеть один статус одновременно. Захват должен быть атомарным. Если используете базу данных, выбирайте подход с учётом её движка, схемы и транзакций — универсальный SQL-фрагмент без этих деталей может дать ложное чувство защиты.

Задачи копятся быстрее, чем обрабатываются

Частый запуск не помогает, если средняя скорость поступления задач выше скорости обработки. Сравнивайте прирост очереди и пропускную способность на реальной нагрузке; смотрите не только на среднее время, но и на самый старый элемент. При росте хвоста уменьшите объём работы на задачу, оптимизируйте внешние вызовы или увеличьте число обработчиков, предварительно проверив защиту от дублей.

Ошибки неотличимы от медленной работы

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

Когда оставлять агент, а когда выносить очередь

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

Инвалидация кеша и проектирование конкретного брокера — отдельные темы; здесь речь только о надёжности фоновой обработки.

Что проверить дальше

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