配置管理 API

Monibuca V6 提供完整的配置管理 API，支持运行时读取和修改配置、查询配置 Schema、验证配置值，以及通过 WebSocket 接收配置变更的实时通知。

获取全局配置

GET /config/global

返回引擎的全局配置。

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "http": {
      "listen": ":8080",
      "cors": true
    },
    "log": {
      "level": "info",
      "file": "./logs/monibuca.log"
    },
    "publish": {
      "kick": false,
      "delay_close": 0
    },
    "subscribe": {
      "sub_audio": true,
      "sub_video": true,
      "idr_mode": 1
    }
  }
}

获取插件配置

GET /config/plugin/{plugin_name}

返回指定插件的当前配置。

请求示例：

curl http://localhost:8080/config/plugin/mp4

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "enable": true,
    "record_path": "./recordings",
    "fragment": false,
    "fragment_duration": 5,
    "max_file_size": 0,
    "max_duration": 0,
    "expire_days": 0,
    "auto_recovery": true,
    "filename_pattern": "{stream}_{date}_{time}.mp4"
  }
}

更新全局配置

PUT /config/global
Content-Type: application/json

{
  "log": {
    "level": "debug"
  }
}

部分更新全局配置，只需传入要修改的字段。更新后立即生效。

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "updated_fields": ["log.level"],
    "restart_required": false
  }
}

更新插件配置

PUT /config/plugin/{plugin_name}
Content-Type: application/json

{
  "record_path": "/data/recordings",
  "expire_days": 30
}

部分更新指定插件的配置。更新会触发插件的 on_config_update() 回调。

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "plugin": "mp4",
    "updated_fields": ["record_path", "expire_days"]
  }
}

Schema 查询

获取全部 Schema

GET /config/schema

返回所有配置的 JSON Schema 定义，包括全局配置和各插件配置。Schema 由 ConfigSchema derive 宏自动生成。

获取插件 Schema

GET /config/schema/{plugin_name}

返回指定插件的配置 Schema。

请求示例：

curl http://localhost:8080/config/schema/mp4

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "plugin": "mp4",
    "title": "MP4 Plugin",
    "description": "MP4 recording and playback plugin",
    "type": "object",
    "properties": {
      "enable": {
        "type": "boolean",
        "label": "Enable",
        "description": "Enable the plugin",
        "default": true
      },
      "record_path": {
        "type": "string",
        "label": "Record Path",
        "description": "Recording directory path",
        "default": "./recordings"
      },
      "fragment": {
        "type": "boolean",
        "label": "Fragment",
        "description": "Enable fragmented MP4 (fMP4)",
        "default": false
      },
      "filename_pattern": {
        "type": "string",
        "label": "Filename Pattern",
        "description": "File naming pattern. Supports: {stream}, {date}, {time}, {timestamp}",
        "pattern": "^[a-zA-Z0-9_{}\\-\\.]+$",
        "default": "{stream}_{date}_{time}.mp4"
      }
    },
    "override_groups": ["Publish", "Subscribe"]
  }
}

Schema 定义可直接用于前端表单的自动生成。

配置验证

POST /config/validate/{plugin_name}
Content-Type: application/json

{
  "record_path": "/data/recordings",
  "expire_days": -1
}

验证配置值是否合法，不实际写入。返回验证结果和错误详情。

验证失败响应：

{
  "code": 400,
  "message": "validation_failed",
  "data": {
    "errors": [
      {
        "field": "expire_days",
        "message": "Value must be non-negative"
      }
    ]
  }
}

重载配置

POST /config/reload

从配置文件重新加载全部配置。等效于重新读取 config.yaml 并应用到运行中的引擎。

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "reloaded_plugins": ["mp4", "snap", "transcode"],
    "errors": []
  }
}

注意

某些配置的变更需要重启对应的服务才能生效，如 HTTP 监听地址、RTMP 端口等。reload 响应中的 restart_required 字段会提示哪些配置需要重启。

WebSocket 实时通知

通过 WebSocket 连接可以接收配置变更的实时通知：

ws://host:port/config/ws

连接示例

const ws = new WebSocket('ws://localhost:8080/config/ws');

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log('Config changed:', msg);
};

通知消息格式

{
  "type": "config_updated",
  "scope": "plugin",
  "plugin": "mp4",
  "fields": ["record_path", "expire_days"],
  "timestamp": "2026-03-18T14:30:00Z",
  "operator": "admin"
}

字段	说明
type	事件类型：config_updated、config_reloaded
scope	变更范围：global 或 plugin
plugin	插件名称（scope 为 plugin 时）
fields	变更的字段列表
timestamp	变更时间
operator	操作者标识

敏感配置加密

Monibuca 使用 AES-256-GCM 加密存储敏感配置字段（如密钥、密码）。加密字段在 Schema 中标记为 sensitive: true，API 响应中以掩码显示：

{
  "auth": {
    "secret": "***"
  }
}

写入时传入明文值，引擎自动加密存储。