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

개요

이 문서는 ServBay 사용자가 macOS 로컬 개발 환경에서 ServBay에 내장된 PHP와 Composer를 활용해 Workerman 기반의 고성능 비동기 네트워크 애플리케이션을 신속하게 구축하고 실행하는 방법을 안내합니다. Workerman은 웹 서버, 실시간 통신 서버, 게임 서버 등 높은 동시 처리가 필요한 각종 네트워크 서비스 구현에 적합한 강력한 PHP 라이브러리입니다. 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: 직관적인 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 환경이 기본 내장 및 설정되어 있어 Workerman 프로젝트를 손쉽게 구축/실행할 수 있도록 도와줍니다.

이 가이드에서는 ServBay 환경에서 Workerman 앱을 신속하게 구축·실행하는 기초 예제(HTTP 서버, WebSocket 서버, TCP 서버)를 단계별로 소개합니다.

TIP

프로젝트 관리의 편의성과 일관성 유지를 위하여, ServBay에서는 모든 로컬 웹사이트 프로젝트 파일을 /Applications/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 내장 터미널 또는 ServBay가 PHP & Composer를 시스템 PATH에 추가했다면 외부 터미널에서도 Composer를 사용할 수 있습니다.

터미널을 열고 아래 명령어로 Composer 상태를 점검하세요:

bash

composer -v

Composer가 정상적으로 설치·설정됐다면 버전 정보를 볼 수 있습니다. 만약 명령어를 찾지 못한다면 ServBay 실행 및 PHP 버전 활성화 상태를 재확인하세요.

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

ServBay 권장 웹사이트 루트 디렉터리로 이동해 새로운 프로젝트 폴더를 만드세요:

bash

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

servbay-workerman-demo라는 디렉터리에 Workerman 프로젝트 파일을 생성할 것입니다.

3. Composer로 Workerman 설치

프로젝트 루트(/Applications/ServBay/www/servbay-workerman-demo)에서 Composer로 Workerman 라이브러리를 설치하세요. Composer가 의존성까지 자동 처리해줍니다:

bash

composer require workerman/workerman

설치가 완료되면, 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 서버를 8080 포트(모든 네트워크 인터페이스)에 바인딩한다는 의미
// 0.0.0.0은 본인/로컬 네트워크 등 다양한 디바이스에서 접근 가능, 8080은 포트 번호
$http_worker = new Worker('http://0.0.0.0:8080');

// Worker 프로세스 개수 설정
// 예시에서는 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 프로세스가 포트 리슨 및 이벤트 처리 시작
Worker::runAll();

코드 설명:

require __DIR__ . '/vendor/autoload.php';: Composer 오토로더를 불러와 Workerman(Class 등) 자동 로드 가능.
use Workerman\...;: 필요한 클래스 임포트.
new Worker('http://0.0.0.0:8080'): Workerman 인스턴스 생성, HTTP + 8080 포트 지정.
$http_worker->count = 4;: 프로세스 수 지정, 동시 처리 성능 향상에 활용.
$http_worker->onMessage = function(TcpConnection $connection, Request $request) { ... };: HTTP 요청 수신 시 실행되는 콜백, $connection으로 응답 전송, $request로 요청 정보 접근, Response로 표준 HTTP 응답 생성.
Worker::runAll();: 이벤트 루프 구동, 선언한 Worker 인스턴스가 모두 동작 시작.

Workerman HTTP 서버 실행하기

프로젝트 폴더(/Applications/ServBay/www/servbay-workerman-demo)에서 터미널을 열고 다음 명령어로 HTTP 서버를 시작하세요:

bash

php http_server.php start

실행 모드 안내:

포그라운드 모드: php http_server.php start 실행 시 서버가 터미널에 정보/로그 출력하며 포그라운드에서 동작합니다. Ctrl+C로 중지. 개발·디버깅에 적합.
데몬(백그라운드) 모드: 운영 환경에서는 백그라운드에서 안정적으로 실행해야 하므로 -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 (코드 갱신 시 활용, 자식 프로세스 순차 재시작 – 중단 없이 서비스 제공)
상태 확인: php http_server.php status (Workerman 프로세스, 메모리, 연결 수 등 확인)

서버가 실행되면 브라우저에서 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 핸드셰이크 자동 처리
$ws_worker = new Worker('websocket://0.0.0.0:8081');

// 4개 프로세스로 동시 연결 처리
$ws_worker->count = 4;

// 새 연결 발생 시 처리
// 신규 클라이언트 접속 시 실행
$ws_worker->onConnect = function(TcpConnection $connection) {
    echo "새 WebSocket 연결: " . $connection->getRemoteIp() . "\n";
};

// 메시지 수신 시 처리
// 클라이언트로부터 WebSocket 메시지 도착 시 실행
// $data는 클라이언트가 보낸 메시지(디코딩 완료된 내용)
$ws_worker->onMessage = function(TcpConnection $connection, $data) {
    echo "수신 메시지: " . $data . "\n";
    // 받은 메시지를 클라이언트에 그대로 돌려보냄
    // $connection->send()는 WebSocket 프레임으로 자동 인코딩
    $connection->send('ServBay Workerman received: ' . $data);
};

// 연결 종료 시 처리
$ws_worker->onClose = function(TcpConnection $connection) {
    echo "WebSocket 연결 종료\n";
};

// 오류 발생 시 처리 (선택 사항)
$ws_worker->onError = function(TcpConnection $connection, $code, $msg) {
    echo "오류 발생: $code - $msg\n";
};

// 모든 Worker 인스턴스 실행
Worker::runAll();

WebSocket 서버 실행

프로젝트 폴더에서 다음 명령어로 WebSocket 서버를 시작하세요:

bash

php websocket_server.php start

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

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

javascript

var ws = new WebSocket("ws://localhost:8081");

ws.onopen = function(event) {
  console.log("WebSocket 연결 열림");
  ws.send("Hello from Browser!"); // 메시지 보내기
};

ws.onmessage = function(event) {
  console.log("서버로부터 메시지:", event.data); // 메시지 수신
};

ws.onclose = function(event) {
  if (event.wasClean) {
    console.log("WebSocket 연결이 정상적으로 종료됨, 코드=" + event.code + " 이유=" + event.reason);
  } else {
    console.error("WebSocket 연결이 비정상적으로 종료됨");
  }
};

ws.onerror = function(error) {
  console.error("WebSocket 에러:", error);
};

// 연결 종료(옵션)
// ws.close();

성공적으로 연결되면 터미널에 연결정보가 출력되고, 메시지 송수신 시 상호 데이터가 화면에 표시됩니다.

Workerman으로 TCP 서버 만들기

Workerman은 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 서버
// 기본 텍스트 프로토콜(줄 끝 '\n'), 필요시 커스텀 가능
$tcp_worker = new Worker('tcp://0.0.0.0:8082');

// 4개 프로세스로 동시 연결 처리
$tcp_worker->count = 4;

// 연결 시 처리
$tcp_worker->onConnect = function(TcpConnection $connection) {
    echo "새 TCP 연결: " . $connection->getRemoteIp() . "\n";
    // 환영 메시지 전송
    $connection->send("Welcome to ServBay Workerman TCP Server!\n");
};

// 메시지 수신 시 처리
// $data는 클라이언트가 보낸 원본 TCP 데이터(프로토콜 파싱 결과)
$tcp_worker->onMessage = function(TcpConnection $connection, $data) {
    echo "수신 데이터: " . $data;
    // 받은 데이터를 클라이언트에 반환
    $connection->send('ServBay Workerman received: ' . $data);
};

// 연결 종료 시 처리
$tcp_worker->onClose = function(TcpConnection $connection) {
    echo "TCP 연결 종료\n";
};

// 모든 Worker 인스턴스 실행
Worker::runAll();

TCP 서버 실행
프로젝트 디렉터리에서 터미널로 아래 명령어를 입력해 TCP 서버를 시작하세요:
bash
```
php tcp_server.php start
```
1
역시 -d 옵션으로 백그라운드 동작이 가능합니다. 실행되면 TCP 클라이언트 툴(예: telnet, nc)로 localhost:8082에 연결해 테스트할 수 있습니다.
macOS/Linux에서는 추가 터미널에서 아래와 같이 입력하면 됩니다:
bash
```
# telnet 사용
telnet localhost 8082

# 또는 netcat(nc) 사용
nc localhost 8082
```
1
2
3
4
5
연결 후 서버의 환영 메시지가 출력되고, 아무 문자열(엔터로 전송)을 입력하면 서버가 해당 내용을 반송합니다.

유의사항

포트 충돌: Workerman이 사용하는 포트(8080, 8081, 8082 등이 예시)와 macOS 및 ServBay 내 다른 실행 중인 서비스가 충돌하지 않는지 확인하세요. 포트가 이미 사용 중이면 Workerman이 실행되지 않고 오류가 발생합니다. lsof -i :포트번호로 사용현황 점검이 가능합니다.
방화벽: macOS의 내장 방화벽 설정에 따라 외부기기가 포트에 접근이 제한될 수 있습니다. 로컬 개발용이라면 문제 없으나, 로컬 네트워크 내 타 기기에서 접속해야 한다면 macOS 방화벽을 별도로 설정하세요.
ServBay 웹 서버와의 관계: Workerman은 고유 포트에서 별도 프로세스로 가동되며, ServBay 내 Caddy/Nginx와는 독립적으로 작동합니다. Workerman 앱은 직접 연결을 처리하며, 별도 리버스 프록시 설정을 하지 않는 한 Caddy/Nginx를 경유하지 않습니다(단, 리버스 프록시 구성도 가능). WebSocket 등 장시간 연결, 고동시성 비동기 서비스에 Workerman이 적합하고, Caddy/Nginx는 짧은 HTTP 요청·응답 처리에 적합한 구조입니다.
PHP 버전: ServBay에서 Workerman을 실행할 때, 해당 PHP 버전이 Workerman 최소 요구사항(5.4 이상)에 부합하는지 확인하세요. ServBay는 여러 PHP 버전을 지원·내장하므로, 프로젝트에 맞는 버전을 컨트롤 패널에서 실행하세요.
확장 모듈: Workerman은 고성능 및 기능 구현을 위해 일부 PHP 확장(event – 존재 시 우선 사용, 성능상 우위, 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: Caddy/Nginx는 전통적 웹서버로 HTTP/HTTPS 요청을 처리하고 PHP-FPM과 함께 사용됩니다(요청 처리 후 PHP 프로세스가 종료). Workerman은 자체 HTTP/WebSocket/TCP 서버로 비동기 네트워크 서비스 구현에 적합하며, 메모리에 상주해 긴 연결·고동시성·실시간 통신에 강점이 있습니다. 전통적인 사이트, RESTful API는 Caddy/Nginx에, 채팅·게임·IoT 등 고동시성/실시간 서비스는 Workerman에 적합합니다. 둘을 조합(예: Caddy/Nginx의 리버스 프록시 → Workerman)해 사용할 수도 있습니다.
Q: ServBay에서 여러 개 Workerman 앱을 동시에 실행할 수 있나요?
- A: 가능합니다. 앱마다 독립된 PHP 프로세스로 각기 다른 포트에서 동작하면 됩니다. 각 서버 스크립트를 별도의 터미널에서 php your_app_server.php start로 실행하고, 포트 충돌만 피하세요.

요약

이 가이드를 통해 빠르고 효율적인 로컬 개발 환경 ServBay에서 Workerman 기반 프로젝트를 신속하게 구축 및 실행하는 방법을 배웠습니다. Workerman의 고성능 및 비동기 특성은 PHP 개발자에게 차세대 네트워크 애플리케이션을 구현할 강력한 역량을 제공합니다. ServBay의 Composer/PHP 올인원 환경과 결합함으로써, 복잡한 환경 설정에 시간을 뺏기지 않고 Workerman 앱의 핵심 비즈니스 구현에 집중할 수 있습니다. 고성능 웹서비스, 실시간 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)

요약