在 ServBay 架設及運行 Workerman 應用

概述

本文旨在指導 ServBay 使用者如何在本機 macOS 和 Windows 開發環境下，利用 ServBay 整合的 PHP 及 Composer，快速搭建並運行基於 Workerman 的高效能非同步網路應用。Workerman 是一款強大的 PHP 函式庫，適合建構各類需高併發處理的網路服務，如 Web 伺服器、即時通訊伺服器、遊戲伺服器等。ServBay 提供即裝即用的開發平台，大幅簡化 Workerman 的環境配置流程。

什麼是 Workerman？

Workerman 是一套完全由 PHP 編寫的開源高效能非同步網路通訊框架。它基於 EventLoop 事件循環機制，實現非同步非阻塞 I/O，能有效處理大量併發連線。與傳統 PHP 網頁開發模式（如 Apache/Nginx + PHP-FPM）不同，Workerman 應用通常以常駐記憶體方式運行，直接監聽指定連接埠並處理網路連線與資料，無需每次請求結束即銷毀程序，大幅提升效能及吞吐量。

藉由 Workerman，開發者可輕鬆建構：

• 高效能 HTTP 伺服器，可直接處理簡單靜態或動態請求，甚至可替代 Apache/Nginx 使用。
• 即時 WebSocket 伺服器，適用於聊天室、即時資料推送等應用。
• 各類自訂協議的 TCP/UDP 伺服器。
• 命令列工具、排程任務、微服務等。

Workerman 的核心特色與優勢

• 高效能：內建事件驅動及非同步非阻塞 I/O，能處理龐大併發連線，效能卓越。
• 多協議支援：原生支援 HTTP、WebSocket、TCP、UDP 等主流網路協議，並提供彈性介面可自行擴充協議。
• 易於上手：簡潔直覺的 API 設計，降低非同步網路程式設計複雜度，PHP 開發者易學易用。
• 彈性擴充：多進程模型設計，有助充分運用多核 CPU 做水平擴充及負載均衡。可輕鬆整合 Composer 套件及既有 PHP 函式庫。
• PHP 生態整合：以 PHP 函式庫形式，與現有 PHP 生態系統緊密結合，可無縫透過 Composer 管理依賴。
• 守護程序模式：支援守護程序（Daemon）方式，穩定在背景執行，適合生產環境佈署，保證服務持續可用。

Workerman 為 PHP 工程師打開打造高效能、即時、高併發網路應用的大門。

利用 ServBay 建構 Workerman 開發環境

ServBay 是專為 Web 開發者量身打造的本機開發環境工具，內建 PHP、Node.js、Python、Go、Java 等主流語言執行環境，並整合 Caddy、Nginx、Apache、MySQL、PostgreSQL、MongoDB、Redis、Memcached 等常用資料庫與伺服器軟體。ServBay 最大優勢在於「即裝即用」，且預設整合 Composer 環境，讓在 ServBay 上架設及執行 Workerman 專案變得更容易。

本教學將以建立基本範例方式，引導如何在 ServBay 環境下快速架設並運行 Workerman 應用，包括簡易 HTTP 伺服器、WebSocket 伺服器及 TCP 伺服器。

TIP

為便於管理與規範，ServBay 建議將所有本機網站專案檔案儲存於以下路徑：

• macOS: /Applications/ServBay/www
• Windows: C:\ServBay\www

本文件中所有專案路徑範例均以此目錄為基準。

前置條件

開始操作前，請確保：

1. 已安裝並啟動 ServBay：請至 ServBay 官方下載頁 取得最新版並安裝。
2. 已啟用 ServBay 的 PHP：於 ServBay 控制面板確認擬使用的 PHP 版本已啟動。Workerman 需 PHP 5.4 以上，建議選用 PHP 7.x 或 8.x 取得最佳效能。
3. 具備基本 PHP 與命令列操作知識：需了解 PHP 語法及如何於終端使用指令操作。

安裝 Workerman

1. 確認 Composer 可用

ServBay 已預設整合 Composer，無需額外安裝。只要 ServBay 已啟動，且擬用 PHP 版本已啟用，即可在 ServBay 終端或外部終端（ServBay 若已將 PHP 與 Composer 加入系統 PATH）中使用 Composer。

開啟終端，輸入以下指令檢查 Composer 是否可用：

composer -v

若 Composer 正常安裝並已配置於 ServBay PHP 環境，終端將顯示 Composer 版本資訊。若出現指令未找到的訊息，請檢查 ServBay 是否已啟動及 PHP 是否已啟用。

2. 建立專案目錄

切換至 ServBay 推薦的網站根目錄，建立新專案資料夾並進入：

macOS:

cd /Applications/ServBay/www
mkdir servbay-workerman-demo
cd servbay-workerman-demo

Windows:

cd C:\ServBay\www
mkdir servbay-workerman-demo
cd servbay-workerman-demo

在此我們將所有 Workerman 專案檔案存放於 servbay-workerman-demo 目錄。

3. 使用 Composer 安裝 Workerman

於專案目錄使用 Composer 安裝 Workerman 套件。此安裝方式建議使用，Composer 會自動處理所有依賴：

專案目錄路徑:

• macOS: /Applications/ServBay/www/servbay-workerman-demo
• Windows: C:\ServBay\www\servbay-workerman-demo

composer require workerman/workerman

Composer 將自動下載 Workerman 與其依賴至當前目錄下的 vendor 資料夾。

撰寫 Workerman HTTP 伺服器程式

HTTP 伺服器是 Workerman 最常見的使用情境之一，可用於建構高效能 Web 應用或 API 服務。

在專案目錄下新建 http_server.php（或自定檔名如 server.php），並加入以下 PHP 程式碼：

<?php
// 引入 Composer 的自動載入檔，讓 Workerman 類別可用
require __DIR__ . '/vendor/autoload.php';

// 載入 Workerman 的 Worker 類
use Workerman\Worker;
use Workerman\Connection\TcpConnection;
use Workerman\Protocols\Http\Request;
use Workerman\Protocols\Http\Response;

// 建立 Worker 實例，指定監聽協議及位址
// 'http://0.0.0.0:8080' 代表建立 HTTP 伺服器並監聽所有網路介面的 8080 埠
// 0.0.0.0 讓本機或同網路設備均可存取，8080 為監聽埠
$http_worker = new Worker('http://0.0.0.0:8080');

// 設定 Worker 進程數量
// 這裡設為 4，表示啟動 4 個獨立 PHP 進程處理請求，可依 CPU 核心數調整
$http_worker->count = 4;

// 定義收到客戶端訊息（HTTP 請求）時的處理邏輯
// $connection 為本次連線物件，可發送回應至客戶端
// $request 為請求物件，包含詳細資訊（URL, Headers, Body 等）
$http_worker->onMessage = function(TcpConnection $connection, Request $request) {
    // 回應客戶端簡單字串作為 HTTP 回應
    // Workerman 會自動處理 HTTP 回應標頭等細節
    $connection->send(new Response(200, [], 'Hello ServBay Workerman HTTP Server!'));
};

// 啟動所有 Worker 實例
// 即 Workerman 主迴圈，開始監聽埠口並處理事件
Worker::runAll();

程式碼說明：

• require __DIR__ . '/vendor/autoload.php';：載入 Composer 的自動載入檔，Workerman 類（如 Worker, Request, Response）即可使用。
• use Workerman\...;：引入所需類別。
• new Worker('http://0.0.0.0:8080')：建立 Workerman 實例，參數指定監聽協議（http）及位址（0.0.0.0:8080）。
• $http_worker->count = 4;：指定啟動幾個進程，增加進程能提升多核併發處理能力。
• $http_worker->onMessage = function(TcpConnection $connection, Request $request) { ... };：Workerman 接收到完整 HTTP 請求時會執行該回呼函式。$connection 用來回傳資料，$request 包含請求內容。用 Response 類建立標準 HTTP 回應。
• Worker::runAll();：啟動 Workerman 事件迴圈，讓所有定義的 Worker 實例開始監聽並處理連線。

運行 Workerman HTTP 伺服器

在專案目錄中開啟終端，輸入指令啟動 HTTP 伺服器：

專案目錄路徑:

• macOS: /Applications/ServBay/www/servbay-workerman-demo
• Windows: C:\ServBay\www\servbay-workerman-demo

php http_server.php start

運行模式說明：

• 前景模式 (Foreground): 執行 php http_server.php start 命令，Workerman 會在前景運行，終端顯示運行資訊及日誌。可按 Ctrl+C 停止，適合開發測試。
• 守護程序模式 (Daemon): 若需背景穩定長期運行，可加入 -d 參數：

  php http_server.php start -d

  Workerman 會在背景運行，並將輸出重定向到日誌檔（預設於 Workerman 目錄下或指定路徑）。

進程管理：

Workerman 提供多種實用進程管理指令：

• 啟動： php http_server.php start（前景）或 php http_server.php start -d（背景）
• 停止： php http_server.php stop（會等現有請求完成後優雅退出）
• 重啟： php http_server.php restart（先停再啟）
• 平滑重啟 (Reload)： php http_server.php reload（常用於程式碼更新，逐一重啟子進程不中斷服務，但需注意生命周期函式如 onWorkerStart）
• 查看狀態： php http_server.php status（顯示運行狀態、記憶體用量、連線數等資訊）

啟動伺服器後，開啟瀏覽器，造訪 http://localhost:8080 或 http://127.0.0.1:8080，即可看到頁面顯示 Hello ServBay Workerman HTTP Server!。

使用 Workerman 建立 WebSocket 伺服器

WebSocket 協議能在客戶端與伺服器間建立持久雙向溝通通道，非常適合即時應用，如線上聊天、股價推送、遊戲等。Workerman 對 WebSocket 支援良好。

1. 撰寫 WebSocket 伺服器程式

   在專案目錄新建 websocket_server.php 檔案，加入：

   <?php
   require __DIR__ . '/vendor/autoload.php';
   
   use Workerman\Worker;
   use Workerman\Connection\TcpConnection;
   
   // 建立 WebSocket 伺服器，監聽 8081 埠
   // 'websocket://0.0.0.0:8081' 即建立 WebSocket 伺服器
   // Workerman 會自動處理 WebSocket 握手
   $ws_worker = new Worker('websocket://0.0.0.0:8081');
   
   // 啟用 4 個進程處理連線
   $ws_worker->count = 4;
   
   // 定義連線建立時的邏輯
   // 新客戶端連接時觸發
   $ws_worker->onConnect = function(TcpConnection $connection) {
       echo "New WebSocket connection from " . $connection->getRemoteIp() . "\n";
   };
   
   // 訊息接收邏輯
   // 伺服器收到客戶端 WebSocket 訊息時觸發
   // $data 為已解碼的客戶端訊息內容
   $ws_worker->onMessage = function(TcpConnection $connection, $data) {
       echo "Received message: " . $data . "\n";
       // 回傳收到的訊息給客戶端
       // $connection->send() 會自動編碼為 WebSocket frame
       $connection->send('ServBay Workerman received: ' . $data);
   };
   
   // 連線關閉時觸發
   $ws_worker->onClose = function(TcpConnection $connection) {
       echo "WebSocket Connection closed\n";
   };
   
   // 錯誤處理邏輯 (選用)
   $ws_worker->onError = function(TcpConnection $connection, $code, $msg) {
       echo "Error: $code - $msg\n";
   };
   
   
   // 啟動所有 Worker 實例
   Worker::runAll();

2. 運行 WebSocket 伺服器

   在專案目錄中執行：

   php websocket_server.php start

   亦可加 -d 背景模式運行。啟動後，可用 WebSocket 客戶端工具連線至 ws://localhost:8081。

   例如，在瀏覽器開發工具的 Console 用 JavaScript 測試：

   var ws = new WebSocket("ws://localhost:8081");
   
   ws.onopen = function(event) {
     console.log("WebSocket connection opened");
     ws.send("Hello from Browser!"); // 傳送訊息
   };
   
   ws.onmessage = function(event) {
     console.log("Message from server:", event.data); // 接收伺服器訊息
   };
   
   ws.onclose = function(event) {
     if (event.wasClean) {
       console.log("WebSocket connection closed cleanly, code=" + event.code + " reason=" + event.reason);
     } else {
       console.error("WebSocket connection died");
     }
   };
   
   ws.onerror = function(error) {
     console.error("WebSocket error:", error);
   };
   
   // 關閉連線 (選擇性)
   // ws.close();

   連線成功後，終端會顯示連線資訊，發送訊息後終端會顯示收到的內容，瀏覽器也會看到伺服器回傳的訊息。

使用 Workerman 建立 TCP 伺服器

Workerman 也可用於打造一般 TCP 伺服器，處理各類基於 TCP 的應用層資料，適用於遊戲後端、物聯網平台、或自訂通訊服務等。

1. 撰寫 TCP 伺服器程式

   在專案目錄新建 tcp_server.php 檔案，加入：

   <?php
   require __DIR__ . '/vendor/autoload.php';
   
   use Workerman\Worker;
   use Workerman\Connection\TcpConnection;
   
   // 建立 TCP 伺服器，監聽 8082 埠
   // 'tcp://0.0.0.0:8082' 代表建立 TCP 伺服器
   // Workerman 預設 Text 協議（行尾為 '\n'），可自訂協議
   $tcp_worker = new Worker('tcp://0.0.0.0:8082');
   
   // 啟用 4 個進程處理連線
   $tcp_worker->count = 4;
   
   // 新連線建立時的邏輯
   $tcp_worker->onConnect = function(TcpConnection $connection) {
       echo "New TCP connection from " . $connection->getRemoteIp() . "\n";
       // 發送歡迎訊息
       $connection->send("Welcome to ServBay Workerman TCP Server!\n");
   };
   
   // 訊息接收邏輯
   // $data 為解析後由客戶端收到的原始 TCP 資料
   $tcp_worker->onMessage = function(TcpConnection $connection, $data) {
       echo "Received data: " . $data;
       // 回傳收到的內容給客戶端
       $connection->send('ServBay Workerman received: ' . $data);
   };
   
   // 連線關閉時
   $tcp_worker->onClose = function(TcpConnection $connection) {
       echo "TCP Connection closed\n";
   };
   
   // 啟動所有 Worker 實例
   Worker::runAll();

2. 運行 TCP 伺服器

   於專案目錄執行：

   php tcp_server.php start

   同樣可加 -d 於背景運行。啟動後，可用 TCP 客戶端工具（如 telnet 或 nc）連線至 localhost:8082。

   例如開啟另一終端窗口，輸入：

   # 使用 telnet
   telnet localhost 8082
   
   # 或用 nc (netcat)
   nc localhost 8082

   連線成功後會收到伺服器歡迎訊息，輸入任意文字並送出（按 Enter，因預設 Text 協議），伺服器將回傳收到的內容。

注意事項

• 連接埠占用：請確認 Workerman 監聽的連接埠（如 8080, 8081, 8082）未被 macOS 或 ServBay 內其他程式占用。若連接埠衝突，Workerman 將無法啟動並報錯。可用 lsof -i :埠號，查詢指定埠是否被占用。
• 防火牆：作業系統防火牆可能限制外部設備存取這些連接埠。於本機開發時通常無礙，若需局域網其他設備存取 Workerman 服務，請檢查與調整作業系統防火牆設置。
• 與 ServBay Web 伺服器的區隔：Workerman 運行於自有監聽埠，與 ServBay 的 Caddy 或 Nginx 為獨立進程與服務。Workerman 通常直接處理連線，不經 Caddy/Nginx 代理（除非另設反向代理）。Workerman 特別適合處理需長連線或高併發非同步場景（如 WebSocket），ServBay 內的 Caddy/Nginx 用於傳統 HTTP 短連線處理。
• PHP 版本：請確保 ServBay 執行 Workerman 的 PHP 版本達最低要求。ServBay 預先安裝多版本 PHP，可於控制面板依需求選擇啟用。
• 擴充依賴：Workerman 依賴部分 PHP 擴充元件以達最佳效能，如 event（若安裝且啟用，Workerman 會優先選用以提升效能）、posix、pcntl（多進程用）。ServBay 預設啟用多數常用擴充，若遇問題請檢查控制面板所選 PHP 版本之擴充啟用狀態。
• 日誌管理：背景（守護程序）模式下，Workerman 的輸出會重導至日誌檔。請定期檢視日誌以掌握應用狀態及潛在錯誤。

常見問題 (FAQ)

• Q: 如何停止 Workerman 伺服器？
  • A: 前景運行（start）時，於終端按 Ctrl+C 即可停止。若背景（守護程序）運行（start -d），需於專案目錄輸入 php your_server_file.php stop 指令。
• Q: 為什麼 Workerman 伺服器無法啟動？
  • A: 最常見原因是監聽連接埠已被占用。請查看終端錯誤訊息，通常會提示埠被占用。可另換未使用的埠，或關掉占用該埠程式。用 lsof -i :埠號 查詢占用該埠的進程。
• Q: ServBay 內的 Caddy/Nginx 與 Workerman 有何不同？我該用哪個？
  • A: ServBay 的 Caddy/Nginx 屬傳統 Web 伺服器，主要處理標準 HTTP/HTTPS 請求，常伴 PHP-FPM 運行，每個請求結束後 PHP 進程可能會結束。Workerman 是 PHP 非同步網路框架，可獨立做 HTTP 伺服器，也支援 WebSocket、TCP 等協議。其以常駐記憶體方式運作，適合高併發、長連線、即時通訊場景。該選用哪個取決於你開發需求：若做傳統網站或 API 較常用 Caddy/Nginx；若做即時聊天、遊戲後端、物聯網等則更適合 Workerman。當然也能搭配，例如 Web 通訊選用 Caddy/Nginx 代理特定請求給 Workerman。
• Q: 我能在 ServBay 內同時運行多個 Workerman 應用嗎？
  • A: 可以。每個 Workerman 應用需在獨立 PHP 進程運行，監聽不同埠口。只要各自寫獨立啟動腳本，於不同終端窗口運行 php your_app_server.php start（或背景模式）即可，記得避免埠號衝突。

總結

依照本教學，你已能掌握如何在 ServBay 高效本機開發環境中，迅速建構並運行 Workerman 專案。Workerman 憑藉高效能與非同步特性，為 PHP 開發者帶來新世代網路應用開發利器。搭配 ServBay 提供的即裝即用 Composer 及 PHP 環境，能有效大幅提升開發效率，使你能專注於 Workerman 應用業務邏輯設計，無需耗時於環境設定。無論是打造高效能 Web 服務，或開發即時互動 WebSocket 應用，ServBay 都是你採用 Workerman 的理想本地開發夥伴。希望本文能助你順利展開 Workerman 的探索之路！