Ctrlk
ДемоОфициальный сайт
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Laravel Horizon

Laravel Horizon — это панель контроля фоновых задач iEXExchanger.

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

Horizon работает поверх очередей Laravel и Redis. Если очередь настроена неправильно или Horizon не запущен, часть фоновых процессов может перестать выполняться или будет выполняться с задержкой.

Где находится Horizon

В панели управления откройте: «Утилиты» — «Horizon и Pulse» — «Laravel Horizon»

Прямой адрес:

Обычным клиентам и менеджерам без технического доступа этот раздел показывать не рекомендуется.

Для чего нужен Horizon

Horizon нужен, чтобы:

  • видеть, работают ли фоновые очереди;

  • проверять, выполняются ли задачи;

  • смотреть ошибки фоновых задач;

  • понимать, какая очередь перегружена;

  • контролировать отправку писем и Telegram-уведомлений;

  • проверять обработку файлов, экспорта, аналитики и webhooks;

  • перезапускать воркеры после обновлений;

  • находить причины задержек в фоновых процессах.

Важное отличие: CRON и Horizon

В системе есть два разных механизма:

Механизм
Что делает

CRON

Запускает задачи по расписанию

Horizon

Выполняет фоновые задачи из очереди

Пример:

  1. CRON запускает команду по расписанию.

  2. Команда ставит задачу в очередь.

  3. Horizon берёт задачу из очереди.

  4. Worker выполняет задачу.

  5. Система сохраняет результат.

То есть CRON часто выступает как диспетчер, а Horizon — как исполнитель фоновой работы.

Что нужно для работы Horizon

Для production-сервера должны быть настроены:

  • Redis;

  • Laravel queue через Redis;

  • запущенный процесс Horizon;

  • Supervisor или аналогичный менеджер процессов;

  • Laravel Scheduler / CRON.

В .env проекта для очередей должен использоваться Redis:

Очереди и письмаФайлы сайта в FastPanel

Если указано:

задачи будут выполняться сразу в текущем процессе, а Horizon не будет обрабатывать их как очередь.

Для production это нежелательно.

Как запускается Horizon

Обычно Horizon запускается через Supervisor.

Подключение к серверу по SSH

Команда запуска:

После изменения настроек, обновления проекта или изменения .env рекомендуется корректно перезапустить Horizon:

После этой команды Horizon завершит текущие воркеры, а Supervisor запустит их заново.

Почему Horizon нужно перезапускать после изменений

Horizon — это долгоживущий процесс. Он загружает конфигурацию при старте.

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

Это может касаться:

  • SMTP;

  • Redis;

  • mail-драйвера;

  • настроек очередей;

  • ключей интеграций;

  • runtime-настроек системы;

  • переменных .env;

  • настроек уведомлений.

После важных изменений выполните:

Основные очереди проекта

В текущем проекте Horizon обрабатывает очереди:

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

Также в проекте есть очередь:

Она используется для AI-ответов в чате заявки.

В текущей конфигурации Horizon очередь ai может не входить в основной список supervisor’а. Если AI-чат должен работать через Horizon, очередь ai нужно добавить в конфигурацию Horizon или запустить отдельный worker для этой очереди.

Supervisor Horizon в проекте

В проекте используется два основных supervisor’а Horizon:

  • supervisor-1;

  • supervisor-analytics.

1

supervisor-1

Основной supervisor обрабатывает рабочие очереди:

В production для него может быть настроено до:

Он отвечает за большинство фоновых задач системы:

  • уведомления;

  • обработку файлов;

  • экспорт;

  • архивирование заявок;

  • webhooks;

  • пересчёт заявок;

  • задачи низкого приоритета;

  • служебные фоновые операции.

2

supervisor-analytics

Отдельный supervisor для аналитики.

Очередь:

В production обычно используется:

Таймаут может быть увеличен до:

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

Приоритеты очередей

Очереди разделяют фоновые задачи по важности и типу нагрузки.

Очередь
Назначение

mail-high

Срочные email-уведомления

mail-low

Обычные и низкоприоритетные email-уведомления

high

Срочные фоновые задачи без mail-канала

default

Общая очередь по умолчанию

media

Обработка файлов и изображений

low

Низкоприоритетные служебные задачи

order-recount-scan

Поиск заявок для пересчёта

order-recount

Пересчёт конкретных заявок

presence

Фоновая активность и присутствие пользователей

analytics

Тяжёлый пересчёт аналитики

ai

AI-ответы в чате заявки

1

mail-high

Высокоприоритетные email-уведомления.

Например:

  • письма подтверждения;

  • коды входа;

  • важные уведомления по заявкам;

  • системные письма, которые должны уйти быстро.

2

mail-low

Обычные и низкоприоритетные email-уведомления.

Например:

  • уведомления, которые не критичны по времени;

  • часть пользовательских и служебных писем;

  • дополнительные уведомления.

3

high

Высокоприоритетные задачи без mail-канала.

Например:

  • срочные Telegram-уведомления;

  • быстрые фоновые действия;

  • события, которые должны обработаться раньше низкоприоритетных задач.

4

low

Низкоприоритетные задачи.

Например:

  • переиндексация поиска;

  • пересчёт уровней клиентов;

  • архивирование заявок;

  • обогащение журналов;

  • служебные действия, которые не должны мешать основным операциям.

5

default

Общая очередь по умолчанию.

Сюда попадают задачи, у которых не задана отдельная очередь.

6

media

Очередь обработки файлов.

Используется Media Manager для фоновой обработки изображений и файлов.

7

order-recount-scan

Очередь сканирования заявок для пересчёта.

Она ищет заявки, которые нужно пересчитать.

8

order-recount

Очередь непосредственного пересчёта заявок.

Сюда попадают конкретные заявки или пачки заявок.

9

presence

Очередь для фоновой активности и присутствия пользователей.

В системе также могут быть отдельные Redis-процессы presence, которые обрабатываются расписанием, а не только Horizon.

10

analytics

Отдельная очередь аналитики.

Используется для тяжёлого фонового пересчёта аналитических данных.

Какие задачи выполняются через Horizon

Через Horizon выполняются разные фоновые задачи iEXExchanger.

Основные группы:

  • уведомления;

  • обработка файлов;

  • пересчёт заявок;

  • аналитика;

  • экспорт заявок;

  • архивирование заявок;

  • импорт данных плагинов;

  • уровни клиентов;

  • глобальный поиск;

  • webhooks;

  • журнал авторизаций;

  • парсер курсов по формуле;

  • AI-ответы в чате заявки;

  • реферальные переходы;

  • бонусный центр.

Уведомления

Job:

Очереди:

Используется системой SmartNotifier.

Через эту задачу отправляются:

  • email-уведомления;

  • Telegram-уведомления;

  • уведомления по заявкам;

  • уведомления администраторам;

  • письма восстановления пароля;

  • письма подтверждения;

  • уведомления о верификации;

  • уведомления по выплатам;

  • тестовые письма.

Как работает отправка уведомления

  1. В системе происходит событие: заявка создана, заявка оплачена, оператор ответил, вход выполнен.

  2. SmartNotifier проверяет, нужно ли отправлять уведомление.

  3. Система определяет канал: email, Telegram или оба.

  4. Система выбирает очередь по приоритету.

  5. В Horizon появляется задача SendNotificationJob.

  6. Worker отправляет уведомление.

  7. Результат фиксируется в логах доставки уведомлений.

Если письма или Telegram-уведомления не приходят, Horizon — одно из первых мест, где нужно проверить ошибки.

Обработка файлов Media Manager

Job:

Очередь:

Используется при загрузке файлов через Media Manager.

Задача:

  • обрабатывает загруженный файл;

  • создаёт служебные данные;

  • готовит варианты изображений;

  • может создавать оптимизированные версии;

  • не заставляет администратора ждать тяжёлую обработку прямо во время загрузки.

Как работает обработка файла

  1. Администратор загружает файл.

  2. Файл сохраняется.

  3. Система ставит задачу ProcessMediaFileJob в очередь media.

  4. Horizon берёт задачу.

  5. Файл обрабатывается.

  6. Данные файла обновляются.

Если worker был выключен, в системе могут быть страховочные команды, которые повторно отправляют необработанные файлы в очередь.

Пересчёт заявок

Jobs:

Очереди:

Используется системой пересчёта заявок.

Задачи:

  • ищут заявки, которые нужно пересчитать;

  • группируют заявки в пачки;

  • пересчитывают конкретные заявки;

  • учитывают настройки пересчёта по статусам и CRON;

  • не выполняют тяжёлый пересчёт прямо в момент действия оператора.

Как работает пересчёт

  1. CRON запускает команду пересчёта.

  2. Команда ставит задачу сканирования в очередь order-recount-scan.

  3. ScanCronCandidatesJob ищет подходящие заявки.

  4. Найденные заявки разбиваются на пачки.

  5. RecountTasksBatchJob отправляет конкретные пересчёты.

  6. RecountTaskJob пересчитывает отдельную заявку.

  7. Результат сохраняется в системе.

Аналитика

Job:

Очередь:

Используется для фонового пересчёта аналитики.

Задача:

  • пересчитывает аналитические данные;

  • обновляет аналитические витрины;

  • обрабатывает последние периоды;

  • выполняет ночной полный пересчёт расширенного окна.

Расписание аналитики

В проекте может быть настроено:

  • каждый час — пересчёт последних 3 дней;

  • ежедневно в 00:20 — полный пересчёт последних 30 дней;

  • каждый час — проверка здоровья аналитики.

Почему аналитика вынесена отдельно

Аналитика может быть тяжёлой: много заявок, большие периоды, агрегаты, прибыль, статусы, операторы.

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

Экспорт заявок

Job:

Очередь:

Используется при экспорте заявок.

Задача:

  • создаёт файл экспорта;

  • применяет выбранные фильтры;

  • формирует файл в нужном формате;

  • сохраняет результат;

  • обновляет статус экспорта.

Как работает экспорт

  1. Менеджер запускает экспорт или срабатывает расписание экспорта.

  2. Система создаёт запись экспорта.

  3. В очередь ставится OrdersExportJob.

  4. Horizon формирует файл.

  5. В экспорте появляется готовый файл для скачивания.

  6. Если произошла ошибка, она фиксируется в статусе экспорта.

Архивация заявок

Job:

Очередь:

Используется системой архивирования заявок.

Задача:

  • берёт запуск архивации;

  • проверяет правила архивации;

  • переносит подходящие заявки в архив;

  • пишет историю запуска;

  • защищается от параллельного запуска.

Как работает архивация

  1. CRON или менеджер запускает архивацию.

  2. Система создаёт запись запуска архивации.

  3. Если это не тестовый запуск, задача отправляется в очередь low.

  4. Horizon выполняет ArchiveOrdersJob.

  5. Заявки переносятся в архив.

  6. В истории архивации появляется результат.

Импорт данных плагинов

Job:

Очередь:

Используется в системе установки и импорта плагинов.

Задача:

  • импортирует большие наборы данных плагина;

  • обрабатывает пары курсов частями;

  • обновляет прогресс импорта;

  • защищает импорт от параллельного запуска;

  • фиксирует ошибку, если импорт не завершился.

Как работает импорт

  1. Администратор устанавливает или активирует плагин.

  2. Если у плагина есть большой список пар, система создаёт импорт.

  3. RunPluginImportJob ставится в очередь.

  4. Horizon обрабатывает данные порциями.

  5. После завершения импорт получает статус выполненного.

  6. Если произошла ошибка, импорт получает статус ошибки.

Уровни клиентов

Jobs:

Очередь:

Используется системой уровней клиентов.

Задачи:

  • пересчитывают уровень одного клиента;

  • запускают массовый пересчёт всех клиентов;

  • пишут историю изменения уровня;

  • не тормозят завершение заявки.

Когда запускается пересчёт

  • после успешной заявки;

  • по расписанию;

  • вручную из админки при массовом пересчёте;

  • после изменения правил уровней.

Глобальный поиск по админке

Job:

Очередь:

Используется для обновления индекса поиска по админке.

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

Это фоновая задача, поэтому она не мешает сохранению формы.

Webhooks API

Job:

Очередь:

Используется системой API/webhooks.

Задача:

  • отправляет webhook на внешний URL;

  • подписывает запрос;

  • сохраняет HTTP-статус ответа;

  • фиксирует успешную доставку;

  • планирует повторную попытку при ошибке.

Как работает доставка webhook

  1. В системе происходит событие.

  2. Создаётся webhook event.

  3. Для endpoint создаётся delivery.

  4. SendWebhookDeliveryJob отправляется в очередь.

  5. Horizon выполняет HTTP-запрос.

  6. Если внешний сервис ответил успешно, доставка отмечается как успешная.

  7. Если произошла ошибка, система фиксирует её и может поставить повторную попытку.

Журнал авторизаций

Job:

Очередь:

Используется для обогащения событий авторизации.

Задача:

  • берёт событие входа;

  • проверяет IP;

  • добавляет GeoIP-информацию;

  • сохраняет страну, город и дополнительные данные.

Эта задача не должна мешать входу пользователя, поэтому выполняется в фоне.

Парсер курсов по формуле

Job:

Очередь:

Используется при обновлении курсов по формуле.

Если администратор запускает обновление, система может поставить задачу в очередь и показать сообщение, что обновление поставлено в очередь.

AI-ответы в чате заявки

Job:

Очередь:

Используется для AI-ответов в чате заявки.

Если AI-чат должен работать через Horizon, очередь ai должна быть добавлена в список очередей Horizon или обработана отдельным worker-процессом.

Логирование реферальных переходов

Job:

Очередь:

Используется для записи посещений по реферальным ссылкам.

Бонусный центр

Job:

Очередь:

Используется для синхронизации данных бонусного центра пользователя.

Что видно в Horizon

В Horizon обычно доступны такие разделы:

  • Dashboard;

  • Jobs;

  • Failed Jobs;

  • Queues;

  • Metrics.

1

Dashboard

Общий экран состояния.

Здесь можно увидеть:

  • активные supervisor’ы;

  • текущую нагрузку;

  • количество jobs;

  • очередь с ожиданием;

  • недавние задачи;

  • ошибки.

2

Jobs

Список задач.

Можно смотреть:

  • какие задачи выполнялись;

  • какие задачи сейчас активны;

  • какие завершились;

  • сколько времени выполнялись.

3

Failed Jobs

Ошибочные задачи.

Здесь важно смотреть:

  • название задачи;

  • очередь;

  • текст ошибки;

  • время ошибки;

  • количество попыток.

Если задача упала, это не всегда означает поломку всей системы.

Например, внешний SMTP, webhook URL или API провайдера мог временно не отвечать.

4

Queues

Состояние очередей.

Если в очереди много задач и они долго не уменьшаются, возможные причины:

  • Horizon не запущен;

  • Redis недоступен;

  • слишком мало worker-процессов;

  • одна из задач зависает;

  • очередь перегружена;

  • worker не слушает нужную очередь.

5

Metrics

Метрики по задачам и очередям.

В проекте может быть настроено хранение снимков метрик для jobs и queues.

Также по расписанию может запускаться:

Это нужно для графиков и статистики Horizon.

Что делать при ошибках Failed Jobs

Если в Horizon появились failed jobs:

  1. Откройте задачу.

  2. Посмотрите название job.

  3. Посмотрите очередь.

  4. Прочитайте текст ошибки.

  5. Определите модуль по названию job.

  6. Исправьте причину.

  7. Повторите задачу, если это безопасно.

Примеры:

Ошибка
Что проверить

Ошибка SMTP

Почтовые настройки

Ошибка webhook

Внешний URL и доступность сервиса

Ошибка файла

Права на storage/public

Ошибка аналитики

Базу данных и нагрузку

Ошибка Redis

Redis и Supervisor

Команды для диагностики

Подключение к серверу по SSH

Проверить статус Horizon:

Корректно перезапустить Horizon:

Посмотреть неудачные задачи Laravel:

Повторить все failed jobs:

Очистить failed jobs:

Проверить Redis:

Если Redis работает, он должен ответить:

Проверить Supervisor:

Что делать, если Horizon не работает

Проверьте по порядку:

  1. Redis установлен и отвечает PONG.

  2. В .env указано QUEUE_DRIVER=redis.

  3. Выполнены миграции таблиц очередей и failed jobs.

  4. Supervisor запущен.

  5. В Supervisor есть процесс Horizon.

  6. Команда php artisan horizon:status показывает активное состояние.

  7. В логах нет ошибок подключения к Redis.

  8. После изменения .env выполнен перезапуск Horizon.

Что делать, если задачи стоят в очереди и не выполняются

Возможные причины:

  • Horizon не запущен;

  • Supervisor не запустил процесс;

  • Redis недоступен;

  • очередь не входит в список Horizon;

  • задача отправляется в отдельную очередь, например ai, а worker её не слушает;

  • задача зависла из-за внешнего сервиса;

  • слишком мало процессов для текущей нагрузки.

Проверьте, в какую очередь попала задача. Если очередь не указана в конфиге Horizon, её нужно добавить в supervisor или запустить отдельный worker.

Что делать, если не приходят письма

Проверьте:

  1. Работает ли Horizon.

  2. Есть ли задачи SendNotificationJob.

  3. Нет ли ошибок в Failed Jobs.

  4. Обрабатываются ли очереди mail-high и mail-low.

  5. Правильно ли настроен SMTP.

  6. Не отключена ли очередь уведомлений.

  7. Не стоит ли QUEUE_DRIVER=sync вместо redis.

Если задача SendNotificationJob падает, причина обычно не в Horizon, а в SMTP, шаблоне письма, получателе или настройках уведомлений.

Что делать, если не обрабатываются изображения

Проверьте:

  • очередь media;

  • задачи ProcessMediaFileJob;

  • права на папки хранения файлов;

  • наличие ошибок в Horizon;

  • включена ли фоновая обработка Media Manager.

Что делать, если не обновляется аналитика

Проверьте:

  • очередь analytics;

  • supervisor supervisor-analytics;

  • задачи AnalyticsRebuildJob;

  • нет ли failed jobs;

  • не выполняется ли уже долгий пересчёт;

  • работает ли scheduler.

Аналитика может выполняться долго. Это нормально для больших проектов.

Что делать после обновления проекта

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

Если используется Supervisor, он сам поднимет Horizon снова.

Если менялись зависимости, настройки Redis, очередей или .env, дополнительно проверьте:

Что важно объяснить клиентам

Horizon не создаёт заявки, не принимает оплаты и не выполняет обмен сам по себе.

Он отвечает за фоновые процессы:

  • отправить уведомление;

  • обработать файл;

  • пересчитать данные;

  • сформировать экспорт;

  • доставить webhook;

  • выполнить аналитику;

  • обработать задачу, которую система поставила в очередь.

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

Рекомендуемая настройка production

Для production рекомендуется:

Очереди и письма

Также должно быть настроено:

  • Redis установлен и доступен;

  • Horizon запущен через Supervisor;

  • Scheduler работает через CRON;

  • Horizon перезапускается после обновлений и важных изменений настроек.

Короткая схема работы

Частые вопросы

Horizon нужен для работы сайта?

Для открытия сайта — не всегда.

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

Почему сайт работает, но письма не приходят?

Сайт может открываться без Horizon, но письма отправляются через очередь.

Проверьте Horizon, очереди mail-high и mail-low, а также failed jobs.

Почему после обновления появились странные ошибки в очередях?

Horizon мог продолжать работать со старой конфигурацией.

Выполните:

Можно ли использовать QUEUE_DRIVER=sync?

Для production не рекомендуется.

При sync задачи выполняются сразу в текущем процессе и могут тормозить сайт или админку. Horizon в таком режиме не будет полноценно контролировать очередь.

Что делать, если очередь ai не выполняется?

Проверьте, добавлена ли очередь ai в конфигурацию Horizon.

Если нет, добавьте её в supervisor Horizon или запустите отдельный worker для этой очереди.

Коротко

Laravel Horizon — это технический центр контроля фоновых задач iEXExchanger.

Через него удобно понимать:

  • работают ли очереди;

  • почему задерживаются письма;

  • где упала обработка файла;

  • почему не сформировался экспорт;

  • почему аналитика не обновилась;

  • какие задачи перегружают систему.

Для стабильной production-работы важно держать включёнными Redis, Supervisor, Scheduler и сам Horizon.

Horizon находится здесь: «Утилиты» — «Horizon и Pulse» — «Laravel Horizon»

ПредыдущаяLaravel PulseСледующаяКак создать резервную копию в FastPanel

Последнее обновление

Это было полезно?