# Laravel Envoy
- [简介](#introduction)
- [安装](#installation)
- [编写任务](#writing-tasks)
- [定义任务](#defining-tasks)
- [多服务器](#multiple-servers)
- [配置](#setup)
- [变量](#variables)
- [片段](#stories)
- [完成钩子](#completion-hooks)
- [运行任务](#running-tasks)
- [任务确认](#confirming-task-execution)
- [通知](#notifications)
- [Slack](#slack)
- [Discord](#discord)
- [Telegram](#telegram)
## 简介
[Laravel Envoy](https://github.com/laravel/envoy) 是在远程服务器上跑常见任务的工具,它使用 [Blade](/docs/laravel/8.x/blade) 风格语法,使用它你就很容易实现部署任务、执行 Artisan 命令等。目前,Envoy 仅支持 Mac 和 Linux 操作系统。不过在Windows上你可以使用 [WSL2](https://docs.microsoft.com/en-us/windows/wsl/install-win10)。
## 安装
首先,使用 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` 文件中。这是一个入门的示例:
```bash
@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` 来强制脚本在本地运行:
```bash
@servers(['localhost' => '127.0.0.1'])
```
#### 导入 Envoy 任务
使用 `@import` 指令,您可以导入其他 Envoy 文件,以便将它们的片段和任务添加到您的文件中。导入文件后,您可以执行它们包含的任务,就像在您自己的 Envoy 文件中定义的一样:
```bash
@import('vendor/package/Envoy.blade.php')
```
### 多服务器
Envoy 可以让您非常轻松在多个服务器上运行任务。首先,将额外的服务器添加到您的 `@servers` 声明中。你应该为每个服务器分配一个唯一的名称。一旦定义了好了额外服务器你就可以在任务的 `on` 数组中使用额外服务器:
```bash
@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` 选项
```bash
@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 工作:
```php
@setup
$now = new DateTime;
@endsetup
```
如果在执行任务之前需要其他 PHP 文件,可以在 `Envoy.blade.php` 文件的顶部使用 `@include` 指令:
```bash
@include('vendor/autoload.php')
@task('restart-queues')
# ...
@endtask
```
### 变量
如果需要,您可以使用命令行将选项值传递到 Envoy 任务:
php vendor/bin/envoy run deploy --branch=master
您可以通过 Blade 的「echo」 语法访问任务中的选项。 您也可以在任务中使用 `if` 语法和循环语法。 例如,在执行 `git pull` 命令之前,让我们验证 `$branch` 变量的存在:
```bash
@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-code` 和 `install-dependencies` 任务:
```bash
@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` 钩子接收已执行完任务的名称:
```php
@after
if ($task === 'deploy') {
// ...
}
@endafter
```
#### `@error`
每次任务执行失败后(状态码非 0 退出),Envoy 脚本会执行所有注册的 `@error` 钩子。 `@after` 钩子接收已执行任务的名称:
```php
@error
if ($task === 'deploy') {
// ...
}
@enderror
```
#### `@success`
如果所有任务都执行成功,那么 Envoy 脚本会执行所有注册的 `@success` 钩子:
```bash
@success
// ...
@endsuccess
```
#### `@finished`
在所有任务执行完之后(无论退出状态如何),所有的 `@finished` 钩子都会被执行。 `@finished` 钩子接收已完成任务的状态码,可以是 `null` 或大于或等于 `0` 的整数:
```bash
@finished
if ($exitCode > 0) {
// 其中一项任务有错误...
}
@endfinished
```
## 运行任务
要运行在 `Envoy.blade.php` 文件中定义的任务或片段,请执行 Envoy 的 `run` 命令,传递您要执行的任务或片段的名称。 当任务运行时, Envoy 将运行任务并显示服务器的输出:
php vendor/bin/envoy run deploy
### 任务确认
如果您希望在服务器上运行给定任务之前提示您进行确认,则应将 `confirm` 指令添加到任务声明中。 此选项对于破坏性操作特别有用:
```bash
@task('deploy', ['on' => 'web', 'confirm' => true])
cd /home/user/example.com
git pull origin {{ $branch }}
php artisan migrate
@endtask
```
## 通知
### Slack
Envoy 支持在执行每个任务后向 [Slack](https://slack.com/) 发送通知。 `@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](https://discord.com) 发送通知。 `@discord` 指令接受 Discord 钩子URL地址和消息内容。您可以在你的服务器设置中创建一个 "Webhook" 并选择该 Webhook 发布到哪个频道上。您需要把完整的 Webhook URL传递給 `@discord`指令:
@finished
@discord('discord-webhook-url')
@endfinished
### Telegram
Envoy 同样也支持在执行完任务后向 [Telegram](https://telegram.org) 发送通知. `@telegram` 指令接受 Telegram 的 Bot ID 和 Chat ID。 你可以使用 [BotFather](https://t.me/botfather) 创建一个机器人来获取到你的Bot ID。 你可以使用 [@username_to_id_bot](https://t.me/username_to_id_bot) 来获取到一个有效的 Chat ID。 你必须传递完整的 Bot ID 和 Chat ID 給 `@telegram` 指令:
@finished
@telegram('bot-id','chat-id')
@endfinished