В этом руководстве описывается процесс подключения плагина Voice в Discourse к медиа-серверу LiveKit. По умолчанию голосовые звонки работают по схеме «точка-точка» (P2P): каждый участник отправляет свой аудиопоток напрямую каждому другому участнику. Это отлично работает для небольших комнат, но потребление полосы пропускания растет вместе с размером комнаты. Маршрутизация звонков через LiveKit позволяет сохранить постоянное значение исходящего трафика для каждого участника, независимо от того, сколько людей присоединяется к комнате.
Требования
Перед началом работы убедитесь, что у вас есть:
- Сайт Discourse с включенным плагином Voice.
- Доступный сервер 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 — Настройка подключения к LiveKit в Discourse
Перейдите в Администрирование → Плагины → Voice, откройте настройки и заполните раздел LiveKit:
| Настройка | Что ввести |
|---|---|
voice_livekit_url |
WebSocket URL, например, wss://livekit.example.com (или ws:// для лабораторных сред с обычным HTTP). |
voice_livekit_api_key |
API-ключ из Шага 2. |
voice_livekit_api_secret |
API-секрет из Шага 2. |
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 не может быть выпущен, а комната пуста, начать работу в режиме «точка-точка» (mesh) вместо блокировки присоединения. По умолчанию отключено — тихое снижение функциональности может скрыть сбой 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 heartbeat. Они необязательны — если их доставка невозможна, звонки будут работать, но очистка займет немного больше времени.
На сервере LiveKit добавьте конечную точку вебхука (плагин отображает точный фрагмент кода на своей панели администратора до поступления первого вебхука):
# livekit.yaml
webhook:
api_key: <ваш-api-ключ>
urls:
- https://forum.example.com/voice/livekit/webhook
Перезапустите LiveKit. Доставки аутентифицируются с помощью API-секрета — не требуется настраивать дополнительный общий секрет.
Шаг 7 — Проверка интеграции
Проверьте панель администратора Voice в Discourse
Перейдите в Администрирование → Плагины → Voice → Панель управления. Как только будет присутствовать любая настройка LiveKit, на панели появится карточка статуса Медиа-сервер LiveKit с активными проверками:
- статус конфигурации (какие настройки присутствуют и какая политика активна),
- можно ли подписывать токены доступа с помощью пары ключей,
- доступен ли сервер и сколько комнат активно,
- последняя автоматическая проверка соединения,
- поступают ли вебхуки.
Используйте кнопку Обновить, чтобы выполнить проверку по запросу.
Вот скриншот панели управления плагином Voice с включенным LiveKit:
Проверьте панель LiveKit
На панели LiveKit также есть детали о звонках. Вот пример:
