---
title: "Laravel Sail: воркери черг, Horizon, Redis, RabbitMQ та failed jobs | DevSense"
description: "Запуск черг Laravel всередині Sail: порівняння sync, redis та database, локальний запуск queue:work та Horizon, RabbitMQ з ком'юніті-драйверами, failed_jobs, queue:restart та відмінності від продакшену."
faq:
  - question: "Чому мої фонові задачі не виконуються в Sail?"
    answer: "На відміну від драйвера 'sync', драйвери 'database' або 'redis' вимагають працюючого процесу воркера. Вам потрібно запустити контейнер воркера або виконати 'sail artisan queue:work' у терміналі."
  - question: "Чому зміни в класах Job не застосовуються в черзі?"
    answer: "Воркери черг Laravel завантажують код застосунку в пам'ять один раз. При зміні коду необхідно виконати команду 'sail artisan queue:restart', щоб примусово перезавантажити воркери."
  - question: "Як запустити планувальник у Laravel Sail без налаштування cron на хост-машині?"
    answer: "Ви можете запустити команду 'sail run --rm laravel.test php artisan schedule:work' в окремому вікні термінала, яка опитуватиме та запускатиме завдання щохвилини локально."
  - question: "Чим управління чергами в Sail відрізняється від продакшену?"
    answer: "У Sail воркери запускаються на передньому плані вашого термінала і зупиняються при його закритті. На продакшені для забезпечення постійної роботи використовуються менеджери процесів, такі як Supervisor або Kubernetes."
---

# Sail: черги та воркери

Ви запускаєте фонове завдання у своєму застосунку Laravel, але нічого не відбувається. На сторінці завдання відображається статус \"В очікуванні\", а записи в базі даних залишаються незмінними. І тут ви усвідомлюєте: в контейнеризованому середовищі фонові завдання не виконуються самі по собі. Без активного процесу воркера (worker), запущеного всередині мережі контейнерів Sail, ваші черги — це просто мертві записи в БД або мовчазні списки Redis.

Спроба запустити воркери черг та планувальник завдань безпосередньо на хост-системі завершиться помилкою, оскільки у них не буде доступу до баз даних, змінних оточення та PHP-розширень всередині контейнерів. Щоб повністю відтворити поведінку продакшену, ви повинні запускати процеси воркерів та керувати ними всередині мережі Compose.

У цьому посібнику ми покажемо, як налаштовувати підключення до черг, запускати воркери та Horizon, обробляти збої завдань та скидати застарілий кеш коду у воркерах.

**Навігація:** [Усі інструменти](../) · [Sail огляд](sail#what-sail-is) · [Бази даних](sail-databases#networking) · [Env та деплой](sail-env-deploy#forward-ports) · [Діагностика](sail-troubleshooting#wsl-filesync)

## Зміст

* [Драйвери](#connections)
* [Запуск `queue:work` у Sail](#queue-work)
* [Horizon (Redis)](#horizon)
* [RabbitMQ та AMQP-пакети](#rabbitmq)
* [Невиконані завдання та повтори (Failed jobs)](#failed-jobs)
* [Зміна коду та `queue:restart`](#restart)
* [Планувальник (`schedule:run`)](#scheduler)
* [Відмінності від продакшену](#production)
* [Часті помилки](#common-mistakes)
* [Тест для самоперевірки](#self-check)

---

<a id="connections"></a>
## Драйвери

Оберіть драйвер черг у файлі `.env`:

```dotenv
# .env
QUEUE_CONNECTION=redis
```

| Драйвер | Використання в Sail |
|--------|-------------------|
| **`sync`** | Синхронна відладка логіки завдань без запуску воркера. |
| **`database`** | Проста асинхронна черга; вимагає таблиці `jobs` та запущеного воркера. |
| **`redis`** | Стандартний вибір для продакшену; інтегрується з Horizon; вимагає служби Redis. |
| **`rabbitmq`** | Обмін повідомленнями за AMQP; вимагає контейнера RabbitMQ та ком'юніті-пакета. |

> [!NOTE]
> **Кешування конфігурації**
> Якщо ви змінили параметр `QUEUE_CONNECTION` або будь-які інші змінні черг, виконайте `sail artisan config:clear` або `sail artisan config:cache` для застосування змін у запущених контейнерах.

---

<a id="queue-work"></a>
## Запуск `queue:work` у Sail

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

```bash
# Terminal
sail artisan queue:work
```

Для більш тонкого налаштування вкажіть підключення та параметри запуску:

```bash
# Terminal
sail artisan queue:work redis --queue=high,default --tries=3 --timeout=90
```

Щоб виконати лише одне завдання та завершити процес (корисно при відладці):

```bash
# Terminal
sail artisan queue:work --once
```

---

<a id="horizon"></a>
## Horizon (Redis)

Laravel Horizon надає зручний веб-інтерфейс та конфігурацію на основі коду для черг Redis.

1. Встановіть Horizon через Composer:
   ```bash
   sail composer require laravel/horizon
   sail artisan horizon:install
   ```
2. Запустіть Horizon всередині контейнера:

```bash
# Terminal
sail artisan horizon
```

Панель керування буде доступна за адресою `http://localhost/horizon`. У процесі розробки Horizon зупиняється натисканням клавіш `Ctrl+C`.

---

<a id="rabbitmq"></a>
## RabbitMQ та AMQP-пакети

Laravel не містить вбудованого драйвера для RabbitMQ. Для використання AMQP:

1. Додайте службу RabbitMQ у файл `docker-compose.yml` ([див. рецепти баз даних](sail-databases#rabbitmq-sidecar)).
2. Встановіть ком'юніті-пакет (наприклад, `vyuldashev/laravel-queue-rabbitmq`).
3. Задайте параметри підключення:

```dotenv
# .env
QUEUE_CONNECTION=rabbitmq
RABBITMQ_HOST=rabbitmq
RABBITMQ_PORT=5672
```

4. Запустіть обробку:
   ```bash
   sail artisan queue:work rabbitmq
   ```

---

<a id="failed-jobs"></a>
## Невиконані завдання та повтори (Failed jobs)

Якщо фонове завдання завершується з виключенням, Laravel записує інформацію про нього в таблицю `failed_jobs`.

- Переглянути список невиконаних завдань:
  ```bash
  sail artisan queue:failed
  ```
- Запустити завдання повторно за ID:
  ```bash
  sail artisan queue:retry 5
  ```
- Очистити всі невиконані завдання:
  ```bash
  sail artisan queue:flush
  ```

---

<a id="restart"></a>
## Зміна коду та `queue:restart`

Воркери черг Laravel завантажують фреймворк та код застосунку в пам'ять один раз і працюють у нескінченному циклі. Якщо ви зміните файл завдання (Job), запущенний воркер продовжить виконувати стару версію коду з пам'яті.

Після кожного збереження змін у коді перезапускайте воркери:

```bash
# Terminal
sail artisan queue:restart
```

> [!NOTE]
> **Автоперезапуск під час розробки**
> Щоб не вводити `queue:restart` постійно при активній локальній розробці, ви можете запустити воркер з прапорцями `--max-jobs=1` або `--once`.

---

<a id="scheduler"></a>
## Планувальник (`schedule:run`)

Sail не містить автоматично запущеного системного демона cron. Для виконання запланованих завдань локально у вас є два шляхи:

1. Запускати планувальник вручную:
   ```bash
   sail artisan schedule:run
   ```
2. Запустити безперервний цикл опитування у фоновому режимі:

```bash
# Terminal
sail run --rm laravel.test php artisan schedule:work
```

---

<a id="production"></a>
## Відмінності від продакшену

| Тема | Sail (локально) | Продакшен |
|-------|------------------|------------------------|
| **Менеджер процесів** | Вручну на передньому плані | Демон **Supervisor** або systemd |
| **Масштабування** | Один контейнер Docker | Кілька контейнерів / автоскейлінг Kubernetes |
| **Отказоустойчивость** | Ручний перезапуск контейнера | Резервні вузли та кластеризація |

---

## ⚠️ Часті помилки

**1. Зміна коду завдання без перезапуску воркера**
Ви виправили помилку в класі Job, але обробник черг продовжує видавати стару помилку.
*Рішення:* Воркер закешував файли PHP. Виконайте `sail artisan queue:restart`.

**2. Запуск `php artisan queue:work` у локальному терміналі хоста**
Запуск команди безпосередньо на вашій машині призведе до помилки через відсутність драйверів баз даних або неможливість розв'язати внутрішні імена хостів контейнерів, такі як `redis` или `mysql`.
*Рішення:* Завжди додавайте префікс `sail` для виконання всередині контейнера: `sail artisan queue:work`.

**3. Використання синхронного драйвера `sync` на постійній основі**
Використання `QUEUE_CONNECTION=sync` виконує завдання миттєво в межах HTTP-запиту. Це маскує проблеми з конкурентністю, таймаутами та серіалізацією даних, які обов'язково випливуть на продакшені.
*Рішення:* Використовуйте `database` або `redis` локально, щоб відповідати поведінці реального сервера.

---

## 🧠 Тест для самоперевірки

1. **Чому запущений воркер черги не виконує новий код, який ви щойно зберегли на диск?**
2. **Яке ім'я хоста потрібно вказати у файлі `.env` для RabbitMQ при роботі всередині Sail?**
3. **Як підтримувати роботу планувальника завдань Laravel у фоновому режимі без налаштування cron на хост-системі?**
4. **Яку команду artisan потрібно виконати для повторного запуску завдання, що завершилося збоєм?**

<details>
<summary><b>Показати відповіді</b></summary>

1. PHP CLI воркери завантажують фреймворк один раз у пам'ять і утримують його. Вони не перечитують файли з диска для кожного нового завдання. Потрібен перезапуск через `sail artisan queue:restart`.
2. Потрібно використовувати ім'я служби з Compose, тобто `rabbitmq`.
3. Запустити команду `sail run --rm laravel.test php artisan schedule:work`, яка утримуватиме процес та викликатиме планувальник щохвилини.
4. Виконати команду `sail artisan queue:retry {id}`, де `{id}` — ідентифікатор завдання з таблиці `failed_jobs`, або `all` для повторення всіх невдалих завдань.
</details>