فرستاده لاراول

• معرفی
• نصب و راه اندازی
• وظایف نوشتن
  • تعریف وظایف
  • چندین سرور
  • برپایی
  • متغیرها
  • داستان ها
  • قلاب
• در حال اجرا وظایف
  • تایید اجرای کار
• اطلاعیه
  • سستی
  • اختلاف
  • تلگرام
  • تیم های مایکروسافت

معرفی

Laravel Envoy ابزاری برای اجرای وظایف رایجی است که روی سرورهای راه دور خود اجرا می کنید. با استفاده از نحو Blade style، می‌توانید به راحتی وظایف مربوط به استقرار، دستورات Artisan و موارد دیگر را تنظیم کنید. در حال حاضر Envoy تنها از سیستم عامل های مک و لینوکس پشتیبانی می کند. با این حال، پشتیبانی از ویندوز با استفاده از WSL2 قابل دستیابی است .

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

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

composer require laravel/envoy --dev

پس از نصب Envoy، باینری Envoy در vendor/bin فهرست برنامه شما در دسترس خواهد بود:

php vendor/bin/envoy

وظایف نوشتن

تعریف وظایف

Tasks بلوک اصلی سازنده Envoy هستند. Tasks دستورات پوسته ای را تعریف می کند که باید در سرورهای راه دور شما هنگام فراخوانی کار اجرا شوند. به عنوان مثال، ممکن است وظیفه ای را تعریف کنید که این php artisan queue:restart دستور را در تمام سرورهای queue worker برنامه شما اجرا کند.

تمام وظایف Envoy شما باید در Envoy.blade.php فایلی در ریشه برنامه شما تعریف شود. در اینجا یک مثال برای شروع شما آورده شده است:

@servers(['web' => ['user@192.168.1.1'], 'workers' => ['user@192.168.1.2']])
 
@task('restart-queues', ['on' => 'workers'])
    cd /home/user/example.com
    php artisan queue:restart
@endtask

همانطور که می بینید، آرایه ای از @servers در بالای فایل تعریف شده است که به شما امکان می دهد از طریق on گزینه اعلان وظایف خود به این سرورها ارجاع دهید. اظهارنامه @servers باید همیشه در یک خط قرار گیرد. در اعلان‌های خود @task ، باید دستورات پوسته‌ای را که باید هنگام فراخوانی وظیفه بر روی سرورهای خود اجرا شوند، قرار دهید.

وظایف محلی

می توانید با تعیین آدرس IP سرور به صورت زیر، یک اسکریپت را مجبور به اجرا در رایانه محلی خود کنید 127.0.0.1 :

@servers(['localhost' => '127.0.0.1'])

واردات وظایف فرستاده

با استفاده از @import دستورالعمل، می‌توانید فایل‌های Envoy دیگر را وارد کنید تا داستان‌ها و وظایف آن‌ها به شما اضافه شود. پس از وارد شدن فایل‌ها، می‌توانید وظایفی را که در آن‌ها وجود دارد، طوری اجرا کنید که گویی در فایل Envoy خودتان تعریف شده‌اند:

@import('vendor/package/Envoy.blade.php')

چندین سرور

Envoy به شما اجازه می دهد تا به راحتی یک کار را در چندین سرور اجرا کنید. ابتدا سرورهای اضافی را به @servers اعلان خود اضافه کنید. به هر سرور باید یک نام منحصر به فرد اختصاص داده شود. هنگامی که سرورهای اضافی خود را تعریف کردید، می توانید هر یک از سرورهای موجود در on آرایه کار را فهرست کنید:

@servers(['web-1' => '192.168.1.1', 'web-2' => '192.168.1.2'])
 
@task('deploy', ['on' => ['web-1', 'web-2']])
    cd /home/user/example.com
    git pull origin {{ $branch }}
    php artisan migrate --force
@endtask

اجرای موازی

به طور پیش فرض، وظایف بر روی هر سرور به صورت سریال اجرا می شود. به عبارت دیگر، اجرای یک کار در سرور اول قبل از ادامه اجرا در سرور دوم به پایان می رسد. اگر می خواهید یک کار را در چندین سرور به صورت موازی اجرا کنید، این parallel گزینه را به اعلان وظیفه خود اضافه کنید:

@servers(['web-1' => '192.168.1.1', 'web-2' => '192.168.1.2'])
 
@task('deploy', ['on' => ['web-1', 'web-2'], 'parallel' => true])
    cd /home/user/example.com
    git pull origin {{ $branch }}
    php artisan migrate --force
@endtask

برپایی

گاهی اوقات، ممکن است لازم باشد قبل از اجرای وظایف Envoy خود کد PHP دلخواه را اجرا کنید. می توانید از @setup دستورالعمل برای تعریف یک بلوک از کد PHP استفاده کنید که باید قبل از انجام وظایف شما اجرا شود:

@setup
    $now = new DateTime;
@endsetup

اگر قبل از اجرای وظیفه خود نیاز به فایل های PHP دیگری دارید، می توانید از @include دستورالعمل موجود در بالای Envoy.blade.php فایل خود استفاده کنید:

@include('vendor/autoload.php')
 
@task('restart-queues')
    # ...
@endtask

متغیرها

در صورت نیاز، می‌توانید آرگومان‌هایی را با مشخص کردن آن‌ها در خط فرمان هنگام فراخوانی Envoy به وظایف Envoy ارسال کنید:

php vendor/bin/envoy run deploy --branch=master

شما می توانید با استفاده از نحو "echo" Blade به گزینه های درون وظایف خود دسترسی داشته باشید. همچنین می توانید if عبارات و حلقه های Blade را در وظایف خود تعریف کنید. به عنوان مثال، اجازه دهید $branch قبل از اجرای دستور ، وجود متغیر را بررسی کنیم git pull :

@servers(['web' => ['user@192.168.1.1']])
 
@task('deploy', ['on' => 'web'])
    cd /home/user/example.com
 
    @if ($branch)
        git pull origin {{ $branch }}
    @endif
 
    php artisan migrate --force
@endtask

داستان ها

داستان ها مجموعه ای از وظایف را تحت یک نام واحد و راحت گروه بندی می کنند. به عنوان مثال، یک deploy داستان ممکن است وظایف update-code و install-dependencies را با فهرست کردن نام وظایف در تعریف خود اجرا کند:

@servers(['web' => ['user@192.168.1.1']])
 
@story('deploy')
    update-code
    install-dependencies
@endstory
 
@task('update-code')
    cd /home/user/example.com
    git pull origin master
@endtask
 
@task('install-dependencies')
    cd /home/user/example.com
    composer install
@endtask

هنگامی که داستان نوشته شد، می توانید آن را به همان روشی که یک کار را فراخوانی می کنید، فراخوانی کنید:

php vendor/bin/envoy run deploy

قلاب

هنگامی که وظایف و داستان ها اجرا می شوند، تعدادی هوک اجرا می شوند. انواع قلاب های پشتیبانی شده توسط Envoy عبارتند از @before , @after , @error , @success , و @finished . تمام کدهای موجود در این هوک ها به صورت PHP تفسیر می شوند و به صورت محلی اجرا می شوند، نه روی سرورهای راه دور که وظایف شما با آنها تعامل دارند.

می توانید به تعداد دلخواه از هر یک از این قلاب ها تعریف کنید. آنها به ترتیبی که در اسکریپت Envoy شما ظاهر می شوند اجرا می شوند.

@before

قبل از اجرای هر کار، تمام @before هوک های ثبت شده در اسکریپت Envoy شما اجرا می شوند. قلاب @before ها نام وظیفه ای را دریافت می کنند که اجرا می شود:

@before
    if ($task === 'deploy') {
        // ...
    }
@endbefore

@after

پس از اجرای هر کار، تمام @after هوک های ثبت شده در اسکریپت Envoy شما اجرا می شوند. قلاب @after ها نام وظیفه ای را که اجرا شده است دریافت می کنند:

@after
    if ($task === 'deploy') {
        // ...
    }
@endafter

@error

پس از هر شکست کاری (خروج با کد وضعیت بزرگتر از 0 )، همه @error هوک های ثبت شده در اسکریپت Envoy شما اجرا می شوند. قلاب @error ها نام وظیفه ای را که اجرا شده است دریافت می کنند:

@error
    if ($task === 'deploy') {
        // ...
    }
@enderror

@success

اگر همه کارها بدون خطا اجرا شده باشند، همه @success هوک های ثبت شده در اسکریپت Envoy شما اجرا می شوند:

@success
    // ...
@endsuccess

@finished

پس از انجام تمام وظایف (صرف نظر از وضعیت خروج)، همه @finished هوک ها اجرا می شوند. قلاب @finished ها کد وضعیت کار تکمیل شده را دریافت می کنند که ممکن است null بزرگتر integer یا مساوی با 0 :

@finished
    if ($exitCode > 0) {
        // There were errors in one of the tasks...
    }
@endfinished

در حال اجرا وظایف

برای اجرای یک کار یا داستانی که در فایل برنامه شما تعریف شده است Envoy.blade.php ، دستور Envoy را اجرا کنید run و نام وظیفه یا داستانی را که می خواهید اجرا کنید، ارسال کنید. Envoy وظیفه را اجرا می کند و خروجی را از سرورهای راه دور شما در حین اجرای کار نمایش می دهد:

php vendor/bin/envoy run deploy

تایید اجرای کار

اگر می‌خواهید قبل از اجرای یک وظیفه معین در سرورهای خود از شما خواسته شود تا تأیید شود، باید دستورالعمل را confirm به اعلان وظیفه خود اضافه کنید. این گزینه به ویژه برای عملیات مخرب مفید است:

@task('deploy', ['on' => 'web', 'confirm' => true])
    cd /home/user/example.com
    git pull origin {{ $branch }}
    php artisan migrate
@endtask

اطلاعیه

سستی

Envoy از ارسال اعلان‌ها به Slack پس از اجرای هر وظیفه پشتیبانی می‌کند. این @slack دستورالعمل یک URL هوک Slack و یک کانال / نام کاربری را می پذیرد. می‌توانید URL وب هوک خود را با ایجاد یک ادغام «WebHooks ورودی» در کنترل پنل Slack خود بازیابی کنید.

شما باید کل URL webhook را به عنوان اولین آرگومان ارائه شده به @slack دستورالعمل ارسال کنید. دومین آرگومان داده شده به @slack دستورالعمل باید نام کانال ( #channel ) یا نام کاربری ( @user ) باشد:

@finished
    @slack('webhook-url', '#bots')
@endfinished

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

@finished
    @slack('webhook-url', '#bots', 'Hello, Slack.')
@endfinished

اختلاف

Envoy همچنین از ارسال اعلان‌ها به Discord پس از اجرای هر وظیفه پشتیبانی می‌کند. این @discord دستورالعمل URL هوک Discord و یک پیام را می پذیرد. می‌توانید با ایجاد یک «Webhook» در تنظیمات سرور خود و انتخاب کانالی که وب‌هوک باید در کدام کانال پست کند، URL وب هوک خود را بازیابی کنید. شما باید کل URL Webhook را به @discord دستورالعمل ارسال کنید:

@finished
    @discord('discord-webhook-url')
@endfinished

تلگرام

Envoy همچنین از ارسال نوتیفیکیشن به تلگرام پس از انجام هر کار پشتیبانی می کند. این @telegram دستورالعمل شناسه ربات تلگرام و شناسه چت را می پذیرد. شما می توانید ID ربات خود را با ایجاد یک ربات جدید با استفاده از BotFather بازیابی کنید . با استفاده از @username_to_id_bot می‌توانید یک شناسه چت معتبر را بازیابی کنید . شما باید کل Bot ID و Chat ID را در @telegram دستورالعمل ارسال کنید:

@finished
    @telegram('bot-id','chat-id')
@endfinished

تیم های مایکروسافت

Envoy همچنین از ارسال اعلان‌ها به تیم‌های مایکروسافت پس از انجام هر کار پشتیبانی می‌کند. این @microsoftTeams دستورالعمل یک Teams Webhook (الزامی)، یک پیام، رنگ تم (موفقیت، اطلاعات، هشدار، خطا) و مجموعه‌ای از گزینه‌ها را می‌پذیرد. شما می توانید با ایجاد یک وب هوک جدید، Teams Webhook خود را بازیابی کنید . Teams API دارای بسیاری از ویژگی های دیگر برای سفارشی کردن جعبه پیام شما مانند عنوان، خلاصه و بخش ها است. می توانید اطلاعات بیشتری را در مستندات تیم های مایکروسافت بیابید . شما باید کل URL Webhook را به @microsoftTeams دستورالعمل ارسال کنید:

@finished
    @microsoftTeams('webhook-url')
@endfinished