Laravel 中文文档

主题

全部文档

Laravel Envoy ​

简介 ​

Laravel Envoy 是在远程服务器上执行常用任务的工具。借助 Blade 风格语法，你可以轻松配置部署、Artisan 命令等任务。目前 Envoy 仅支持 Mac 与 Linux；Windows 可通过 WSL2 使用。

安装 ​

首先使用 Composer 将 Envoy 安装到项目中：

shell
composer require laravel/envoy --dev

安装完成后，Envoy 二进制文件位于应用的 vendor/bin 目录：

shell
php vendor/bin/envoy

编写任务 ​

定义任务 ​

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

所有 Envoy 任务都应定义在应用根目录的 Envoy.blade.php 中。示例如下：

blade
@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，即可强制脚本在本机运行：

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

导入 Envoy 任务 ​

使用 @import 指令可导入其他 Envoy 文件，使其 story 与任务加入你的文件。导入后，可像在本文件中定义的一样执行其中的任务：

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

多台服务器 ​

Envoy 可轻松在多台服务器上运行同一任务。先在 @servers 中增加服务器，每台需有唯一名称，再在任务的 on 数组中列出它们：

blade
@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 选项：

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

php
@setup
    $now = new DateTime;
@endsetup

若需在任务执行前 require 其他 PHP 文件，可在 Envoy.blade.php 顶部使用 @include：

blade
@include('vendor/autoload.php')

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

变量 ​

如有需要，可在调用 Envoy 时通过命令行向任务传递参数：

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

可在任务中用 Blade 的「echo」语法访问这些选项，也可使用 Blade 的 if 与循环。例如，在执行 git pull 前先确认 $branch 是否存在：

blade
@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 ​

Story 将一组任务归到一个便捷名称下。例如，deploy story 可通过在定义中列出任务名来运行 update-code 与 install-dependencies：

blade
@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

编写完成后，调用 story 的方式与调用任务相同：

shell
php vendor/bin/envoy run deploy

钩子 ​

任务与 story 运行时会执行若干钩子。Envoy 支持的钩子类型有 @before、@after、@error、@success 和 @finished。这些钩子中的代码按 PHP 解释，并在本地执行，而不是在任务所交互的远程服务器上。

每种钩子可以定义多个，按它们在 Envoy 脚本中出现的顺序执行。

@before ​

每次任务执行前，会运行脚本中注册的所有 @before 钩子。@before 会收到即将执行的任务名称：

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

@after ​

每次任务执行后，会运行所有 @after 钩子。@after 会收到已执行的任务名称：

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

@error ​

任务失败（退出码大于 0）后，会运行所有 @error 钩子。@error 会收到已执行的任务名称：

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

@success ​

若所有任务均无错误执行完毕，会运行所有 @success 钩子：

blade
@success
    // ...
@endsuccess

@finished ​

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

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

运行任务 ​

要运行 Envoy.blade.php 中定义的任务或 story，执行 Envoy 的 run 命令并传入名称。Envoy 会执行任务，并在运行过程中显示远程服务器的输出：

shell
php vendor/bin/envoy run deploy

确认任务执行 ​

若希望在服务器上运行某任务前先确认，请在任务声明中加入 confirm。该选项对破坏性操作尤其有用：

blade
@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 的第一个参数；第二个参数为频道名（#channel）或用户名（@user）：

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

默认情况下，Envoy 会向通知频道发送描述已执行任务的消息。也可向 @slack 传入第三个参数以覆盖为自定义消息：

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

Discord ​

Envoy 也支持在每次任务执行后向 Discord 发送通知。@discord 接受 Discord hook URL 与消息。可在服务器设置中创建「Webhook」并选择发布频道以获取 URL。请将完整 Webhook URL 传入 @discord：

blade
@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：

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

Microsoft Teams ​

Envoy 也支持在每次任务执行后向 Microsoft Teams 发送通知。@microsoftTeams 接受 Teams Webhook（必填）、消息、主题色（success、info、warning、error）以及选项数组。可通过创建新的 incoming webhook 获取。Teams API 还支持 title、summary、sections 等属性；详见 Microsoft Teams 文档。请将完整 Webhook URL 传入 @microsoftTeams：

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