> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Laravel Reverb

> Laravel 애플리케이션에 실시간 WebSocket 통신을 제공하는 공식 서버 패키지

<Info>
  이 페이지는 Reverb 서버 자체의 셋업과 운용에 초점을 맞추고 있습니다.
  브로드캐스트 이벤트의 작성이나 Laravel Echo의 사용법은 [브로드캐스트](/ko/broadcasting)를 참조해 주세요.
</Info>

## Reverb란

[Laravel Reverb](https://github.com/laravel/reverb)는 Laravel이 공식으로 제공하는 셀프 호스트형 WebSocket 서버입니다.
외부 서비스에의 의존 없이, 고속이고 스케일 가능한 실시간 통신을 Laravel 애플리케이션에 추가할 수 있습니다.

Reverb는 [브로드캐스트](/ko/broadcasting) 기반 위에서 동작하며, 서버 사이드의 이벤트를 WebSocket 경유로 브라우저에 전달하는 역할을 담당합니다.

```mermaid theme={null}
flowchart LR
    A["브라우저<br>Laravel Echo"] -->|"WebSocket 접속"| B["Laravel Reverb<br>서버"]
    B -->|"인가·라우팅"| C["채널<br>관리"]
    C -->|"이벤트 배포"| A
    D["Laravel 앱<br>이벤트 발화"] -->|"브로드캐스트<br>(큐 경유)"| B
```

## 설치

`install:broadcasting` Artisan 명령을 사용하면, Reverb를 포함한 모든 의존 관계를 한꺼번에 설치할 수 있습니다.

```shell theme={null}
php artisan install:broadcasting
```

명령 실행 시에 Reverb를 선택하거나, `--reverb` 옵션을 붙여 실행하면 자동적으로 Reverb가 셋업됩니다.

```shell theme={null}
php artisan install:broadcasting --reverb
```

이 명령은 다음을 수행합니다.

* Composer 패키지 (`laravel/reverb`)의 설치
* NPM 패키지 (`laravel-echo`, `pusher-js`)의 설치
* `.env`에의 환경 변수 추가
* `config/reverb.php`의 생성

수동으로 설치하는 경우는 Composer로 패키지를 추가한 후 `reverb:install`을 실행합니다.

```shell theme={null}
composer require laravel/reverb
php artisan reverb:install
```

## 설정

### 애플리케이션 인증 정보

클라이언트와 서버의 접속 확립에 사용할 인증 정보를 환경 변수로 설정합니다.

```ini theme={null}
REVERB_APP_ID=my-app-id
REVERB_APP_KEY=my-app-key
REVERB_APP_SECRET=my-app-secret
```

이러한 값은 `config/reverb.php`의 `apps` 섹션에서 참조됩니다.

### 허용할 오리진 (Allowed Origins)

클라이언트 리퀘스트를 허용할 오리진을 `config/reverb.php`의 `allowed_origins`로 제한할 수 있습니다.

```php theme={null}
'apps' => [
    [
        'app_id' => 'my-app-id',
        'allowed_origins' => ['laravel.com'],
        // ...
    ]
]
```

모든 오리진을 허용하는 경우는 `*`을 지정합니다.

### 여러 앱 대응

1개의 Reverb 서버에서 여러 애플리케이션에 대응할 수 있습니다.
`config/reverb.php`의 `apps` 배열에 여러 엔트리를 추가합니다.

```php theme={null}
'apps' => [
    [
        'app_id' => 'my-app-one',
        // ...
    ],
    [
        'app_id' => 'my-app-two',
        // ...
    ],
],
```

### SSL 설정

프로덕션 환경에서는 Nginx 등의 웹 서버가 SSL 종단을 담당하고, Reverb에 리퀘스트를 프록시하는 것이 일반적입니다.
로컬 개발 환경에서 Secure WebSocket (`wss://`)을 사용하고 싶은 경우는, Laravel Herd나 Valet의 인증서를 활용할 수 있습니다.

```shell theme={null}
php artisan reverb:start --host="0.0.0.0" --port=8080 --hostname="laravel.test"
```

인증서를 수동으로 지정하는 경우는 `config/reverb.php`의 `tls` 옵션을 설정합니다.

```php theme={null}
'options' => [
    'tls' => [
        'local_cert' => '/path/to/cert.pem'
    ],
],
```

## 서버 기동

`reverb:start` Artisan 명령으로 서버를 기동합니다.

```shell theme={null}
php artisan reverb:start
```

기본적으로 `0.0.0.0:8080`에서 기동합니다.
`--host` / `--port` 옵션으로 커스텀 어드레스를 지정할 수 있습니다.

```shell theme={null}
php artisan reverb:start --host=127.0.0.1 --port=9000
```

환경 변수로도 지정할 수 있습니다.

```ini theme={null}
REVERB_SERVER_HOST=0.0.0.0
REVERB_SERVER_PORT=8080
```

<Info>
  `REVERB_SERVER_HOST` / `REVERB_SERVER_PORT`는 서버 자체의 리슨 어드레스입니다.
  `REVERB_HOST` / `REVERB_PORT`는 Laravel 앱이 브로드캐스트 메시지를 송신하는 앞의 어드레스입니다.
  프로덕션 환경에서는 이들이 다른 경우가 있습니다.
</Info>

### 디버그 모드

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

```shell theme={null}
php artisan reverb:start --debug
```

### 서버의 재기동

Reverb는 상주 프로세스이기 때문에, 코드의 변경을 반영하려면 재기동이 필요합니다.
`reverb:restart` 명령은 모든 접속을 graceful하게 종료한 후 서버를 정지합니다.

```shell theme={null}
php artisan reverb:restart
```

Supervisor 등의 프로세스 매니저를 사용하고 있는 경우, 정지 후에 자동적으로 재기동됩니다.

## 모니터링

Reverb는 [Laravel Pulse](https://laravel.com/docs/pulse)와의 연계를 지원하고 있습니다.
접속 수나 메시지 수를 실시간으로 대시보드에 표시할 수 있습니다.

우선 `config/pulse.php`에 Reverb의 레코더를 추가합니다.

```php theme={null}
use Laravel\Reverb\Pulse\Recorders\ReverbConnections;
use Laravel\Reverb\Pulse\Recorders\ReverbMessages;

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

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

    // ...
],
```

다음으로 Pulse 대시보드의 템플릿에 카드를 추가합니다.

```blade theme={null}
<x-pulse>
    <livewire:reverb.connections cols="full" />
    <livewire:reverb.messages cols="full" />
    ...
</x-pulse>
```

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

## 프로덕션 환경에서의 운용

### 파일 오픈 제한

WebSocket 접속은 1접속당 1파일 디스크립터를 소비합니다.
OS 레벨의 제한을 확인하고, 필요에 따라 상한을 올립니다.

```shell theme={null}
ulimit -n
```

`/etc/security/limits.conf`에서 상한을 변경할 수 있습니다.

```ini theme={null}
# /etc/security/limits.conf
forge        soft  nofile  10000
forge        hard  nofile  10000
```

### 이벤트 루프 (ext-uv)

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

```shell theme={null}
pecl install uv
```

`ext-uv`를 이용할 수 있는 경우, Reverb는 자동적으로 그쪽을 사용합니다.

### Nginx 리버스 프록시

프로덕션 환경에서는 Reverb를 직접 공개하지 않고, Nginx 등의 웹 서버로 프록시합니다.
아래는 Nginx의 설정 예입니다.

```nginx theme={null}
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는 WebSocket 접속을 `/app`에서, API 리퀘스트를 `/apps`에서 받습니다.
  웹 서버의 설정에서 양쪽 URI에의 접근을 허용해 주세요.
</Warning>

동시 접속 수를 늘리려면 `nginx.conf`의 `worker_rlimit_nofile`과 `worker_connections`를 조정합니다.

```nginx theme={null}
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.conf`의 `minfds`를 설정해 필요한 파일 디스크립터를 확보합니다.

```ini theme={null}
[supervisord]
...
minfds=10000
```

Supervisor의 설정 예:

```ini theme={null}
[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 기능을 사용한 수평 스케일링이 가능합니다.

```mermaid theme={null}
flowchart TB
    LB["로드 밸런서"] --> R1["Reverb 서버 1"]
    LB --> R2["Reverb 서버 2"]
    LB --> R3["Reverb 서버 3"]
    R1 <-->|"pub/sub"| Redis["Redis"]
    R2 <-->|"pub/sub"| Redis
    R3 <-->|"pub/sub"| Redis
```

`.env`에서 스케일링을 활성화합니다.

```env theme={null}
REVERB_SCALING_ENABLED=true
```

Reverb는 애플리케이션의 기본 Redis 접속을 사용해 서버 간에 메시지를 주고받습니다.
여러 Reverb 서버를 기동하고, 로드 밸런서로 리퀘스트를 분산합니다.

<Info>
  [Laravel Cloud](https://cloud.laravel.com)에서는 인프라 관리 없이 Reverb 대응 앱을 배포할 수 있는
  풀 매니지드 WebSocket 인프라를 제공하고 있습니다.
</Info>

## 이벤트

Reverb는 접속·메시지의 라이프사이클에서 이하의 이벤트를 발행합니다.
[이벤트 리스너](/ko/events)로 이들을 받아, 독자적인 처리를 추가할 수 있습니다.

| 이벤트                | 설명                             |
| ------------------ | ------------------------------ |
| `ChannelCreated`   | 채널이 작성되었을 때 (최초의 접속이 서브스크라이브)  |
| `ChannelRemoved`   | 채널이 삭제되었을 때 (마지막 접속이 언서브스크라이브) |
| `ConnectionPruned` | 오래된 접속이 서버에 의해 절단되었을 때         |
| `MessageReceived`  | 클라이언트로부터 메시지를 수신했을 때           |
| `MessageSent`      | 클라이언트에 메시지를 송신했을 때             |

이러한 이벤트는 모두 `Laravel\Reverb\Events` 네임스페이스에 속합니다.

## 다음 단계

<Card title="브로드캐스트" href="/ko/broadcasting">
  브로드캐스트 이벤트의 작성, 채널 인가, Laravel Echo의 설정 방법을 확인
</Card>

<Card title="이벤트와 리스너" href="/ko/events">
  Reverb가 발행하는 이벤트를 받기 위한 Laravel 이벤트 시스템을 배움
</Card>


## Related topics

- [브로드캐스팅](/ko/broadcasting.md)
- [Laravel 11 이후의 새 앱 구조 FAQ](/ko/advanced/app-structure-faq.md)
- [배포](/ko/deployment.md)
- [Laravel Cloud — Laravel 전용 PaaS의 전모](/ko/blog/laravel-cloud.md)
- [2026년 3월 Laravel 업데이트](/ko/blog/changelog/202603.md)