Envoy 部署工具

未匹配的标注
本文档最新版为 10.x,旧版本可能放弃维护,推荐阅读最新版!

Laravel Envoy

简介

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

完成钩子

当任务和片段完成后,将会触发很多钩子。 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

本文章首发在 LearnKu.com 网站上。

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

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

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

上一篇 下一篇
《L03 构架 API 服务器》
你将学到如 RESTFul 设计风格、PostMan 的使用、OAuth 流程,JWT 概念及使用 和 API 开发相关的进阶知识。
《L02 从零构建论坛系统》
以构建论坛项目 LaraBBS 为线索,展开对 Laravel 框架的全面学习。应用程序架构思路贴近 Laravel 框架的设计哲学。
贡献者:1
讨论数量: 0
发起讨论 只看当前版本


暂无话题~