Laravel Envoy

• 简介
• 安装
• 编写任务
  • 定义任务
  • 多台服务器
  • 设置
  • 变量
  • 故事
  • 钩子
• 运行任务
  • 确认任务执行
• 通知
  • Slack
  • Discord
  • Telegram
  • Microsoft Teams

简介

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

安装

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

composer require laravel/envoy --dev

安装 Envoy 后，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 文件，以便将它们的 story 和任务添加到你的文件。 导入文件后，你可以像在自己的 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

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

@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

故事

故事将一组任务分组在单个方便的名称下。 例如，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

编写完 story 后，你可以像调用任务一样调用它

php vendor/bin/envoy run deploy

钩子

当任务和 story 运行时，会执行许多钩子。 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 文件中定义的任务或 story，请执行 Envoy 的 run 命令，并传递要执行的任务或 story 的名称。 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 控制面板中创建一个“传入 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

Telegram

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 有许多其他属性可以自定义你的消息框，如标题、摘要和部分。 你可以在 Microsoft Teams 文档 中找到更多信息。 你应该将整个 Webhook URL 传递到 @microsoftTeams 指令中

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