Envoy-Laravel 文档-果果开发

简介

Laravel Envoy 是一款用于在远程服务器上执行常用任务的工具。借助 Blade 风格的语法，你可以轻松配置部署任务、Artisan 命令等。目前，Envoy 仅支持 Mac 和 Linux 操作系统。不过，借助 WSL2，也可以在 Windows 上使用。

安装

首先，使用 Composer 包管理器将 Envoy 安装到你的项目中：

composer require laravel/envoy --dev

安装完成后，Envoy 可执行文件将位于应用的 vendor/bin 目录中：

php vendor/bin/envoy

编写任务

定义任务

任务是 Envoy 的基本构成单元。任务定义了在被调用时应在远程服务器上执行的 shell 命令。例如，你可以定义一个任务，在所有应用的队列工作服务器上执行 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 声明中，应放置任务被调用时要在服务器上执行的 shell 命令。

本地任务

你可以将服务器的 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

设置

有时，你可能需要在使用 Envoy 任务之前执行一些任意的 PHP 代码。你可以使用 @setup 指令来定义一段应在任务运行前执行的 PHP 代码：

@setup
    $now = new DateTime;
@endsetup

如果需要在任务执行前引入其他 PHP 文件，可以在 Envoy.blade.php 文件顶部使用 @include 指令：

@include('vendor/autoload.php')

@task('restart-queues')
    # ...
@endtask

变量

如有需要，你可以在调用 Envoy 时，通过命令行指定参数，将其传递给 Envoy 任务：

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

你可以在任务中使用 Blade 的 “echo” 语法来访问这些选项。你还可以在任务中定义 Blade 的 if 语句和循环。例如，我们来在执行 git pull 命令前，检查 $branch 变量是否存在：

@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

故事

故事（Stories）可将一组任务归拢到同一个便捷的名称之下。例如，一个 deploy 故事可以在其定义中列出任务名称，从而运行 update-code 和 install-dependencies 任务：

@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

钩子

任务和故事运行时，会执行一系列钩子（hooks）。Envoy 支持的钩子类型有 @before、@after、@error、@success 和 @finished。这些钩子中的所有代码都会被当作 PHP 进行解析，并会在本地执行，而不会在你任务所交互的远程服务器上执行。

每种钩子你都可以按需定义任意多个，它们会按照在 Envoy 脚本中出现的顺序依次执行。

`@before`

在每个任务执行之前，Envoy 脚本中注册的所有 @before 钩子都会执行。@before 钩子会接收到即将执行的任务名称：

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

`@after`

在每个任务执行之后，Envoy 脚本中注册的所有 @after 钩子都会执行。@after 钩子会接收到已执行的任务名称：

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

`@error`

在每次任务失败后（即退出状态码大于 0 时），Envoy 脚本中注册的所有 @error 钩子都会执行。@error 钩子会接收到已执行的任务名称：

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

`@success`

如果所有任务都无差错地执行完成，Envoy 脚本中注册的所有 @success 钩子都会执行：

@success
    // ...
@endsuccess

`@finished`

在所有任务执行完毕后（无论退出状态如何），所有的 @finished 钩子都会执行。@finished 钩子会接收到已完成任务的退出状态码，该状态码可能是 null，也可能是大于或等于 0 的 integer：

@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

通知

Slack

Envoy 支持在每个任务执行完毕后，向 Slack 发送通知。@slack 指令接收一个 Slack 钩子 URL 以及频道/用户名。你可以在 Slack 控制面板中创建 “Incoming WebHooks” 集成来获取 webhook URL。

你应该将完整的 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 指令接收一个 Discord 钩子 URL 和一条消息。你可以在服务器设置中创建一个“Webhook”，并选择该 Webhook 应该发布到的频道，以此获取你的 webhook URL。你应该将完整的 Webhook URL 传递给 @discord 指令：

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

Envoy 还支持在每次任务执行完毕后，向 Telegram 发送通知。@telegram 指令接收一个 Telegram Bot ID 和一个 Chat ID。你可以通过 BotFather 创建一个新机器人，以此获取你的 Bot ID。你可以使用 @username_to_id_bot 获取有效的 Chat ID。你应该将完整的 Bot ID 和 Chat ID 传递给 @telegram 指令：

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

Microsoft Teams

Envoy 还支持在每次任务执行完毕后，向 Microsoft Teams 发送通知。@microsoftTeams 指令接收一个 Teams Webhook（必填）、一条消息、主题颜色（success、info、warning、error）以及一个选项数组。你可以通过创建一个新的传入 webhook 来获取 Teams Webhook。Teams API 还有许多其他属性，可用于自定义你的消息框，如 title、summary 和 sections。你可以在Microsoft Teams 文档中查找更多信息。你应该将完整的 Webhook URL 传递给 @microsoftTeams 指令：

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