Envoy

簡介 (Introduction)

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

安裝 (Installation)

首先,使用 Composer 套件管理器將 Envoy 安裝到你的專案中:

composer require laravel/envoy --dev

安裝 Envoy 後,Envoy 二進位檔案將在你的應用程式的 vendor/bin 目錄中可用:

php vendor/bin/envoy

撰寫任務 (Writing Tasks)

定義任務 (Defining Tasks)

任務是 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

如你所見,檔案頂部定義了一個 @servers 陣列,允許你透過任務宣告的 on 選項引用這些伺服器。@servers 宣告應始終放在單行上。在你的 @task 宣告中,你應該放置在調用任務時應在伺服器上執行的 shell 指令。

本機任務 (Local Tasks)

你可以透過將伺服器的 IP 位址指定為 127.0.0.1 來強制腳本在本機電腦上執行:

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

匯入 Envoy 任務 (Importing Envoy Tasks)

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

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

多伺服器 (Multiple Servers)

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

預設情況下,任務將在每個伺服器上串行執行。換句話說,任務將在第一個伺服器上完成執行後才會繼續在第二個伺服器上執行。如果你希望在多個伺服器上並行執行任務,請在任務宣告中新增 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

設定 (Setup)

有時,你可能需要在執行 Envoy 任務之前執行任意 PHP 程式碼。你可以使用 @setup 指令定義一個 PHP 程式碼區塊,該區塊應在你的任務之前執行:

@setup
    $now = new DateTime;
@endsetup

如果你需要在執行任務之前引入其他 PHP 檔案,可以在 Envoy.blade.php 檔案的頂部使用 @include 指令:

@include('vendor/autoload.php')

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

變數 (Variables)

如果需要,你可以在調用 Envoy 時在命令列上指定參數來將其傳遞給 Envoy 任務:

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

你可以使用 Blade 的「輸出」語法在任務中存取這些選項。你也可以在任務中定義 Blade 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

故事 (Stories)

故事將一組任務組合在一個單一、方便的名稱下。例如,deploy 故事可以透過在其定義中列出任務名稱來執行 update-code 和 install-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

鉤子 (Hooks)

當任務和故事執行時,會執行多個鉤子。Envoy 支援的鉤子類型有 @before、@after、@error、@success 和 @finished。所有這些鉤子中的程式碼都被解釋為 PHP 並在本機執行,而不是在你的任務互動的遠端伺服器上執行。

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

@before

在每個任務執行之前,所有在 Envoy 腳本中註冊的 @before 鉤子都會執行。@before 鉤子接收將要執行的任務名稱:

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

@after

在每個任務執行之後,所有在 Envoy 腳本中註冊的 @after 鉤子都會執行。@after 鉤子接收已執行的任務名稱:

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

@error

在每個任務失敗後（以大於 0 的狀態碼退出）,所有在 Envoy 腳本中註冊的 @error 鉤子都會執行。@error 鉤子接收已執行的任務名稱:

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

@success

如果所有任務都已執行而沒有錯誤,所有在 Envoy 腳本中註冊的 @success 鉤子都會執行:

@success
    // ...
@endsuccess

@finished

在所有任務執行完畢後（無論退出狀態如何）,所有 @finished 鉤子都會被執行。@finished 鉤子接收已完成任務的狀態碼,它可能是 null 或大於或等於 0 的 integer:

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

執行任務 (Running Tasks)

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

php vendor/bin/envoy run deploy

確認任務執行 (Confirming Task Execution)

如果你希望在伺服器上執行給定任務之前提示確認,你應該在任務宣告中新增 confirm 指令。此選項對於破壞性操作特別有用:

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

通知 (Notifications)

Slack

Envoy 支援在每個任務執行後向 Slack 發送通知。@slack 指令接受一個 Slack hook URL 和一個頻道/使用者名稱。你可以透過在 Slack 控制面板中建立「Incoming WebHooks」整合來取得你的 webhook URL。

你應該將完整的 webhook URL 作為第一個參數傳遞給 @slack 指令。第二個參數應該是頻道名稱（#channel）或使用者名稱（@user）:

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

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

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

Discord

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

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

Telegram

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

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

Microsoft Teams

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

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