Laravel Envoy

• 简介
• 安装
• 编写任务
  • 定义任务
  • 多服务器
  • 配置
  • 变量
  • 片段
  • 完成钩子
• 运行任务
  • 任务确认
• 通知
  • Slack
  • Discord
  • Telegram

简介

Laravel Envoy 是在远程服务器上跑常见任务的工具，它使用 Blade 风格语法，使用它你就很容易实现部署任务、执行 Artisan 命令等。目前，Envoy 仅支持 Mac 和 Linux 操作系统。不过在Windows上你可以使用 WSL2。

安装

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

composer require laravel/envoy --dev

一旦完成安装了 Envoy，你可以在你应用中的 vendor/bin 目录使用 Envoy 二进制文件:

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

如您所见，在文件顶部定义了一个 @server 数组，允许您在任务声明的 on 选项中引用这些服务器。@server 声明应始终放在单行上。在你的 @task 声明中，你应该放置在任务执行时应该在你的服务器上运行的 Bash 代码。

本地任务

您可以通过将服务器的 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 任务：

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

您可以通过 Blade 的「echo」 语法访问任务中的选项。 您也可以在任务中使用 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 支持的钩子类型有 @after， @error， @success，和 @finished。这些钩子中的所有代码均被当做 PHP 代码执行，并且是在本地执行的，而不是在与您的任务进行交互的远程服务器上执行。

您可以根据需要注册不同的钩子，并且可以重复注册同一种钩子。它们将按照在 Envoy 脚本中出现的顺序执行。

@after

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

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

@error

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

@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 发送通知。 @slack 指令接受 Slack 钩子 URL 和通道名称。 您可以通过在 Slack 控制面板中创建 Incoming WebHooks 集成来检索您的 webhook URL 。 您应该将整个 webhook URL 传递给 @slack 指令：

您应该将整个 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传递給 @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

本译文仅用于学习和交流目的，转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议，如果我们的工作有侵犯到您的权益，请及时联系我们。

原文地址：https://learnku.com/docs/laravel/8.5/env...

译文地址：https://learnku.com/docs/laravel/8.5/env...