缓存管理
接口列表
| 方法 | 路径 | 说明 |
|---|---|---|
POST | /cache-manage/clean | 清理全部音乐缓存 |
PUT | /cache-manage/config | 更新缓存配置 |
GET | /cache-manage/config | 获取缓存配置 |
GET | /cache-manage/stats | 获取缓存统计信息 |
POST | /cache-manage/validate-dir | 验证缓存目录 |
POST /cache-manage/clean
清理全部音乐缓存
删除服务端所有已缓存的音乐文件,清理后需要重新下载
需要认证
此接口需要 Bearer Token 认证
响应
200 - 清理成功
类型： map[string]string
500 - 清理失败
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
PUT /cache-manage/config
更新缓存配置
更新服务端音乐缓存的配置,如最大缓存大小和缓存目录。cache_dir 为空字符串时恢复使用默认目录。transcode_format 非空（mp3/m4a/ogg/flac/wav）时,缓存网络歌曲落盘会统一转码为该格式(缺 ffmpeg 或转码失败时保留原格式),transcode_quality 为可选码率(128/192/320,空或非法为最高质量)。更新后会自动触发 LRU 淘汰检查。切换目录时不会自动迁移旧缓存文件。
需要认证
此接口需要 Bearer Token 认证
请求体
缓存配置
类型： CacheConfig
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
cache_dir | string | 否 | 自定义缓存目录，空字符串表示使用默认目录 |
max_size | integer | 否 | 最大缓存大小（字节），0 表示无限制 |
transcode_format | string | 否 | TranscodeFormat 缓存网络歌曲落盘时统一转码的目标格式（mp3/m4a/ogg/flac/wav）。 |
| 空字符串表示不转码、按上游原格式落盘（默认）。缺 ffmpeg 或转码失败时优雅降级保留原格式。 | |||
transcode_quality | string | 否 | TranscodeQuality 转码目标码率（128/192/320），空或非法值表示最高质量。仅对有损格式生效。 |
响应
200 - 更新后的缓存配置
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
cache_dir | string | 否 | |
default_cache_dir | string | 否 | |
max_size | integer | 否 | |
transcode_format | string | 否 | |
transcode_quality | string | 否 |
400 - 请求参数无效
类型： map[string]string
500 - 更新失败
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
GET /cache-manage/config
获取缓存配置
获取服务端音乐缓存的配置信息,包括最大缓存大小限制、缓存目录路径、缓存转码格式(transcode_format)与码率(transcode_quality)。cache_dir 为空表示使用 default_cache_dir;transcode_format 为空表示缓存不转码、按原格式落盘。
需要认证
此接口需要 Bearer Token 认证
响应
200 - 缓存配置
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
cache_dir | string | 否 | |
default_cache_dir | string | 否 | |
max_size | integer | 否 | |
transcode_format | string | 否 | |
transcode_quality | string | 否 |
500 - 服务器错误
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
GET /cache-manage/stats
获取缓存统计信息
获取服务端音乐缓存的统计信息,包括总大小、文件数量和最大缓存限制
需要认证
此接口需要 Bearer Token 认证
响应
200 - 缓存统计信息
类型： CacheStats
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
file_count | integer | 否 | 文件数量 |
max_size | integer | 否 | 最大缓存大小（字节），0 表示无限制 |
total_size | integer | 否 | 总大小（字节） |
500 - 服务器错误
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
POST /cache-manage/validate-dir
验证缓存目录
验证指定目录是否可用作缓存目录。目录不存在时自动创建,检查可写性并返回磁盘空间信息。
需要认证
此接口需要 Bearer Token 认证
请求体
目录路径
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
path | string | 否 |
响应
200 - 验证结果
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
created | boolean | 否 | |
error | string | 否 | |
free_size | integer | 否 | |
total_size | integer | 否 | |
valid | boolean | 否 |
400 - 请求参数无效
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json