Reverb

簡介 (Introduction)

Laravel Reverb 為您的 Laravel 應用程式帶來極速且可擴展的即時 WebSocket 通訊,並與 Laravel 現有的事件廣播工具套件無縫整合。

安裝 (Installation)

您可以使用 install:broadcasting Artisan 指令來安裝 Reverb:

php artisan install:broadcasting

設定 (Configuration)

在幕後,install:broadcasting Artisan 指令會執行 reverb:install 指令,該指令會使用一組合理的預設設定選項來安裝 Reverb。如果您想要進行任何設定變更,可以透過更新 Reverb 的環境變數或更新 config/reverb.php 設定檔來完成。

應用程式憑證 (Application Credentials)

為了建立與 Reverb 的連線,必須在客戶端和伺服器之間交換一組 Reverb「應用程式」憑證。這些憑證在伺服器上設定,用於驗證來自客戶端的請求。您可以使用以下環境變數來定義這些憑證:

REVERB_APP_ID=my-app-id
REVERB_APP_KEY=my-app-key
REVERB_APP_SECRET=my-app-secret

允許的來源 (Allowed Origins)

您也可以透過更新 config/reverb.php 設定檔中 apps 區段內的 allowed_origins 設定值來定義客戶端請求可能來自的來源。任何來自未列在允許來源清單中的請求都將被拒絕。您可以使用 * 來允許所有來源:

'apps' => [
    [
        'app_id' => 'my-app-id',
        'allowed_origins' => ['laravel.com'],
        // ...
    ]
]

額外的應用程式 (Additional Applications)

通常,Reverb 為安裝它的應用程式提供 WebSocket 伺服器。然而,可以使用單一 Reverb 安裝來服務多個應用程式。

例如,您可能希望維護一個單一的 Laravel 應用程式,透過 Reverb 為多個應用程式提供 WebSocket 連線。這可以透過在應用程式的 config/reverb.php 設定檔中定義多個 apps 來實現:

'apps' => [
    [
        'app_id' => 'my-app-one',
        // ...
    ],
    [
        'app_id' => 'my-app-two',
        // ...
    ],
],

SSL

在大多數情況下,安全的 WebSocket 連線由上游網頁伺服器(Nginx 等)處理,然後再將請求代理到您的 Reverb 伺服器。

然而,有時候讓 Reverb 伺服器直接處理安全連線會很有用,例如在本機開發期間。如果您使用 Laravel Herd 的安全網站功能,或者您使用 Laravel Valet 並對您的應用程式執行了 secure 指令,您可以使用為您的網站產生的 Herd / Valet 憑證來保護您的 Reverb 連線。要這樣做,請將 REVERB_HOST 環境變數設定為您網站的主機名稱,或在啟動 Reverb 伺服器時明確傳遞主機名稱選項:

php artisan reverb:start --host="0.0.0.0" --port=8080 --hostname="laravel.test"

由於 Herd 和 Valet 網域解析為 localhost,執行上述指令將使您的 Reverb 伺服器可透過安全的 WebSocket 協定 (wss) 在 wss://laravel.test:8080 存取。

您也可以透過在應用程式的 config/reverb.php 設定檔中定義 tls 選項來手動選擇憑證。在 tls 選項陣列中,您可以提供 PHP 的 SSL 上下文選項支援的任何選項:

'options' => [
    'tls' => [
        'local_cert' => '/path/to/cert.pem'
    ],
],

執行伺服器 (Running the Server)

可以使用 reverb:start Artisan 指令來啟動 Reverb 伺服器:

php artisan reverb:start

預設情況下,Reverb 伺服器將在 0.0.0.0:8080 啟動,使其可從所有網路介面存取。

如果您需要指定自訂的主機或連接埠,可以在啟動伺服器時透過 --host 和 --port 選項來完成:

php artisan reverb:start --host=127.0.0.1 --port=9000

或者,您可以在應用程式的 .env 設定檔中定義 REVERB_SERVER_HOST 和 REVERB_SERVER_PORT 環境變數。

REVERB_SERVER_HOST 和 REVERB_SERVER_PORT 環境變數不應與 REVERB_HOST 和 REVERB_PORT 混淆。前者指定執行 Reverb 伺服器本身的主機和連接埠,而後者則指示 Laravel 將廣播訊息發送到何處。例如,在正式環境中,您可能會將來自公開 Reverb 主機名稱的連接埠 443 請求路由到在 0.0.0.0:8080 上運作的 Reverb 伺服器。在這種情況下,您的環境變數將定義如下:

REVERB_SERVER_HOST=0.0.0.0
REVERB_SERVER_PORT=8080

REVERB_HOST=ws.laravel.com
REVERB_PORT=443

除錯 (Debugging)

為了提高效能,Reverb 預設不會輸出任何除錯資訊。如果您想查看通過 Reverb 伺服器的資料流,可以為 reverb:start 指令提供 --debug 選項:

php artisan reverb:start --debug

重新啟動 (Restarting)

由於 Reverb 是一個長時間執行的程序,對程式碼的變更不會反映出來,除非透過 reverb:restart Artisan 指令重新啟動伺服器。

reverb:restart 指令確保所有連線在停止伺服器之前都被優雅地終止。如果您使用程序管理器(如 Supervisor)執行 Reverb,伺服器將在所有連線終止後由程序管理器自動重新啟動:

php artisan reverb:restart

監控 (Monitoring)

Reverb 可以透過與 Laravel Pulse 的整合來監控。透過啟用 Reverb 的 Pulse 整合,您可以追蹤伺服器處理的連線數和訊息數。

要啟用整合,您應該首先確保已安裝 Pulse。然後,將任何 Reverb 的記錄器新增到應用程式的 config/pulse.php 設定檔中:

use Laravel\Reverb\Pulse\Recorders\ReverbConnections;
use Laravel\Reverb\Pulse\Recorders\ReverbMessages;

'recorders' => [
    ReverbConnections::class => [
        'sample_rate' => 1,
    ],

    ReverbMessages::class => [
        'sample_rate' => 1,
    ],

    // ...
],

接下來,將每個記錄器的 Pulse 卡片新增到您的 Pulse 儀表板:

<x-pulse>
    <livewire:reverb.connections cols="full" />
    <livewire:reverb.messages cols="full" />
    ...
</x-pulse>

連線活動是透過定期輪詢新更新來記錄的。為了確保此資訊在 Pulse 儀表板上正確呈現,您必須在 Reverb 伺服器上執行 pulse:check 守護程序。如果您在水平擴展設定中執行 Reverb,您應該只在其中一台伺服器上執行此守護程序。

在正式環境執行 Reverb (Running Reverb in Production)

由於 WebSocket 伺服器的長時間執行特性,您可能需要對伺服器和主機環境進行一些最佳化,以確保您的 Reverb 伺服器能夠有效處理伺服器上可用資源的最佳連線數。

[!NOTE] 如果您的網站由 Laravel Forge 管理,您可以直接從「Application」面板自動為 Reverb 最佳化您的伺服器。透過啟用 Reverb 整合,Forge 將確保您的伺服器已準備好用於正式環境,包括安裝任何必要的擴充套件並增加允許的連線數。

開啟的檔案 (Open Files)

每個 WebSocket 連線都會保存在記憶體中,直到客戶端或伺服器斷開連線。在 Unix 和類 Unix 環境中,每個連線都由一個檔案表示。然而,在作業系統和應用程式層級通常都有允許開啟檔案數量的限制。

作業系統 (Operating System)

在基於 Unix 的作業系統上,您可以使用 ulimit 指令來確定允許的開啟檔案數量:

ulimit -n

此指令將顯示不同使用者允許的開啟檔案限制。您可以透過編輯 /etc/security/limits.conf 檔案來更新這些值。例如,將 forge 使用者的最大開啟檔案數更新為 10,000 將如下所示:

# /etc/security/limits.conf
forge        soft  nofile  10000
forge        hard  nofile  10000

事件迴圈 (Event Loop)

在幕後,Reverb 使用 ReactPHP 事件迴圈來管理伺服器上的 WebSocket 連線。預設情況下,此事件迴圈由 stream_select 驅動,不需要任何額外的擴充套件。然而,stream_select 通常限制為 1,024 個開啟的檔案。因此,如果您計劃處理超過 1,000 個並發連線,您將需要使用不受相同限制約束的替代事件迴圈。

當可用時,Reverb 將自動切換到由 ext-uv 驅動的迴圈。此 PHP 擴充套件可透過 PECL 安裝:

pecl install uv

網頁伺服器 (Web Server)

在大多數情況下,Reverb 在伺服器上的非面向網頁的連接埠上執行。因此,為了將流量路由到 Reverb,您應該設定反向代理。假設 Reverb 在主機 0.0.0.0 和連接埠 8080 上執行,並且您的伺服器使用 Nginx 網頁伺服器,可以使用以下 Nginx 網站設定為您的 Reverb 伺服器定義反向代理:

server {
    ...

    location / {
        proxy_http_version 1.1;
        proxy_set_header Host $http_host;
        proxy_set_header Scheme $scheme;
        proxy_set_header SERVER_PORT $server_port;
        proxy_set_header REMOTE_ADDR $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";

        proxy_pass http://0.0.0.0:8080;
    }

    ...
}

[!WARNING] Reverb 在 /app 監聽 WebSocket 連線,並在 /apps 處理 API 請求。您應該確保處理 Reverb 請求的網頁伺服器可以服務這兩個 URI。如果您使用 Laravel Forge 管理您的伺服器,您的 Reverb 伺服器預設將被正確設定。

通常,網頁伺服器被設定為限制允許的連線數,以防止伺服器過載。要將 Nginx 網頁伺服器上允許的連線數增加到 10,000,應更新 nginx.conf 檔案的 worker_rlimit_nofile 和 worker_connections 值:

user forge;
worker_processes auto;
pid /run/nginx.pid;
include /etc/nginx/modules-enabled/*.conf;
worker_rlimit_nofile 10000;

events {
  worker_connections 10000;
  multi_accept on;
}

上述設定將允許每個程序產生最多 10,000 個 Nginx 工作程序。此外,此設定將 Nginx 的開啟檔案限制設定為 10,000。

連接埠 (Ports)

基於 Unix 的作業系統通常會限制可以在伺服器上開啟的連接埠數量。您可以透過以下指令查看目前允許的範圍:

cat /proc/sys/net/ipv4/ip_local_port_range
# 32768	60999

上述輸出顯示伺服器最多可以處理 28,231 (60,999 - 32,768) 個連線,因為每個連線都需要一個空閒的連接埠。雖然我們建議使用水平擴展來增加允許的連線數,但您可以透過更新伺服器的 /etc/sysctl.conf 設定檔中允許的連接埠範圍來增加可用的開啟連接埠數量。

程序管理 (Process Management)

在大多數情況下,您應該使用程序管理器(如 Supervisor)來確保 Reverb 伺服器持續執行。如果您使用 Supervisor 執行 Reverb,您應該更新伺服器的 supervisor.conf 檔案的 minfds 設定,以確保 Supervisor 能夠開啟處理 Reverb 伺服器連線所需的檔案:

[supervisord]
...
minfds=10000

擴展 (Scaling)

如果您需要處理超過單一伺服器允許的連線數,您可以水平擴展您的 Reverb 伺服器。利用 Redis 的發布/訂閱功能,Reverb 能夠管理跨多個伺服器的連線。當您的應用程式的其中一個 Reverb 伺服器接收到訊息時,該伺服器將使用 Redis 將傳入的訊息發布到所有其他伺服器。

要啟用水平擴展,您應該在應用程式的 .env 設定檔中將 REVERB_SCALING_ENABLED 環境變數設定為 true:

REVERB_SCALING_ENABLED=true

接下來,您應該有一個專用的中央 Redis 伺服器,所有 Reverb 伺服器都將與之通訊。Reverb 將使用為您的應用程式設定的預設 Redis 連線將訊息發布到所有 Reverb 伺服器。

一旦您啟用了 Reverb 的擴展選項並設定了 Redis 伺服器,您只需在能夠與您的 Redis 伺服器通訊的多個伺服器上呼叫 reverb:start 指令。這些 Reverb 伺服器應該放置在負載平衡器後面,該負載平衡器將傳入的請求均勻分配到各個伺服器。

Reverb

On this page