WooCommerce: разбор зависших задач Action Scheduler через WP-CLI

Action Scheduler — очередь фоновых операций, используемая WooCommerce и другими плагинами WordPress. Через неё выполняются действия, которые не следует запускать в рамках обычного запроса к сайту: обработка вебхуков, уведомления, обновление данных, задачи подписок и интеграций.

Если задачи долго остаются в статусе pending или переходят в failed, не удаляйте таблицы очереди, не меняйте статусы массово через SQL и не запускайте все задания без ограничений. Сначала определите проблемный hook, изучите журнал выполнения, устраните причину и только затем обработайте очередь контролируемыми пакетами.

Ниже приведён порядок диагностики через Scheduled Actions и WP-CLI, пробного запуска отдельных заданий, пакетной обработки очереди и очистки старой истории. Общая настройка WP-Cron и оптимизация WooCommerce в этой инструкции не рассматриваются.

Как понять, что очередь действительно зависла

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

Основные статусы Action Scheduler:

• pending — действие ожидает времени запуска или доступного обработчика очереди;
• in-progress — задание получено обработчиком и выполняется;
• complete — callback завершился без зарегистрированной ошибки;
• failed — выполнение завершилось ошибкой или было признано неуспешным;
• canceled — действие отменено и больше не должно запускаться.

Action Scheduler фиксирует создание, запуск, завершение и ошибки задач в собственном журнале. В нём также виден способ запуска, например WP-Cron или WP-CLI. Поэтому журнал конкретной задачи — основная точка диагностики, а не просто архив старых сообщений.

Отдельно оцените старые записи in-progress. Несколько недавно начатых задач в таком статусе нормальны. Давние записи могут говорить о прерванном PHP-процессе, долгом callback или оставшемся claim. Не редактируйте идентификаторы блокировок в базе вручную: Action Scheduler сам освобождает просроченные claims, а прямое вмешательство может нарушить обработку очереди.

Что подготовить перед работой

Для команд нужен WP-CLI в окружении сайта. На VPS их обычно выполняют по SSH из каталога WordPress. На виртуальном хостинге используйте SSH-доступ или терминал панели, если провайдер их предоставляет. Root-доступ для команд Action Scheduler не требуется.

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

При наличии WP-CLI резервную копию базы можно создать штатной командой WordPress:

wp db export before-action-scheduler-work.sql

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

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

Проверка окружения WP-CLI

Перейдите в каталог установки WordPress и убедитесь, что WP-CLI загрузил нужный сайт:

cd /path/to/wordpress
wp core is-installed
wp plugin is-active woocommerce

Путь /path/to/wordpress приведён как пример. На виртуальном хостинге он зависит от структуры аккаунта, домена и панели управления. Если команду нужно запускать из другого каталога, передайте путь явно:

wp --path=/path/to/wordpress core is-installed

Для multisite или окружения, где адрес сайта нельзя определить однозначно, может потребоваться параметр --url:

wp --path=/path/to/wordpress --url=https://shop.example.com action-scheduler status

Запускайте WP-CLI от системного пользователя, которому принадлежат файлы сайта или который используется для обслуживания WordPress. Не применяйте sudo без необходимости: файлы кэша и временные данные, созданные другим владельцем, впоследствии могут вызвать проблемы с правами.

Проверьте, что пространство команд доступно:

wp action-scheduler
wp action-scheduler --help

Если WP-CLI сообщает, что команда не зарегистрирована, убедитесь, что WooCommerce и плагин, содержащий Action Scheduler, активны для выбранного сайта. Проверьте также, не запускается ли WordPress с параметрами --skip-plugins или --skip-themes. Полное отключение плагинов может убрать и CLI-команду, и callbacks, нужные заданиям.

Набор подкоманд и параметров зависит от установленной версии Action Scheduler. Перед использованием примеров проверьте локальную справку:

wp help action-scheduler
wp help action-scheduler run
wp help action-scheduler action list
wp help action-scheduler clean

Action Scheduler предусматривает команды run, clean, status, а также операции просмотра и запуска отдельных actions. Локальная справка WP-CLI точнее всего отражает возможности версии, установленной на конкретном сайте.

Диагностика через Scheduled Actions

Начните с интерфейса WordPress. Экран очереди обычно доступен по пути «WooCommerce → Статус → Запланированные действия». В части конфигураций он находится в разделе «Инструменты → Запланированные действия».

На экране можно отфильтровать actions по статусу, найти hook, увидеть группу, назначенное время и журнал отдельного задания. Интерфейс позволяет вручную запустить pending action, что удобно для единичной проверки, но не подходит для большой очереди.

1. Откройте вкладку Pending и отсортируйте задания по дате.
2. Отделите просроченные actions от задач, назначенных на будущее.
3. Запишите hooks, которые формируют основную часть очереди.
4. Проверьте группы: они часто помогают связать action с плагином или подсистемой.
5. Откройте несколько старых pending actions и изучите их журналы.
6. Перейдите на вкладку Failed и найдите задания с теми же hooks.
7. Сравните текст ошибок, аргументы и время появления.

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

Что искать в журнале задачи

Читайте журнал от первой записи к последней. Он показывает создание action, попытки запуска и конечный результат. Для failed action особенно важна последняя ошибка, но предшествующие события помогают понять, повторялась ли проблема и каким runner выполнялась задача.

• Call to undefined function или Class not found — код, добавивший callback, не загрузился либо был удалён;
• no callbacks are registered — для hook отсутствует обработчик, что часто происходит после отключения или удаления плагина;
• PHP Fatal error, TypeError или необработанное исключение — ошибка кода или несовместимые данные;
• ошибка HTTP, авторизации или лимита внешнего API — повторять выполнение до восстановления интеграции бессмысленно;
• ошибка базы, блокировка или обрыв соединения — сначала проверьте состояние базы и конкурирующие процессы;
• превышение памяти или времени выполнения — запускайте меньшие пакеты, но дополнительно оцените ресурсоёмкость одного action.

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

Просмотр очереди через WP-CLI

Сначала получите сводку о состоянии очереди:

wp action-scheduler status

Команда позволяет оценить хранилище и очередь без запуска действий. Затем запросите pending и failed actions. Поддерживаемые поля фильтрации уточняйте через wp help action-scheduler action list. В версиях с соответствующими параметрами команды выглядят так:

wp action-scheduler action list --status=pending --per-page=50 --format=table
wp action-scheduler action list --status=failed --per-page=50 --format=table

Для дальнейшей работы нужны как минимум ID, hook, статус, группа и назначенная дата. Если табличный вывод неудобен, сохраните результаты в CSV:

wp action-scheduler action list --status=failed --per-page=200 --format=csv > failed-actions.csv

Создайте этот файл до очистки failed actions: после удаления журнал конкретной задачи нельзя будет использовать для диагностики.

Чтобы получить сведения об одной операции, используйте её ID:

wp action-scheduler action get 12345
wp action-scheduler action get 12345 --format=json

Замените 12345 реальным идентификатором. Передавайте ID только числом и не подставляйте непроверенные значения из пользовательского ввода.

Как связать hook с источником

Название hook — главный ориентир, но не всегда достаточный. Посмотрите группу и аргументы action, затем проверьте, какой активный плагин регистрирует соответствующий callback. Если hook относится к удалённому расширению, запускать его обычно бессмысленно: обработчика больше нет.

Не удаляйте задания только потому, что название hook незнакомо. Сначала найдите источник в коде сайта или документации плагина. При SSH-доступе можно выполнить текстовый поиск по каталогу плагинов:

grep -R "problem_hook_name" wp-content/plugins/

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

Почему не стоит начинать с массового запуска

Команда wp action-scheduler run обрабатывает готовые к запуску pending actions. Если очередь накопилась из-за ограничений веб-запросов, WP-CLI может разобрать её быстрее: CLI-процесс обычно не связан теми же лимитами, что HTTP-запрос. Поэтому этот способ подходит для крупных и долгих очередей.

Но WP-CLI не исправляет ошибочный callback. Если первая задача стабильно вызывает исключение, массовый запуск создаст новые failed actions, повторные внешние запросы и дополнительную нагрузку. До запуска необходимо:

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

Если причина накопления связана с нерегулярным запуском WP-Cron, не ограничивайтесь ручным разбором очереди. После устранения инцидента проверьте, как запускаются фоновые задания сайта. Практические различия WP-Cron и системного планировщика разобраны в статье о настройке wp-cron и real cron в WordPress.

Безопасный пакетный запуск pending actions

Для первой проверки запустите один небольшой пакет:

wp action-scheduler run --batch-size=10 --batches=1

Параметр --batch-size=10 ограничивает число actions в пакете, а --batches=1 — количество пакетов в одной команде. Такой запуск нужен не для быстрого опустошения очереди, а для оценки времени, памяти, ошибок и влияния на сайт.

Сразу после выполнения проверьте состояние:

wp action-scheduler status
wp action-scheduler action list --status=failed --per-page=20 --format=table

Также обновите Scheduled Actions и убедитесь, что обработанные actions получили ожидаемый статус. Проверяйте не только очередь, но и результат: появился ли вебхук у получателя, обновился ли заказ, отправилось ли письмо, завершился ли импорт.

Если пробный пакет прошёл нормально, увеличивайте нагрузку постепенно:

wp action-scheduler run --batch-size=25 --batches=1
wp action-scheduler run --batch-size=50 --batches=2

Эти числа — примеры поэтапного теста, а не универсальные параметры производительности. Один action может выполняться мгновенно, другой — обращаться к медленному API или выполнять тяжёлый запрос. Подбирайте пакет по фактическому времени работы и доступным ресурсам.

Не применяйте сразу --batches=0 к неизвестной очереди. Нулевое значение означает продолжение обработки, пока не останется подходящих actions. На большой очереди это создаёт длительный процесс и неконтролируемую нагрузку. Режим допустим только после успешных ограниченных запусков и при наблюдении за сайтом.

Запуск по hook или группе

Когда причина установлена и нужно обработать определённый тип действий, ограничьте очередь по hook:

wp action-scheduler run --hooks=example_hook_name --batch-size=20 --batches=1

Либо по группе:

wp action-scheduler run --group=example-group --batch-size=20 --batches=1

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

Фильтры --hooks и --group используйте только после проверки зависимостей между actions. Если требуется исключить известную тяжёлую группу, сначала проверьте синтаксис в локальной справке:

wp help action-scheduler run

Если установленная версия поддерживает параметр --exclude-groups, передавайте ему реальные slug групп. Не объединяйте --group и --exclude-groups: при выборе конкретной группы исключения игнорируются.

Когда опасен параметр --force

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

Не добавляйте --force, пока не убедитесь, что другой runner действительно не работает. Одновременные обработчики могут конкурировать за таблицы базы, обращаться к одному API или выполнять однотипные операции над заказами. На виртуальном хостинге принудительная конкуренция особенно часто упирается в лимиты CPU, памяти и числа процессов.

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

Как работать с failed actions

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

1. Откройте журнал action.
2. Установите и устраните причину ошибки.
3. Проверьте фактический результат предыдущей попытки.
4. Выберите одно тестовое задание.
5. Запустите его отдельно, если повторение операции безопасно.
6. Проверьте новый статус, журнал и прикладной результат.
7. Только после этого принимайте решение по остальным actions.

Для отдельного action предусмотрена команда запуска по ID:

wp action-scheduler action run 12345

Перед выполнением откройте справку установленной версии:

wp help action-scheduler action run

Поведение зависит от статуса action и версии библиотеки. Если команда не разрешает повторный запуск failed action, используйте штатный механизм повтора конкретного плагина или действие в административном интерфейсе, если оно доступно. Не переводите failed-записи в pending прямым SQL-запросом: это обходит прикладные проверки и может повторно запустить необратимые операции.

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

Очистка очереди командой clean

Очистка нужна для удаления старых завершённых записей и уменьшения объёма накопленной истории. Это не способ исправить pending-очередь, а удаление failed actions не устраняет причину их появления.

По умолчанию action-scheduler clean работает с завершёнными и отменёнными actions старше установленного периода. Точные значения для вашей версии уточняйте через справку. Стандартный порог составляет 31 день для статусов canceled и complete.

Для контролируемой очистки задайте параметры явно:

wp action-scheduler clean --status=complete,canceled --before='31 days ago' --batch-size=20 --batches=5 --pause=1

• --status=complete,canceled ограничивает удаление завершёнными и отменёнными actions;
• --before='31 days ago' выбирает записи старше указанного срока;
• --batch-size=20 удаляет по 20 actions каждого выбранного статуса в одном пакете;
• --batches=5 ограничивает число пакетов;
• --pause=1 добавляет паузу между пакетами и снижает непрерывную нагрузку.

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

Удаление старых failed actions

Удаляйте failed actions только после того, как ошибка диагностирована и устранена, нужные задания повторены или признаны неактуальными, журналы больше не требуются для расследования и создана резервная копия базы. При необходимости предварительно сохраните список actions в CSV.

Пример ограниченной очистки старых ошибок:

wp action-scheduler clean --status=failed --before='90 days ago' --batch-size=20 --batches=5 --pause=1

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

Не включайте pending и in-progress в массовую очистку, если цель — убрать старую историю. Pending actions могут представлять невыполненные бизнес-операции, а in-progress — активную работу обработчика.

Проверка результата

После запуска и очистки повторите диагностику:

wp action-scheduler status
wp action-scheduler action list --status=pending --per-page=50 --format=table
wp action-scheduler action list --status=failed --per-page=50 --format=table

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

• просроченных pending actions стало меньше;
• новые failed actions с прежней ошибкой не появляются;
• выполненные действия переходят в complete;
• очередь не заполняется тем же hook быстрее, чем обрабатывается;
• журнал показывает запуск через WP-CLI и нормальное завершение;
• ожидаемые изменения действительно появились в WooCommerce или внешней системе;
• сайт и административная панель отвечают без заметного ухудшения.

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

Типовые ошибки при запуске через WP-CLI

Команда action-scheduler не найдена

Проверьте каталог WordPress, параметры --path и --url, активность WooCommerce и отсутствие --skip-plugins. Если на сервере несколько версий PHP, убедитесь, что WP-CLI запускается совместимой с сайтом версией и загружает те же расширения PHP.

После запуска появляются новые failed actions

Остановите массовую обработку и изучите последний журнал. Не увеличивайте размер пакета: новая ошибка означает, что причина не устранена или проявилась зависимость между actions. Проверьте один ID и соответствующий бизнес-результат.

Процесс завершается из-за памяти

Уменьшите --batch-size и --batches. Если даже один action требует слишком много памяти, проблема находится в callback или обрабатываемых им данных. Увеличение лимита PHP без анализа лишь отложит повторное падение.

Команда долго не возвращает управление

Не запускайте второй экземпляр с --force автоматически. Дождитесь результата либо проверьте доступными средствами, продолжает ли работать процесс. Долгое выполнение может быть связано с внешним HTTP-запросом, большим SQL-запросом или тяжёлой операцией внутри одного action.

Задание стало complete, но операция не выполнена

Статус complete означает, что Action Scheduler не зарегистрировал ошибку callback. Это не гарантирует прикладной результат, если код плагина подавил ошибку или получил неожиданный ответ внешнего сервиса. Проверяйте журналы WooCommerce, расширения и удалённой системы.

Безопасный рабочий сценарий

1. Создайте резервную копию базы данных.
2. Проверьте сайт и доступность CLI-команд.
3. Откройте Scheduled Actions и отделите просроченные pending actions от будущих.
4. Сгруппируйте проблемные записи по hook и group.
5. Изучите журналы нескольких pending и failed actions.
6. Устраните общую причину ошибки.
7. Запустите один action или небольшой пакет из 10 заданий.
8. Проверьте статус, журнал и фактический результат.
9. Постепенно увеличивайте размер пакета, наблюдая за ресурсами и новыми ошибками.
10. После стабилизации удалите старые complete и canceled actions.
11. Удаляйте failed actions только после расследования и сохранения нужных данных.

Главный принцип — не смешивать диагностику, повторный запуск и очистку. Pending-очередь сначала обрабатывают, failed actions сначала исследуют, а завершённую историю удаляют последней. Такой порядок позволяет разобрать крупное накопление заданий, не скрывая исходную ошибку и не создавая неконтролируемую нагрузку на WooCommerce.