Настройки VideoGrace Server

Настройки сервера делятся на две группы. Сетевые и инфраструктурные параметры задаются в vgserver.conf или переменных окружения сервиса. Данные организации, лицензия, пользователи, группы, конференции и права доступа управляются через панель администратора.

Где находятся настройки

На Linux основные файлы и данные сервера находятся в:

/opt/VideoGrace/Server/

Конфигурационный файл:

/opt/VideoGrace/Server/vgserver.conf

Базы данных:

/opt/VideoGrace/Server/db

Журналы:

/var/log/vgserver

Ключевые группы настроек

Раздел	Что настраивает
`Network`	адрес сервера, TCP-порт, IPv6
`Security`	путь к TLS-сертификату и приватному ключу
`Translator` / media core	UDP-порты RTP/RTCP трансляторов
`WebRTC`	включение WebRTC Gateway, внешний адрес ICE, UDP-диапазон WebRTC
`CAN`	сервисная шина управления recorder, tolmach, consolidator и внешними RTC nodes
`Auth`	JWT-secret, TTL access token, TTL refresh token, сервисная авторизация
`Integration`	опциональный партнерский API, signed join links и отдельная `integration.db`
`Push`	offline push-уведомления браузерных клиентов для звонков и сообщений
`Mail`	общий SMTP relay для приглашений и восстановления пароля
`Storage`	локальное object storage для вложений чатов, аватаров и будущих записей
`Fail2Ban`	включение и параметры защиты от частых неавторизованных подключений
Панель администратора	организация, лицензия, пользователи, группы, конференции, права доступа, мониторинг

Сетевые настройки

Для публичного сервера укажите домен в Network.Address:

[Network]
Address = vc.example.com
Port = 443

Этот адрес используется клиентами и должен совпадать с TLS-сертификатом. Подробнее см. сеть сервера.

TLS-сертификаты

В секции Security можно указать сертификат и приватный ключ:

[Security]
Cert = /etc/letsencrypt/live/vc.example.com/fullchain.pem
PrivKey = /etc/letsencrypt/live/vc.example.com/privkey.pem

Если сертификат не задан или не подходит к адресу сервера, браузеры не будут доверять подключению. Для публичных web-клиентов используйте доверенный сертификат Let's Encrypt или корпоративного CA.

Если подходящий сертификат не найден, сервер выпускает внутренний сертификат через локальный VideoGrace Root CA и продолжает запуск. В этом режиме на странице входа web-клиент показывает ссылку на PKI-инструкцию, а сервер отдает:

https://<адрес-сервера>/pki/
https://<адрес-сервера>/pki/rootCA.crt

На странице /pki/ указано, под каким доменом или IP нужно подключаться после установки сертификата. Установите rootCA.crt в доверенные корневые центры сертификации на клиентских устройствах. Для публичных инсталляций этот режим следует рассматривать как fallback; предпочтительно использовать Let's Encrypt или корпоративный CA.

WebRTC

Для браузерных клиентов WebRTC является основным media path. Настройте внешний адрес и UDP-диапазон:

[WebRTC]
Enabled = 1
BindAddress = 0.0.0.0
ExternalAddress = vc.example.com
PortRangeBegin = 43000
PortRangeEnd = 43999

Откройте этот диапазон на firewall и, если сервер за NAT, пробросьте его без подмены номеров портов.

Offline push-уведомления

Push используется для уведомлений о входящих звонках и новых сообщениях, когда браузерный клиент сейчас offline. Подписка создается в web-клиенте, а endpoint и ключи сохраняются сервером в БД. Приватный VAPID-ключ остается только на сервере; публичный ключ клиент получает из https://<сервер>/api/v1.0/server_info.

Эти параметры можно задать в панели администратора: Настройки сервера → Offline Push. При сохранении через админку Push sender перечитывает настройки сразу; перезапуск нужен только если параметры переопределены переменными окружения или меняется окружение сервиса.

Команда протокола push_subscription_update поддерживает два типа подписок:

Provider	Назначение
`webpush`	Браузерный Push API: `endpoint`, `p256dh`, `auth`, `expiration_time`, `subscription`.
`fcm`	Нативные Android/KMP клиенты: `token` содержит FCM registration token. Отправка через FCM HTTP v1 подключается отдельным sender'ом.

Минимальная конфигурация:

[Push]
Enabled = 1
TTL = 3600
MaxQueueSize = 4096
Subject = mailto:admin@example.com
VapidPublicKey = <base64url_public_key>
VapidPrivateKey = <base64url_private_key>

Переменные окружения имеют приоритет над vgserver.conf:

`vgserver.conf`	Переменная окружения	Назначение
`Push.Enabled`	`VG_PUSH_ENABLED`	Включает отправку offline push.
`Push.TTL`	`VG_PUSH_TTL`	Время жизни push-сообщения в секундах.
`Push.MaxQueueSize`	`VG_PUSH_MAX_QUEUE_SIZE`	Максимальное число ожидающих push-заданий в памяти. При переполнении удаляются самые старые задания.
`Push.Subject`	`VG_PUSH_SUBJECT`	Контакт отправителя VAPID, обычно `mailto:` или HTTPS URL.
`Push.VapidPublicKey`	`VG_PUSH_VAPID_PUBLIC_KEY`	Публичный P-256 VAPID-ключ в base64url. Отдается клиенту через `server_info`.
`Push.VapidPrivateKey`	`VG_PUSH_VAPID_PRIVATE_KEY`	Приватный P-256 VAPID-ключ в base64url. Храните как секрет сервера.

Сгенерировать пару ключей можно локально:

node -e "const crypto=require('crypto');const ecdh=crypto.createECDH('prime256v1');ecdh.generateKeys();const b64u=b=>b.toString('base64').replace(/\+/g,'-').replace(/\//g,'_').replace(/=+$/,'');console.log('VapidPublicKey='+b64u(ecdh.getPublicKey()));console.log('VapidPrivateKey='+b64u(ecdh.getPrivateKey()));"

После изменения VAPID-ключей перезапустите сервер. Браузеры с уже созданной подпиской пересоздадут ее при следующей синхронизации, потому что клиент сравнивает ключ подписки с ключом, полученным от сервера.

Проверка настройки:

Откройте https://<сервер>/api/v1.0/server_info и убедитесь, что push_enabled=true, а push_vapid_public_key заполнен.
В web-клиенте разрешите уведомления в настройках пользователя.
Проверьте, что в БД появились записи в таблице push_subscriptions.
В журнале сервера должна быть строка PushNotificationSender configured.
Выйдите вторым клиентом offline и отправьте ему звонок или личное сообщение.

Поддержка браузеров:

Платформа	Статус
Chrome / Chromium / Edge desktop и Android	Поддерживается через стандартный Web Push. Отдельные ключи Google/FCM в VideoGrace не задаются: браузер сам выдает endpoint, сервер подписывает отправку VAPID-ключом.
Firefox desktop и Android	Поддерживается через стандартный Web Push при включенных Service Worker и Notifications.
Safari macOS	Поддерживается только на HTTPS-сайте и зависит от версии Safari/macOS и системных разрешений уведомлений.
iOS / iPadOS Safari	Background push работает только для установленного web-приложения на экран «Домой» на поддерживаемых версиях iOS/iPadOS. Обычная вкладка Safari не является надежным offline-push клиентом.

Для всех браузеров обязательны HTTPS, доверенный TLS-сертификат, доступный service worker /sw.js и разрешение уведомлений от пользователя. Если сервер использует внутренний VideoGrace Root CA, этот CA должен быть установлен и доверен на устройстве до создания push-подписки.

Почта и SMTP relay

Один общий SMTP transport обслуживает письма VideoGrace: приглашения в конференции, приглашения на платформу и восстановление пароля. Настройки доступны в панели администратора: Настройки сервера → Почта / SMTP. После сохранения transport перечитывает конфигурацию без перезапуска сервера.

Минимальная конфигурация для relay с STARTTLS:

[Mail]
Enabled = 1
Host = smtp.example.com
Port = 587
Security = starttls
VerifyTls = 1
Username = no-reply@example.com
Password = <smtp-password>
FromAddress = no-reply@example.com
FromName = VideoGrace
TimeoutSec = 15
MaxQueueSize = 256
ResetTokenTtlSec = 1800

Параметр	Переменная окружения	Назначение
`Mail.Enabled`	`VG_MAIL_ENABLED`	Включает почтовые функции и признак `password_reset_enabled` в `server_info`.
`Mail.Host`	`VG_MAIL_HOST`	DNS-имя SMTP relay.
`Mail.Port`	`VG_MAIL_PORT`	Обычно `587` для STARTTLS или `465` для TLS.
`Mail.Security`	`VG_MAIL_SECURITY`	`starttls`, `tls` или `none`.
`Mail.VerifyTls`	`VG_MAIL_VERIFY_TLS`	Проверять цепочку и имя TLS-сертификата SMTP-сервера. В production оставляйте `1`.
`Mail.Username`	`VG_MAIL_USERNAME`	Логин SMTP AUTH LOGIN. Пустой логин отключает AUTH для доверенного relay.
`Mail.Password`	`VG_MAIL_PASSWORD`	Пароль SMTP. Храните как секрет сервиса.
`Mail.FromAddress`	`VG_MAIL_FROM_ADDRESS`	Адрес envelope/header From; многие relay требуют совпадения с разрешенным отправителем.
`Mail.FromName`	`VG_MAIL_FROM_NAME`	Отображаемое имя отправителя.
`Mail.TimeoutSec`	`VG_MAIL_TIMEOUT_SEC`	Таймаут сетевой операции SMTP.
`Mail.MaxQueueSize`	`VG_MAIL_MAX_QUEUE_SIZE`	Верхняя граница фоновой очереди писем в памяти.
`Mail.ResetTokenTtlSec`	`VG_MAIL_RESET_TOKEN_TTL_SEC`	Срок действия одноразовой ссылки восстановления, от 300 до 86400 секунд.

Пароль в административном API является write-only: браузер получает только mail_password_set=true. Пустое поле пароля при сохранении не удаляет существующий секрет. Переменные окружения systemd/Docker имеют приоритет при запуске; после сохранения через админку текущий процесс использует записанную конфигурацию, но при следующем рестарте переменные окружения снова будут применены.

Режим без шифрования

Security=none допустим только для доверенного локального relay в закрытой сети. Для внешнего SMTP используйте starttls или tls с VerifyTls=1.

Проверка настройки:

Разрешите серверу исходящее TCP-соединение к SMTP host и порту.
Сохраните настройки в админке.
Введите адрес администратора в блоке проверки и нажмите Отправить тест.
При ошибке проверьте журнал сервера: тест возвращает фактическую ошибку DNS, TLS, AUTH или SMTP-код.
Проверьте приглашение из окна конференции и ссылку Забыли пароль? на странице входа.

Ссылки восстановления одноразовые. В БД хранится только SHA-256 токена; после успешной смены пароля все refresh token и активные сессии пользователя отзываются. Ответ на запрос восстановления одинаков для существующего и неизвестного email, чтобы API не раскрывал список учетных записей.

Хранилище и вложения

Вложения чатов, изображения, аватары и будущие записи проходят через серверное object storage. В 3.0 основной backend - локальная файловая система; S3 должен подключаться за тем же интерфейсом позже.

База метаданных задается в секции Db:

[Db]
StorageDb = /opt/VideoGrace/Server/db/storage.db

Если StorageDb указан относительным путем, сервер размещает его рядом с MainDb.

Файловый backend задается в секции Storage:

[Storage]
Type = fs
Root = /opt/VideoGrace/Server/storage
MaxObjectSize = 1073741824
MaxChunkSize = 4194304
PendingUploadTtlSec = 86400
OrphanUploadTtlSec = 86400

Параметр	Назначение
`Type`	Тип backend. Сейчас production-путь - `fs`.
`Root`	Каталог объектов. Сервер создает его при старте.
`MaxObjectSize`	Максимальный размер одного файла.
`MaxChunkSize`	Максимальный размер одного HTTP chunk upload запроса.
`PendingUploadTtlSec`	Сколько хранить незавершенные загрузки до очистки.
`OrphanUploadTtlSec`	Сколько хранить загруженные, но не привязанные к сообщению объекты.

HTTP API загрузки пишет файл чанками, поэтому большие вложения не проходят через CommandLoop и не блокируют media hot path. После отправки сообщения сервер привязывает blob к конкретному диалогу или конференции. По умолчанию вложение приватное; публичные объекты используются только там, где сервер явно выставляет публичную видимость.

Garbage collector storage запускается при старте сервера и удаляет незавершенные или не привязанные к сообщению загрузки старше заданных TTL.

В web-клиенте вложения отображаются в чате: изображения открываются в полноэкранном просмотре, видео и аудио воспроизводятся встроенными плеерами, остальные файлы скачиваются с сохранением исходного имени. Приватные вложения не получают открытый token в URL; клиент читает их авторизованным HTTPS-запросом.

В панели администратора доступны настройки storage и показатели dashboard: число объектов, ожидающие загрузки, объем blob-данных, свободное место файловой системы и ошибки доступа к БД или каталогу.

CAN service bus

CAN нужен для внешних сервисных worker'ов: recorder, tolmach, consolidator, RTC node. Сервисы сами открывают исходящее WSS-подключение к серверу:

wss://<адрес-сервера>/can

Минимальная конфигурация:

[CAN]
Enabled = 1
ServiceToken = <длинный_случайный_секрет>

ServiceToken не является пользовательским токеном. Его нужно хранить как секрет сервиса и не использовать в браузерном клиенте. CAN передает только команды и статусы; media идет по RTP/WSM/WebRTC, а записи и файлы загружаются через HTTPS storage API.

Если CAN-worker должен входить в конференцию как сервисный пользователь, используйте service_accounts и JWT-flow. Это описано отдельно: JWT и сервисные учетные записи.

Внешняя RTC-нода

RTC-нода (RtcTranslator) сама подключается к серверу по /can, поэтому в конфиге головного сервера не нужно перечислять адреса RTC-нод. Сервер видит live-ноды по node_id, а клиенты получают список доступных RTC routes автоматически.

На самой RTC-ноде нужно настроить ICE-адрес, который будет виден браузерам:

VG_CAN_URL=wss://core.example.com/can
VG_CAN_SERVICE_TOKEN=<секрет_CAN>
VG_CAN_NODE_ID=rtc-eu-1
VG_WEBRTC_BIND_ADDRESS=0.0.0.0
VG_WEBRTC_ADVERTISE_ADDRESS=rtc-eu-1.example.com
VG_WEBRTC_PORT_RANGE_BEGIN=43000
VG_WEBRTC_PORT_RANGE_END=43999

VG_WEBRTC_ADVERTISE_ADDRESS должен быть публичным DNS/IP этой RTC-ноды. UDP-диапазон VG_WEBRTC_PORT_RANGE_BEGIN/END должен быть открыт на firewall/NAT. Если этот адрес не задан, worker может отдать браузеру приватный адрес интерфейса, и WebRTC с внешних сетей не подключится.

Порт RTP-транслятора не настраивается на RTC-нODE. Core передает translator_host и translator_port отдельно при старте каждого media endpoint. translator_host берется из Network.Address / VG_ADDR.

Для subscribe-направления RTC-нода отправляет adjust packet с правильным receiver_ssrc на core translator. Core translator запоминает source address этого packet'а и дальше отправляет media на этот адрес. Поэтому адрес RTC-ноды не нужно прописывать на core.

Если Network.Address не задан, core использует 127.0.0.1 как последний fallback. Это подходит только для локального/in-process режима, но не для удаленной RTC-ноды.

Партнерская интеграция

Backend-to-backend Integration API является опциональным и по умолчанию отключен:

[Db]
IntegrationDb = /opt/VideoGrace/Server/db/integration.db

[Integration]
Enabled = 1
PublicUrl = https://vc.example.com

При Enabled = 0 сервер не создает и не открывает integration.db, а запросы /api/v1/integration/* получают HTTP 404. После включения сервер создает чистую БД партнерских комнат и service account-ов; данные из старых таблиц main.db не импортируются. Для применения настройки перезапустите сервер.

Проверка отключенного режима:

python3 tests/integration/vg_integration_api_smoke.py \
  --base-url https://vc.example.com \
  --expect-disabled

Настройка service account и полный smoke-тест описаны в документе разработчика protocol/integration-api.md.

Изменение настроек

После изменения vgserver.conf перезапустите сервис:

sudo systemctl restart vgserver

Проверьте статус:

sudo systemctl status vgserver --no-pager

И журнал:

sudo journalctl -u vgserver -n 100 --no-pager