设置

接口列表

方法	路径	说明
`GET`	`/logs/export`	导出后端日志
`PUT`	`/settings/equalizer`	保存均衡器配置
`GET`	`/settings/equalizer`	获取均衡器配置
`PUT`	`/settings/http-proxy`	保存 HTTP 代理配置
`GET`	`/settings/http-proxy`	获取 HTTP 代理配置
`PUT`	`/settings/library-browse`	保存曲库浏览视图配置
`GET`	`/settings/library-browse`	获取曲库浏览视图配置
`PUT`	`/settings/log-level`	更新日志等级
`GET`	`/settings/log-level`	获取日志等级
`PUT`	`/settings/plugin-auto-update`	保存插件自动更新开关
`GET`	`/settings/plugin-auto-update`	获取插件自动更新开关
`PUT`	`/settings/plugin-keep-alive`	保存插件常驻白名单
`GET`	`/settings/plugin-keep-alive`	获取插件常驻白名单
`PUT`	`/settings/tab-config`	保存底部导航栏 Tab 配置
`GET`	`/settings/tab-config`	获取底部导航栏 Tab 配置
`PUT`	`/settings/user-preferences`	保存用户偏好设置
`GET`	`/settings/user-preferences`	获取用户偏好设置

GET /logs/export

导出后端日志

将后端落盘的日志文件（<data_dir>/logs/ 下按天轮转的文件）按时间从旧到新拼接，逐行脱敏后作为纯文本附件返回，触发浏览器下载。脱敏会抹除密钥/token/密码、Authorization/Cookie 头、URL 内嵌凭证、客户端 IP 主机位、用户主目录名等敏感信息，便于用户安全地附到 issue。远程服务器、桌面 Bundle、移动 Bundle 三种模式下均可用（均由同一份后端提供该端点）。无日志文件时返回仅含提示行的文本。

需要认证

此接口需要 Bearer Token 认证

响应

200 - 脱敏后的后端日志（text/plain）

类型： file

500 - 读取日志目录失败

类型： map[string]string

内容类型

响应： text/plain

PUT /settings/equalizer

保存均衡器配置

保存全局均衡器（EQ）配置。bands 必须包含 10 个元素，每个值在 -12 ~ +12 范围内（单位 dB）。preset 为预设名称（flat/rock/pop/jazz/classical/bass_boost/treble_boost/vocal/custom）。

需要认证

此接口需要 Bearer Token 认证

请求体

均衡器配置

类型： equalizerSetting

字段	类型	必填
`bands`	number[]	否
`enabled`	boolean	否
`preset`	string	否

响应

200 - 保存后的均衡器配置

类型： equalizerSetting

字段	类型	必填
`bands`	number[]	否
`enabled`	boolean	否
`preset`	string	否

400 - 请求格式错误

类型： ErrorResponse

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

500 - 保存配置失败

类型： ErrorResponse

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

内容类型

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

GET /settings/equalizer

获取均衡器配置

获取全局均衡器（EQ）配置，包含启用状态、预设名称和 10 段频段增益（31Hz–16kHz，单位 dB，范围 -12 ~ +12）。未配置时返回默认值（关闭 + flat 预设 + 全 0）。

需要认证

此接口需要 Bearer Token 认证

响应

200 - 均衡器配置

类型： equalizerSetting

字段	类型	必填
`bands`	number[]	否
`enabled`	boolean	否
`preset`	string	否

内容类型

响应： application/json

PUT /settings/http-proxy

保存 HTTP 代理配置

设置全局 HTTP 代理地址（如 http://192.168.1.1:7890）。设为空字符串则关闭代理。保存后即时生效，无需重启。

需要认证

此接口需要 Bearer Token 认证

请求体

代理配置

类型： httpProxySetting

字段	类型	必填	说明
`proxy`	string	否

响应

200 - 保存后的代理配置

类型： httpProxySetting

字段	类型	必填	说明
`proxy`	string	否

400 - 请求格式错误或代理地址无效

类型： ErrorResponse

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

500 - 保存配置失败

类型： ErrorResponse

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

内容类型

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

GET /settings/http-proxy

获取 HTTP 代理配置

获取全局 HTTP 代理地址。所有后端外发请求（插件下载、注册表拉取、升级检查等）会通过此代理转发。未配置时返回空字符串（直连）。

需要认证

此接口需要 Bearer Token 认证

响应

200 - 代理配置

类型： httpProxySetting

字段	类型	必填	说明
`proxy`	string	否

内容类型

响应： application/json

PUT /settings/library-browse

保存曲库浏览视图配置

保存用户自定义的曲库浏览页视图显示与顺序。每个 view 的 key 必须属于合法的 14 个 key 且不能重复；未出现的 key 会按默认顺序补到末尾（visible=true），保证返回完整 14 项。

需要认证

此接口需要 Bearer Token 认证

请求体

曲库浏览视图配置

类型： libraryBrowseSetting

字段	类型	必填	说明
`views`	libraryBrowseView[]	否

响应

200 - 保存后的配置

类型： libraryBrowseSetting

字段	类型	必填	说明
`views`	libraryBrowseView[]	否

400 - 请求格式错误或校验失败

类型： ErrorResponse

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

500 - 保存配置失败

类型： ErrorResponse

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

内容类型

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

GET /settings/library-browse

获取曲库浏览视图配置

获取用户自定义的曲库统一浏览页视图显示与顺序。共 14 个视图，分三组：歌曲组 all(全部)/local(本地)/remote(网络)/radio(电台)；分类组 artist(歌手)/album(专辑)/genre(流派)/year(年份)/decade(年代)/language(语种)/style(风格)；歌单组 playlist(全部歌单)/playlist_normal(普通歌单)/playlist_radio(电台歌单)。未配置时返回默认（全部可见、默认顺序）。返回始终包含完整 14 项。

需要认证

此接口需要 Bearer Token 认证

响应

200 - 曲库浏览视图配置

类型： libraryBrowseSetting

字段	类型	必填	说明
`views`	libraryBrowseView[]	否

内容类型

响应： application/json

PUT /settings/log-level

更新日志等级

切换 slog 全局日志等级并持久化。新等级即时生效，重启后从 DB 恢复。

需要认证

此接口需要 Bearer Token 认证

请求体

等级请求（debug/info/warn/error）

类型： logLevelSettingRequest

字段	类型	必填	说明
`level`	string	否

响应

200 - 返回更新后的 level

类型： map[string]string

400 - 请求格式错误或等级非法

类型： map[string]string

500 - 保存配置失败

类型： map[string]string

内容类型

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

GET /settings/log-level

获取日志等级

返回当前 slog 全局日志等级

需要认证

此接口需要 Bearer Token 认证

响应

200 - 返回 level 字段：debug/info/warn/error

类型： map[string]string

内容类型

响应： application/json

PUT /settings/plugin-auto-update

保存插件自动更新开关

开启/关闭插件后台自动更新。开启后后台 ticker 会定时对有更新源的插件执行“检查更新 + 下载安装 + 热重载”。开关即时生效，无需重启。

需要认证

此接口需要 Bearer Token 认证

请求体

开关请求

类型： pluginAutoUpdateSetting

字段	类型	必填	说明
`enabled`	boolean	否

响应

200 - 返回 enabled 字段表示更新后的开关状态

类型： pluginAutoUpdateSetting

字段	类型	必填	说明
`enabled`	boolean	否

400 - 请求格式错误

类型： ErrorResponse

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

500 - 保存配置失败

类型： ErrorResponse

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

内容类型

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

GET /settings/plugin-auto-update

获取插件自动更新开关

获取“后台自动更新已安装插件”开关的当前状态。开启后，服务会在启动后延迟数分钟检查一次、之后每 6 小时定时检查所有具有远程更新源的插件并自动更新。默认关闭。

需要认证

此接口需要 Bearer Token 认证

响应

200 - 返回 enabled 字段表示开关状态

类型： pluginAutoUpdateSetting

字段	类型	必填	说明
`enabled`	boolean	否

内容类型

响应： application/json

PUT /settings/plugin-keep-alive

保存插件常驻白名单

设置不会被自动休眠的插件 entryPath 列表。保存后即时生效，白名单中的插件将跳过空闲检查，始终保持运行。

需要认证

此接口需要 Bearer Token 认证

请求体

常驻白名单

类型： pluginKeepAliveSetting

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

响应

200 - 保存后的白名单

类型： pluginKeepAliveSetting

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

400 - 请求格式错误

类型： ErrorResponse

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

500 - 保存配置失败

类型： ErrorResponse

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

内容类型

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

GET /settings/plugin-keep-alive

获取插件常驻白名单

获取不会被自动休眠的插件 entryPath 列表。白名单中的插件即使空闲超过 10 分钟也不会被卸载。未配置时返回空列表。

需要认证

此接口需要 Bearer Token 认证

响应

200 - 常驻白名单

类型： pluginKeepAliveSetting

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

内容类型

响应： application/json

PUT /settings/tab-config

保存底部导航栏 Tab 配置

保存用户自定义的底部导航栏 Tab 配置。首页和设置固定显示（不在配置中），可选项为歌曲库、歌单和插件 Tab，可选项总数不超过 10 个。每个插件 Tab 的 entry_path 和 name 不能为空，且不能重复。移动端超过 5 个时自动折叠到「更多」菜单。

需要认证

此接口需要 Bearer Token 认证

请求体

Tab 配置

类型： tabConfigSetting

字段	类型	必填
`plugin_tabs`	pluginTabEntry[]	否
`show_library`	boolean	否
`show_playlists`	boolean	否

响应

200 - 保存后的 Tab 配置

类型： tabConfigSetting

字段	类型	必填
`plugin_tabs`	pluginTabEntry[]	否
`show_library`	boolean	否
`show_playlists`	boolean	否

400 - 请求格式错误或校验失败

类型： ErrorResponse

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

500 - 保存配置失败

类型： ErrorResponse

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

内容类型

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

GET /settings/tab-config

获取底部导航栏 Tab 配置

获取用户自定义的底部导航栏 Tab 配置。首页和设置固定显示，歌曲库和歌单可关闭，可选项（歌曲库+歌单+插件 Tab）总数不超过 10 个。未配置时返回默认值（4 个 Tab：首页、歌曲库、歌单、设置）。移动端超过 5 个时自动折叠到「更多」菜单，桌面端侧边栏可全部展示。

需要认证

此接口需要 Bearer Token 认证

响应

200 - Tab 配置

类型： tabConfigSetting

字段	类型	必填
`plugin_tabs`	pluginTabEntry[]	否
`show_library`	boolean	否
`show_playlists`	boolean	否

内容类型

响应： application/json

PUT /settings/user-preferences

保存用户偏好设置

保存用户跨设备同步的偏好设置。客户端登录后拉取、修改偏好时推送，实现多设备间偏好同步。

需要认证

此接口需要 Bearer Token 认证

请求体

用户偏好设置

类型： userPreferencesSetting

字段	类型	必填
`audio_quality`	string	否
`local_cache_max_size`	integer	否
`play_mode`	string	否
`playlist_view_mode`	string	否
`theme_mode`	string	否
`volume`	number	否

响应

200 - 保存后的用户偏好设置

类型： userPreferencesSetting

字段	类型	必填
`audio_quality`	string	否
`local_cache_max_size`	integer	否
`play_mode`	string	否
`playlist_view_mode`	string	否
`theme_mode`	string	否
`volume`	number	否

400 - 请求格式错误

类型： ErrorResponse

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

500 - 保存配置失败

类型： ErrorResponse

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

内容类型

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

GET /settings/user-preferences

获取用户偏好设置

获取用户跨设备同步的偏好设置，包括主题、播放模式、视图模式、音质、缓存上限和音量。未配置时返回默认值。

需要认证

此接口需要 Bearer Token 认证

响应

200 - 用户偏好设置

类型： userPreferencesSetting

字段	类型	必填
`audio_quality`	string	否
`local_cache_max_size`	integer	否
`play_mode`	string	否
`playlist_view_mode`	string	否
`theme_mode`	string	否
`volume`	number	否

内容类型

响应： application/json

设置 ​

接口列表 ​

GET /logs/export ​

响应 ​

200 - 脱敏后的后端日志（text/plain） ​

500 - 读取日志目录失败 ​

内容类型 ​

PUT /settings/equalizer ​

请求体 ​

响应 ​

200 - 保存后的均衡器配置 ​

400 - 请求格式错误 ​

500 - 保存配置失败 ​

内容类型 ​

GET /settings/equalizer ​

响应 ​

200 - 均衡器配置 ​

内容类型 ​

PUT /settings/http-proxy ​

请求体 ​

响应 ​

200 - 保存后的代理配置 ​

400 - 请求格式错误或代理地址无效 ​

500 - 保存配置失败 ​

内容类型 ​

GET /settings/http-proxy ​

响应 ​

200 - 代理配置 ​

内容类型 ​

PUT /settings/library-browse ​

请求体 ​

响应 ​

200 - 保存后的配置 ​

400 - 请求格式错误或校验失败 ​

500 - 保存配置失败 ​

内容类型 ​

GET /settings/library-browse ​

响应 ​

200 - 曲库浏览视图配置 ​

内容类型 ​

PUT /settings/log-level ​

请求体 ​

响应 ​

200 - 返回更新后的 level ​

400 - 请求格式错误或等级非法 ​

500 - 保存配置失败 ​

内容类型 ​

GET /settings/log-level ​

响应 ​

200 - 返回 level 字段：debug/info/warn/error ​

内容类型 ​

PUT /settings/plugin-auto-update ​

请求体 ​

响应 ​

200 - 返回 enabled 字段表示更新后的开关状态 ​

400 - 请求格式错误 ​

500 - 保存配置失败 ​

内容类型 ​

GET /settings/plugin-auto-update ​

响应 ​

200 - 返回 enabled 字段表示开关状态 ​

内容类型 ​

PUT /settings/plugin-keep-alive ​

请求体 ​

响应 ​

200 - 保存后的白名单 ​

400 - 请求格式错误 ​

500 - 保存配置失败 ​

内容类型 ​

GET /settings/plugin-keep-alive ​

响应 ​

200 - 常驻白名单 ​

内容类型 ​

PUT /settings/tab-config ​

请求体 ​

响应 ​

200 - 保存后的 Tab 配置 ​

400 - 请求格式错误或校验失败 ​

500 - 保存配置失败 ​

内容类型 ​

设置

接口列表

GET /logs/export

响应

200 - 脱敏后的后端日志（text/plain）

500 - 读取日志目录失败

内容类型

PUT /settings/equalizer

请求体

响应

200 - 保存后的均衡器配置

400 - 请求格式错误

500 - 保存配置失败

内容类型

GET /settings/equalizer

响应

200 - 均衡器配置

内容类型

PUT /settings/http-proxy

请求体

响应

200 - 保存后的代理配置

400 - 请求格式错误或代理地址无效

500 - 保存配置失败

内容类型

GET /settings/http-proxy

响应

200 - 代理配置

内容类型

PUT /settings/library-browse

请求体

响应

200 - 保存后的配置

400 - 请求格式错误或校验失败

500 - 保存配置失败

内容类型

GET /settings/library-browse

响应

200 - 曲库浏览视图配置

内容类型

PUT /settings/log-level

请求体

响应

200 - 返回更新后的 level

400 - 请求格式错误或等级非法

500 - 保存配置失败

内容类型

GET /settings/log-level

响应

200 - 返回 level 字段：debug/info/warn/error

内容类型

PUT /settings/plugin-auto-update

请求体

响应

200 - 返回 enabled 字段表示更新后的开关状态

400 - 请求格式错误

500 - 保存配置失败

内容类型

GET /settings/plugin-auto-update

响应

200 - 返回 enabled 字段表示开关状态

内容类型

PUT /settings/plugin-keep-alive

请求体

响应

200 - 保存后的白名单

400 - 请求格式错误

500 - 保存配置失败

内容类型

GET /settings/plugin-keep-alive

响应

200 - 常驻白名单

内容类型

PUT /settings/tab-config

请求体

响应

200 - 保存后的 Tab 配置

400 - 请求格式错误或校验失败

500 - 保存配置失败

内容类型