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" }
  }
}

字段	备注
type	string、number 或 boolean 其中之一。 任何其他值都会被接受，但会收到纯文本输入并且在保存时不进行类型检查。
default	值 config.get 返回，直到管理员保存覆盖。 其 JSON 类型应与 type 匹配。
description	在管理员表单中显示在字段旁边的标签。 当为空时，回退到键名。

键名不能以 __ 开头。 该前缀保留用于主机注入的每实例状态，声明如 __internal 的关键字无法加载。

管理员看到的内容

声明了 config 块的插件在其详细页面的 Admin → Plugins 下会有一个 设置 标签。 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（在 JavaScript 中为 undefined，在 Python 中为 None）。 传递一个您可以运行的后备值。

完整的签名位于 APIs 参考。

验证和存储

当管理员保存表单时，Owncast 会根据模式检查每个值，然后存储：

• 在清单中未声明的键以 400 unknown config key 被拒绝。
• string 字段必须接收字符串，number 字段接收数字，boolean 字段接收布尔值。 类型不匹配将被拒绝。 任何其他声明的 type 将按原样存储。
• 请求体的大小限制为 1 MB。

覆盖在插件自己的键/值存储中保持在保留的键 owncast.config 下，按插件的 slug 名称空间化。 其他插件无法读取它们，它们在重启和重装时仍然存在。 发布后更改 slug 会启动一个新存储，因此保存的覆盖返回其默认值，适用于您所有 KV 数据 的相同规则。