JS插件管理

接口列表

方法	路径	说明
`GET`	`/jsplugins`	列出所有 JS 插件
`PUT`	`/jsplugins/{id}`	更新 JS 插件
`DELETE`	`/jsplugins/{id}`	删除 JS 插件
`GET`	`/jsplugins/{id}`	获取 JS 插件详情
`GET`	`/jsplugins/{id}/check-update`	检查 JS 插件更新
`POST`	`/jsplugins/{id}/disable`	禁用 JS 插件
`POST`	`/jsplugins/{id}/enable`	启用 JS 插件
`POST`	`/jsplugins/{id}/update`	下载并更新 JS 插件
`POST`	`/jsplugins/registry/install`	从注册表安装插件
`POST`	`/jsplugins/registry/refresh`	刷新插件注册表
`POST`	`/jsplugins/storage/cleanup`	清理孤儿持久化存储
`POST`	`/jsplugins/update-all`	批量更新所有 JS 插件
`POST`	`/jsplugins/upload`	上传安装 JS 插件
`GET`	`/plugins/health`	音源健康度
`PUT`	`/settings/plugin-registries`	保存插件订阅源列表
`GET`	`/settings/plugin-registries`	获取插件订阅源列表

GET /jsplugins

列出所有 JS 插件

获取 JS 插件列表

需要认证

此接口需要 Bearer Token 认证

响应

200 - JS插件列表

类型： map[string]any

401 - 未授权

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

500 - 服务器错误

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

内容类型

请求： application/json
响应： application/json

PUT /jsplugins/{id}

更新 JS 插件

上传新的 JS 插件文件以更新现有插件

需要认证

此接口需要 Bearer Token 认证

路径参数

参数	类型	必填	说明
`id`	integer	是	插件ID

表单参数

参数	类型	必填	说明
`file`	file	是	JS插件文件 (.jsplugin.zip)

响应

200 - 更新成功

类型： map[string]any

400 - 请求数据错误

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

401 - 未授权

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

404 - 插件不存在

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

500 - 服务器错误

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

内容类型

请求： multipart/form-data
响应： application/json

DELETE /jsplugins/{id}

删除 JS 插件

根据插件ID删除 JS 插件。可通过 keep_data 参数保留插件数据目录（文件系统存储），持久化存储（数据库）始终保留。

需要认证

此接口需要 Bearer Token 认证

路径参数

参数	类型	必填	说明
`id`	integer	是	插件ID

查询参数

参数	类型	必填	说明
`keep_data`	string	否	是否保留插件数据目录（true/false，默认 false）

响应

200 - 删除成功

类型： map[string]any

401 - 未授权

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

404 - 插件不存在

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

500 - 服务器错误

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

内容类型

请求： application/json
响应： application/json

GET /jsplugins/{id}

获取 JS 插件详情

根据插件ID获取 JS 插件的详细信息

需要认证

此接口需要 Bearer Token 认证

路径参数

参数	类型	必填	说明
`id`	integer	是	插件ID

响应

200 - JS插件信息

类型： map[string]any

401 - 未授权

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

404 - 插件不存在

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

内容类型

请求： application/json
响应： application/json

GET /jsplugins/{id}/check-update

检查 JS 插件更新

检查指定 JS 插件的远程更新

需要认证

此接口需要 Bearer Token 认证

路径参数

参数	类型	必填	说明
`id`	integer	是	插件ID

响应

200 - 更新信息

类型： map[string]any

401 - 未授权

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

404 - 插件不存在

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

500 - 服务器错误

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

内容类型

请求： application/json
响应： application/json

POST /jsplugins/{id}/disable

禁用 JS 插件

禁用指定的 JS 插件

需要认证

此接口需要 Bearer Token 认证

路径参数

参数	类型	必填	说明
`id`	integer	是	插件ID

响应

200 - 禁用成功

类型： map[string]any

401 - 未授权

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

404 - 插件不存在

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

500 - 服务器错误

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

内容类型

请求： application/json
响应： application/json

POST /jsplugins/{id}/enable

启用 JS 插件

启用指定的 JS 插件

需要认证

此接口需要 Bearer Token 认证

路径参数

参数	类型	必填	说明
`id`	integer	是	插件ID

响应

200 - 启用成功

类型： map[string]any

401 - 未授权

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

404 - 插件不存在

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

500 - 服务器错误

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

内容类型

请求： application/json
响应： application/json

POST /jsplugins/{id}/update

下载并更新 JS 插件

从远程下载并更新指定的 JS 插件。设置 force=true 可跳过版本检查强制重新下载安装。

需要认证

此接口需要 Bearer Token 认证

路径参数

参数	类型	必填	说明
`id`	integer	是	插件ID

响应

200 - 更新成功

类型： map[string]any

401 - 未授权

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

404 - 插件不存在

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

500 - 服务器错误

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

内容类型

请求： application/json
响应： application/json

POST /jsplugins/registry/install

从注册表安装插件

从注册表中的 download_url 下载 ZIP 并安装插件。如果 entry_path 已存在则自动走更新路径。支持 GitHub 代理。可选传入 token 字段用于从需要认证的私有源下载；若未提供 token 但提供了 source_url（「全部」聚合模式），后端会自动从 plugin_registries 配置解析该源存储的 token。

需要认证

此接口需要 Bearer Token 认证

请求体

安装请求

类型： registryInstallRequest

字段	类型	必填	说明
`download_url`	string	否
`github_proxy`	string	否
`source_url`	string	否	SourceURL 插件所属订阅源 URL。「全部」聚合模式安装时回传：
当未显式提供 token 时，后端据此从 plugin_registries 配置解析该源的 token。
`token`	string	否

响应

200 - 安装结果（更新已有插件）

类型： jsPluginUploadResponse

字段	类型	必填
`failed`	integer	否
`message`	string	否
`results`	jsPluginUploadResult[]	否
`success`	integer	否
`total`	integer	否

201 - 安装结果（新插件）

类型： jsPluginUploadResponse

字段	类型	必填
`failed`	integer	否
`message`	string	否
`results`	jsPluginUploadResult[]	否
`success`	integer	否
`total`	integer	否

400 - 请求格式错误

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

500 - 下载或安装失败

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

内容类型

请求： application/json
响应： application/json

POST /jsplugins/registry/refresh

刷新插件注册表

拉取订阅源（含递归 includes），去重合并后返回分页的可用插件列表。每个插件标注是否已安装及是否有更新。默认拉取单个 registry_url，可选传入 token 字段访问需要认证的私有源（如 GitHub 私有仓库 PAT）。当 all_sources=true 时忽略 registry_url/token，改为聚合已保存的所有启用订阅源（各源用自身存储的 token），跨源按 entry_path 去重、高版本优先。

需要认证

此接口需要 Bearer Token 认证

请求体

刷新请求

类型： registryRefreshRequest

字段	类型	必填
`all_sources`	boolean	否
`github_proxy`	string	否
`page`	integer	否
`page_size`	integer	否
`registry_url`	string	否
`search`	string	否
`token`	string	否

响应

200 - 插件列表

类型： registryRefreshResponse

字段	类型	必填
`page`	integer	否
`page_size`	integer	否
`plugins`	registryPluginEntry[]	否
`total`	integer	否
`warnings`	string[]	否

400 - 请求格式错误

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

500 - 拉取注册表失败

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

内容类型

请求： application/json
响应： application/json

POST /jsplugins/storage/cleanup

清理孤儿持久化存储

删除 plugin_storage 表中不属于任何已安装插件的数据。当插件被卸载后，其持久化存储数据会保留在数据库中；此端点用于清理这些无主数据。

需要认证

此接口需要 Bearer Token 认证

响应

200 - 清理完成

类型： map[string]string

500 - 服务器错误

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

内容类型

响应： application/json

POST /jsplugins/update-all

批量更新所有 JS 插件

检查并更新所有具有远程更新源的 JS 插件。跳过无 update_url 的插件和已是最新版的插件，逐个下载并安装更新，失败不中断其他插件的更新流程。设置 force=true 可跳过版本检查强制重新下载安装所有插件。

需要认证

此接口需要 Bearer Token 认证

请求体

请求参数

类型： object

响应

200 - 批量更新结果

类型： jsPluginBatchUpdateResponse

字段	类型	必填
`failed`	integer	否
`message`	string	否
`results`	jsPluginBatchUpdateResult[]	否
`skipped`	integer	否
`total`	integer	否
`updated`	integer	否

500 - 服务器错误

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

内容类型

请求： application/json
响应： application/json

POST /jsplugins/upload

上传安装 JS 插件

上传新的 JS 插件文件（.jsplugin.zip 压缩包）

需要认证

此接口需要 Bearer Token 认证

表单参数

参数	类型	必填	说明
`file`	file	是	JS插件文件 (.jsplugin.zip)

响应

201 - 上传成功

类型： map[string]any

400 - 请求数据错误

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

401 - 未授权

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

500 - 服务器错误

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

内容类型

请求： multipart/form-data
响应： application/json

GET /plugins/health

音源健康度

返回各音乐源插件的下载成功率、健康度分类(green/yellow/red)与最近 5 条失败原因。

需要认证

此接口需要 Bearer Token 认证

响应

200 - OK

类型： pluginHealthResponse

字段	类型	必填	说明
`plugins`	PluginHealthSnapshot[]	否

内容类型

响应： application/json

PUT /settings/plugin-registries

保存插件订阅源列表

保存用户配置的插件注册表订阅源 URL 列表。每个源包含 URL、名称和是否启用。

需要认证

此接口需要 Bearer Token 认证

请求体

订阅源列表

类型： pluginRegistriesSetting

字段	类型	必填	说明
`registries`	RegistryConfig[]	否

响应

200 - 保存后的订阅源列表

类型： pluginRegistriesSetting

字段	类型	必填	说明
`registries`	RegistryConfig[]	否

400 - 请求格式错误

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

500 - 保存配置失败

类型： ErrorResponse

字段	类型	必填	说明
`detail`	string	否	详细错误信息（可选）示例: `"详细错误信息"`
`error`	string	否	错误信息示例: `"操作失败"`

内容类型

请求： application/json
响应： application/json

GET /settings/plugin-registries

获取插件订阅源列表

获取用户保存的所有插件注册表订阅源 URL。未配置时返回空列表。

需要认证

此接口需要 Bearer Token 认证

响应

200 - 订阅源列表

类型： pluginRegistriesSetting

字段	类型	必填	说明
`registries`	RegistryConfig[]	否

内容类型

响应： application/json

JS插件管理 ​

接口列表 ​

GET /jsplugins ​

响应 ​

200 - JS插件列表 ​

401 - 未授权 ​

500 - 服务器错误 ​

内容类型 ​

PUT /jsplugins/{id} ​

路径参数 ​

表单参数 ​

响应 ​

200 - 更新成功 ​

400 - 请求数据错误 ​

401 - 未授权 ​

404 - 插件不存在 ​

500 - 服务器错误 ​

内容类型 ​

DELETE /jsplugins/{id} ​

路径参数 ​

查询参数 ​

响应 ​

200 - 删除成功 ​

401 - 未授权 ​

404 - 插件不存在 ​

500 - 服务器错误 ​

内容类型 ​

GET /jsplugins/{id} ​

路径参数 ​

响应 ​

200 - JS插件信息 ​

401 - 未授权 ​

404 - 插件不存在 ​

内容类型 ​

GET /jsplugins/{id}/check-update ​

路径参数 ​

响应 ​

200 - 更新信息 ​

401 - 未授权 ​

404 - 插件不存在 ​

500 - 服务器错误 ​

内容类型 ​

POST /jsplugins/{id}/disable ​

路径参数 ​

响应 ​

200 - 禁用成功 ​

401 - 未授权 ​

404 - 插件不存在 ​

500 - 服务器错误 ​

内容类型 ​

POST /jsplugins/{id}/enable ​

路径参数 ​

响应 ​

200 - 启用成功 ​

401 - 未授权 ​

404 - 插件不存在 ​

500 - 服务器错误 ​

内容类型 ​

POST /jsplugins/{id}/update ​

路径参数 ​

响应 ​

200 - 更新成功 ​

401 - 未授权 ​

404 - 插件不存在 ​

500 - 服务器错误 ​

内容类型 ​

POST /jsplugins/registry/install ​

请求体 ​

响应 ​

200 - 安装结果（更新已有插件） ​

201 - 安装结果（新插件） ​

400 - 请求格式错误 ​

500 - 下载或安装失败 ​

内容类型 ​

POST /jsplugins/registry/refresh ​

请求体 ​

响应 ​

200 - 插件列表 ​

400 - 请求格式错误 ​

500 - 拉取注册表失败 ​

JS插件管理

接口列表

GET /jsplugins

响应

200 - JS插件列表

401 - 未授权

500 - 服务器错误

内容类型

PUT /jsplugins/{id}

路径参数

表单参数

响应

200 - 更新成功

400 - 请求数据错误

401 - 未授权

404 - 插件不存在

500 - 服务器错误

内容类型

DELETE /jsplugins/{id}

路径参数

查询参数

响应

200 - 删除成功

401 - 未授权

404 - 插件不存在

500 - 服务器错误

内容类型

GET /jsplugins/{id}

路径参数

响应

200 - JS插件信息

401 - 未授权

404 - 插件不存在

内容类型

GET /jsplugins/{id}/check-update

路径参数

响应

200 - 更新信息

401 - 未授权

404 - 插件不存在

500 - 服务器错误

内容类型

POST /jsplugins/{id}/disable

路径参数

响应

200 - 禁用成功

401 - 未授权

404 - 插件不存在

500 - 服务器错误

内容类型

POST /jsplugins/{id}/enable

路径参数

响应

200 - 启用成功

401 - 未授权

404 - 插件不存在

500 - 服务器错误

内容类型

POST /jsplugins/{id}/update

路径参数

响应

200 - 更新成功

401 - 未授权

404 - 插件不存在

500 - 服务器错误

内容类型

POST /jsplugins/registry/install

请求体

响应

200 - 安装结果（更新已有插件）

201 - 安装结果（新插件）

400 - 请求格式错误

500 - 下载或安装失败

内容类型

POST /jsplugins/registry/refresh

请求体

响应

200 - 插件列表

400 - 请求格式错误

500 - 拉取注册表失败