Laravel Horizon - Knowledge of Laravel

Horizon 是什麼

Laravel Horizon 是為 Laravel Redis 佇列專用的監控儀表板。它可即時視覺化 Job 的吞吐量、執行時間、失敗狀況，並以程式碼管理 worker 設定。

Horizon 是擴充佇列基本功能的套件。請先熟悉佇列與 Job後再閱讀本頁。此外，後端必須使用 Redis。

安裝

Horizon 使用 Redis 作為佇列後端，請確認 config/queue.php 的 QUEUE_CONNECTION 為 redis。目前尚未支援 Redis Cluster。

透過 Composer 安裝：

composer require laravel/horizon

安裝完成後發布 Horizon 的資產與設定檔。

php artisan horizon:install

此指令會產生 config/horizon.php 與 app/Providers/HorizonServiceProvider.php。

設定

config/horizon.php 結構

config/horizon.php 集中管理所有 worker 設定，其核心為 environments 選項。

'environments' => [
    'production' => [
        'supervisor-1' => [
            'connection' => 'redis',
            'queue' => ['default', 'notifications'],
            'balance' => 'auto',
            'autoScalingStrategy' => 'time',
            'minProcesses' => 1,
            'maxProcesses' => 10,
            'balanceMaxShift' => 1,
            'balanceCooldown' => 3,
            'tries' => 3,
            'timeout' => 60,
        ],
    ],

    'local' => [
        'supervisor-1' => [
            // 其他值會從 defaults 區塊繼承
            'maxProcesses' => 3,
        ],
    ],
],

Horizon 內部使用名為 horizon 的 Redis 連線，請不要在 config/database.php 中把此名稱用於其他連線。

CSP nonce（Content Security Policy）

若要在 Horizon 視圖中為 script / style 標籤加上 Content Security Policy 所需的 nonce 屬性，可以使用 Horizon::cspNonce。因為每次請求都需要新的 nonce，通常會在中介軟體中呼叫。

use Closure;
use Illuminate\Http\Request;
use Laravel\Horizon\Horizon;
use Symfony\Component\HttpFoundation\Response;

public function handle(Request $request, Closure $next): Response
{
    Horizon::cspNonce('csp-nonce');

    return $next($request);
}

將此中介軟體加入 config/horizon.php 的 middleware 選項。

'middleware' => [
    'web',
    App\Http\Middleware\AddHorizonCspNonce::class,
],

Supervisor

每個環境可包含一或多個「Supervisor」。Supervisor 是 worker 群組的管理單位，同一環境內可同時執行多個具備不同佇列、平衡策略與程序數的 Supervisor。

預設值

透過 defaults 選項為所有 Supervisor 設定共同的預設值。

'defaults' => [
    'supervisor-1' => [
        'connection' => 'redis',
        'queue' => ['default'],
        'balance' => 'auto',
        'tries' => 1,
        'timeout' => 60,
        'maxProcesses' => 1,
    ],
],

維護模式

應用程式處於維護模式時，Horizon 預設不會處理 Job。若要強制處理，可使用 force 選項。

'environments' => [
    'production' => [
        'supervisor-1' => [
            'force' => true,
        ],
    ],
],

Job 最大重試次數

'environments' => [
    'production' => [
        'supervisor-1' => [
            'tries' => 10,
        ],
    ],
],

tries 設為 0 表示允許無限次重試。

Job 逾時

'environments' => [
    'production' => [
        'supervisor-1' => [
            'timeout' => 60,
        ],
    ],
],

timeout 請比 config/queue.php 的 retry_after 短數秒。此外，auto 平衡策略可能強制結束執行超過此值的 Job。

backoff（重試等待時間）

指定拋出例外後至下次重試的等待秒數。

// 固定值
'backoff' => 10,

// 階段式（指數退避）
'backoff' => [1, 5, 10],

其他 worker 選項

除了 tries、timeout、backoff，各 Supervisor 還支援控制 worker 程序行為與自動重啟時機的選項。定期重啟長時間執行的程序是防止記憶體洩漏的好習慣。

'environments' => [
    'production' => [
        'supervisor-1' => [
            // ...
            'memory' => 128,
            'maxJobs' => 1000,
            'maxTime' => 3600,
            'sleep' => 3,
            'rest' => 0,
            'nice' => 0,
        ],
    ],
],

memory — worker 程序在重啟前可使用的最大記憶體量（MB），預設 128
maxJobs — 重啟前處理的 Job 數，0 代表無限，預設 0
maxTime — 重啟前可運作的秒數，0 代表不以時間重啟，預設 0
sleep — 沒有 Job 時，下次輪詢前等待的秒數，預設 3
rest — 每 Job 處理之間暫停的秒數，預設 0
nice — worker 程序的優先度（“niceness”），值越大優先度越低，預設 0

平衡策略

Horizon 提供 3 種 worker 平衡策略。

auto（預設）

依佇列負載自動調整 worker 數，並以 minProcesses 與 maxProcesses 指定範圍。

'supervisor-1' => [
    'balance' => 'auto',
    'autoScalingStrategy' => 'time', // 或 'size'
    'minProcesses' => 1,
    'maxProcesses' => 10,
    'balanceMaxShift' => 1,
    'balanceCooldown' => 3,
],

time — 以清空佇列的預估時間進行擴縮
size — 依佇列中 Job 數量擴縮

auto 策略下佇列順序並不代表優先度。若要強制優先順序，請使用多個 Supervisor。

simple

固定 worker 數，並平均分配給指定的佇列。

'supervisor-1' => [
    'balance' => 'simple',
    'processes' => 10,
    'queue' => ['default', 'notifications'],
],

在上例中會分別配置 5 個 worker 給 default 與 notifications。

false（不平衡）

嚴格依佇列列表順序優先。行為與 Laravel 預設佇列系統相同，但仍會依積累量調整 worker 數。

'supervisor-1' => [
    'balance' => false,
    'queue' => ['default', 'notifications'],
    'minProcesses' => 1,
    'maxProcesses' => 10,
],

default 佇列的 Job 永遠會優先於 notifications。

儀表板授權

Horizon 儀表板可透過 /horizon 存取。在本機環境預設任何人都可存取，但正式環境中應以 Gate 定義限制存取權限。編輯 app/Providers/HorizonServiceProvider.php 的 gate() 方法。

use App\Models\User;
use Illuminate\Support\Facades\Gate;

protected function gate(): void
{
    Gate::define('viewHorizon', function (User $user) {
        return in_array($user->email, [
            '[email protected]',
        ]);
    });
}

若不需要認證（例如以 IP 限制保護），可以把參數改為可選。

Gate::define('viewHorizon', function (User $user = null) {
    // 以 IP 位址等進行限制時
    return true;
});

啟動 Horizon

基本指令

# 啟動
php artisan horizon

# 暫停 / 繼續
php artisan horizon:pause
php artisan horizon:continue

# 暫停 / 繼續特定 Supervisor
php artisan horizon:pause-supervisor supervisor-1
php artisan horizon:continue-supervisor supervisor-1

# 狀態確認
php artisan horizon:status
php artisan horizon:supervisor-status supervisor-1

# 優雅關閉
php artisan horizon:terminate

本機開發：自動重啟

若要偵測檔案變更自動重啟 Horizon，可使用 horizon:listen。

npm install --save-dev chokidar
php artisan horizon:listen

# 在 Docker / Vagrant 環境
php artisan horizon:listen --poll

使用 Supervisor 持續運行

正式環境中透過 Supervisor 讓 Horizon 持續運作。

安裝 Supervisor

sudo apt-get install supervisor

建立設定檔

建立 /etc/supervisor/conf.d/horizon.conf：

[program:horizon]
process_name=%(program_name)s
command=php /home/forge/example.com/artisan horizon
autostart=true
autorestart=true
user=forge
redirect_stderr=true
stdout_logfile=/home/forge/example.com/horizon.log
stopwaitsecs=3600

stopwaitsecs 請設定比最長 Job 執行時間更大的值。太小的話 Supervisor 會在 Job 執行過程中強制中止。

啟動 Supervisor

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start horizon

部署時

每次部署後請重啟 Horizon 以套用變更。

php artisan horizon:terminate

只要 Supervisor 設為 autostart=true / autorestart=true，關閉後就會自動重啟。

Job 管理

靜音化

不希望顯示於儀表板「已完成 Job」清單的 Job，可在 config/horizon.php 靜音化。

'silenced' => [
    App\Jobs\ProcessPodcast::class,
],

// 以標籤靜音
'silenced_tags' => [
    'notifications',
],

也可以透過實作 Silenced 介面達成。

use Laravel\Horizon\Contracts\Silenced;

class ProcessPodcast implements ShouldQueue, Silenced
{
    use Queueable;
    // ...
}

指標與監控

Horizon 的指標儀表板會顯示 Job / 佇列的吞吐量與執行時間。請安排定期擷取快照。

// routes/console.php
use Illuminate\Support\Facades\Schedule;

Schedule::command('horizon:snapshot')->everyFiveMinutes();

可透過 config/horizon.php 的 metrics.trim_snapshots 設定為指標圖表保留的快照數量。此設定以「數量」而非「時間」限制，因此實際保留期間會隨 horizon:snapshot 執行頻率變動。

'metrics' => [
    'trim_snapshots' => [
        'job' => 24,
        'queue' => 24,
    ],
],

要移除所有指標資料，執行下列指令：

php artisan horizon:clear-metrics

Job 失敗通知

當佇列等待時間過長時可以收到通知。請在 app/Providers/HorizonServiceProvider.php 的 boot() 中設定。

use Laravel\Horizon\Horizon;

public function boot(): void
{
    parent::boot();

    Horizon::routeMailNotificationsTo('[email protected]');
    Horizon::routeSlackNotificationsTo('slack-webhook-url', '#ops');
    Horizon::routeSmsNotificationsTo('15556667777');
}

等待時間的閾值

在 config/horizon.php 的 waits 中設定觸發通知的等待秒數。

'waits' => [
    'redis:critical' => 30,  // 等待 30 秒以上通知
    'redis:default' => 60,
    'redis:batch' => 120,
],

設為 0 表示停用該佇列的通知。

失敗 Job 管理

失敗的 Job 可以用 ID 或 UUID 刪除。

# 刪除特定失敗 Job
php artisan horizon:forget 5

# 刪除所有失敗 Job
php artisan horizon:forget --all

若要清除佇列中的所有 Job：

# 清除預設佇列
php artisan horizon:clear

# 清除特定佇列
php artisan horizon:clear --queue=emails

升級

進行 Horizon 主版本升級時，請務必參閱升級指南。

佇列與 Job

Laravel 佇列的基礎。說明 Job 的建立、派發、批次處理與失敗處理。

Redis

作為 Horizon 後端所需的 Redis 設定與用法。

​Horizon 是什麼

​安裝

​設定

​config/horizon.php 結構

​CSP nonce（Content Security Policy）

​Supervisor

​預設值

​維護模式

​Job 最大重試次數

​Job 逾時

​backoff（重試等待時間）

​其他 worker 選項

​平衡策略

​儀表板授權

​啟動 Horizon

​基本指令

​本機開發：自動重啟

​使用 Supervisor 持續運行

​安裝 Supervisor

​建立設定檔

​啟動 Supervisor

​部署時

​Job 管理

​標籤

​靜音化

​指標與監控

​Job 失敗通知

​等待時間的閾值

​失敗 Job 管理

​升級

​相關頁面

佇列與 Job

Redis

Horizon 是什麼

安裝

設定

config/horizon.php 結構

CSP nonce（Content Security Policy）

Supervisor

預設值

維護模式

Job 最大重試次數

Job 逾時

backoff（重試等待時間）

其他 worker 選項

平衡策略

儀表板授權

啟動 Horizon

基本指令

本機開發：自動重啟

使用 Supervisor 持續運行

安裝 Supervisor

建立設定檔

啟動 Supervisor

部署時

Job 管理

標籤

靜音化

指標與監控

Job 失敗通知

等待時間的閾值

失敗 Job 管理

升級

相關頁面