Configuration via Plugins

Owncast предоставляет плагинам два способа, позволяющих администратору изменять настройки. Объявите блок config в манифесте, и Owncast отобразит типизированную форму для вас, без HTML для администратора и без кода для сохранения или загрузки. Или зарегистрируйте страницу admin и предоставьте свой собственный HTML.

Используйте блок манифеста config для простых, типизированных параметров: строки, числа и переключатели. Обратитесь к настраиваемой странице администратора только тогда, когда вам нужен интерфейс, который не может выразить автоформа, например, сгруппированная компоновка, живой предварительный просмотр или кнопка действия, вызывающая ваше собственное API. Оба могут сосуществовать. У плагина может быть как вкладка настроек автоформы, так и одна или несколько настраиваемых страниц администратора.

Объявите настройки в манифесте

Каждая запись в разделе config имеет type, default и description:

{
  "config": {
    "greeting": { "type": "string", "default": "welcome!", "description": "First-join message" },
    "cooldownMs": { "type": "number", "default": 2000, "description": "Per-user command cooldown" },
    "modOnly": { "type": "boolean", "default": false, "description": "Restrict to moderators" }
  }
}

Поле	Заметки
тип	Одно из string, number или boolean. Любое другое значение принимается, но получает обычный текстовый ввод и никакой проверки типа при сохранении.
по умолчанию	Значение, возвращаемое config.get, до того как администратор сохранит переопределение. Его тип JSON должен соответствовать type.
описание	Метка, отображаемая рядом с полем в форме администратора. Возвращает имя ключа, когда пусто.

Имена ключей не могут начинаться с __. Этот префикс зарезервирован для состояния на экземпляре, которое вводит хост, и плагин, который объявляет ключ как __internal, не загружается.

Что видит администратор

Плагин, который объявляет блок config, получает вкладку Настройки на своей странице подробностей в разделе Администратор → Плагины. Owncast создает форму из схемы:

• string отображает текстовый ввод, number - числовой ввод, а boolean - переключатель.
• description - это метка поля.
• default отображается до тех пор, пока администратор не сохранит переопределение.
• Ключ, название которого выглядит как учетные данные, отображает как маскированный ввод пароля. Сравнение нечувствительно к регистру и срабатывает, когда имя содержит secret, password, token, apikey или api_key, или является самостоятельным словом key. Таким образом, apiKey, clientSecret, accessToken и webhook_secret маскируются. Имена, такие как accessKey или keyValue, не маскируются, потому что key совпадает только полностью. Назовите секретное поле apiKey, api_key или все, что заканчивается на Secret или Token, если хотите, чтобы оно было замаскировано.

Плагин без блока config не отображает вкладку Настройки.

Чтение значений во время выполнения

owncast.config.get(key, fallback?) возвращает переопределение администратора, если оно установлено, иначе возвращает объявленный по умолчанию, уже разобранный в объявленный тип.

JavaScript

const cooldownMs = owncast.config.get('cooldownMs', 2000);
const modOnly = owncast.config.get('modOnly', false);

Python

cooldown_ms = owncast.config.get("cooldownMs", 2000)
mod_only = owncast.config.get("modOnly", False)

config.get является амбиентным, поэтому ему не нужны разрешения. Поле number возвращается как число, а boolean как логическое значение, так что вам не нужно разбивать строки самостоятельно. Для неизвестного ключа или объявленного ключа, который не имеет ни значения по умолчанию, ни сохраненного переопределения, возвращается fallback (undefined в JavaScript и None в Python, когда вы передаете none). Передайте запасной вариант, с которым вы можете работать.

Полная подпись находится в справочнике API.

Валидация и хранение

Когда администратор сохраняет форму, Owncast проверяет каждое значение на соответствие схеме перед сохранением:

• Ключ, не объявленный в манифесте, отклоняется с сообщением 400 unknown config key.
• Поле string должно получать строку, number - число, а boolean - логическое значение. Несоответствие типов отклоняется. Любой другой объявленный type сохраняется как есть.
• Размер тела запроса ограничен 1 МБ.

Переопределения сохраняются в собственном хранилище ключей/значений плагина под зарезервированным ключом owncast.config, с пространством имен по slug плагина. Другие плагины не могут их читать, и они сохраняются при перезапусках и переустановках. Изменение slug после выпуска начинает новое хранилище, поэтому сохраненные переопределения возвращаются к своим значениям по умолчанию, то же правило применяется к остальным вашим KV данным.