Laravel Reverb

번역일: 2026년 6월 20일

Laravel Reverb

소개
설치
설정
서버 실행
- 디버깅
- 재시작
프로덕션에서 Reverb 실행

소개

Laravel Reverb는 빠르고 확장 가능한 실시간 WebSocket 통신을 Laravel 애플리케이션에 직접 제공하며, Laravel의 이벤트 브로드캐스팅 도구와 자연스럽게 통합됩니다.

설치

WARNING

Laravel Reverb를 사용하려면 PHP 8.2 이상, Laravel 10.47 이상이 필요합니다.

Composer를 사용하여 Reverb를 프로젝트에 설치합니다:

composer require laravel/reverb

패키지 설치 후, 아래 설치 명령을 실행하면 설정 파일 퍼블리시, 필수 환경 변수 추가, 이벤트 브로드캐스팅 활성화가 한 번에 처리됩니다:

php artisan reverb:install

설정

reverb:install 명령은 합리적인 기본값으로 Reverb를 자동 설정합니다. 설정을 변경하려면 .env 파일의 환경 변수를 수정하거나, config/reverb.php 파일을 직접 편집하면 됩니다.

애플리케이션 자격 증명

클라이언트가 Reverb 서버에 연결할 때는 서버-클라이언트 간에 자격 증명(Credentials)을 교환해야 합니다. 이 자격 증명은 서버 측에서 설정되며 클라이언트의 요청을 검증하는 데 사용됩니다. 다음 환경 변수로 정의할 수 있습니다:

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

허용된 오리진

클라이언트 요청을 허용할 오리진(Origin)을 제한할 수 있습니다. config/reverb.php의 apps 섹션 안에서 allowed_origins 값을 설정하면 됩니다. 목록에 없는 오리진에서 온 요청은 거부됩니다. 모든 오리진을 허용하려면 *를 사용하세요:

'apps' => [
    [
        'id' => 'my-app-id',
        'allowed_origins' => ['example.co.kr'],
        // ...
    ]
]

추가 애플리케이션

Reverb는 기본적으로 설치된 애플리케이션 하나를 위한 WebSocket 서버로 동작하지만, 단일 Reverb 인스턴스로 여러 애플리케이션을 동시에 서비스할 수도 있습니다.

예를 들어, 하나의 Laravel 애플리케이션이 Reverb를 통해 여러 서비스에 WebSocket 연결을 제공해야 하는 경우, config/reverb.php에 apps 항목을 여러 개 정의하면 됩니다:

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

SSL

대부분의 경우, 보안 WebSocket 연결(wss://)은 Nginx 같은 업스트림 웹 서버에서 처리한 뒤 Reverb 서버로 프록시됩니다.

그러나 로컬 개발 환경에서는 Reverb 서버가 보안 연결을 직접 처리하는 것이 편리할 수 있습니다. Laravel Herd의 보안 사이트 기능이나 Laravel Valet의 secure 명령을 사용하고 있다면, Herd / Valet이 생성한 인증서를 Reverb에서도 활용할 수 있습니다. 이를 위해 REVERB_HOST 환경 변수를 사이트 호스트명으로 설정하거나, 서버 시작 시 --hostname 옵션을 직접 전달하세요:

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

Herd와 Valet 도메인은 localhost로 해석되므로, 위 명령을 실행하면 wss://laravel.test:8080으로 보안 WebSocket 서버에 접근할 수 있게 됩니다.

인증서를 직접 지정하려면 config/reverb.php의 tls 옵션을 사용하세요. PHP SSL 컨텍스트 옵션을 그대로 활용할 수 있습니다:

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

서버 실행

reverb:start Artisan 명령으로 Reverb 서버를 시작합니다:

php artisan reverb:start

기본적으로 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 환경 변수를 정의할 수도 있습니다.

NOTE

REVERB_SERVER_HOST / REVERB_SERVER_PORT와 REVERB_HOST / REVERB_PORT는 역할이 다릅니다. 전자는 Reverb 서버 프로세스가 바인딩할 주소와 포트이고, 후자는 Laravel이 브로드캐스트 메시지를 보낼 대상 주소입니다.

예를 들어, 프로덕션에서 공개 도메인의 443번 포트로 들어오는 요청을 내부적으로 0.0.0.0:8080의 Reverb 서버로 라우팅하는 경우, 환경 변수는 다음과 같이 설정합니다:

REVERB_SERVER_HOST=0.0.0.0
REVERB_SERVER_PORT=8080

REVERB_HOST=ws.example.co.kr
REVERB_PORT=443

디버깅

성능을 위해 Reverb는 기본적으로 디버그 정보를 출력하지 않습니다. 서버를 통과하는 데이터 흐름을 확인하고 싶다면 --debug 옵션을 사용하세요:

php artisan reverb:start --debug

재시작

Reverb는 장기 실행 프로세스이므로, 코드 변경 사항을 반영하려면 서버를 재시작해야 합니다. reverb:restart 명령을 사용하면 기존 연결을 안전하게 종료한 뒤 서버가 재시작됩니다:

php artisan reverb:restart

Supervisor 같은 프로세스 관리자를 사용하고 있다면, 모든 연결이 종료된 후 프로세스 관리자가 자동으로 서버를 재시작합니다.

프로덕션에서 Reverb 실행

WebSocket 서버는 지속적으로 실행되는 장기 프로세스이기 때문에, 서버 자원을 효율적으로 활용하고 최대한 많은 연결을 처리하려면 몇 가지 최적화가 필요합니다.

NOTE

사이트가 Laravel Forge로 관리되고 있다면, "Application" 패널에서 Reverb 통합을 활성화하는 것만으로 서버 최적화를 자동으로 처리할 수 있습니다. Forge는 필요한 PHP 확장 설치 및 허용 연결 수 증가 등을 자동으로 구성해 줍니다.

열린 파일 수 제한

각 WebSocket 연결은 클라이언트 또는 서버가 연결을 끊을 때까지 메모리에 유지됩니다. Unix 계열 환경에서는 각 연결이 파일 디스크립터 하나로 표현되므로, 운영체제와 애플리케이션 수준의 열린 파일 수 제한에 주의해야 합니다.

운영체제 설정

현재 허용된 열린 파일 수 제한은 ulimit 명령으로 확인할 수 있습니다:

ulimit -n

/etc/security/limits.conf 파일을 편집하여 이 값을 변경할 수 있습니다. 예를 들어, forge 사용자의 최대 열린 파일 수를 10,000으로 늘리려면 다음과 같이 설정합니다:

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

이벤트 루프

Reverb는 내부적으로 ReactPHP 이벤트 루프를 사용하여 WebSocket 연결을 관리합니다. 기본값은 stream_select 기반 루프로, 추가 확장 없이 동작하지만 열린 파일 1,024개로 제한됩니다. 동시 연결이 1,000개를 넘을 것으로 예상된다면 이 제한이 없는 대안 이벤트 루프를 사용해야 합니다.

Reverb는 ext-event, ext-ev, ext-uv 중 하나가 설치되어 있으면 자동으로 해당 루프로 전환합니다. 이 확장들은 PECL로 설치할 수 있습니다:

pecl install event# 또는pecl install ev# 또는pecl install uv

웹 서버

대부분의 경우 Reverb는 외부에 직접 노출되지 않는 내부 포트에서 실행됩니다. 외부 트래픽을 Reverb로 라우팅하려면 리버스 프록시를 설정해야 합니다. Reverb가 0.0.0.0:8080에서 실행 중이고 Nginx를 사용한다면, 다음과 같이 설정합니다:

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;
    }

    ...
}

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;
}

이 설정으로 Nginx 워커당 최대 10,000개의 연결과 열린 파일을 허용하게 됩니다.

포트

Unix 계열 운영체제는 서버에서 열 수 있는 포트 범위에 제한이 있습니다. 현재 허용된 포트 범위는 다음 명령으로 확인할 수 있습니다:

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

위 출력 결과는 각 연결마다 포트 하나가 필요하므로 최대 28,231개(60,999 - 32,768)의 연결을 처리할 수 있음을 의미합니다. 연결 수를 늘리려면 수평 스케일링을 권장하지만, /etc/sysctl.conf에서 포트 범위를 직접 확장하는 방법도 있습니다.

프로세스 관리

Reverb 서버가 지속적으로 실행되도록 Supervisor 같은 프로세스 관리자를 사용하는 것이 좋습니다. Supervisor로 Reverb를 실행하는 경우, supervisor.conf의 minfds 값을 충분히 크게 설정하여 Reverb가 연결 처리에 필요한 파일을 열 수 있도록 해야 합니다:

[supervisord]
...
minfds=10000

스케일링

단일 서버로는 감당하기 어려운 연결 수가 필요하다면, Reverb 서버를 수평으로 스케일링할 수 있습니다. Redis의 Pub/Sub 기능을 활용하면 여러 서버에 걸쳐 연결을 관리할 수 있습니다. 한 Reverb 서버가 메시지를 수신하면 Redis를 통해 나머지 모든 서버에 해당 메시지를 전달합니다.

수평 스케일링을 활성화하려면 .env 파일에 다음 환경 변수를 설정하세요:

REVERB_SCALING_ENABLED=true

다음으로, 모든 Reverb 서버가 통신할 중앙 Redis 서버가 필요합니다. Reverb는 애플리케이션에 설정된 기본 Redis 연결을 사용하여 메시지를 각 서버에 전달합니다.

스케일링 옵션과 Redis 설정을 마쳤으면, Redis 서버에 접근 가능한 여러 서버에서 각각 reverb:start 명령을 실행하세요. 이 Reverb 서버들은 로드 밸런서 뒤에 배치하여 들어오는 요청이 균등하게 분산되도록 구성해야 합니다.