راهاندازی Laravel Horizon روی سرور مجازی و اختصاصی: مانیتورینگ و مقیاسپذیری خودکار صفهای Redis
اگر صف کارهای لاراولتان را با php artisan queue:work ساده اجرا میکنید، یک جایی که تعداد job زیاد شود، نمیدانید چند تا در حال پردازش است یا چرا یکی گیر کرده. راهاندازی Laravel Horizon دقیقا همین مشکل را حل میکند: یک داشبورد زنده روی صفهای Redis، به همراه کنترل تعداد کارگرها.
این راهنما نصب Horizon، اتصالش به Redis، نگهداشتنش زنده با Supervisor، امنسازی داشبورد و اتصال به دیپلوی را روی یک سرور مجازی یا اختصاصی قدمبهقدم توضیح میدهد.
Horizon چیست و چرا به Redis نیاز دارد
Horizon یک پکیج رسمی لاراول است که روی صفهای Redis یک داشبورد وب میگذارد: تعداد job در حال اجرا، زمان پردازش هر صف، jobهای شکستخورده و امکان retry از همان صفحه. بدون Horizon هم صف کار میکند، فقط چشمتان به آن نیست.

نکتهٔ مهم همین «Redis» است. Horizon روی درایور database یا sync کار نمیکند؛ فقط صفهایی که درایورشان redis باشد را مانیتور میکند. اگر الان از صف دیتابیس استفاده میکنید، اول باید به Redis مهاجرت کنید؛ نحوهٔ کار با Redis کنار لاراول را این راهنما جدا توضیح داده.
چرا VPS یا سرور اختصاصی، نه هاست اشتراکی
این جایی است که خیلیها گیر میکنند: روی هاست لاراول اشتراکی معمولی، نه سرویس Redis نصب است و نه اجازه اجرای یک پراسس دائمی مثل Supervisor را میدهند. پنل هاست برای اجرای سایت ساخته شده، نه برای نگهداشتن یک worker که باید ۲۴ ساعته روشن بماند.
برای Horizon سه چیز لازم است که فقط روی سرور مجازی یا سرور اختصاصی با دسترسی root دارید:
- نصب و اجرای خود Redis (یا دسترسی به یک Redis جداگانه)
- اجرای یک پراسس مدیریتکننده مثل Supervisor که worker را زنده نگه دارد
- دسترسی SSH برای تنظیم و ریاستارت در زمان دیپلوی
اگر هنوز بین هاست و سرور مجازی برای لاراول تصمیم نگرفتهاید، این راهنما تفاوتهای عملی دو گزینه را جدا بررسی کرده.
نصب Horizon روی پروژه
از ریشهٔ پروژه لاراول روی سرور:
composer require laravel/horizon
php artisan horizon:install
php artisan migrate
دستور دوم فایل config/horizon.php را میسازد و asset داشبورد را publish میکند. دستور migrate دو جدول برای jobهای شکستخورده و تگها اضافه میکند.
اتصال به Redis
در فایل .env پروژه، درایور صف و کانکشن Redis را مشخص کنید:
QUEUE_CONNECTION=redis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=یک-رمز-قوی
REDIS_PORT=6379
اگر Redis روی همان سرور لاراول نصب است، REDIS_HOST همان 127.0.0.1 میماند. اگر یک سرور جدا برای Redis دارید (معمول وقتی چند سرور اپلیکیشن پشت یک Redis مشترک هستند)، آدرس داخلی همان سرور را بگذارید، نه IP عمومی — ترافیک بین دو سرور بهتر است از شبکه خصوصی رد شود.
نصب اکستنشن PHP هم لازم است؛ یا phpredis (سریعتر، نیاز به کامپایل) یا پکیج Composer predis/predis (نصب سادهتر، کمی کندتر). برای شروع predis کافی است:
composer require predis/predis
اگر Redis روی همین سرور تازه نصب میشود، راهاندازی و امنسازی Redis مرحله به مرحله رمز و دسترسی آن را هم پوشش میدهد.
تعریف صفها و تعداد کارگرها
در config/horizon.php، بخش environments مشخص میکند هر محیط (production، local) چند worker با چه تنظیماتی اجرا کند:
'environments' => [
'production' => [
'supervisor-1' => [
'connection' => 'redis',
'queue' => ['default', 'emails'],
'balance' => 'auto',
'minProcesses' => 1,
'maxProcesses' => 10,
'tries' => 3,
],
],
],
سه حالت balance معنی متفاوتی دارند و انتخاب غلط یا منابع سرور را هدر میدهد یا صف را کند میکند:
| حالت balance | رفتار | مناسب چه موقع |
|---|---|---|
simple | تعداد ثابت worker، بدون تغییر خودکار | بار صف تقریبا همیشه یکسان است |
auto | تعداد worker را بین min و max بر اساس حجم صف بالا و پایین میبرد | بار صف نوسان دارد (مثلا شبها کمتر) |
false | مقیاسپذیری خاموش، فقط همان تعداد اولیه | میخواهید خودتان دستی کنترل کنید |
برای اکثر پروژهها auto با یک maxProcesses متناسب با تعداد vCPU سرور شروع خوبی است؛ بیشتر از تعداد هسته، worker روی هم صف میکشند نه موازی کار میکنند.
نگهداشتن Horizon زنده با Supervisor
خود Horizon هم یک پراسس PHP است که باید همیشه روشن بماند؛ اگر سرور ریاستارت شود یا پراسس crash کند، باید خودکار بالا بیاید. ابزار استاندارد برای این کار Supervisor است (مستقل از همان supervisor که در config Horizon دیدیم، فقط اسمشان شبیه هم است).
نصب Supervisor روی اوبونتو یا دبیان:
sudo apt install supervisor
یک فایل تنظیمات در /etc/supervisor/conf.d/horizon.conf بسازید:
[program:horizon]
process_name=%(program_name)s
command=php /var/www/project/artisan horizon
autostart=true
autorestart=true
user=www-data
redirect_stderr=true
stdout_logfile=/var/www/project/storage/logs/horizon.log
stopwaitsecs=3600
عدد stopwaitsecs مهم است: وقتی Supervisor بخواهد Horizon را متوقف کند، اینقدر صبر میکند تا jobهای در حال اجرا تمام شوند، قبل از kill کردن پراسس. برای صفهایی با job طولانی، این عدد را بالاتر بگذارید.
بعد از ساخت فایل:
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start horizon:*
امنسازی داشبورد Horizon
آدرس پیشفرض داشبورد /horizon است و هر کسی که آدرس را بداند میتواند صفهای شما را ببیند، مگر دسترسی را محدود کنید. در app/Providers/HorizonServiceProvider.php متد gate همین کار را میکند:
protected function gate()
{
Gate::define('viewHorizon', function ($user) {
return in_array($user->email, [
'admin@example.com',
]);
});
}
این روش فرض میکند کاربر از قبل لاگین کرده است. اگر Horizon روی یک پروژه بدون سیستم لاگین کاربر است (مثلا یک API)، راه سادهتر محدود کردن مسیر /horizon در تنظیمات وبسرور به IP دفتر یا پشت یک VPN است، بهجای باز گذاشتنش روی اینترنت با یک گیت PHP. برای تنظیمات کاملتر دسترسی به خود سرور، امنسازی دسترسی SSH نقطهٔ شروع خوبی است.
اتصال به فرایند دیپلوی
نکتهای که زود فراموش میشود: بعد از هر دیپلوی کد جدید، workerهای در حال اجرا هنوز نسخهٔ قبلی کد را در حافظه دارند. باید به Horizon بگویید کد عوض شده:
php artisan horizon:terminate
این دستور workerها را بعد از تمام شدن job جاریشان متوقف میکند، نه فورا. چون autorestart=true در تنظیمات Supervisor هست، خودش دوباره بالا میآید و اینبار کد جدید را میخواند. این خط را آخر اسکریپت دیپلوی بگذارید، بعد از composer install و php artisan migrate — برای تنظیم کامل همین اسکریپت روی سرور، دیپلوی لاراول با Nginx، PHP-FPM و Supervisor را ببینید.
برای مانیتورینگ تاریخچهٔ صف در طول زمان، Horizon یک دستور snapshot دارد که باید هر چند دقیقه اجرا شود تا نمودارهای داشبورد داده داشته باشند:
// در app/Console/Kernel.php
$schedule->command('horizon:snapshot')->everyFiveMinutes();
جمعبندی
Horizon کار صف Redis را از یک جعبهٔ سیاه به یک داشبورد قابلرصد تبدیل میکند، اما خودش به یک سرور با دسترسی کامل نیاز دارد تا Redis و Supervisor را اجرا کند. برای شروع روی یک پروژه تازه، یک سرور مجازی آریانت برای چند صف با بار متوسط کافی است؛ برای صفهای با حجم بالا یا چند اپلیکیشن کنار هم، یک سرور اختصاصی منابع ثابت و پیشبینیپذیرتری میدهد.
سؤالات متداول
آیا Horizon را میتوان بدون Redis استفاده کرد؟
نه. Horizon فقط صفهایی با درایور redis را مانیتور میکند؛ صف دیتابیس یا sync را نشان نمیدهد.
فرق Horizon با اجرای چند queue:work دستی چیست؟queue:work فقط یک worker را اجرا میکند و وضعیتش را جایی ذخیره نمیکند. Horizon چند worker را با تعداد خودکار مدیریت میکند و همهٔ متریکها (تعداد job، زمان پردازش، خطاها) را در یک داشبورد نشان میدهد.
بعد از هر دیپلوی باید Horizon را ریاستارت کنم؟
برای اینکه worker کد جدید را بخواند، بله. horizon:terminate همین کار را امن انجام میدهد، چون قبل از توقف صبر میکند job جاری تمام شود.
چند worker برای شروع کافی است؟
برای یک صف با بار کم تا متوسط، minProcesses: 1 و maxProcesses برابر تعداد vCPU سرور نقطهٔ شروع خوبی است. بعد با نگاه به داشبورد Horizon و طول صف، عدد را بالا یا پایین ببرید.




