Русский
Español- Пакеты
- Laravel Envoy
Документация Laravel 10.x
Laravel Envoy
Присоединяйся к нашему Telegram сообществу @webblend!
Здесь ты найдешь сниппеты по Laravel и полезные советы по веб-разработке.
Введение
Laravel Envoy - это инструмент для выполнения общих задач, которые вы выполняете на своих удаленных серверах. Используя синтаксис в стиле Blade, вы можете легко настраивать задачи для развертывания, выполнения команд Artisan и многого другого. В настоящее время Envoy поддерживает только операционные системы Mac и Linux. Тем не менее, поддержка Windows достижима с использованием WSL2.
Установка
Сначала установите Envoy в свой проект, используя менеджер пакетов Composer:
composer require laravel/envoy --devПосле установки Envoy исполняемый файл Envoy будет доступен в каталоге vendor/bin вашего приложения:
php vendor/bin/envoyНаписание задач
Определение задач
Задачи - это основной строительный блок Envoy. Задачи определяют команды оболочки, которые должны выполняться на ваших удаленных серверах при вызове задачи. Например, вы можете определить задачу, которая выполняет команду php artisan queue:restart на всех серверах вашего рабочего процесса очереди приложения.
Все ваши задачи Envoy должны быть определены в файле Envoy.blade.php в корне вашего приложения. Вот пример, чтобы вы смогли начать:
@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'])Импорт задач из Envoy
С помощью директивы @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Настройка
Иногда вам может потребоваться выполнить произвольный PHP-код перед выполнением ваших задач Envoy. Вы можете использовать директиву @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. Вы также можете определять операторы Blade if и циклы внутри ваших задач. Например, давайте проверим наличие переменной $branch перед выполнением команды git pull:
@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, перечислив имена задач в ее определении:
@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 или целым числом, большим или равным 0:
@finished if ($exitCode > 0) { // В одной из задач произошли ошибки... }@endfinishedЗапуск задач
Чтобы выполнить задачу или историю, определенную в файле Envoy.blade.php вашего приложения, выполните команду run Envoy, передав имя задачи или истории, которую вы хотите выполнить. 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Уведомления
Slack
Envoy поддерживает отправку уведомлений в Slack после выполнения каждой задачи. Директива @slack принимает URL-адрес Slack hook и канал/имя пользователя. Вы можете получить свой URL-адрес веб-крючка, создав "входящую веб-крючку" в панели управления Slack.
Вы должны передать весь URL-адрес веб-крючка в качестве первого аргумента, переданного директиве @slack. Вторым аргументом, переданным директиве @slack, должно быть имя канала (#channel) или имя пользователя (@user):
@finished @slack('webhook-url', '#bots')@endfinishedПо умолчанию уведомления Envoy будут отправлять сообщение в канал уведомлений, описывающее выполненную задачу. Однако вы можете перезаписать это сообщение собственным сообщением, передав третий аргумент директиве @slack:
@finished @slack('webhook-url', '#bots', 'Hello, Slack.')@endfinishedDiscord
Envoy также поддерживает отправку уведомлений в Discord после выполнения каждой задачи. Директива @discord принимает URL-адрес Discord hook и сообщение. Вы можете получить свой URL-адрес веб-крючка, создав "Webhook" в настройках вашего сервера и выбрав канал, в который должен поступить веб-крючок. Вы должны передать весь URL-адрес веб-крючка в директиву @discord:
@finished @discord('discord-webhook-url')@endfinishedTelegram
Envoy также поддерживает отправку уведомлений в Telegram после выполнения каждой задачи. Директива @telegram принимает идентификатор бота Telegram и идентификатор чата. Вы можете получить идентификатор бота, создав нового бота с помощью BotFather. Вы можете получить допустимый идентификатор чата с использованием @username_to_id_bot. Вы должны передать полный идентификатор бота и чата в директиву @telegram:
@finished @telegram('bot-id','chat-id')@endfinishedMicrosoft Teams
Envoy также поддерживает отправку уведомлений в Microsoft Teams после выполнения каждой задачи. Директива @microsoftTeams принимает Teams Webhook (обязательно), сообщение, цвет темы (success, info, warning, error) и массив опций. Вы можете получить свой Teams Webhook, создав новый входящий веб-крючок. У Teams API есть много других атрибутов для настройки вашего блока сообщений, таких как заголовок, резюме и секции. Более подробную информацию вы найдете в документации Microsoft Teams. Вы должны передать весь URL-адрес веб-крючка в директиву @microsoftTeams:
@finished @microsoftTeams('webhook-url')@endfinished