ServBay에서 Workerman 애플리케이션 구축 및 실행

개요

이 문서는 ServBay 사용자가 macOS 및 Windows에서 ServBay에 내장된 PHP 환경과 Composer를 활용하여 Workerman 기반의 고성능 비동기 네트워크 애플리케이션을 신속하게 구축하고 실행하는 방법을 안내합니다. Workerman은 고동시성 처리가 필요한 다양한 네트워크 서비스(웹 서버, 실시간 통신 서버, 게임 서버 등)에 적합한 강력한 PHP 라이브러리입니다. ServBay는 환경 설정 절차를 대폭 간소화해주는 바로 사용할 수 있는 개발 플랫폼을 제공합니다.

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 라이브러리로써 Composer를 통한 의존성 관리, 기존 PHP 생태계와 무리 없이 통합
데몬(서비스) 모드: 백그라운드에서 확실하게 실행할 수 있는 데몬 방식 지원. 프로덕션 환경 배포에 적합, 서비스의 안정성 보장

Workerman은 PHP 개발자에게 고성능, 실시간, 고동시성 네트워크 애플리케이션 구현의 새로운 가능성을 엽니다.

ServBay를 이용한 Workerman 개발 환경 구축

ServBay는 웹 개발자를 위해 설계된 로컬 개발 환경 도구로, 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

예제의 모든 프로젝트 경로는 해당 디렉터리를 기준으로 설명합니다.

사전 준비 사항

시작하기 전, 다음 조건을 충족하세요:

ServBay 설치 및 정상 실행: ServBay 공식 웹사이트에서 최신 버전 ServBay를 다운로드하여 설치하세요.
PHP 활성화: ServBay의 컨트롤 패널에서 사용할 PHP 버전이 활성화되어 있는지 확인하세요. Workerman은 PHP 5.4 이상이 필요하며, 최적 성능을 위해 PHP 7.x 또는 8.x 사용을 권장합니다.
기본 PHP 및 커맨드라인 사용 지식: PHP 문법과 터미널에서 명령어 도구를 사용하는 기본적인 지식이 필요합니다.

Workerman 설치

1. Composer 사용 가능 여부 확인

ServBay에는 Composer가 내장되어 있어 별도의 설치가 필요 없습니다. ServBay 환경을 시작하고 사용할 PHP 버전을 활성화하세요. ServBay는 자동으로 해당 PHP 버전별 Composer 환경을 설정합니다. ServBay의 터미널 또는 시스템 PATH에 PHP와 Composer가 추가되어 있다면 외부 터미널에서 Composer를 사용할 수 있습니다.

터미널을 열어 다음 명령어로 Composer가 정상적으로 동작하는지 확인하세요:

bash

composer -v

Composer가 ServBay PHP 환경에 제대로 설치 및 설정되어 있다면 버전 정보가 출력됩니다. 명령을 찾을 수 없다면 ServBay 실행 및 PHP 버전 활성화를 다시 확인하세요.

2. 프로젝트 디렉터리 생성

ServBay 권장 웹 루트 디렉터리로 이동하여 새 프로젝트 디렉터리를 만들고 진입하세요:

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

여기서 servbay-workerman-demo 라는 디렉터리를 생성해 Workerman 프로젝트 파일을 저장합니다.

3. Composer로 Workerman 설치

프로젝트 디렉터리에서 Composer로 Workerman 라이브러리를 설치하세요. Composer가 의존성을 자동으로 관리합니다.

프로젝트 디렉터리 경로:

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

bash

composer require workerman/workerman

Composer는 Workerman 및 관련 의존성을 vendor 폴더에 자동으로 다운로드합니다.

Workerman HTTP 서버 코드 작성

HTTP 서버는 Workerman의 대표적인 활용 사례로, 고성능 웹 애플리케이션이나 API 서비스를 구축할 때 사용합니다.

프로젝트 디렉터리에 http_server.php (또는 원하는 파일명, 예: server.php) 파일을 만들고 아래 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 서버를 생성하며 모든 네트워크 인터페이스(0.0.0.0)의 8080 포트를 감시함
// 0.0.0.0은 로컬 및 LAN 내 다른 기기에서도 접근 가능, 8080은 감시 포트 번호
$http_worker = new Worker('http://0.0.0.0:8080');

// Worker 프로세스 수 설정
// 여기서는 4개로 설정, 즉 요청을 처리하는 별도의 PHP 프로세스를 4개 생성함. CPU 코어 수에 따라 조정 가능
$http_worker->count = 4;

// 클라이언트 메시지(HTTP 요청) 수신 시 처리 로직 정의
// $connection은 현재 연결 객체로, 클라이언트에 응답 전송에 사용
// $request는 현재 요청 객체 (URL, 헤더, 바디 등 상세 정보 포함)
$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(...) { ... };: HTTP 요청 수신 시 실행되는 콜백 함수, 클라이언트에 응답 전송
Worker::runAll();: 워커 실행, 모든 이벤트 처리 루프 시작

Workerman HTTP 서버 실행

프로젝트 디렉터리에서 다음 명령어로 HTTP 서버를 시작합니다:

프로젝트 디렉터리 경로:

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

bash

php http_server.php start

실행 모드 설명:

포그라운드 모드: php http_server.php start 명령 실행 시 서버가 포그라운드에서 실행되며, 터미널에 실행 정보 및 로그가 출력됩니다. Ctrl+C로 서버를 중지할 수 있습니다. 개발 및 디버깅에 적합합니다.
데몬(백그라운드) 모드: 프로덕션 환경에서는 보통 Workerman을 백그라운드 서비스로 안정적으로 실행해야 합니다. -d 옵션을 사용하세요:
bash
```
php http_server.php start -d
```
1
백그라운드 실행 시 출력이 로그 파일로 리디렉션됩니다 (기본적으로 Workerman 디렉터리 또는 지정한 경로).

프로세스 관리 명령어:

Workerman은 편리한 프로세스 관리 명령어를 제공합니다:

시작: php http_server.php start (포그라운드) 또는 php http_server.php start -d (백그라운드)
정지: php http_server.php stop (현재 요청 처리 후 우아하게 종료)
재시작: php http_server.php restart (정지 후 재시작)
구동 중 재시작(리로드): 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을 매우 쉽게 지원합니다.

WebSocket 서버 코드 작성

프로젝트 디렉터리에 websocket_server.php 파일을 생성하고 다음 코드를 추가하세요:

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

WebSocket 서버 실행

프로젝트 디렉터리에서 아래 명령어로 WebSocket 서버를 시작하세요:

bash

php websocket_server.php start

-d 옵션으로 백그라운드 실행도 가능합니다. 서버가 시작되면 WebSocket 클라이언트에서 ws://localhost:8081로 연결할 수 있습니다.

예를 들어 브라우저 개발자도구 Console에서 아래 JavaScript로 테스트할 수 있습니다:

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 기반의 게임 서버, IoT 플랫폼, 사용자정의 통신 서비스 등 다양한 활용이 가능합니다.

TCP 서버 코드 작성

프로젝트 디렉터리에 tcp_server.php 파일을 생성하고 다음 코드를 추가하세요:

php

<?php
require __DIR__ . '/vendor/autoload.php';

use Workerman\Worker;
use Workerman\Connection\TcpConnection;

// TCP 서버 인스턴스 생성, 8082 포트 감시
// 'tcp://0.0.0.0:8082'로 TCP 서버 생성
// Workerman은 기본적으로 텍스트 프로토콜(줄 끝 \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();

TCP 서버 실행
프로젝트 디렉터리에서 아래 명령어로 TCP 서버를 시작하세요:
bash
```
php tcp_server.php start
```
1
-d 옵션으로 백그라운드 실행도 가능합니다. 서버가 시작되면 TCP 클라이언트 툴로 localhost:8082에 연결할 수 있습니다.
예를 들어 다른 터미널 창에서 아래 명령어를 실행하세요:
bash
```
# telnet 사용
telnet localhost 8082

# 또는 nc(netcat) 사용
nc localhost 8082
```
1
2
3
4
5
연결이 성공하면 환영 메시지가 출력됩니다. 텍스트 입력 후 Enter(줄 바꿈)는 서버가 받은 데이터의 에코 메시지를 돌려줍니다(기본적으로 텍스트 프로토콜 사용).

주의사항

포트 중복 문제: Workerman이 사용하는 포트(예: 8080, 8081, 8082)가 macOS 또는 ServBay의 다른 프로그램과 충돌하지 않는지 확인하세요. 포트 충돌 시 Workerman이 실행되지 않고 에러가 발생합니다. lsof -i :포트번호 명령어로 포트 사용 상태를 확인할 수 있습니다.
방화벽 설정: OS의 내장 방화벽이 외부에서 해당 포트에 접근하는 것을 차단할 수 있습니다. 로컬 개발 환경에서는 문제가 되지 않지만, LAN 내 타 기기에서 접속이 필요하다면 방화벽 설정을 점검하세요.
ServBay 웹 서버와의 관계: Workerman은 자체적으로 포트를 감시하는 독립 프로세스(예: Caddy/Nginx와 별개)로 동작합니다. 보통 직접 연결을 처리하며, Caddy/Nginx를 통해 reverse proxy를 구성하지 않는 이상 두 서비스는 독립적입니다. Workerman은 WebSocket, 고동시성, 장기 연결에 적합하며, ServBay의 Caddy/Nginx는 일반적인 짧은 연결 HTTP 처리에 적합합니다.
PHP 버전: Workerman 실행에 쓰는 PHP 버전이 최소 요구사항(5.4 이상)을 충족하는지 확인하세요. ServBay에 여러 PHP 버전이 기본 설치되어 있으니 필요한 버전을 컨트롤 패널에서 선택/활성화하세요.
확장 의존성: Workerman은 event(설치 및 활성시 성능 더 좋음), posix, pcntl(멀티 프로세스 지원) 등 PHP 확장에 일부 의존합니다. ServBay는 대부분 확장을 기본 활성화하지만, 문제가 있을 경우 해당 PHP 버전 별 확장 활성 여부를 확인하세요.
로그 관리: 데몬(백그라운드) 모드에서 실행할 경우 Workerman의 출력은 로그 파일로 전환됩니다. 애플리케이션 상태 및 오류 파악을 위해 주기적으로 로그 파일을 확인하세요.

자주 묻는 질문 (FAQ)

Q: Workerman 서버를 어떻게 중지하나요?
- A: 서버가 포그라운드에서 실행 중이라면 터미널에서 Ctrl+C로 중지할 수 있습니다. 데몬(백그라운드) 모드로 실행 중이라면 프로젝트 디렉터리에서 php your_server_file.php stop 명령어로 종료하세요.
Q: Workerman 서버가 실행되지 않는 이유는?
- A: 가장 흔한 원인은 감시하는 포트가 이미 다른 서비스에 의해 점유된 경우입니다. 터미널에 표시되는 오류 정보를 확인하시고, 포트 충돌 시 새로운 포트를 사용하거나 해당 포트를 사용 중인 프로그램을 중지하세요. lsof -i :포트번호로 포트 사용 중인 프로세스 확인 가능합니다.
Q: ServBay의 Caddy/Nginx와 Workerman의 차이 및 사용 기준은?
- A: Caddy/Nginx는 전통적인 웹 서버로 HTTP/HTTPS 요청 처리에 최적화되어 PHP-FPM과 연동해 요청마다 프로세스가 종료될 수 있습니다. Workerman은 PHP 비동기 네트워크 프레임워크로, 자체적으로 HTTP, WebSocket, TCP 등을 감시하며 메모리 상에서 상주합니다. 고동시성, 장기 연결, 실시간 통신 앱에 더 적합합니다. 일반적인 웹, RESTful API는 Caddy/Nginx가 적합하고, 실시간 채팅, 게임 백엔드, IoT 서비스 등은 Workerman이 적합합니다. 필요시 reverse proxy로 Caddy/Nginx와 Workerman을 병행할 수 있습니다.
Q: ServBay에서 여러 Workerman 애플리케이션을 동시 실행할 수 있나요?
- A: 가능합니다. 각 Workerman 앱별로 고유한 PHP 프로세스(및 포트)를 할당하세요. 각각의 실행 스크립트를 만들고 별도 터미널 또는 백그라운드에서 php your_app_server.php start로 구동하면 됩니다. 단, 포트 충돌에 주의하세요.

마무리

이 가이드로 ServBay의 강력한 로컬 개발 환경을 활용하여 Workerman 프로젝트를 신속히 구축 및 실행하는 방법을 익혔습니다. Workerman은 고성능, 비동기 특성 덕분에 PHP 개발자에게 차세대 네트워크 애플리케이션 구현의 강력한 도구를 제공합니다. ServBay의 Composer, PHP 통합 환경을 활용하면 복잡한 환경 설정 대신 비즈니스 로직 개발에 집중할 수 있습니다. 고성능 웹 서비스, 실시간 WebSocket 애플리케이션 등 어느 분야든 ServBay는 Workerman 개발의 최고의 로컬 파트너입니다. 이 문서가 Workerman의 새로운 가능성을 여는 첫걸음이 되길 바랍니다!

ServBay에서 Workerman 애플리케이션 구축 및 실행 ​

개요 ​

Workerman이란? ​

Workerman의 핵심 기능과 장점 ​

ServBay를 이용한 Workerman 개발 환경 구축 ​

사전 준비 사항 ​

Workerman 설치 ​

1. Composer 사용 가능 여부 확인 ​

2. 프로젝트 디렉터리 생성 ​

3. Composer로 Workerman 설치 ​

Workerman HTTP 서버 코드 작성 ​

Workerman HTTP 서버 실행 ​

Workerman으로 WebSocket 서버 만들기 ​

Workerman으로 TCP 서버 만들기 ​

주의사항 ​

자주 묻는 질문 (FAQ) ​

마무리 ​

ServBay에서 Workerman 애플리케이션 구축 및 실행

개요

Workerman이란?

Workerman의 핵심 기능과 장점

ServBay를 이용한 Workerman 개발 환경 구축

사전 준비 사항

Workerman 설치

1. Composer 사용 가능 여부 확인

2. 프로젝트 디렉터리 생성

3. Composer로 Workerman 설치

Workerman HTTP 서버 코드 작성

Workerman HTTP 서버 실행

Workerman으로 WebSocket 서버 만들기

Workerman으로 TCP 서버 만들기

주의사항

자주 묻는 질문 (FAQ)

마무리