跳至内容

Laravel Envoy

介绍

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

安装

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

1composer require laravel/envoy --dev

一旦安装了 Envoy，Envoy 二进制文件将出现在应用程序的vendor/bin目录中：

1php vendor/bin/envoy

写作任务

定义任务

任务是 Envoy 的基本构建块。任务定义了在调用时应在远程服务器上执行的 shell 命令。例如，您可以定义一个任务，php artisan queue:restart在应用程序的所有队列工作服务器上执行该命令。

所有 Envoy 任务都应该定义在Envoy.blade.php应用程序根目录的一个文件中。以下是入门示例：

1@servers(['web' => ['user@192.168.1.1'], 'workers' => ['user@192.168.1.2']])
2 
3@task('restart-queues', ['on' => 'workers'])
4    cd /home/user/example.com
5    php artisan queue:restart
6@endtask

如您所见，@servers文件顶部定义了一个数组，允许您通过on任务声明的选项引用这些服务器。@servers声明应始终放在一行中。在@task声明中，您应该放置调用任务时应在服务器上执行的 Shell 命令。

本地任务

您可以通过指定服务器的 IP 地址来强制脚本在本地计算机上运行127.0.0.1：

1@servers(['localhost' => '127.0.0.1'])

导入 Envoy 任务

使用该@import指令，您可以导入其他 Envoy 文件，以便将它们的故事和任务添加到您的文件中。导入文件后，您可以执行它们包含的任务，就像它们在您自己的 Envoy 文件中定义一样：

1@import('vendor/package/Envoy.blade.php')

多台服务器

Envoy 允许您轻松地在多个服务器上运行任务。首先，在@servers声明中添加其他服务器。每个服务器都应分配一个唯一的名称。定义好其他服务器后，您可以在任务的数组中列出每个服务器on：

1@servers(['web-1' => '192.168.1.1', 'web-2' => '192.168.1.2'])
2 
3@task('deploy', ['on' => ['web-1', 'web-2']])
4    cd /home/user/example.com
5    git pull origin {{ $branch }}
6    php artisan migrate --force
7@endtask

并行执行

默认情况下，任务将在每台服务器上串行执行。换句话说，任务将在第一台服务器上运行完毕后，再继续在第二台服务器上执行。如果您希望在多台服务器上并行运行任务，请parallel在任务声明中添加以下选项：

1@servers(['web-1' => '192.168.1.1', 'web-2' => '192.168.1.2'])
2 
3@task('deploy', ['on' => ['web-1', 'web-2'], 'parallel' => true])
4    cd /home/user/example.com
5    git pull origin {{ $branch }}
6    php artisan migrate --force
7@endtask

设置

有时，您可能需要在运行 Envoy 任务之前执行任意 PHP 代码。您可以使用该@setup指令定义在任务之前执行的 PHP 代码块：

1@setup
2    $now = new DateTime;
3@endsetup

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

1@include('vendor/autoload.php')
2 
3@task('restart-queues')
4    # ...
5@endtask

变量

如果需要，您可以在调用 Envoy 时在命令行上指定参数，以将参数传递给 Envoy 任务：

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

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

 1@servers(['web' => ['user@192.168.1.1']])
 2 
 3@task('deploy', ['on' => 'web'])
 4    cd /home/user/example.com
 5 
 6    @if ($branch)
 7        git pull origin {{ $branch }}
 8    @endif
 9 
10    php artisan migrate --force
11@endtask

故事

故事将一组任务归类到一个方便的名称下。例如，一个deploy故事可以通过在其定义中列出任务名称来运行update-code和任务：install-dependencies

 1@servers(['web' => ['user@192.168.1.1']])
 2 
 3@story('deploy')
 4    update-code
 5    install-dependencies
 6@endstory
 7 
 8@task('update-code')
 9    cd /home/user/example.com
10    git pull origin master
11@endtask
12 
13@task('install-dependencies')
14    cd /home/user/example.com
15    composer install
16@endtask

故事写完后，您可以按照调用任务的相同方式调用它：

1php vendor/bin/envoy run deploy

钩子

当任务和故事运行时，会执行一些钩子。Envoy 支持的钩子类型包括@before、@after、@error、@success和@finished。这些钩子中的所有代码都会被解释为 PHP 代码并在本地执行，而不是在任务与之交互的远程服务器上执行。

您可以根据需要定义任意数量的钩子。它们将按照在 Envoy 脚本中出现的顺序执行。

@before

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

1@before
2    if ($task === 'deploy') {
3        // ...
4    }
5@endbefore

@after

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

1@after
2    if ($task === 'deploy') {
3        // ...
4    }
5@endafter

@error

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

1@error
2    if ($task === 'deploy') {
3        // ...
4    }
5@enderror

@success

@success如果所有任务都执行成功且没有错误，则 Envoy 脚本中注册的所有钩子都会执行：

1@success
2    // ...
3@endsuccess

@finished

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

1@finished
2    if ($exitCode > 0) {
3        // There were errors in one of the tasks...
4    }
5@endfinished

正在运行的任务

要运行应用程序文件中定义的任务或故事Envoy.blade.php，请执行 Envoy 的run命令，并传递要执行的任务或故事的名称。Envoy 将执行该任务，并在任务运行时显示来自远程服务器的输出：

1php vendor/bin/envoy run deploy

确认任务执行

如果您希望在服务器上运行给定任务之前Prompts确认，则应confirm在任务声明中添加该指令。此选项对于破坏性操作特别有用：

1@task('deploy', ['on' => 'web', 'confirm' => true])
2    cd /home/user/example.com
3    git pull origin {{ $branch }}
4    php artisan migrate
5@endtask

通知

松弛

Envoy 支持在每次任务执行后向Slack发送通知。该@slack指令接受一个 Slack hook URL 和一个频道/用户名。您可以在 Slack 控制面板中创建“Incoming WebHooks”集成来获取您的 webhook URL。

您应该将整个 webhook URL 作为传递给该@slack指令的第一个参数。传递给该指令的第二个参数@slack应该是频道名称 ( #channel) 或用户名 ( @user)：

1@finished
2    @slack('webhook-url', '#bots')
3@endfinished

默认情况下，Envoy 通知会向通知通道发送一条描述已执行任务的消息。但是，您可以通过向该指令传递第三个参数来用您自己的自定义消息覆盖此消息@slack：

1@finished
2    @slack('webhook-url', '#bots', 'Hello, Slack.')
3@endfinished

不和谐

Envoy 还支持在每次任务执行后向Discord发送通知。该@discord指令接受一个 Discord 钩子 URL 和一条消息。您可以在服务器设置中创建“Webhook”，并选择 Webhook 应该发布到哪个频道，从而获取 Webhook URL。您应该将完整的 Webhook URL 传递给该@discord指令：

1@finished
2    @discord('discord-webhook-url')
3@endfinished

电报

Envoy 还支持在每次执行任务后向Telegram发送通知。该@telegram指令接受 Telegram 机器人 ID 和聊天 ID。您可以使用BotFather创建新机器人来获取您的机器人 ID。您可以使用@username_to_id_bot获取有效的聊天 ID 。您应该将完整的机器人 ID 和聊天 ID 传递给该@telegram指令：

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

微软团队

Envoy 还支持在每次执行任务后向Microsoft Teams@microsoftTeams发送通知。该指令接受一个 Teams Webhook（必需）、一条消息、主题颜色（成功、信息、警告、错误）和一系列选项。您可以通过创建一个新的传入 webhook来检索您的 Teams Webhook。Teams API 有许多其他属性可用于自定义消息框，例如标题、摘要和部分。您可以在Microsoft Teams 文档中找到更多信息。您应该将整个 Webhook URL 传递到该@microsoftTeams指令中：

1@finished
2    @microsoftTeams('webhook-url')
3@endfinished