Laravel Reverb

업데이트됨

번역일: 2026년 6월 20일

이 페이지는 원문이 업데이트되어 번역이 갱신되었습니다.

원문 수정: 2026년 6월 20일
번역 갱신: 2026년 6월 20일

Laravel Reverb

소개
설치
설정
서버 실행
- 디버깅
- 재시작
모니터링
프로덕션 환경에서 Reverb 운영
이벤트

소개

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

설치

install:broadcasting Artisan 명령어로 Reverb를 설치할 수 있습니다:

php artisan install:broadcasting

설정

install:broadcasting 명령어를 실행하면 내부적으로 reverb:install 명령어가 함께 실행되며, 합리적인 기본 설정으로 Reverb가 설치됩니다. 설정을 변경하려면 .env 파일의 환경 변수를 수정하거나 config/reverb.php 파일을 직접 편집하면 됩니다.

애플리케이션 인증 정보

클라이언트가 Reverb에 연결하려면 클라이언트와 서버 사이에 Reverb "애플리케이션" 인증 정보가 교환되어야 합니다. 이 인증 정보는 서버에서 설정하며, 클라이언트 요청의 유효성을 검증하는 데 사용됩니다. 다음 환경 변수로 인증 정보를 정의할 수 있습니다:

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

허용 오리진

클라이언트 요청을 허용할 오리진은 config/reverb.php 파일의 apps 섹션 내 allowed_origins 값으로 설정합니다. 목록에 없는 오리진에서 온 요청은 거부됩니다. 모든 오리진을 허용하려면 *를 사용하세요:

'apps' => [
    [
        'app_id' => 'my-app-id',
        'allowed_origins' => ['example.com'],
        // ...
    ]
]

다중 애플리케이션

기본적으로 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로 해석되므로, 위 명령어를 실행하면 Reverb 서버에 wss://laravel.test:8080으로 보안 WebSocket 프로토콜(wss)을 통해 접근할 수 있습니다.

인증서를 직접 지정하려면 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.com
REVERB_PORT=443

디버깅

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

php artisan reverb:start --debug

재시작

Reverb는 장시간 실행되는 프로세스이므로, 코드 변경 사항을 반영하려면 서버를 재시작해야 합니다. reverb:restart Artisan 명령어를 사용하세요:

php artisan reverb:restart

reverb:restart 명령어는 서버를 중지하기 전에 모든 기존 연결을 안전하게 종료합니다. Supervisor 같은 프로세스 관리자를 사용 중이라면, 모든 연결이 종료된 후 프로세스 관리자가 서버를 자동으로 재시작합니다.

모니터링

Reverb는 Laravel Pulse와의 통합을 통해 모니터링할 수 있습니다. Reverb의 Pulse 통합을 활성화하면 서버에서 처리 중인 연결 수와 메시지 수를 추적할 수 있습니다.

먼저 Pulse를 설치한 뒤, config/pulse.php 파일에 Reverb 레코더를 추가하세요:

use Laravel\Reverb\Pulse\Recorders\ReverbConnections;
use Laravel\Reverb\Pulse\Recorders\ReverbMessages;

'recorders' => [
    ReverbConnections::class => [
        'sample_rate' => 1,
    ],

    ReverbMessages::class => [
        'sample_rate' => 1,
    ],

    // ...
],

그런 다음, Pulse 대시보드에 각 레코더에 해당하는 카드를 추가하세요:

<x-pulse>
    <livewire:reverb.connections cols="full" />
    <livewire:reverb.messages cols="full" />
    ...
</x-pulse>

연결 활동은 주기적인 폴링으로 기록됩니다. Pulse 대시보드에서 이 정보가 올바르게 표시되려면 Reverb 서버에서 pulse:check 데몬을 실행해야 합니다. 수평 확장 구성으로 운영 중이라면 서버 중 하나에서만 이 데몬을 실행하세요.

프로덕션 환경에서 Reverb 운영

WebSocket 서버는 장시간 실행되는 특성 때문에, 서버에서 사용 가능한 리소스 내에서 최적의 연결 수를 처리할 수 있도록 서버와 호스팅 환경을 일부 최적화해야 할 수 있습니다.

NOTE

Laravel Cloud는 Laravel Reverb 클러스터 기반의 완전 관리형 WebSocket 인프라를 제공합니다. 인프라를 직접 관리하지 않고도 Reverb 기반 애플리케이션을 쉽게 확장하고 배포할 수 있습니다.

열린 파일 수 제한

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

운영체제 설정

Unix 계열 운영체제에서 현재 허용된 열린 파일 수는 다음 명령어로 확인할 수 있습니다:

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로 동작하며 별도 확장이 필요 없지만, stream_select는 열린 파일 수가 1,024개로 제한되어 있습니다. 따라서 1,000개 이상의 동시 연결을 처리할 계획이라면 이 제한이 없는 대체 이벤트 루프를 사용해야 합니다.

ext-uv 확장이 설치되어 있으면 Reverb가 자동으로 ext-uv 기반 루프로 전환합니다. 이 PHP 확장은 PECL을 통해 설치할 수 있습니다:

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

    ...
}

WARNING

Reverb는 /app 경로에서 WebSocket 연결을 수신하고 /apps 경로에서 API 요청을 처리합니다. 웹 서버가 이 두 URI를 모두 처리할 수 있도록 설정해야 합니다. Laravel Forge로 서버를 관리하는 경우 Reverb 서버가 기본적으로 올바르게 설정됩니다.

일반적으로 웹 서버는 서버 과부하를 방지하기 위해 허용 연결 수를 제한합니다. 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;
}

이 설정은 프로세스당 최대 10,000개의 Nginx 워커를 생성하고, Nginx의 열린 파일 수 제한도 10,000으로 설정합니다.

포트

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

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

위 출력 결과를 보면 각 연결마다 빈 포트가 하나씩 필요하므로, 서버가 최대 28,231개(60,999 - 32,768)의 연결을 처리할 수 있음을 알 수 있습니다. 더 많은 연결이 필요한 경우 수평 확장을 권장하지만, /etc/sysctl.conf 파일에서 허용 포트 범위를 늘려 가용 포트 수를 늘릴 수도 있습니다.

프로세스 관리

대부분의 경우 Supervisor 같은 프로세스 관리자를 사용하여 Reverb 서버가 지속적으로 실행되도록 해야 합니다. Supervisor로 Reverb를 실행할 때는 supervisor.conf 파일의 minfds 값을 조정하여 Supervisor가 Reverb 서버의 연결 처리에 필요한 파일을 열 수 있도록 해야 합니다:

[supervisord]
...
minfds=10000

수평 확장

단일 서버가 처리할 수 있는 연결 수 이상을 처리해야 한다면 Reverb 서버를 수평으로 확장할 수 있습니다. Reverb는 Redis의 Pub/Sub 기능을 활용하여 여러 서버에 걸친 연결을 관리합니다. 한 Reverb 서버가 메시지를 수신하면 Redis를 통해 다른 모든 서버에 해당 메시지를 발행합니다.

수평 확장을 활성화하려면 .env 파일에 REVERB_SCALING_ENABLED 환경 변수를 true로 설정하세요:

REVERB_SCALING_ENABLED=true

그런 다음, 모든 Reverb 서버가 통신할 전용 중앙 Redis 서버를 준비해야 합니다. Reverb는 애플리케이션에 설정된 기본 Redis 연결을 사용하여 모든 Reverb 서버에 메시지를 발행합니다.

확장 옵션을 활성화하고 Redis 서버를 구성한 뒤에는, Redis 서버와 통신 가능한 여러 서버에서 각각 reverb:start 명령어를 실행하면 됩니다. 이 Reverb 서버들은 들어오는 요청을 균등하게 분산하는 로드 밸런서 뒤에 배치해야 합니다.

이벤트

Reverb는 연결 및 메시지 처리 생명주기 동안 내부 이벤트를 디스패치합니다. 이 이벤트에 리스너를 등록하여 연결이 관리되거나 메시지가 교환될 때 원하는 동작을 수행할 수 있습니다.

Reverb가 디스패치하는 이벤트 목록은 다음과 같습니다:

`Laravel\Reverb\Events\ChannelCreated`

채널이 생성될 때 디스패치됩니다. 일반적으로 특정 채널에 첫 번째 연결이 구독할 때 발생합니다. Laravel\Reverb\Protocols\Pusher\Channel 인스턴스를 전달받습니다.

`Laravel\Reverb\Events\ChannelRemoved`

채널이 제거될 때 디스패치됩니다. 일반적으로 채널의 마지막 연결이 구독을 해제할 때 발생합니다. Laravel\Reverb\Protocols\Pusher\Channel 인스턴스를 전달받습니다.

`Laravel\Reverb\Events\ConnectionPruned`

서버가 오래된 연결을 정리할 때 디스패치됩니다. Laravel\Reverb\Contracts\Connection 인스턴스를 전달받습니다.

`Laravel\Reverb\Events\MessageReceived`

클라이언트 연결로부터 메시지가 수신될 때 디스패치됩니다. Laravel\Reverb\Contracts\Connection 인스턴스와 원시 문자열 $message를 전달받습니다.

`Laravel\Reverb\Events\MessageSent`

클라이언트 연결로 메시지가 전송될 때 디스패치됩니다. Laravel\Reverb\Contracts\Connection 인스턴스와 원시 문자열 $message를 전달받습니다.