Laravel Horizon

• معرفی
• نصب و راه اندازی
  • پیکربندی
  • استراتژی های متعادل سازی
  • مجوز داشبورد
  • مشاغل خاموش
• ارتقاء Horizon
• Running Horizon
  • استقرار Horizon
• برچسب ها
• اطلاعیه
• معیارهای
• حذف مشاغل ناموفق
• پاک کردن مشاغل از صف

معرفی

قبل از جستجو در Laravel Horizon، باید با خدمات صف پایه لاراول آشنا شوید . Horizon صف لاراول را با ویژگی‌های اضافی افزایش می‌دهد که اگر از قبل با ویژگی‌های صف اولیه ارائه شده توسط لاراول آشنا نباشید، ممکن است گیج‌کننده باشد.

Laravel Horizon یک داشبورد زیبا و پیکربندی کد محور برای صف‌های Redis با قدرت لاراول شما فراهم می‌کند . Horizon به شما این امکان را می دهد تا به راحتی معیارهای کلیدی سیستم صف خود را مانند توان عملیاتی، زمان اجرا و خرابی های شغلی نظارت کنید.

هنگام استفاده از Horizon، تمام تنظیمات queue worker شما در یک فایل پیکربندی ساده ذخیره می شود. با تعریف پیکربندی کارگر برنامه خود در یک فایل کنترل‌شده نسخه، می‌توانید به راحتی تعداد کارگران صف برنامه خود را در هنگام استقرار برنامه خود تغییر دهید.

نصب و راه اندازی

Laravel Horizon مستلزم این است که از Redis برای قدرت بخشیدن به صف خود استفاده کنید . بنابراین، باید اطمینان حاصل کنید که اتصال صف شما redis در فایل پیکربندی برنامه شما تنظیم شده است config/queue.php .

می توانید Horizon را با استفاده از مدیریت بسته Composer در پروژه خود نصب کنید:

composer require laravel/horizon

پس از نصب Horizon، دارایی های آن را با استفاده از horizon:install دستور Artisan منتشر کنید:

php artisan horizon:install

پیکربندی

پس از انتشار دارایی های Horizon، فایل پیکربندی اولیه آن در آدرس قرار خواهد گرفت config/horizon.php . این فایل پیکربندی به شما امکان می دهد تا گزینه های queue worker را برای برنامه خود پیکربندی کنید. هر گزینه پیکربندی شامل شرحی از هدف خود است، بنابراین حتما این فایل را به طور کامل بررسی کنید.

Horizon از یک اتصال Redis به نام horizon داخلی استفاده می کند. این نام اتصال Redis رزرو شده است و نباید به یک اتصال Redis دیگر در database.php فایل پیکربندی یا به عنوان مقدار use گزینه موجود در horizon.php فایل پیکربندی اختصاص داده شود.

محیط ها

پس از نصب، گزینه اولیه پیکربندی Horizon که باید با آن آشنا شوید، environments گزینه پیکربندی است. این گزینه پیکربندی آرایه‌ای از محیط‌هایی است که برنامه شما روی آن اجرا می‌شود و گزینه‌های پردازش کارگر را برای هر محیط تعریف می‌کند. به طور پیش فرض، این ورودی حاوی یک production و local محیط است. با این حال، می‌توانید در صورت نیاز محیط‌های بیشتری را اضافه کنید:

'environments' => [
    'production' => [
        'supervisor-1' => [
            'maxProcesses' => 10,
            'balanceMaxShift' => 1,
            'balanceCooldown' => 3,
        ],
    ],
 
    'local' => [
        'supervisor-1' => [
            'maxProcesses' => 3,
        ],
    ],
],

هنگامی که Horizon را راه اندازی می کنید، از گزینه های پیکربندی فرآیند کارگر برای محیطی که برنامه شما در آن اجرا می شود استفاده می کند. به طور معمول، محیط با مقدار APP_ENV متغیر محیطی تعیین می شود . به عنوان مثال، محیط پیش‌فرض local Horizon به گونه‌ای پیکربندی شده است که سه فرآیند کارگر را شروع کند و به طور خودکار تعداد پردازش‌های کارگر اختصاص داده شده به هر صف را متعادل کند. محیط پیش‌فرض production به گونه‌ای پیکربندی شده است که حداکثر 10 فرآیند کارگر را شروع کند و به طور خودکار تعداد پردازش‌های کارگر اختصاص داده شده به هر صف را متعادل کند.

باید اطمینان حاصل کنید که environments بخشی از فایل پیکربندی شما horizon حاوی یک ورودی برای هر محیطی است که قصد دارید Horizon را در آن اجرا کنید.

ناظران

همانطور که در فایل تنظیمات پیش‌فرض Horizon می‌بینید، هر محیط می‌تواند شامل یک یا چند "سرپرست" باشد. به طور پیش فرض، فایل پیکربندی این سرپرست را به صورت supervisor-1 ; با این حال، شما آزادید که نام سرپرستان خود را هر چه می خواهید بنویسید. هر ناظر اساساً مسئول "نظارت" گروهی از فرآیندهای کارگری است و از ایجاد تعادل بین فرآیندهای کارگر در صف ها مراقبت می کند.

اگر می‌خواهید گروه جدیدی از فرآیندهای کارگری را تعریف کنید که باید در آن محیط اجرا شوند، می‌توانید سرپرست‌های اضافی را به یک محیط معین اضافه کنید. اگر می‌خواهید یک استراتژی متوازن متفاوت یا تعداد فرآیند کارگری برای یک صف معین که توسط برنامه شما استفاده می‌شود، تعریف کنید، می‌توانید این کار را انجام دهید.

حالت تعمیر و نگهداری

در حالی که برنامه شما در حالت نگهداری است ، کارهای در صف توسط Horizon پردازش نمی شوند مگر اینکه گزینه سرپرست به صورت فایل پیکربندی Horizon force تعریف شده باشد : true

'environments' => [
    'production' => [
        'supervisor-1' => [
            // ...
            'force' => true,
        ],
    ],
],

مقادیر پیش فرض

در فایل پیکربندی پیش فرض Horizon، یک defaults گزینه پیکربندی را مشاهده خواهید کرد. این گزینه پیکربندی مقادیر پیش فرض را برای سرپرستان برنامه شما مشخص می کند . مقادیر پیکربندی پیش‌فرض سرپرست در پیکربندی ناظر برای هر محیط ادغام می‌شود و به شما این امکان را می‌دهد که از تکرار غیرضروری هنگام تعریف سرپرست‌های خود جلوگیری کنید.

استراتژی های متعادل سازی

برخلاف سیستم صف پیش‌فرض لاراول، Horizon به شما این امکان را می‌دهد تا از بین سه استراتژی متعادل‌سازی کارگر انتخاب کنید: simple , auto و false . این simple استراتژی مشاغل ورودی را به طور مساوی بین فرآیندهای کارگر تقسیم می کند:

'balance' => 'simple',

این auto استراتژی که پیش‌فرض فایل پیکربندی است، تعداد فرآیندهای کارگر در هر صف را بر اساس حجم کاری فعلی صف تنظیم می‌کند. به عنوان مثال، اگر notifications صف شما دارای 1000 شغل معلق باشد در حالی که render صف شما خالی است، Horizon کارگران بیشتری را به notifications صف شما اختصاص می دهد تا زمانی که صف خالی شود.

هنگام استفاده از auto استراتژی، می‌توانید گزینه‌ها minProcesses و maxProcesses پیکربندی را برای کنترل حداقل و حداکثر تعداد فرآیندهای کارگری تعریف کنید که Horizon باید به بالا و پایین‌تر مقیاس شود:

'environments' => [
    'production' => [
        'supervisor-1' => [
            'connection' => 'redis',
            'queue' => ['default'],
            'balance' => 'auto',
            'autoScalingStrategy' => 'time',
            'minProcesses' => 1,
            'maxProcesses' => 10,
            'balanceMaxShift' => 1,
            'balanceCooldown' => 3,
            'tries' => 3,
        ],
    ],
],

مقدار autoScalingStrategy پیکربندی تعیین می‌کند که Horizon بر اساس کل مدت زمانی که برای پاک کردن صف ( time استراتژی) طول می‌کشد یا تعداد کل کارهای موجود در صف ( size استراتژی) فرآیندهای کارگر بیشتری را به صف‌ها اختصاص می‌دهد.

مقادیر پیکربندی balanceMaxShift و balanceCooldown پیکربندی تعیین می‌کنند که Horizon با چه سرعتی مقیاس می‌شود تا تقاضای کارگران را برآورده کند. در مثال بالا، حداکثر یک فرآیند جدید در هر سه ثانیه ایجاد یا از بین می‌رود. شما آزاد هستید که این مقادیر را در صورت لزوم بر اساس نیازهای برنامه خود تغییر دهید.

وقتی این balance گزینه روی تنظیم شود false ، رفتار پیش‌فرض لاراول استفاده می‌شود، که در آن صف‌ها به ترتیبی که در پیکربندی شما فهرست شده‌اند پردازش می‌شوند.

مجوز داشبورد

داشبورد Horizon ممکن است از طریق /horizon مسیر قابل دسترسی باشد. به طور پیش فرض، شما فقط می توانید در local محیط به این داشبورد دسترسی داشته باشید. با این حال، در فایل شما ، یک تعریف دروازه مجوز app/Providers/HorizonServiceProvider.php وجود دارد . این گیت مجوز دسترسی به Horizon را در محیط های غیر محلی کنترل می کند . شما آزاد هستید که این گیت را در صورت نیاز برای محدود کردن دسترسی به نصب Horizon خود تغییر دهید:

/**
 * Register the Horizon gate.
 *
 * This gate determines who can access Horizon in non-local environments.
 */
protected function gate(): void
{
    Gate::define('viewHorizon', function (User $user) {
        return in_array($user->email, [
            'taylor@laravel.com',
        ]);
    });
}

استراتژی های احراز هویت جایگزین

به یاد داشته باشید که لاراول به طور خودکار کاربر تأیید شده را به بسته شدن گیت تزریق می کند. اگر برنامه شما امنیت Horizon را از طریق روش دیگری مانند محدودیت IP فراهم می کند، کاربران Horizon شما ممکن است نیازی به "ورود به سیستم" نداشته باشند. بنابراین، برای اینکه لاراول را مجبور کنید نیازی به احراز هویت نداشته باشد، باید function (User $user) امضای بسته شدن بالا را به تغییر دهید. function (User $user = null)

مشاغل خاموش

گاهی اوقات، ممکن است علاقه ای به مشاهده مشاغل خاصی که توسط برنامه یا بسته های شخص ثالث ارسال شده اند نباشید. به جای اینکه این مشاغل در لیست «کارهای تکمیل شده» شما فضایی اشغال کنند، می توانید آنها را ساکت کنید. برای شروع، نام کلاس کار را به silenced گزینه پیکربندی در فایل پیکربندی برنامه خود اضافه کنید horizon :

'silenced' => [
    App\Jobs\ProcessPodcast::class,
],

از طرف دیگر، کاری که می‌خواهید بی‌صدا کنید، می‌تواند Laravel\Horizon\Contracts\Silenced رابط را پیاده‌سازی کند. اگر یک کار این رابط را پیاده سازی کند، به طور خودکار خاموش می شود، حتی اگر در silenced آرایه پیکربندی وجود نداشته باشد:

use Laravel\Horizon\Contracts\Silenced;
 
class ProcessPodcast implements ShouldQueue, Silenced
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
 
    // ...
}

ارتقاء Horizon

هنگام ارتقاء به نسخه اصلی جدید Horizon، مهم است که راهنمای ارتقا را به دقت مرور کنید . علاوه بر این، هنگام ارتقاء به هر نسخه جدید Horizon، باید دارایی های Horizon را مجدداً منتشر کنید:

php artisan horizon:publish

برای به روز نگه داشتن دارایی ها و جلوگیری از مشکلات در به روز رسانی های بعدی، می توانید این vendor:publish --tag=laravel-assets دستور را به post-update-cmd اسکریپت های فایل برنامه خود اضافه کنید composer.json :

{
    "scripts": {
        "post-update-cmd": [
            "@php artisan vendor:publish --tag=laravel-assets --ansi --force"
        ]
    }
}

Running Horizon

هنگامی که سرپرستان و کارگران خود را در فایل پیکربندی برنامه خود پیکربندی کردید config/horizon.php ، می توانید Horizon را با استفاده از horizon دستور Artisan راه اندازی کنید. این دستور واحد تمام فرآیندهای کارگر پیکربندی شده برای محیط فعلی را شروع می کند:

php artisan horizon

می توانید فرآیند Horizon را متوقف کنید و به آن دستور دهید تا با استفاده از دستورات horizon:pause و horizon:continue Artisan به پردازش کارهای خود ادامه دهد:

php artisan horizon:pause
 
php artisan horizon:continue

همچنین می‌توانید با استفاده از دستورات و Artisan، سرپرست‌های خاص Horizon را متوقف کرده و ادامه دهید : horizon:pause-supervisor horizon:continue-supervisor

php artisan horizon:pause-supervisor supervisor-1
 
php artisan horizon:continue-supervisor supervisor-1

می توانید وضعیت فعلی فرآیند Horizon را با استفاده از horizon:status دستور Artisan بررسی کنید:

php artisan horizon:status

می‌توانید با استفاده از horizon:terminate دستور Artisan، فرآیند Horizon را به‌خوبی خاتمه دهید. همه کارهایی که در حال حاضر توسط آنها پردازش می شود تکمیل می شود و سپس Horizon اجرای آن را متوقف می کند:

php artisan horizon:terminate

استقرار Horizon

هنگامی که آماده استقرار Horizon در سرور واقعی برنامه خود هستید، باید یک مانیتور فرآیند را برای نظارت بر فرمان پیکربندی کنید php artisan horizon و در صورت خروج غیرمنتظره آن را مجددا راه اندازی کنید. نگران نباشید، در ادامه به نحوه نصب مانیتور فرآیند خواهیم پرداخت.

در طول فرآیند استقرار برنامه خود، باید به فرآیند Horizon دستور دهید تا پایان یابد تا توسط مانیتور فرآیند شما مجدداً راه اندازی شود و تغییرات کد شما را دریافت کند:

php artisan horizon:terminate

نصب سوپروایزر

Supervisor یک مانیتور فرآیند برای سیستم عامل لینوکس است و horizon در صورت توقف اجرای فرآیند شما به طور خودکار مجدداً راه اندازی می شود. برای نصب Supervisor در اوبونتو، می توانید از دستور زیر استفاده کنید. اگر از اوبونتو استفاده نمی کنید، احتمالاً می توانید Supervisor را با استفاده از مدیریت بسته سیستم عامل خود نصب کنید:

sudo apt-get install supervisor

اگر پیکربندی Supervisor به نظر می رسد بسیار دشوار است، از Laravel Forge استفاده کنید ، که به طور خودکار Supervisor را برای پروژه های Laravel شما نصب و پیکربندی می کند.

پیکربندی سرپرست

فایل های پیکربندی ناظر معمولاً در دایرکتوری سرور شما ذخیره می شوند /etc/supervisor/conf.d . در این فهرست، می‌توانید هر تعداد فایل پیکربندی ایجاد کنید که به سرپرست آموزش می‌دهد که چگونه فرآیندهای شما باید نظارت شوند. به عنوان مثال، بیایید یک horizon.conf فایل ایجاد کنیم که یک horizon فرآیند را شروع و نظارت کند:

[program:horizon]
process_name=%(program_name)s
command=php /home/forge/example.com/artisan horizon
autostart=true
autorestart=true
user=forge
redirect_stderr=true
stdout_logfile=/home/forge/example.com/horizon.log
stopwaitsecs=3600

هنگام تعریف پیکربندی Supervisor خود، باید مطمئن شوید که مقدار از stopwaitsecs تعداد ثانیه های مصرف شده توسط طولانی ترین کار شما بیشتر باشد. در غیر این صورت، Supervisor ممکن است کار را قبل از اتمام پردازش آن از بین ببرد.

در حالی که مثال های بالا برای سرورهای مبتنی بر اوبونتو معتبر هستند، مکان و پسوند فایل مورد انتظار از فایل های پیکربندی Supervisor ممکن است بین سایر سیستم عامل های سرور متفاوت باشد. لطفاً برای اطلاعات بیشتر به اسناد سرور خود مراجعه کنید.

راه اندازی سرپرست

پس از ایجاد فایل پیکربندی، می توانید پیکربندی Supervisor را به روز کنید و فرآیندهای نظارت شده را با استفاده از دستورات زیر شروع کنید:

sudo supervisorctl reread
 
sudo supervisorctl update
 
sudo supervisorctl start horizon

برای اطلاعات بیشتر در مورد اجرای Supervisor، به مستندات Supervisor مراجعه کنید .

برچسب ها

Horizon به شما این امکان را می‌دهد که «برچسب‌ها» را به مشاغل، از جمله پست‌های ارسالی، رویدادهای پخش، اعلان‌ها و شنوندگان رویداد در صف اختصاص دهید. در واقع، Horizon به طور هوشمندانه و خودکار اکثر مشاغل را بسته به مدل های Eloquent که به شغل متصل شده اند برچسب گذاری می کند. برای مثال به شغل زیر نگاهی بیندازید:

<?php
 
namespace App\Jobs;
 
use App\Models\Video;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
 
class RenderVideo implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
 
    /**
     * Create a new job instance.
     */
    public function __construct(
        public Video $video,
    ) {}
 
    /**
     * Execute the job.
     */
    public function handle(): void
    {
        // ...
    }
}

اگر این کار با نمونه ای در صف قرار گیرد App\Models\Video که دارای id ویژگی باشد 1 ، به طور خودکار تگ را دریافت می کند App\Models\Video:1 . این به این دلیل است که Horizon ویژگی های شغل را برای هر مدل Eloquent جستجو می کند. اگر مدل‌های Eloquent پیدا شوند، Horizon با استفاده از نام کلاس و کلید اصلی مدل، کار را هوشمندانه برچسب‌گذاری می‌کند:

use App\Jobs\RenderVideo;
use App\Models\Video;
 
$video = Video::find(1);
 
RenderVideo::dispatch($video);

برچسب زدن دستی مشاغل

اگر می خواهید به صورت دستی تگ ها را برای یکی از اشیاء در صف خود تعریف کنید، می توانید یک tags متد در کلاس تعریف کنید:

class RenderVideo implements ShouldQueue
{
    /**
     * Get the tags that should be assigned to the job.
     *
     * @return array<int, string>
     */
    public function tags(): array
    {
        return ['render', 'video:'.$this->video->id];
    }
}

برچسب زدن دستی شنوندگان رویداد

هنگام بازیابی برچسب ها برای شنونده رویداد در صف، Horizon به طور خودکار نمونه رویداد را به tags متد ارسال می کند و به شما امکان می دهد داده های رویداد را به برچسب ها اضافه کنید:

class SendRenderNotifications implements ShouldQueue
{
    /**
     * Get the tags that should be assigned to the listener.
     *
     * @return array<int, string>
     */
    public function tags(VideoRendered $event): array
    {
        return ['video:'.$event->video->id];
    }
}

اطلاعیه

هنگام پیکربندی Horizon برای ارسال اعلان‌های Slack یا SMS، باید پیش‌نیازهای کانال اعلان مربوطه را بررسی کنید .

اگر می‌خواهید زمانی که یکی از صف‌های شما زمان انتظار طولانی دارد به شما اطلاع داده شود، می‌توانید از روش‌های Horizon::routeMailNotificationsTo ، Horizon::routeSlackNotificationsTo و و استفاده کنید Horizon::routeSmsNotificationsTo . می توانید این متدها را از boot متد برنامه خود فراخوانی کنید App\Providers\HorizonServiceProvider :

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    parent::boot();
 
    Horizon::routeSmsNotificationsTo('15556667777');
    Horizon::routeMailNotificationsTo('example@example.com');
    Horizon::routeSlackNotificationsTo('slack-webhook-url', '#channel');
}

پیکربندی آستانه های زمان انتظار اعلان

می توانید پیکربندی کنید که چند ثانیه در config/horizon.php فایل پیکربندی برنامه شما به عنوان "انتظار طولانی" در نظر گرفته شود. گزینه waits پیکربندی در این فایل به شما امکان می دهد آستانه انتظار طولانی را برای هر ترکیب اتصال / صف کنترل کنید. هر ترکیب نامشخص اتصال / صف به طور پیش فرض در آستانه انتظار طولانی 60 ثانیه است:

'waits' => [
    'redis:critical' => 30,
    'redis:default' => 60,
    'redis:batch' => 120,
],

معیارهای

Horizon شامل یک داشبورد معیار است که اطلاعاتی را در مورد زمان انتظار شغل و صف و توان ارائه می دهد. برای پر کردن این داشبورد، باید snapshot دستور Artisan Horizon را طوری پیکربندی کنید که هر پنج دقیقه در فایل برنامه شما اجرا شود routes/console.php :

use Illuminate\Support\Facades\Schedule;
 
Schedule::command('horizon:snapshot')->everyFiveMinutes();

حذف مشاغل ناموفق

اگر می خواهید یک کار ناموفق را حذف کنید، می توانید از horizon:forget دستور استفاده کنید. این horizon:forget فرمان ID یا UUID کار ناموفق را به عنوان تنها آرگومان خود می پذیرد:

php artisan horizon:forget 5

پاک کردن مشاغل از صف

اگر می خواهید همه کارها را از صف پیش فرض برنامه خود حذف کنید، می توانید این کار را با استفاده از horizon:clear دستور Artisan انجام دهید:

php artisan horizon:clear

می توانید queue گزینه ای برای حذف مشاغل از یک صف خاص ارائه دهید:

php artisan horizon:clear --queue=emails