Xây dựng và chạy ứng dụng Workerman trong ServBay

Tổng quan

Tài liệu này hướng dẫn người dùng ServBay cách xây dựng và chạy nhanh các ứng dụng mạng hiệu năng cao dựa trên Workerman, tận dụng môi trường PHP và Composer đã tích hợp sẵn trên macOS và Windows. Workerman là một thư viện PHP mạnh mẽ, chuyên dùng để xây dựng các dịch vụ mạng có yêu cầu xử lý đồng thời lớn như máy chủ Web, truyền thông thời gian thực, game server, v.v. ServBay cung cấp nền tảng phát triển sẵn sàng sử dụng, giúp đơn giản hóa đáng kể quy trình cấu hình môi trường cho Workerman.

Workerman là gì?

Workerman là một framework truyền thông mạng bất đồng bộ hiệu năng cao, mã nguồn mở, phát triển hoàn toàn bằng PHP. Dựa trên cơ chế vòng lặp sự kiện EventLoop, Workerman thực thi I/O bất đồng bộ không chặn, xử lý hiệu quả lượng lớn kết nối đồng thời. Khác với mô hình phát triển Web PHP truyền thống (Apache/Nginx + PHP-FPM), ứng dụng Workerman thường chạy thường trú trong bộ nhớ, lắng nghe trên cổng nhất định và trực tiếp xử lý kết nối mạng, giúp loại bỏ chi phí khởi tạo/huỷ PHP process sau mỗi request, qua đó tăng mạnh hiệu năng và khả năng xử lý.

Với Workerman, nhà phát triển có thể dễ dàng xây dựng:

Máy chủ HTTP hiệu năng cao, có thể thay thế Apache/Nginx cho các ứng dụng đơn giản.
Máy chủ WebSocket thời gian thực cho chat, đẩy dữ liệu, v.v.
Máy chủ TCP/UDP cho các giao thức tùy chỉnh.
Công cụ dòng lệnh, tác vụ định kỳ, microservice...

Tính năng và lợi thế nổi bật của Workerman

Hiệu năng cao: Được thiết kế dựa trên sự kiện và I/O bất đồng bộ – xử lý hàng nghìn kết nối đồng thời hiệu quả vượt trội.
Hỗ trợ đa giao thức: Tích hợp sẵn các giao thức HTTP, WebSocket, TCP, UDP phổ biến, và API linh hoạt cho giao thức tùy chỉnh.
Dễ sử dụng: API trực quan, thân thiện với PHP Developer giúp lập trình mạng bất đồng bộ trở nên đơn giản.
Mở rộng linh hoạt: Hỗ trợ đa tiến trình giúp khai thác tốt CPU đa nhân và cân bằng tải. Dễ dàng tích hợp package Composer hoặc thư viện PHP hiện có.
Tương thích hệ sinh thái PHP: Là một thư viện PHP nên có thể quản lý dependency với Composer một cách liền mạch.
Chạy nền (Daemon): Hỗ trợ chế độ daemon chạy ngầm ổn định phù hợp triển khai production, đảm bảo dịch vụ luôn sẵn sàng.

Workerman mở ra cánh cửa phát triển ứng dụng mạng hiệu năng cao, thời gian thực cho cộng đồng lập trình viên PHP.

Xây dựng môi trường phát triển Workerman với ServBay

ServBay là bộ công cụ môi trường phát triển chuyên biệt cho lập trình viên Web, tích hợp các runtime PHP, Node.js, Python, Go, Java… cùng các server/database phổ biến: Caddy, Nginx, Apache, MySQL, PostgreSQL, MongoDB, Redis, Memcached… Điểm mạnh lớn của ServBay là tính “cài là chạy”, đặc biệt Composer đã được cài đặt và cấu hình sẵn sàng, đem lại sự tiện lợi vượt trội khi xây dựng ứng dụng Workerman.

Hướng dẫn này sẽ tạo các ví dụ cơ bản minh hoạ cách xây dựng và vận hành nhanh ứng dụng Workerman trong ServBay, gồm: máy chủ HTTP đơn giản, máy chủ WebSocket và máy chủ TCP.

TIP

Để quản lý và chuẩn hoá tốt, ServBay đề xuất lưu code dự án vào các thư mục sau:

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

Mọi ví dụ đường dẫn trong tài liệu đều căn cứ vào các thư mục này.

Điều kiện tiên quyết

Trước khi bắt đầu, hãy đảm bảo các yêu cầu sau:

Đã cài đặt và khởi động ServBay: Truy cập website chính thức của ServBay để tải và cài đặt phiên bản mới nhất.
PHP đã được bật trong ServBay: Mở bảng điều khiển ServBay, chọn và bật phiên bản PHP muốn sử dụng. Workerman cần PHP >= 5.4, nhưng nên dùng PHP 7.x hoặc 8.x để đạt tối ưu hiệu năng.
Có kiến thức PHP và thao tác dòng lệnh: Nắm vững cú pháp PHP và biết dùng chương trình dòng lệnh trong terminal.

Cài đặt Workerman

1. Kiểm tra Composer đã sẵn sàng

Composer đã được tích hợp trong ServBay, không cần cài riêng. Chỉ cần đảm bảo môi trường ServBay đã khởi động và đúng PHP version được bật. Composer sẽ tự động cấu hình khớp với từng phiên bản PHP. Có thể sử dụng Composer qua terminal nội bộ của ServBay hoặc từ terminal ngoài nếu ServBay đã thêm PHP và Composer vào PATH hệ thống.

Mở terminal, kiểm tra Composer bằng lệnh:

bash

composer -v

Nếu cấu hình đúng, bạn sẽ thấy bản thông tin Composer. Nếu bị báo lỗi, kiểm tra lại ServBay đã chạy và PHP đã được bật chưa.

2. Tạo thư mục dự án

Di chuyển tới thư mục gốc website ServBay và tạo thư mục dự án mới, sau đó vào thư mục đó:

macOS:

bash

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

Windows:

cmd

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

Ở đây, servbay-workerman-demo là tên thư mục chứa code Workerman.

3. Cài Workerman qua Composer

Trong thư mục dự án, chạy Composer để cài Workerman và các dependency:

Đường dẫn dự án:

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

bash

composer require workerman/workerman

Composer sẽ tự động tải Workerman về vendor của dự án.

Viết code máy chủ Workerman HTTP

Máy chủ HTTP là một trong những use case phổ biến nhất của Workerman — giúp xây dựng Web service hoặc API hiệu năng cao.

Trong thư mục dự án, tạo file http_server.php (hoặc tên bạn thích, như server.php) và chèn đoạn mã sau:

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 服务器，监听所有网络接口（0.0.0.0）的 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 协议会自动处理 HTTP 响应头等细节
    $connection->send(new Response(200, [], 'Hello ServBay Workerman HTTP Server!'));
};

// 运行所有的 Worker 实例
// 这是 Workerman 的主循环，启动后 Worker 进程开始监听端口并处理事件
Worker::runAll();

Giải thích mã:

require __DIR__ . '/vendor/autoload.php';: Nạp file autoload của Composer giúp sử dụng các class của Workerman (Worker, Request, Response,...).
use Workerman\...;: Import các class cần thiết.
new Worker('http://0.0.0.0:8080'): Tạo instance Workerman, lắng nghe giao thức HTTP ở lĩnh vực "0.0.0.0:8080".
$http_worker->count = 4;: Tạo 4 tiến trình PHP — có thể thay đổi tuỳ số core CPU.
$http_worker->onMessage = function(...) { ... };: Callback này xử lý request HTTP nhận được. Đối tượng $connection dùng gửi data về client, $request chứa info của request. Class Response dùng để trả về response HTTP đúng chuẩn.
Worker::runAll();: Khởi chạy vòng lặp sự kiện, bắt đầu lắng nghe kết nối và xử lý.

Chạy máy chủ HTTP Workerman

Trong dự án, dùng terminal thực hiện lệnh sau để khởi động server:

Đường dẫn dự án:

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

bash

php http_server.php start

Chế độ chạy:

Chạy foreground: Lệnh trên sẽ chạy server ở terminal, hiện log thông tin, dừng bằng Ctrl+C. Phù hợp debug, phát triển.
Chạy daemon (background): Thêm tham số -d để chạy ngầm:
bash
```
php http_server.php start -d
```
1
Log sẽ được chuyển vào file log.

Quản lý tiến trình:

Workerman cung cấp loạt lệnh quản trị tiện lợi:

Start: php http_server.php start (foreground) hoặc php http_server.php start -d (background)
Stop: php http_server.php stop (dừng nhẹ, xử lý hết request rồi mới thoát)
Restart: php http_server.php restart (stop rồi start lại)
Reload: php http_server.php reload (thường dùng khi cập nhật code, server sẽ reload tiến trình không làm gián đoạn service)
Kiểm tra status: php http_server.php status (xem trạng thái, RAM, số kết nối...)

Khởi động xong bạn mở trình duyệt và vào http://localhost:8080 hoặc http://127.0.0.1:8080, màn hình sẽ hiện dòng chữ Hello ServBay Workerman HTTP Server!.

Tạo máy chủ WebSocket với Workerman

WebSocket tạo kết nối hai chiều liên tục giữa client/server, cực kỳ phù hợp với ứng dụng thời gian thực (chat, push data, game…).

Viết code máy chủ WebSocket

Tạo file websocket_server.php và chèn đoạn mã sau:

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 帧发送
    $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();

Chạy máy chủ WebSocket

Trong thư mục dự án, dùng lệnh sau để khởi chạy server:

bash

php websocket_server.php start

Có thể thêm -d chạy nền. Xong rồi, kết nối tới ws://localhost:8081 bằng công cụ WebSocket (ví dụ trình duyệt, Postman, v.v).

Test nhanh qua Console Chrome/Firefox:

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();

Khi connect thành công, terminal sẽ log thông tin kết nối/nhận dữ liệu. Browser sẽ nhận lại tin nhắn echo server trả về.

Tạo máy chủ TCP bằng Workerman

Workerman cũng có thể xây dựng máy chủ TCP tuỳ chỉnh cho các ứng dụng: game backend, IoT, truyền thông riêng...

Viết code máy chủ TCP

Tạo file tcp_server.php và thêm code sau:

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();

Chạy máy chủ TCP
Trong dự án, chạy server TCP bằng lệnh:
bash
```
php tcp_server.php start
```
1
Có thể thêm -d để chạy nền. Sau khi chạy, dùng công cụ TCP Client (telnet hoặc nc) để test:
bash
```
# Dùng telnet
telnet localhost 8082

# Hoặc dùng nc
nc localhost 8082
```
1
2
3
4
5
Khi kết nối thành công, server sẽ gửi thông báo chào mừng. Gõ text và enter (do mặc định là giao thức Text, kết thúc bằng \n), server sẽ phản hồi lại nội dung bạn gửi.

Lưu ý khi sử dụng

Cổng đang sử dụng: Đảm bảo các cổng 8080, 8081, 8082 không bị hệ điều hành hoặc ứng dụng khác trong ServBay chiếm dụng. Nếu bị trùng, Workerman sẽ báo lỗi và không start được. Kiểm tra bằng lệnh lsof -i :port.
Firewall: Tường lửa OS có thể ngăn thiết bị khác trong mạng truy cập cổng trên. Nếu cần, hãy cấu hình firewall cho phép truy cập.
Quan hệ với máy chủ Web ServBay: Workerman chạy trên cổng riêng biệt, là tiến trình độc lập với Caddy/Nginx bên trong ServBay. Thông thường, Workerman xử lý trực tiếp kết nối thay vì đi qua proxy như Caddy/Nginx (trừ khi bạn thiết lập reverse proxy). Workerman chuyên cho quy trình kết nối lâu, đồng thời cao (WebSocket), còn Caddy/Nginx phù hợp với xử lý HTTP truyền thống ngắn hạn.
Phiên bản PHP: Chắc chắn bạn dùng đúng phiên bản PHP đáp ứng yêu cầu của Workerman (ServBay cài nhiều bản PHP, bạn chọn/kích hoạt bản phù hợp trên panel).
Phụ thuộc vào extension: Workerman dùng một số extension như event (nếu cài và bật sẽ tối ưu hiệu năng), posix, pcntl để xử lý đa tiến trình. ServBay kích hoạt phần lớn extension phổ biến, nếu gặp vấn đề hãy kiểm tra lại extension tương ứng đã bật chưa.
Log: Khi chạy daemon mode, output sẽ vào file log. Hãy kiểm tra log định kỳ để theo dõi tình trạng/server lỗi.

Giải đáp thắc mắc thường gặp (FAQ)

Q: Làm thế nào dừng máy chủ Workerman?
- A: Nếu chạy foreground (start), chỉ cần bấm Ctrl+C ở terminal. Nếu chạy daemon (start -d), dùng lệnh php your_server_file.php stop trong thư mục dự án.
Q: Server Workerman không khởi động được?
- A: Phổ biến nhất là cổng bị dùng bởi app khác. Kiểm tra thông báo lỗi trên terminal. Cố gắng đổi cổng khác hoặc dừng chương trình đang chiếm cổng. Dùng lệnh lsof -i :port.
Q: So sánh Caddy/Nginx trong ServBay và Workerman? Dùng cái nào?
- A: Caddy/Nginx là web server xử lý HTTP/HTTPS truyền thống với PHP-FPM, mỗi request xong thì PHP process có thể bị huỷ. Workerman là PHP framework mạng bất đồng bộ, có thể chạy HTTP server riêng, xử lý WebSocket, TCP, v.v. Workerman chuyên cho xử lý đồng thời lớn, kết nối lâu và realtime. Chọn cái nào tuỳ use-case: Website/API truyền thống dùng Caddy/Nginx, còn chat, backend game, IoT... nên dùng Workerman. Cũng có thể kết hợp ví dụ dùng Caddy/Nginx reverse proxy forward request tới Workerman.
Q: Có thể chạy nhiều app Workerman cùng lúc trong ServBay không?
- A: Có. Mỗi app phải chạy thành tiến trình PHP riêng, lắng nghe cổng khác nhau. Chỉ cần viết script riêng, start ở các terminal khác hoặc chạy nền đảm bảo không bị trùng cổng.

Tổng kết

Sau hướng dẫn này, bạn đã biết cách nhanh chóng cài đặt, chạy ứng dụng Workerman trong môi trường ServBay tối ưu cho phát triển local. Workerman mang lại sức mạnh xử lý đồng thời, hiệu năng cao cho PHP, giải quyết tốt các nhu cầu ứng dụng mạng thế hệ mới. Với môi trường Composer, PHP "ready to use" của ServBay, bạn tiết kiệm nhiều thời gian cấu hình, tập trung vào business logic của Workerman app. Từ dịch vụ web hiệu năng cao đến ứng dụng realtime interact WebSocket, ServBay sẽ là người bạn đồng hành lý tưởng khi phát triển Workerman. Chúc bạn thành công khám phá Workerman cùng ServBay!

Xây dựng và chạy ứng dụng Workerman trong ServBay ​

Tổng quan ​

Workerman là gì? ​

Tính năng và lợi thế nổi bật của Workerman ​

Xây dựng môi trường phát triển Workerman với ServBay ​

Điều kiện tiên quyết ​

Cài đặt Workerman ​

1. Kiểm tra Composer đã sẵn sàng ​

2. Tạo thư mục dự án ​

3. Cài Workerman qua Composer ​

Viết code máy chủ Workerman HTTP ​

Chạy máy chủ HTTP Workerman ​

Tạo máy chủ WebSocket với Workerman ​

Tạo máy chủ TCP bằng Workerman ​

Lưu ý khi sử dụng ​

Giải đáp thắc mắc thường gặp (FAQ) ​

Tổng kết ​

Xây dựng và chạy ứng dụng Workerman trong ServBay

Tổng quan

Workerman là gì?

Tính năng và lợi thế nổi bật của Workerman

Xây dựng môi trường phát triển Workerman với ServBay

Điều kiện tiên quyết

Cài đặt Workerman

1. Kiểm tra Composer đã sẵn sàng

2. Tạo thư mục dự án

3. Cài Workerman qua Composer

Viết code máy chủ Workerman HTTP

Chạy máy chủ HTTP Workerman

Tạo máy chủ WebSocket với Workerman

Tạo máy chủ TCP bằng Workerman

Lưu ý khi sử dụng

Giải đáp thắc mắc thường gặp (FAQ)

Tổng kết