介绍
Laravel Envoy (opens in a new tab) 是一个用于在您的远程服务器上执行常见任务的工具。使用 Blade 风格的语法,您可以轻松地为部署、Artisan 命令等设置任务。目前,Envoy 仅支持 Mac 和 Linux 操作系统。然而,使用 WSL2 (opens in a new tab) 可以实现对 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' => ['user@192.168.1.1'], 'workers' => ['user@192.168.1.2']])
@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' => ['user@192.168.1.1']])
@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' => ['user@192.168.1.1']])
@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
钩子会接收到将要执行的任务的名称:
@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
的 整数
:
@finished
if ($exitCode > 0) {
// 其中一个任务存在错误...
}
@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 (opens in a new tab) 发送通知。@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 (opens in a new tab) 发送通知。@discord
指令接受一个 Discord 钩子 URL 和一条消息。您可以通过在服务器设置中创建一个“Webhook”并选择该 Webhook 应发布到的频道来获取您的 Webhook URL。您应该将整个 Webhook URL 传递到 @discord
指令中:
@finished
@discord('discord-webhook-url')
@endfinished
Telegram
Envoy 还支持在每个任务执行后向 Telegram (opens in a new tab) 发送通知。@telegram
指令接受一个 Telegram Bot ID 和一个 Chat ID。您可以通过使用 BotFather (opens in a new tab) 创建一个新的机器人来获取您的 Bot ID。您可以使用 @username_to_id_bot (opens in a new tab) 获取有效的 Chat ID。您应该将整个 Bot ID 和 Chat ID 传递到 @telegram
指令中:
@finished
@telegram('bot-id','chat-id')
@endfinished
Microsoft Teams
Envoy 还支持在每个任务执行后向 Microsoft Teams (opens in a new tab) 发送通知。@microsoftTeams
指令接受一个 Teams Webhook(必填)、一条消息、主题颜色(成功、信息、警告、错误)和一个选项数组。您可以通过创建一个新的 传入 Webhook (opens in a new tab) 来获取您的 Teams Webhook。Teams API 还有许多其他属性可用于自定义您的消息框,如标题、摘要和部分。您可以在 Microsoft Teams 文档 (opens in a new tab) 中找到更多信息。您应该将整个 Webhook URL 传递到 @microsoftTeams
指令中:
@finished
@microsoftTeams('webhook-url')
@endfinished