Cron и очереди в Yii2: что проверять при поддержке сайта

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

Что обычно живёт в cron

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

crontab -l

Хороший cron понятен без расшифровки. В нём указан полный путь к PHP, полный путь к проекту и желательно логирование вывода.

* * * * * cd /var/www/site.ru && /usr/bin/php yii queue/run >> runtime/logs/cron.log 2>&1
0 3 * * * cd /var/www/site.ru && /usr/bin/php yii sitemap/generate >> runtime/logs/sitemap.log 2>&1

Если команда записана без полного пути, она может работать в консоли и не работать из cron. У cron другое окружение, другой PATH и иногда другая версия PHP.

Проверить версию PHP

На сервере может быть несколько версий PHP. Сайт работает на PHP 8.2, а cron запускает системный PHP 7.4. После обновления кода это легко превращается в ошибку.

php -v
/usr/bin/php -v
which php

В cron лучше указывать конкретный бинарник, который подходит проекту. На хостингах это может быть php82, php8.2 или путь из панели управления.

Очередь Yii2

Если используется yii2-queue, нужно понять, какой драйвер подключён: database, redis, file или другой. Команды проверки зависят от настройки, но общий подход одинаковый: посмотреть количество задач, ошибки и работающий воркер.

php yii queue/info
php yii queue/listen

Для разового запуска можно использовать:

php yii queue/run

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

sudo systemctl status yii-queue.service
sudo systemctl restart yii-queue.service

Зависшие процессы

Иногда задача не падает, а висит. Например, ждёт внешний API без таймаута или обрабатывает слишком большой пакет данных. Тогда новые задания копятся, а визуально кажется, что очередь просто “молчит”.

ps aux | grep yii
ps aux | grep queue

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

$mutex = Yii::$app->mutex;

if (!$mutex->acquire('import-products', 0)) {
    return;
}

try {
    // выполнение импорта
} finally {
    $mutex->release('import-products');
}

Логи фоновых команд

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

tail -n 100 runtime/logs/cron.log
tail -n 100 runtime/logs/app.log

В Yii2 можно писать в отдельную категорию:

Yii::info('Начат импорт товаров', 'import');
Yii::error($e->getMessage(), 'import');

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

Таймауты и размеры пакетов

Фоновые задачи часто ломаются не из-за логики, а из-за размера данных. Команда работала на тысяче записей, но начала падать на ста тысячах. В таких случаях лучше обрабатывать данные пакетами.

$query = Product::find()->where(['status' => 'A']);

foreach ($query->batch(500) as $products) {
    foreach ($products as $product) {
        // обработка товара
    }
}

Для внешних API обязательно нужны таймауты. Запрос без таймаута может подвесить воркер надолго.

Что проверить при поддержке

1. Есть ли запись команды в crontab.
2. Запускается ли команда вручную из директории проекта.
3. Совпадает ли версия PHP в cron и на сайте.
4. Пишется ли лог выполнения.
5. Нет ли зависших процессов.
6. Не копятся ли задачи в очереди.
7. Перезапущен ли воркер после деплоя.
8. Есть ли защита от параллельного запуска тяжёлых команд.

После исправления

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

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