Skip to content

Latest commit

 

History

History
332 lines (241 loc) · 17.3 KB

envoy.md

File metadata and controls

332 lines (241 loc) · 17.3 KB
Raw

Laravel 9 · Пакет Laravel Envoy

Введение

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'])

Импорт задач 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

Вы можете получить доступ к параметрам ваших задач, используя синтаксис «вывода» 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

Перед выполнением каждой задачи будут выполняться все хуки @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) {
        // В одной из задач произошли ошибки ...
    }
@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 принимает 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

Discord

Envoy также поддерживает отправку уведомлений в Discord после выполнения каждой задачи. Директива @discord принимает WebHook URL и сообщение. Вы можете получить WebHook URL, создав «Webhook» в настройках сервера и выбрав канал, на который WebHook должен публиковать сообщения. Вы должны передать полный WebHook URL в директиву @discord:

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

Telegram

Envoy также поддерживает отправку уведомлений в Telegram после выполнения каждой задачи. Директива @telegram принимает идентификатор бота Telegram и идентификатор чата. Вы можете получить свой идентификатор бота, создав нового бота в BotFather. Вы можете получить действительный идентификатор чата, используя @username_to_id_bot. Вы должны передать полный идентификатор бота и идентификатор чата в директиву @telegram:

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

Microsoft Teams

Envoy также поддерживает отправку уведомлений в Microsoft Teams после выполнения каждой задачи. Директива @microsoftTeams принимает веб-хук Teams (обязательно), сообщение, цвет темы (по типу сообщения: успешно, информация, предупреждение, ошибка) и массив параметров. Вы можете получить веб-хук Teams, создав новый входящий веб-хук. В Teams API есть множество других атрибутов для настройки сообщения, например заголовок, сводка и разделы. Дополнительную информацию можно найти в документации Microsoft Teams. Вы должны передать полный URL-адрес веб-хука в директиву @microsoftTeams:

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