메인 콘텐츠로 건너뛰기
이 페이지는 Reverb 서버 자체의 셋업과 운용에 초점을 맞추고 있습니다. 브로드캐스트 이벤트의 작성이나 Laravel Echo의 사용법은 브로드캐스트를 참조해 주세요.

Reverb란

Laravel Reverb는 Laravel이 공식으로 제공하는 셀프 호스트형 WebSocket 서버입니다. 외부 서비스에의 의존 없이, 고속이고 스케일 가능한 실시간 통신을 Laravel 애플리케이션에 추가할 수 있습니다. Reverb는 브로드캐스트 기반 위에서 동작하며, 서버 사이드의 이벤트를 WebSocket 경유로 브라우저에 전달하는 역할을 담당합니다.

설치

install:broadcasting Artisan 명령을 사용하면, Reverb를 포함한 모든 의존 관계를 한꺼번에 설치할 수 있습니다.
php artisan install:broadcasting
명령 실행 시에 Reverb를 선택하거나, --reverb 옵션을 붙여 실행하면 자동적으로 Reverb가 셋업됩니다.
php artisan install:broadcasting --reverb
이 명령은 다음을 수행합니다.
  • Composer 패키지 (laravel/reverb)의 설치
  • NPM 패키지 (laravel-echo, pusher-js)의 설치
  • .env에의 환경 변수 추가
  • config/reverb.php의 생성
수동으로 설치하는 경우는 Composer로 패키지를 추가한 후 reverb:install을 실행합니다.
composer require laravel/reverb
php artisan reverb:install

설정

애플리케이션 인증 정보

클라이언트와 서버의 접속 확립에 사용할 인증 정보를 환경 변수로 설정합니다.
REVERB_APP_ID=my-app-id
REVERB_APP_KEY=my-app-key
REVERB_APP_SECRET=my-app-secret
이러한 값은 config/reverb.phpapps 섹션에서 참조됩니다.

허용할 오리진 (Allowed Origins)

클라이언트 리퀘스트를 허용할 오리진을 config/reverb.phpallowed_origins로 제한할 수 있습니다.
'apps' => [
    [
        'app_id' => 'my-app-id',
        'allowed_origins' => ['laravel.com'],
        // ...
    ]
]
모든 오리진을 허용하는 경우는 *을 지정합니다.

여러 앱 대응

1개의 Reverb 서버에서 여러 애플리케이션에 대응할 수 있습니다. config/reverb.phpapps 배열에 여러 엔트리를 추가합니다.
'apps' => [
    [
        'app_id' => 'my-app-one',
        // ...
    ],
    [
        'app_id' => 'my-app-two',
        // ...
    ],
],

SSL 설정

프로덕션 환경에서는 Nginx 등의 웹 서버가 SSL 종단을 담당하고, Reverb에 리퀘스트를 프록시하는 것이 일반적입니다. 로컬 개발 환경에서 Secure WebSocket (wss://)을 사용하고 싶은 경우는, Laravel Herd나 Valet의 인증서를 활용할 수 있습니다.
php artisan reverb:start --host="0.0.0.0" --port=8080 --hostname="laravel.test"
인증서를 수동으로 지정하는 경우는 config/reverb.phptls 옵션을 설정합니다.
'options' => [
    'tls' => [
        'local_cert' => '/path/to/cert.pem'
    ],
],

서버 기동

reverb:start Artisan 명령으로 서버를 기동합니다.
php artisan reverb:start
기본적으로 0.0.0.0:8080에서 기동합니다. --host / --port 옵션으로 커스텀 어드레스를 지정할 수 있습니다.
php artisan reverb:start --host=127.0.0.1 --port=9000
환경 변수로도 지정할 수 있습니다.
REVERB_SERVER_HOST=0.0.0.0
REVERB_SERVER_PORT=8080
REVERB_SERVER_HOST / REVERB_SERVER_PORT는 서버 자체의 리슨 어드레스입니다. REVERB_HOST / REVERB_PORT는 Laravel 앱이 브로드캐스트 메시지를 송신하는 앞의 어드레스입니다. 프로덕션 환경에서는 이들이 다른 경우가 있습니다.

디버그 모드

성능을 위해 Reverb는 기본적으로 디버그 정보를 출력하지 않습니다. 접속이나 메시지의 흐름을 확인하고 싶은 경우는 --debug 옵션을 사용합니다.
php artisan reverb:start --debug

서버의 재기동

Reverb는 상주 프로세스이기 때문에, 코드의 변경을 반영하려면 재기동이 필요합니다. reverb:restart 명령은 모든 접속을 graceful하게 종료한 후 서버를 정지합니다.
php artisan reverb:restart
Supervisor 등의 프로세스 매니저를 사용하고 있는 경우, 정지 후에 자동적으로 재기동됩니다.

모니터링

Reverb는 Laravel 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>
접속 상황을 올바르게 기록하기 위해, Reverb 서버에서 pulse:check 데몬을 기동해 주세요. 수평 스케일링 구성인 경우, pulse:check는 1대의 서버에서만 실행합니다.

프로덕션 환경에서의 운용

파일 오픈 제한

WebSocket 접속은 1접속당 1파일 디스크립터를 소비합니다. OS 레벨의 제한을 확인하고, 필요에 따라 상한을 올립니다.
ulimit -n
/etc/security/limits.conf에서 상한을 변경할 수 있습니다.
# /etc/security/limits.conf
forge        soft  nofile  10000
forge        hard  nofile  10000

이벤트 루프 (ext-uv)

Reverb는 기본적으로 PHP의 stream_select를 사용하지만, 이는 최대 1,024 파일의 제한이 있습니다. 1,000 이상의 동시 접속을 다루는 경우는 ext-uv를 설치해 제한을 해방합니다.
pecl install uv
ext-uv를 이용할 수 있는 경우, Reverb는 자동적으로 그쪽을 사용합니다.

Nginx 리버스 프록시

프로덕션 환경에서는 Reverb를 직접 공개하지 않고, Nginx 등의 웹 서버로 프록시합니다. 아래는 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;
    }

    ...
}
Reverb는 WebSocket 접속을 /app에서, API 리퀘스트를 /apps에서 받습니다. 웹 서버의 설정에서 양쪽 URI에의 접근을 허용해 주세요.
동시 접속 수를 늘리려면 nginx.confworker_rlimit_nofileworker_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;
}

프로세스 관리 (Supervisor)

프로덕션 환경에서는 Supervisor로 Reverb 프로세스를 관리합니다. supervisor.confminfds를 설정해 필요한 파일 디스크립터를 확보합니다.
[supervisord]
...
minfds=10000
Supervisor의 설정 예:
[program:reverb]
process_name=%(program_name)s
command=php /path/to/artisan reverb:start
autostart=true
autorestart=true
user=forge
redirect_stderr=true
stdout_logfile=/path/to/reverb.log

스케일링 (Redis)

단일 서버로는 처리할 수 없는 접속 수가 필요한 경우, Redis의 pub/sub 기능을 사용한 수평 스케일링이 가능합니다. .env에서 스케일링을 활성화합니다.
REVERB_SCALING_ENABLED=true
Reverb는 애플리케이션의 기본 Redis 접속을 사용해 서버 간에 메시지를 주고받습니다. 여러 Reverb 서버를 기동하고, 로드 밸런서로 리퀘스트를 분산합니다.
Laravel Cloud에서는 인프라 관리 없이 Reverb 대응 앱을 배포할 수 있는 풀 매니지드 WebSocket 인프라를 제공하고 있습니다.

이벤트

Reverb는 접속·메시지의 라이프사이클에서 이하의 이벤트를 발행합니다. 이벤트 리스너로 이들을 받아, 독자적인 처리를 추가할 수 있습니다.
이벤트설명
ChannelCreated채널이 작성되었을 때 (최초의 접속이 서브스크라이브)
ChannelRemoved채널이 삭제되었을 때 (마지막 접속이 언서브스크라이브)
ConnectionPruned오래된 접속이 서버에 의해 절단되었을 때
MessageReceived클라이언트로부터 메시지를 수신했을 때
MessageSent클라이언트에 메시지를 송신했을 때
이러한 이벤트는 모두 Laravel\Reverb\Events 네임스페이스에 속합니다.

다음 단계

브로드캐스트

브로드캐스트 이벤트의 작성, 채널 인가, Laravel Echo의 설정 방법을 확인

이벤트와 리스너

Reverb가 발행하는 이벤트를 받기 위한 Laravel 이벤트 시스템을 배움
마지막 수정일 2026년 7월 13일