Laravel 特使

Introduction

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

Installation

首先,使用 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' => ['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

Setup

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

@setup
    $now = new DateTime;
@endsetup

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

@include('vendor/autoload.php')

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

Variables

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

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

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

@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

Stories

故事将一组任务分组在一个方便的名称下。例如,一个deploy 故事可能会运行update-codeinstall-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

Hooks

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

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

@before

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

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

@after

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

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

@error

每次任务失败后(退出时状态码大于0), 全部@error 在您的 Envoy 脚本中注册的钩子将执行。这@error 钩子接收已执行任务的名称:

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

@success

如果所有任务都没有错误地执行,则所有@success 在您的 Envoy 脚本中注册的钩子将执行:

@success
    // ...
@endsuccess

@finished

在所有任务执行完毕后(不管退出状态如何),所有的@finished 钩子将被执行。这@finished 钩子接收完成任务的状态码,这可能是null 或一个integer 大于或等于0:

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

运行任务

运行应用程序中定义的任务或故事Envoy.blade.php 文件,执行特使的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

Notifications

Slack

Envoy 支持发送通知到Slack 每个任务执行后。这@slack 指令接受一个 Slack 挂钩 URL 和一个频道/用户名。您可以通过在 Slack 控制面板中创建“Incoming 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 指令接受电报机器人 ID 和聊天 ID。您可以通过使用创建新的机器人来检索您的机器人 IDBotFather.您可以使用检索有效的聊天 ID@username_to_id_bot.您应该将整个机器人 ID 和聊天 ID 传递到@telegram 指示:

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

微软团队

Envoy 还支持发送通知到微软团队 每个任务执行后。这@microsoftTeams 指令接受 Teams Webhook(必需)、消息、主题颜色(成功、信息、警告、错误)和一系列选项。您可以通过创建一个新的传入网络钩子. Teams API 具有许多其他属性来自定义您的消息框,例如标题、摘要和部分。您可以在微软团队文档.您应该将整个 Webhook URL 传递到@microsoftTeams 指示:

@finished
    @microsoftTeams('webhook-url')
@endfinished
豫ICP备18041297号-2