git 9b744ef2a5e47ac201b3a06831d64513f6bf69c9
Laravel Envoy – это инструмент для выполнения общих задач, запускаемых на ваших удаленных серверах. Используя синтаксис в стиле Blade, вы можете легко настроить задачи для развертывания, команд Artisan и многое другое. В настоящее время Envoy поддерживает только операционные системы Mac и Linux. Однако поддержка Windows достижима с помощью WSL2.
Для начала установите Envoy с помощью менеджера пакетов Composer в свой проект:
composer require laravel/envoy --dev
После установки исполняемый файл Envoy будет доступен в каталоге вашего приложения vendor/bin
:
php vendor/bin/envoy
Задачи – это основной «строительный блок» Envoy. Задачи определяются командами оболочки, выполняемыми на ваших удаленных серверах при вызове задачи. Например, вы можете определить задачу, которая выполнит команду php artisan queue:restart
обработчика очереди на серверах вашего приложения.
Все ваши задачи Envoy должны быть определены в файле Envoy.blade.php
в корне вашего приложения. Например:
@servers(['web' => ['[email protected]'], 'workers' => ['[email protected]']])
@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
По желанию можно выполнить произвольный 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
Вы можете получить доступ к параметрам ваших задач, используя синтаксис «вывода» Blade. Вы также можете определять операторы if
и циклы Blade в своих задачах. Например, давайте проверим наличие переменной $branch
перед выполнением команды git pull
:
@servers(['web' => ['[email protected]']])
@task('deploy', ['on' => 'web'])
cd /home/user/example.com
@if ($branch)
git pull origin {{ $branch }}
@endif
php artisan migrate --force
@endtask
Истории группируют набор задач под одним удобным названием. Например, вы можете сгруппировать запуск задач update-code
и install-dependencies
, перечислив их имена в определении истории deploy
:
@servers(['web' => ['[email protected]']])
@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
, зарегистрированные в вашем скрипте Envoy. Хуки @before
получают имя задачи, которая будет выполняться:
@before
if ($task === 'deploy') {
// ...
}
@endbefore
После выполнения каждой задачи будут выполняться все хуки @after
, зарегистрированные в вашем сценарии Envoy. Хуки @after
получат имя запущенной задачи:
@after
if ($task === 'deploy') {
// ...
}
@endafter
После каждого сбоя задачи (выход с кодом состояния больше 0
) будут выполняться все хуки @error
, зарегистрированные в вашем сценарии Envoy. Хуки @error
получат имя запущенной задачи:
@error
if ($task === 'deploy') {
// ...
}
@enderror
Если все задачи выполнены без ошибок, то все хуки @success
, зарегистрированные в вашем сценарии Envoy, будут выполнены:
@success
// ...
@endsuccess
После выполнения всех задач (независимо от статуса выхода) будут выполнены все хуки @finished
. Хуки @finished
получат код состояния завершенной задачи, который может быть null
или integer
, большим или равным 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
Envoy поддерживает отправку уведомлений в Slack после выполнения каждой задачи. Директива @slack
принимает WebHook URL и имя канала / пользователя. Вы можете получить WebHook URL, создав интеграцию «Incoming WebHooks» в панели управления Slack.
Вы должны передать полный WebHook URL в качестве первого аргумента директивы @slack
. Вторым аргументом, передаваемым директиве @slack
, должно быть имя канала #channel
или имя пользователя @user
:
@finished
@slack('webhook-url', '#bots')
@endfinished
По умолчанию уведомления Envoy отправляют сообщение в канал уведомлений с описанием выполненной задачи. Однако вы можете назначить свое сообщение, передав третий аргумент директиве @slack
:
@finished
@slack('webhook-url', '#bots', 'Hello, Slack.')
@endfinished
Envoy также поддерживает отправку уведомлений в Discord после выполнения каждой задачи. Директива @discord
принимает WebHook URL и сообщение. Вы можете получить WebHook URL, создав «Webhook» в настройках сервера и выбрав канал, на который WebHook должен публиковать сообщения. Вы должны передать полный WebHook URL в директиву @discord
:
@finished
@discord('discord-webhook-url')
@endfinished
Envoy также поддерживает отправку уведомлений в Telegram после выполнения каждой задачи. Директива @telegram
принимает идентификатор бота Telegram и идентификатор чата. Вы можете получить свой идентификатор бота, создав нового бота в BotFather. Вы можете получить действительный идентификатор чата, используя @username_to_id_bot
. Вы должны передать полный идентификатор бота и идентификатор чата в директиву @telegram
:
@finished
@telegram('bot-id','chat-id')
@endfinished
Envoy также поддерживает отправку уведомлений в Microsoft Teams после выполнения каждой задачи. Директива @microsoftTeams
принимает WebHook URL (обязательный), сообщение, цвет темы (success, info, warning, error) и массив параметров. Вы можете получить свой Teams WebHook URL, создав новый incoming webhook. В Teams API есть множество других атрибутов для настройки окна сообщения, например заголовок, сводка и разделы. Дополнительную информацию можно найти в Microsoft Teams documentation. Вы должны передать весь URL-адрес веб-перехватчика в директиву @microsoftTeams
:
@finished
@microsoftTeams('webhook-url')
@endfinished