Laravel Envoy

簡介
安裝
編寫任務
- 定義任務
- 多個伺服器
- 設定
- 變數
- Stories
- Hooks
執行任務
- 確認任務執行
通知

簡介

Laravel Envoy 是一個工具，用於執行您在遠端伺服器上運行的常見任務。使用 Blade 風格語法，您可以輕鬆設定部署、Artisan 命令等的任務。目前，Envoy 僅支援 Mac 和 Linux 作業系統。但是，使用 WSL2 可以實現 Windows 支援。

安裝

首先，使用 Composer 套件管理器將 Envoy 安裝到您的專案中

1composer require laravel/envoy --dev

composer require laravel/envoy --dev

安裝 Envoy 後，Envoy 二進制檔案將在您應用程式的 vendor/bin 目錄中可用

1php vendor/bin/envoy

php vendor/bin/envoy

編寫任務

定義任務

任務是 Envoy 的基本構建模組。任務定義了在調用任務時應在遠端伺服器上執行的 shell 命令。例如，您可以定義一個任務，該任務在您的所有應用程式佇列工作伺服器上執行 php artisan queue:restart 命令。

您的所有 Envoy 任務都應在應用程式根目錄的 Envoy.blade.php 檔案中定義。以下是一個範例，可讓您開始使用

1@servers(['web' => ['[email protected]'], 'workers' => ['[email protected]']])
2 
3@task('restart-queues', ['on' => 'workers'])
4    cd /home/user/example.com
5    php artisan queue:restart
6@endtask

@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 來強制腳本在本機電腦上運行

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

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

匯入 Envoy 任務

使用 @import 指令，您可以匯入其他 Envoy 檔案，以便將它們的故事和任務新增到您的檔案中。匯入檔案後，您可以像執行您自己的 Envoy 檔案中定義的任務一樣執行它們包含的任務

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

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

多個伺服器

Envoy 允許您輕鬆地跨多個伺服器運行任務。首先，將其他伺服器新增到您的 @servers 宣告中。每個伺服器都應分配一個唯一的名稱。定義其他伺服器後，您可以在任務的 on 陣列中列出每個伺服器

1@servers(['web-1' => '192.168.1.1', 'web-2' => '192.168.1.2'])
2 
3@task('deploy', ['on' => ['web-1', 'web-2']])
4    cd /home/user/example.com
5    git pull origin {{ $branch }}
6    php artisan migrate --force
7@endtask

@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 選項新增到您的任務宣告中

1@servers(['web-1' => '192.168.1.1', 'web-2' => '192.168.1.2'])
2 
3@task('deploy', ['on' => ['web-1', 'web-2'], 'parallel' => true])
4    cd /home/user/example.com
5    git pull origin {{ $branch }}
6    php artisan migrate --force
7@endtask

@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 程式碼區塊

1@setup
2    $now = new DateTime;
3@endsetup

@setup
    $now = new DateTime;
@endsetup

如果您需要在執行任務之前要求其他 PHP 檔案，您可以使用 @include 指令在 Envoy.blade.php 檔案的頂部

1@include('vendor/autoload.php')
2 
3@task('restart-queues')
4    # ...
5@endtask

@include('vendor/autoload.php')

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

變數

如果需要，您可以透過在調用 Envoy 時在命令列上指定參數來將參數傳遞給 Envoy 任務

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

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

您可以使用 Blade 的「echo」語法存取任務中的選項。您也可以在任務中定義 Blade if 語句和迴圈。例如，在執行 git pull 命令之前，我們先驗證 $branch 變數是否存在

 1@servers(['web' => ['[email protected]']])
 2 
 3@task('deploy', ['on' => 'web'])
 4    cd /home/user/example.com
 5 
 6    @if ($branch)
 7        git pull origin {{ $branch }}
 8    @endif
 9 
10    php artisan migrate --force
11@endtask

@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

Stories

故事將一組任務分組在一個方便的名稱下。例如，deploy 故事可以透過在其定義中列出任務名稱來運行 update-code 和 install-dependencies 任務

 1@servers(['web' => ['[email protected]']])
 2 
 3@story('deploy')
 4    update-code
 5    install-dependencies
 6@endstory
 7 
 8@task('update-code')
 9    cd /home/user/example.com
10    git pull origin master
11@endtask
12 
13@task('install-dependencies')
14    cd /home/user/example.com
15    composer install
16@endtask

@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

編寫完故事後，您可以像調用任務一樣調用它

1php vendor/bin/envoy run deploy

php vendor/bin/envoy run deploy

Hooks

當任務和故事運行時，將執行許多 hooks。Envoy 支援的 hook 類型為 @before、@after、@error、@success 和 @finished。這些 hooks 中的所有程式碼都被解釋為 PHP 並在本機執行，而不是在您的任務與之互動的遠端伺服器上執行。

您可以根據需要定義任意數量的這些 hooks。它們將按照它們在您的 Envoy 腳本中出現的順序執行。

`@before`

在每次任務執行之前，Envoy 腳本中註冊的所有 @before hooks 都將執行。@before hooks 接收將要執行的任務名稱

1@before
2    if ($task === 'deploy') {
3        // ...
4    }
5@endbefore

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

`@after`

在每次任務執行之後，Envoy 腳本中註冊的所有 @after hooks 都將執行。@after hooks 接收已執行的任務名稱

1@after
2    if ($task === 'deploy') {
3        // ...
4    }
5@endafter

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

`@error`

在每次任務失敗（退出狀態碼大於 0）之後，Envoy 腳本中註冊的所有 @error hooks 都將執行。@error hooks 接收已執行的任務名稱

1@error
2    if ($task === 'deploy') {
3        // ...
4    }
5@enderror

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

`@success`

如果所有任務都已執行且沒有錯誤，則 Envoy 腳本中註冊的所有 @success hooks 都將執行

1@success
2    // ...
3@endsuccess

@success
    // ...
@endsuccess

`@finished`

在所有任務都已執行後（無論退出狀態如何），都將執行所有 @finished hooks。@finished hooks 接收已完成任務的狀態碼，該狀態碼可能是 null 或大於或等於 0 的 integer

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

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

執行任務

要運行在應用程式的 Envoy.blade.php 檔案中定義的任務或故事，請執行 Envoy 的 run 命令，並傳遞您要執行的任務或故事的名稱。Envoy 將執行任務並在任務運行時顯示來自遠端伺服器的輸出

1php vendor/bin/envoy run deploy

php vendor/bin/envoy run deploy

確認任務執行

如果您希望在伺服器上運行給定任務之前收到確認提示，則應將 confirm 指令新增到您的任務宣告中。此選項對於破壞性操作特別有用

1@task('deploy', ['on' => 'web', 'confirm' => true])
2    cd /home/user/example.com
3    git pull origin {{ $branch }}
4    php artisan migrate
5@endtask

@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 指令的第一個引數傳遞。給定給 @slack 指令的第二個引數應為頻道名稱 (#channel) 或使用者名稱 (@user)

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

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

預設情況下，Envoy 通知將向通知頻道發送一條訊息，描述已執行的任務。但是，您可以透過將第三個引數傳遞給 @slack 指令，使用您自己的自訂訊息覆寫此訊息

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

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

Discord

Envoy 也支援在每次任務執行後將通知發送到 Discord。@discord 指令接受 Discord hook URL 和訊息。您可以透過在伺服器設定中建立「Webhook」並選擇 webhook 應發佈到的頻道來檢索您的 webhook URL。您應將整個 Webhook URL 傳遞到 @discord 指令中

1@finished
2    @discord('discord-webhook-url')
3@endfinished

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

Envoy 也支援在每次任務執行後將通知發送到 Telegram。@telegram 指令接受 Telegram Bot ID 和 Chat ID。您可以透過使用 BotFather 建立新的 bot 來檢索您的 Bot ID。您可以使用 @username_to_id_bot 檢索有效的 Chat ID。您應將整個 Bot ID 和 Chat ID 傳遞到 @telegram 指令中

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

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

Envoy 也支援在每次任務執行後將通知發送到 Microsoft Teams。@microsoftTeams 指令接受 Teams Webhook（必填）、訊息、主題顏色（success、info、warning、error）和選項陣列。您可以透過建立新的 incoming webhook 來檢索您的 Teams Webhook。Teams API 有許多其他屬性可以自訂您的訊息框，例如標題、摘要和區段。您可以在 Microsoft Teams 文件中找到更多資訊。您應將整個 Webhook URL 傳遞到 @microsoftTeams 指令中

1@finished
2    @microsoftTeams('webhook-url')
3@endfinished

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

序言

入門指南

架構概念

基礎知識

深入探討

安全性

資料庫

Eloquent ORM

測試

套件