Поиск
Справочник

Очереди Laravel на сервере: queue:work и Supervisor

Письма, обработку картинок и другие долгие дела Laravel откладывает в очередь, а выполняет их отдельный процесс — воркер, команда php artisan queue:work. Если воркер не запущен, задачи копятся и не выполняются. На сервере воркер запускают под Supervisor: он стартует воркер при загрузке и поднимает его, если тот завершился.

≈ 7 мин чтения
Содержание 12

Что сделать прямо сейчас

  1. Поставьте Supervisor: sudo apt install supervisor — подробнее.
  2. Создайте файл воркера: sudo nano /etc/supervisor/conf.d/laravel-worker.conf — и вставьте готовые настройки.
  3. Примените: sudo supervisorctl reread, затем sudo supervisorctl update.
  4. Проверьте: sudo supervisorctl status — у воркеров должно быть RUNNING.

Команды вводятся на сервере: подключитесь к нему по SSH (как подключиться). Проект в примерах лежит в /var/www/example.com.

Как работает очередь

ЧтоГде
сайт кладёт задачу в очередьстрока QUEUE_CONNECTION в .env, в новом проекте — database
задачи хранятсяв таблице jobs базы данных
задачи выполняетворкер — команда php artisan queue:work
задачи, которые не удалисьв таблице failed_jobs

Таблицы jobs и failed_jobs создаёт стандартная миграция нового проекта. Если таблицы jobs нет — создайте её:

php artisan make:queue-table
php artisan migrate --force

С Redis задачи хранятся в памяти Redis, а не в базе — Laravel и Redis.

Проверьте воркер вручную

Перед настройкой Supervisor запустите воркер руками от пользователя сайта:

cd /var/www/example.com
sudo -u www-data php artisan queue:work

Ответ: Processing jobs from the [default] queue. Дальше по строке на каждую задачу: сначала RUNNING, потом DONE или FAIL. Остановить — Ctrl+C.

Воркер работает, пока его не остановить, и держит код в памяти. Если закрыть SSH, он остановится — для работы без перерыва нужен Supervisor.

Файл Supervisor для воркера

Это пример из документации Laravel, подставленный под папку /var/www/example.com и пользователя www-data:

[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/example.com/artisan queue:work --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/example.com/storage/logs/worker.log
stopwaitsecs=3600

Сохраните файл: Ctrl+O, Enter, выход — Ctrl+X. Имя файла должно заканчиваться на .conf.

СтрокаЧто значит
[program:laravel-worker]имя программы в Supervisor
process_name=…имена копий: laravel-worker_00, laravel-worker_01
command=…команда воркера, путь к artisan — полный
autostart=trueзапускать при загрузке сервера
autorestart=trueперезапускать, если воркер завершился
stopasgroup=true и killasgroup=trueостанавливать воркер вместе с его дочерними процессами
user=www-dataот какого пользователя работает воркер
numprocs=2сколько копий запустить; в документации 8 — для небольшого VPS хватит 1–2
stdout_logfile=…куда писать вывод воркера
stopwaitsecs=3600сколько секунд ждать, пока воркер закончит задачу, при остановке

stopwaitsecs должно быть больше, чем длится самая долгая задача. Иначе Supervisor завершит воркер посреди задачи.

Как устроен файл Supervisor — в статье Установка Supervisor.

Как применить и проверить

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl status

reread читает новый файл, update запускает воркеры. В ответе status — строки laravel-worker:laravel-worker_00 и laravel-worker:laravel-worker_01 с состоянием RUNNING.

Вывод воркера смотрите в файле:

tail -f /var/www/example.com/storage/logs/worker.log

Выход — Ctrl+C.

КомандаЧто делает
sudo supervisorctl start "laravel-worker:*"запустить все копии
sudo supervisorctl stop "laravel-worker:*"остановить все копии
sudo supervisorctl restart "laravel-worker:*"перезапустить все копии

Звёздочку берите в кавычки, как в примерах.

Ключи queue:work

КлючПо умолчаниюЧто значит
--tries=31сколько раз пробовать задачу, прежде чем записать её в упавшие
--timeout=6060сколько секунд может идти одна задача
--sleep=33сколько секунд ждать, если задач нет
--max-time=36000 — без ограничениячерез сколько секунд воркер завершится сам, а Supervisor запустит новый
--memory=128128при каком расходе памяти в мегабайтах воркер завершится
--max-jobs=10000 — без ограниченияпосле скольких задач воркер завершится
--queue=high,defaultочередь defaultкакие очереди разбирать и в каком порядке
--force—работать и в режиме обслуживания

С --max-time и --max-jobs воркер время от времени завершается и Supervisor запускает свежий — так память не растёт без конца.

timeout и retry_after

В файле config/queue.php у соединений database и redis есть настройка retry_after — 90 секунд. Если задача выполняется дольше, Laravel считает её зависшей и отдаёт другому воркеру.

Документация Laravel требует: --timeout должен быть на несколько секунд меньше retry_after. Тогда зависший воркер завершится раньше, чем задачу отдадут второй раз.

Задача длится--timeoutretry_after
до минуты60 — по умолчанию90 — по умолчанию
до 5 минут--timeout=300DB_QUEUE_RETRY_AFTER=330 в .env

Для Redis строка в .env — REDIS_QUEUE_RETRY_AFTER. Не забудьте и stopwaitsecs в файле Supervisor — оно должно быть больше --timeout.

После выкладки нового кода

Воркер загружает код один раз при запуске и новых файлов не видит. После каждой выкладки перезапустите воркеры:

php artisan queue:restart

Ответ: Broadcasting queue restart signal. Каждый воркер доделает текущую задачу и завершится, а Supervisor запустит его заново уже с новым кодом.

Сигнал перезапуска хранится в кеше приложения — кеш должен работать. Команда php artisan reload делает то же и ещё перезапускает планировщик — Выкладка обновлений.

Упавшие задачи

Задача, которая не удалась за все попытки --tries, попадает в таблицу failed_jobs.

КомандаЧто делает
php artisan queue:failedсписок упавших задач с ID
php artisan queue:retry IDвернуть задачу в очередь
php artisan queue:retry allвернуть все упавшие задачи
php artisan queue:retry --queue=nameвернуть задачи одной очереди
php artisan queue:forget IDудалить одну упавшую задачу
php artisan queue:flushудалить все упавшие задачи
php artisan queue:flush --hours=48удалить упавшие задачи старше 48 часов

Перед повтором найдите причину в журнале storage/logs/laravel.log — иначе задача упадёт снова. Если таблицы failed_jobs нет — php artisan make:queue-failed-table и php artisan migrate --force.

Ошибки и как их исправить

Что видитеПричинаЧто делать
письма и задачи не выполняютсяворкер не запущензапустите под Supervisor
задачи выполняются по старому кодуворкер не перезапущен после выкладкиphp artisan queue:restart
в status FATAL или BACKOFFворкер падает при запускесмотрите worker.log и ошибки Supervisor
Queue restarting is currently disabled.в коде проекта выключен перезапуск воркеровперезапустите через sudo supervisorctl restart "laravel-worker:*"
Base table or view not found с таблицей jobsнет таблицы очередиphp artisan make:queue-table и php artisan migrate --force
задача выполняется дважды--timeout больше retry_afterпоправьте значения
laravel.log could not be opened в worker.logнет прав на storageРазбор
воркер завершается с ошибкой памятизадаче не хватило памятиmemory_limit

Тексты сообщений сверены по исходному коду Laravel 13.42.0.

Источники

Сверено 13 ноября 2026 года.

Где попробовать. Команды из статьи безопаснее сначала повторить на отдельном тестовом сервере, а не на рабочем. Подойдёт VPS с Ubuntu, например Timeweb Cloud Реклама. АО «ТАЙМВЭБ», ИНН 7810353960. erid: CQH36pWzJpoBWKF332yG5h2XQ4cVubfBmkvqAitFqcpzWs. Как зайти на него после заказа — в статье Как подключиться к VPS по SSH.

Что почитать дальше