Skip to content

profiles.md

Latest commit

 

History

History
218 lines (151 loc) · 15.9 KB

profiles.md

File metadata and controls

218 lines (151 loc) · 15.9 KB
Raw

Профили

Профиль - это переиспользуемый шаблон конфигурации OLCRTC в формате YAML. Это основная концепция панели: вы создаёте профиль один раз, и для каждого подписчика автоматически генерируется собственный контейнер на его основе.

Примеры профилей

Что такое профиль

Хранятся в таблице profiles в PostgreSQL с тремя полями:

Поле Значение
name Человекочитаемое отображаемое имя (например, "Germany - VP8")
tag Короткий уникальный идентификатор, используемый в именах контейнеров и URL (например, de_vp8). Только латиница, цифры и _, не может быть пустым. Кнопка создания недоступна, пока тег не пройдёт валидацию.
profile Сам YAML-шаблон OLCRTC

Управление профилями происходит на странице панели Profiles: создание, редактирование, удаление, поиск. При создании/редактировании панель проверяет YAML-конфигурацию по множеству правил (валидный YAML, обязательные поля, форматы значений). Ошибки отображаются в реальном времени перед сохранением.

Где хранятся профили

В PostgreSQL. Конкретная конфигурация для каждого пользователя, которую реально запускает контейнер, создаётся динамически и записывается внутри контейнера в:

/tmp/olcwave/config.yaml

Как профиль превращается в работающую конфигурацию

Когда для пользователя запрашивается подписка, для каждого профиля, для которого у пользователя ещё нет контейнера, панель выполняет:

  1. Парсит YAML профиля.
  2. Генерирует crypto.key — перезаписывает его новым случайным 32-байтным hex-значением (64 hex-символа). Вы никогда не задаёте его вручную.
  3. Автоматически создаёт комнату для поддерживаемых провайдеров — если в профиле указан auth.token и поддерживаемый auth.provider, а room.id пуст, панель вызывает API провайдера для создания новой комнаты. Полученный ID комнаты подставляется в конфигурацию.
  4. Завершает room id если provider=jitsi — берёт room.id и разбивает его по /:
    • Если это просто базовый URL без пути, например https://jitsi.example.org (три части: https:, ``, jitsi.example.org), добавляется случайное имя комнаты длиной 16 байт в hex → `https://jitsi.example.org/`.
    • Если путь комнаты уже существует, но имя пустое, оно заполняется случайным значением.
    • Если имя комнаты уже указано, оно остаётся без изменений.
  5. Снова сохраняет результат в YAML.

Поля, добавляемые backend

При сохранении профиля backend автоматически добавляет/перезаписывает:

  • mode: srv — принудительно устанавливается.
  • data: data — принудительно устанавливается.
  • crypto.key: "" — устанавливается пустым. Реальный ключ генерируется при каждом запуске контейнера.

При редактировании профиля в UI эти поля скрыты — вы не редактируете их вручную.

Валидация room.id

Панель проверяет конфигурацию в реальном времени при создании/редактировании профиля:

  • Если auth.provider поддерживает автогенерацию и указан auth.token:
    • room.id становится опциональным. Если он указан, появится предупреждение, что ID будет сгенерирован автоматически.
    • Если auth.token не указан, room.id обязателен.
  • Если указаны и auth.token, и room.id, будет показано предупреждение: поле room.id будет проигнорировано, комната создастся автоматически.

После этого запускается контейнер с этой конфигурацией (см. ниже), а его расположение добавляется в пакет подписки, который возвращается клиенту.

Имена контейнеров

Каждый контейнер получает имя:

olcwave-<profile.tag>-<user.short_uuid>

например:

olcwave-de_vp8-rfWMs-graH-cPXRz

Не используйте - внутри tag, иначе определение владельца контейнера сломается. short_uuid может содержать дефисы - backend корректно парсит имя контейнера даже если UUID включает дефисы.

crypto.key - не указывается

В шаблоне профиля не пишите блок crypto. Backend автоматически устанавливает crypto.key: "" при сохранении, а реальный ключ генерируется для каждого пользователя при запуске контейнера.

Если вы укажете crypto.key в профиле, он будет перезаписан.

provider: jitsi и комната

Когда auth provider - Jitsi, room.id является базовым URL Jitsi. Нужно указывать только сервер:

auth:
  provider: jitsi
room:
  id: "https://jitsi.example.org"

Панель сама добавляет случайное имя комнаты для каждого пользователя, поэтому каждый пользователь получает изолированную комнату автоматически. Создавать комнаты вручную не нужно.

Автоматическая генерация комнат

Для некоторых провайдеров панель умеет автоматически создавать комнаты через их API. Вам больше не нужно вручную создавать комнату и копировать её ID.

Как это работает

  1. Вы указываете в профиле auth.provider и auth.token для провайдера, поддерживающего автогенерацию.
  2. Не указываете room.id (или удаляете его) — комната будет создана автоматически.
  3. При запросе подписки панель вызывает API провайдера, создаёт новую комнату и подставляет её ID каждому пользователю.

Как получить токен

Токен можно получить из cookie или local storage после входа в аккаунт провайдера:

  1. Откройте сайт провайдера и войдите в аккаунт.
  2. Откройте DevTools (F12).
  3. Перейдите на вкладку Storage (или Application).
  4. Найдите необходимые данные аутентификации (cookie или запись local storage).
  5. Скопируйте значение и вставьте в панель.

Панель принимает как простое строковое значение токена, так и JSON, из которого автоматически извлечёт accessToken.

Как включить в панели

При создании или редактировании профиля с подходящим провайдером:

  1. В модальном окне появится информационная подсказка: "Можно включить автогенерацию комнаты и не писать room.id вручную".
  2. В заголовке модального окна станет доступна кнопка "Enable Auto Rooms" (с иконкой искры).
  3. Нажмите на неё — откроется окно с инструкцией и полем для ввода токена.
  4. Введите токен и нажмите "Enable Auto Rooms".
  5. Панель автоматически:
    • Добавит auth.token в YAML профиля.
    • Удалит секцию room (комната будет создаваться автоматически).
  6. Если всё прошло успешно, вы увидите зелёное уведомление, и окно закроется через 1.5 секунды.

Пример конфигурации с автогенерацией

auth:
  provider: <provider_name>
  token: "<token>"
net:
  transport: vp8channel
  dns: "8.8.8.8:53"
vp8:
  fps: 30
  batch_size: 64

Обратите внимание: room.id отсутствует — он будет сгенерирован автоматически. В полях provider и token укажите свои значения.

Ограничения и ошибки

  • Автогенерация работает только для отдельных провайдеров.
  • Если токен невалидный или истёк, создание комнаты завершится ошибкой, и подписка не будет выдана.
  • При обновлении подписки панель проверяет, существует ли комната на стороне провайдера. Если комната была удалена или токен стал недействительным, соответствующий контейнер останавливается и удаляется. При следующем обновлении подписки будет создана новая комната.
  • Для остальных провайдеров (например, Jitsi) автогенерация не применяется — там используются другие схемы.

Пример профиля

Минимальный профиль OLCRTC (то, что вы пишете в UI):

auth:
  provider: jitsi
room:
  id: "https://jitsi.example.org"
net:
  transport: datachannel
  dns: "8.8.8.8:53"

Backend автоматически добавит mode: srv, data: data и crypto.key: "" при сохранении. При редактировании эти поля скрыты.

Transport

OLCRTC поддерживает транспорты помимо datachannel. Панель распознаёт:

  • vp8channel
  • seichannel
  • videochannel

и читает соответствующий раздел.

Пример с VP8:

auth:
  provider: jitsi
room:
  id: "https://jitsi.example.org"
net:
  transport: vp8channel
  dns: "8.8.8.8:53"
vp8:
  fps: 60
  batch: 64

Поля, которые реально читает панель

При генерации конфигураций и записей подписки backend использует следующие ключи. Всё остальное из YAML передаётся в OLCRTC без изменений.

Ключ Для чего используется
auth.provider Записывается в URI подписки и пакет OLCBox (auth_provider)
auth.token Токен аутентификации для автоматического создания комнат; опционально, для некоторых провайдеров удаляется из конфигурации контейнера
net.transport Выбирает транспорт; должен быть одним из: datachannel, vp8channel, seichannel, videochannel
room.id Адрес комнаты; автоматически дополняется для Jitsi; опционально при использовании auth.token с провайдерами, поддерживающими автогенерацию
crypto.key Перезаписывается новым случайным ключом для каждого пользователя
vp8.* Если transport равен vp8channel: fps (ограничение 1–120) и batch (ограничение 1–64) добавляются в пакет
sei.* Если transport равен seichannel: fps, batch_size, fragment_size, ack_timeout_ms используются при создании компактного URI
video.* Если transport равен videochannel: width, height, fps, bitrate, hw, codec, qr_size, qr_recovery, tile_module, tile_rs

Редактирование и удаление профилей

Оба действия специально имеют побочные эффекты для работающих контейнеров:

  • Редактирование профиля → все контейнеры, в имени которых содержится этот tag, останавливаются. Они будут пересозданы с новым шаблоном при следующем обновлении подписки пользователя.
  • Удаление профиля → соответствующие контейнеры останавливаются и удаляются.

Таким образом, редактирование профиля фактически означает: "переразвернуть этот профиль для всех пользователей при следующем обновлении их подписки".