Laravel Envoy

簡介
安裝
編寫任務
執行任務
- 確認任務執行
通知

簡介

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 檔案，可以在 Envoy.blade.php 檔案的頂部使用 @include 指令。

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)

故事 (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)

當任務和故事執行時，會觸發一系列鉤子。Envoy 支援的鉤子型別包括 @before、@after、@error、@success 和 @finished。這些鉤子中的所有程式碼都會被視為 PHP 並於本地執行，而不是在你任務所互動的遠端伺服器上執行。

你可以根據需要定義任意數量的鉤子。它們將按照在 Envoy 指令碼中出現的順序執行。

`@before`

在每個任務執行之前，指令碼中註冊的所有 @before 鉤子都將執行。@before 鉤子會接收即將執行的任務名稱。

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

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

`@after`

在每個任務執行之後，指令碼中註冊的所有 @after 鉤子都將執行。@after 鉤子會接收剛剛執行完畢的任務名稱。

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

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

`@error`

在每個任務失敗（退出狀態碼大於 0）後，指令碼中註冊的所有 @error 鉤子都將執行。@error 鉤子會接收執行失敗的任務名稱。

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

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

`@success`

如果所有任務都成功執行且沒有錯誤，指令碼中註冊的所有 @success 鉤子都將執行。

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

@success
    // ...
@endsuccess

`@finished`

在所有任務執行完畢後（無論退出狀態如何），所有 @finished 鉤子都將執行。@finished 鉤子會接收已完成任務的狀態碼，該值可能為 null 或大於等於 0 的整數。

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 指令的第一個引數。第二個引數應為頻道名稱 (#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 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 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