Laravel Envoy

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

简介

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

安装

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

1composer require laravel/envoy --dev

composer require laravel/envoy --dev

一旦 Envoy 安装完成，Envoy 二进制文件将在您应用程序的 vendor/bin 目录中可用

1php vendor/bin/envoy

php vendor/bin/envoy

编写任务

定义任务

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

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

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

@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 来强制脚本在您的本地计算机上运行

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

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

导入 Envoy 任务

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

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

@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

@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 选项添加到您的任务声明中

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

@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 代码块

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

@setup
    $now = new DateTime;
@endsetup

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

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

@include('vendor/autoload.php')

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

变量

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

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

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

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

 1@servers(['web' => ['[email protected]']])
 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

@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 任务

 1@servers(['web' => ['[email protected]']])
 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

@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

故事编写完成后，您可以像调用任务一样调用它

1php vendor/bin/envoy run deploy

php vendor/bin/envoy run deploy

钩子

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

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

`@before`

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

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

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

`@after`

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

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

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

`@error`

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

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

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

`@success`

如果所有任务都已无错误执行，则将在您的 Envoy 脚本中注册的所有 @success 钩子都将执行

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

@success
    // ...
@endsuccess

`@finished`

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

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

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

运行任务

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

1php vendor/bin/envoy run deploy

php vendor/bin/envoy run deploy

确认任务执行

如果您希望在服务器上运行给定任务之前获得确认提示，您应该将 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

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

通知

Slack

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

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

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

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

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

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

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

Discord

Envoy 还支持在每次任务执行后向 Discord 发送通知。@discord 指令接受 Discord hook URL 和消息。您可以通过在服务器设置中创建“Webhook”并选择 webhook 应发布到的频道来检索您的 webhook URL。您应该将整个 Webhook URL 传递到 @discord 指令中

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

@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 指令中

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

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

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

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

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

序言

入门指南

架构概念

基础知识

深入了解

安全性

数据库

Eloquent ORM

测试

软件包