이 가이드에서는 Discourse의 Voice 플러그인을 LiveKit 미디어 서버에 연결하는 방법을 단계별로 안내합니다. 기본적으로 음성 통화는 피어투피어(P2P) 방식으로 작동하며, 모든 참가자가 자신의 오디오를 다른 모든 참가자에게 직접 전송합니다. 이는 소규모 방에서는 잘 작동하지만, 방의 크기가 커질수록 대역폭 사용량이 증가합니다. LiveKit을 통해 통화를 라우팅하면 참가자가 몇 명이든 상관없이 각 참가자의 업로드량이 일정하게 유지됩니다.
사전 요구 사항
시작하기 전에 다음 사항이 준비되어 있는지 확인하세요.
- Voice 플러그인이 활성화된 Discourse 사이트
- 접근 가능한 LiveKit 서버 및 해당 API 자격 증명. LiveKit을 자체 호스팅하거나 LiveKit Cloud와 같은 관리형 서비스를 사용할 수 있습니다.
- Discourse 사이트의 관리자 권한
1단계 — Voice 플러그인 활성화
Voice는 Discourse에 번들링되어 제공됩니다. 관리자 → 설정 → 플러그인으로 이동하여 Voice (voice_enabled) 설정을 켜세요.
2단계 — LiveKit 서버 프로비저닝 및 자격 증명 기록
LiveKit 배포 환경에서 다음 세 가지가 필요합니다: WebSocket URL, API 키, API 시크릿.
LiveKit Cloud를 사용하는 경우 이 단계들은 비교적 간단합니다:
- LiveKit Cloud 대시보드에서 프로젝트를 생성합니다.
- 프로젝트의 설정 → 키 페이지에서 API 키와 API 시크릿을 표시합니다.
- WebSocket URL을 기록합니다 (예:
wss://my-project.livekit.cloud).
자체 호스팅 LiveKit 설치의 경우, 해당 문서를 참조하십시오.
3단계 — Discourse에서 LiveKit 연결 구성
관리자 → 플러그인 → Voice로 이동하여 설정을 열고 LiveKit 섹션을 입력하세요:
| 설정 | 입력 내용 |
|---|---|
voice_livekit_url |
WebSocket URL, 예: wss://livekit.example.com (일반 HTTP 랩의 경우 ws://). |
voice_livekit_api_key |
2단계에서 얻은 API 키. |
voice_livekit_api_secret |
2단계에서 얻은 API 시크릿. |
voice_livekit_room_policy |
LiveKit을 사용할 방 지정. |
voice_livekit_room_policy 설정은 방이 전송 방식을 선택하는 방법을 결정합니다:
| 정책 | 동작 |
|---|---|
disabled |
모든 통화가 피어투피어로 실행됩니다 (기본값). |
per_room |
방 생성자/관리자가 방 폼의 미디어 서버(SFU) 사용 체크박스를 통해 개별 방을 선택적으로 활성화합니다. |
all_rooms |
모든 방이 LiveKit을 통해 라우팅됩니다. |
5단계 — 선택적 추가 설정
이러한 설정은 통합을 세밀하게 조정합니다:
| 설정 | 목적 |
|---|---|
voice_livekit_room_prefix |
LiveKit의 방 이름 네임스페이스 접두사. 여러 사이트가 하나의 LiveKit 서버를 공유하는 경우, 사이트마다 고유한 접두사를 설정하세요. 비어 있으면 사이트의 데이터베이스 이름이 기본값으로 사용됩니다. |
voice_livekit_mesh_fallback |
LiveKit 토큰을 발급할 수 없고 방이 비어 있는 경우, 참가 실패 대신 피어투피어 메시에서 시작합니다. 기본적으로 꺼져 있습니다 — 조용한 성능 저하는 LiveKit 장애를 가릴 수 있기 때문입니다. |
voice_livekit_recording_enabled |
LiveKit에서 실행되는 통화의 녹음을 방 모더레이터가 허용하도록 설정합니다. 녹음은 LiveKit Egress에 의해 생성되며 LiveKit 배포 환경의 저장소(S3, GCS, 로컬 디스크)에 저장됩니다 — Discourse에 업로드되지 않습니다. |
voice_livekit_recording_filepath |
LiveKit Egress에 전달되는 파일 경로, 예: voice/{room_name}-{utc}. {room_name}, {room_id}, {time}, {utc}와 같은 플레이스홀더를 지원합니다. 파일 확장자는 자동으로 추가됩니다. |
6단계 — 선택: LiveKit 웹훅 활성화
웹훅은 조정 전용 백업 수단입니다. 참가자의 연결이 갑자기 끊기거나 방이 종료될 때, 웹훅을 사용하면 플러그인이 하트비트 TTL을 기다리지 않고 몇 초 내에 존재 상태와 방 상태를 정리할 수 있습니다. 이는 선택 사항입니다 — 전달되지 못하더라도 통화는 계속 작동하지만, 정리 과정이 약간 더 오래 걸릴 뿐입니다.
LiveKit 서버에서 웹훅 엔드포인트를 추가하세요 (플러그인은 첫 번째 웹훅이 도착할 때까지 관리자 대시보드에서 정확한 스니펫을 표시합니다):
# livekit.yaml
webhook:
api_key: <your-api-key>
urls:
- https://forum.example.com/voice/livekit/webhook
LiveKit을 재시작하세요. 전송은 API 시크릿으로 인증되므로 추가적인 공유 시크릿 구성이 필요하지 않습니다.
7단계 — 통합 검증
Discourse Voice 관리자 대시보드 확인
관리자 → 플러그인 → Voice → 대시보드로 이동하세요. LiveKit 설정이 하나 이상 존재하면, 대시보드에는 실시간 체크가 포함된 LiveKit 미디어 서버 상태 카드가 표시됩니다:
- 구성 상태 (존재하는 설정 및 활성 정책),
- 키 페어로 액세스 토큰을 서명할 수 있는지 여부,
- 서버에 접근할 수 있는지 여부 및 활성 방 수,
- 마지막 자동 연결성 검사,
- 웹훅 수신 여부.
새로고침을 사용하여 온디맨드 프로브를 실행하세요.
LiveKit이 활성화된 Voice 플러그인 대시보드 스크린샷은 다음과 같습니다:
LiveKit 대시보드 확인
LiveKit 대시보드에도 통화에 대한 세부 정보가 있습니다. 예시는 다음과 같습니다:
