Очереди Laravel на сервере: queue:work и Supervisor
Письма, обработку картинок и другие долгие дела Laravel откладывает в очередь, а выполняет их отдельный процесс — воркер, команда php artisan queue:work. Если воркер не запущен, задачи копятся и не выполняются. На сервере воркер запускают под Supervisor: он стартует воркер при загрузке и поднимает его, если тот завершился.
Содержание 12
Что сделать прямо сейчас
- Поставьте Supervisor:
sudo apt install supervisor— подробнее. - Создайте файл воркера:
sudo nano /etc/supervisor/conf.d/laravel-worker.conf— и вставьте готовые настройки. - Примените:
sudo supervisorctl reread, затемsudo supervisorctl update. - Проверьте:
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 statusreread читает новый файл, 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=3 | 1 | сколько раз пробовать задачу, прежде чем записать её в упавшие |
--timeout=60 | 60 | сколько секунд может идти одна задача |
--sleep=3 | 3 | сколько секунд ждать, если задач нет |
--max-time=3600 | 0 — без ограничения | через сколько секунд воркер завершится сам, а Supervisor запустит новый |
--memory=128 | 128 | при каком расходе памяти в мегабайтах воркер завершится |
--max-jobs=1000 | 0 — без ограничения | после скольких задач воркер завершится |
--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. Тогда зависший воркер завершится раньше, чем задачу отдадут второй раз.
| Задача длится | --timeout | retry_after |
|---|---|---|
| до минуты | 60 — по умолчанию | 90 — по умолчанию |
| до 5 минут | --timeout=300 | DB_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.
Источники
- Документация Laravel: Queues — на английском: queue:work, файл Supervisor, queue:restart, retry_after и упавшие задачи.
- Шаблон config/queue.php — на английском: соединение database, retry_after 90 и таблица failed_jobs.
- Исходный код команды queue:work в Laravel 13.42.0 — на английском: ключи и значения по умолчанию.
- Документация Supervisor — на английском: строки секции program.
Сверено 13 ноября 2026 года.
Что почитать дальше
- Laravel на серверевсе статьи о работе проекта на VPS.
- Планировщик Laravel и cronзадачи по расписанию.
- Установка Supervisorкоманды supervisorctl и состояния программ.