Агенты и cron в Битрикс: как не пропустить фоновую задачу

Редакция Romanov Lab · Опубликовано 13 октября 2026

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

Агент, cron и работа после ответа решают разные задачи

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

Cron устраняет зависимость запуска от посетителей, но не гарантирует успешное выполнение бизнес-операции. Сервер может быть недоступен, PHP завершиться с ошибкой, а внешний получатель отклонить данные. Поэтому обещание «перенесём на cron, и всё будет надёжно» неполно: необходимы проверка результата и план повторной обработки.

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

Проведите инвентаризацию перед изменением расписания

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

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

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

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

Выберите поведение после простоя

У периодического агента плановая дата сдвигается на заданный интервал; после задержки он может отрабатывать пропущенные запуски. Непериодический режим не предназначен для воспроизведения всех пропущенных плановых интервалов. Параметр period и расчёт следующего запуска описаны в справочнике CAgent::AddAgent. Название «точно в указанное время» не отменяет ограничений реального окружения.

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

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

Учебный разбор: выгрузка перестала обновляться ночью

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

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

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

Проверьте командное окружение

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

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

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

Длинную работу делите на проверяемые части

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

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

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

Наблюдение за результатом и приёмка

Храните минимум четыре события: запланировано, начато, завершено, результат опубликован или принят. Добавьте обработанный объём и причину ошибки без чувствительных данных. Возраст последнего успешного результата часто полезнее зелёного статуса расписания.

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

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