Envoy

前言

Laravel Envoy 是一个用于在远程服务器上执行常用任务的工具。它使用与 Blade 相同的语法，可以轻松定义部署、Artisan 命令执行等任务。

Envoy 目前仅支持 macOS 和 Linux。若在 Windows 中使用，需要通过 WSL2。

安装

使用 Composer 包管理器将 Envoy 安装到项目中。

composer require laravel/envoy --dev

安装完成后，vendor/bin 目录下即可使用 Envoy 可执行文件。

php vendor/bin/envoy

任务的创建

任务的定义

任务是 Envoy 的基本构成要素。任务用于定义在任务执行时应在远程服务器上运行的 shell 命令。例如，可以定义一个在所有队列 Worker 服务器上执行 php artisan queue:restart 命令的任务。所有 Envoy 任务都定义在应用根目录下的 Envoy.blade.php 文件中。

@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，可以强制在本地计算机上运行脚本。

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

Envoy 任务的导入

使用 @import 指令可以导入其他 Envoy 文件，将其 story 或 task 加入到自己的文件中。导入后，可以像在自己的 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

并行执行

默认情况下，任务在各服务器上是串行执行的。也就是说，任务在第 1 台服务器完成后，才会开始在第 2 台服务器执行。如果希望在多台服务器上并行执行，可以在任务声明中添加 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 指令。

@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”语法访问选项，也可以使用 Blade 的 if 语句和循环。例如，若希望在执行 git pull 命令前确认 $branch 变量存在，可以这样写。

@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

故事（Story）

Story 用一个方便的名字将一系列任务分组。例如，可以在 deploy story 中一起执行 update-code 和 install-dependencies 任务。

@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

编写完 story 后，可以像调用任务一样调用它。

php vendor/bin/envoy run deploy

完成钩子

在任务和 story 执行时会触发多个钩子。Envoy 支持的钩子类型有 @before、@after、@error、@success、@finished。这些钩子内的代码都会作为 PHP 解释，并在本地执行，而不是在任务操作的远程服务器上。每种钩子可以定义任意多个，会按其在 Envoy 脚本中书写的顺序执行。

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

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

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

@success
    // ...
@endsuccess

@finished
    if ($exitCode > 0) {
        // 某个任务发生了错误...
    }
@endfinished

@finished 钩子会接收已执行完的任务的状态码。状态码为 null 或大于等于 0 的整数。

执行任务

要执行应用 Envoy.blade.php 文件中定义的任务或 story，可运行 Envoy 的 run 命令并传入要执行的任务或 story 名称。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 的 Webhook URL 与频道名（或用户名）。Webhook URL 可以通过在 Slack 控制面板中创建”Incoming WebHooks”集成来获取。 @slack 指令的第 1 个参数为整个 Webhook URL。第 2 个参数为频道名（#channel）或用户名（@user）。

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

默认情况下会向通知频道发送描述所执行任务的消息。通过向 @slack 指令传入第 3 个参数，可以自定义消息。

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

Discord

Envoy 也支持在每个任务执行后向 Discord 发送通知。@discord 指令接收 Discord 的 Webhook URL 与消息。Webhook URL 可以在服务器设置中创建”Webhook”并选择发送目标频道获得。

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

Envoy 也支持在每个任务执行后向 Telegram 发送通知。@telegram 指令接收 Telegram Bot ID 与 Chat ID。Bot ID 可以通过在 BotFather 创建新 bot 得到。Chat ID 可以使用 @username_to_id_bot 获取。

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

Microsoft Teams

Envoy 也支持在每个任务执行后向 Microsoft Teams 发送通知。@teams 指令接收 Teams 的 webhook（必需）、消息、主题颜色（success, info, warning, error）以及可选的配置数组。Teams 的 webhook 可通过创建 Incoming Webhook 获得。Teams API 还有许多其他配置项，可以自由创建自定义消息卡片。详情请参阅 Microsoft Teams 的文档。

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

Envoy 前提是通过 SSH 连接到远程服务器。根据运行环境，可能需要事先完成密钥认证配置及对服务器的访问控制。若需要更高级的部署自动化，也可以考虑与部署指南或 GitHub Actions 结合使用。

架构

数据库

Eloquent

安全

事件

邮件与通知

支付

异步处理

实时通信

调度

缓存与优化

国际化

文件与存储

调试与监控

控制台与 CLI

性能

前端

AI 开发

开发环境

前言

安装

任务的创建

任务的定义

本地任务

Envoy 任务的导入

多台服务器

并行执行

初始化设置

变量

故事（Story）

完成钩子

执行任务

任务执行的确认

通知

Slack

Discord

Telegram

Microsoft Teams

​前言

​安装

​任务的创建

​任务的定义

​本地任务

​Envoy 任务的导入

​多台服务器

​并行执行

​初始化设置

​变量

​故事（Story）

​完成钩子

​执行任务

​任务执行的确认

​通知

​Slack

​Discord

​Telegram

​Microsoft Teams

前言

安装

任务的创建

任务的定义

本地任务

Envoy 任务的导入

多台服务器

并行执行

初始化设置

变量

故事（Story）

完成钩子

执行任务

任务执行的确认

通知

Slack

Discord

Telegram

Microsoft Teams