扫描管理
接口列表
| 方法 | 路径 | 说明 |
|---|---|---|
POST | /scan | 扫描并导入本地音乐 |
POST | /scan/cancel | 取消扫描 |
GET | /scan/dir-names | 获取所有目录名称 |
GET | /scan/directories | 获取子目录列表 |
POST | /scan/fingerprints | 触发批量指纹计算 |
GET | /scan/fingerprints/progress | 获取指纹计算进度 |
GET | /scan/fingerprints/status | 获取指纹计算状态 |
GET | /scan/progress | 获取扫描进度 |
PUT | /settings/auto-scan | 更新自动扫描配置 |
GET | /settings/auto-scan | 获取自动扫描配置 |
PUT | /settings/music-path | 更新音乐路径与扫描排除配置 |
GET | /settings/music-path | 获取音乐路径与扫描排除配置 |
PUT | /settings/scan-auto-create-playlists | 更新「扫描后自动创建歌单」开关 |
GET | /settings/scan-auto-create-playlists | 获取「扫描后自动创建歌单」开关 |
PUT | /settings/scan-playlist-mode | 更新歌单创建方式 |
GET | /settings/scan-playlist-mode | 获取歌单创建方式 |
PUT | /settings/scan-title-source | 更新扫描标题来源配置 |
GET | /settings/scan-title-source | 获取扫描标题来源配置 |
POST /scan
扫描并导入本地音乐
异步扫描音乐目录并导入新发现的音乐文件到数据库，立即返回，可通过进度接口查询状态。 reimport=true 时对已入库文件也重新提取元数据；默认 false 走增量（跳过已存在且时长有效的文件）。 paths 为目录级定向扫描（Issue #262）：省略/为空时扫描整个音乐根目录；非空时只扫描给定目录（含子目录）， 且过期记录清理仅收敛到这些目录之内（不影响其余曲库）。每个目录必须位于音乐根目录之下，否则返回 400。
需要认证
此接口需要 Bearer Token 认证
请求体
扫描请求参数
类型： ScanRequest
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
paths | string[] | 否 | Paths 为目录级定向扫描（Issue #262）：为空时扫描整个音乐根目录（默认行为）； |
| 非空时只扫描给定目录（含子目录），过期记录清理也仅收敛到这些目录之内。 | |||
| 每个目录必须位于音乐根目录之下，否则返回 400。 | |||
reimport | boolean | 否 |
响应
200 - 扫描任务已启动
类型： map[string]any
400 - 指定目录不在音乐目录下
类型： map[string]string
409 - 扫描正在进行中
类型： map[string]string
500 - 启动扫描失败
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
POST /scan/cancel
取消扫描
取消正在进行的扫描任务
需要认证
此接口需要 Bearer Token 认证
响应
200 - 取消成功
类型： map[string]any
400 - 没有正在进行的扫描任务
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
GET /scan/dir-names
获取所有目录名称
递归收集音乐目录下所有唯一的目录名称，按字母排序返回，用于排除目录名称的自动补全
需要认证
此接口需要 Bearer Token 认证
响应
200 - 目录名称列表
类型： map[string]any
500 - 收集目录名称失败
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
GET /scan/directories
获取子目录列表
返回指定路径下的一级子目录列表，用于目录树懒加载。path 为空时返回音乐根目录下的子目录
需要认证
此接口需要 Bearer Token 认证
查询参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
path | string | 否 | 目录路径（为空时使用音乐根目录） |
响应
200 - 子目录列表
类型： map[string]any
400 - 无效的路径
类型： map[string]string
500 - 读取目录失败
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
POST /scan/fingerprints
触发批量指纹计算
异步为本地歌曲计算音频指纹，需要 ffmpeg 支持 chromaprint。若已有任务在运行则打断重启。传入 recompute_all=true 时清空已有指纹后重新计算全部。
需要认证
此接口需要 Bearer Token 认证
请求体
计算选项
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
recompute_all | boolean | 否 |
响应
200 - 任务已启动
类型： map[string]any
400 - chromaprint 不可用
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
GET /scan/fingerprints/progress
获取指纹计算进度
查询当前指纹计算任务的进度
需要认证
此接口需要 Bearer Token 认证
响应
200 - 计算进度
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
computed | integer | 否 | |
failed | integer | 否 | |
status | string | 否 | idle, running, done |
total | integer | 否 |
内容类型
- 响应：
application/json
GET /scan/fingerprints/status
获取指纹计算状态
返回 ffmpeg chromaprint 可用性以及本地歌曲指纹计算统计
需要认证
此接口需要 Bearer Token 认证
响应
200 - 指纹状态
类型： map[string]any
内容类型
- 响应：
application/json
GET /scan/progress
获取扫描进度
获取当前扫描任务的进度信息
需要认证
此接口需要 Bearer Token 认证
响应
200 - 扫描进度信息
类型： ScanProgress
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
cleaned_files | integer | 否 | 清理的过期文件数 |
cue_split_sources | integer | 否 | splitting_cue 阶段已处理的 CUE 来源数 |
current_file | string | 否 | 当前处理的文件 |
discovered_files | integer | 否 | scanning 阶段已发现的音频文件数 |
end_time | string | 否 | 结束时间 |
error | string | 否 | 错误信息 |
failed_files | integer | 否 | 失败的文件数 |
imported_files | integer | 否 | 已导入文件数 |
local_song_count | integer | 否 | 扫描完成后数据库中本地歌曲总数 |
scanned_files | integer | 否 | 已扫描文件数 |
skipped_files | integer | 否 | 跳过的文件数（已存在） |
start_time | string | 否 | 开始时间 |
status | any | 否 | 当前状态 |
total_files | integer | 否 | 总文件数 |
内容类型
- 请求：
application/json - 响应：
application/json
PUT /settings/auto-scan
更新自动扫描配置
设置自动扫描的启用状态和扫描间隔。interval_seconds 有效范围 [60, 86400]。更新后立即生效（无需重启）。
需要认证
此接口需要 Bearer Token 认证
请求体
自动扫描配置
类型： AutoScanSetting
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
enabled | boolean | 否 | |
interval_seconds | integer | 否 |
响应
200 - OK
类型： AutoScanSetting
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
enabled | boolean | 否 | |
interval_seconds | integer | 否 |
400 - 请求格式错误或参数无效
类型： map[string]string
500 - 保存配置失败
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
GET /settings/auto-scan
获取自动扫描配置
返回自动扫描的启用状态和扫描间隔（秒）。默认关闭，间隔 3600 秒（1 小时）。
需要认证
此接口需要 Bearer Token 认证
响应
200 - OK
类型： AutoScanSetting
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
enabled | boolean | 否 | |
interval_seconds | integer | 否 |
内容类型
- 响应：
application/json
PUT /settings/music-path
更新音乐路径与扫描排除配置
写入 music_path 配置并触发 Scanner 重建 + 清理排除目录中的歌曲（与 admin /configs PUT 的副作用一致）。
需要认证
此接口需要 Bearer Token 认证
请求体
配置内容
类型： MusicPathSetting
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
auto_create_exclude_dirs | string[] | 否 | |
exclude_dirs | string[] | 否 | |
exclude_paths | string[] | 否 | |
path | string | 否 |
响应
200 - OK
类型： MusicPathSetting
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
auto_create_exclude_dirs | string[] | 否 | |
exclude_dirs | string[] | 否 | |
exclude_paths | string[] | 否 | |
path | string | 否 |
400 - 请求格式错误
类型： map[string]string
500 - 保存配置失败
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
GET /settings/music-path
获取音乐路径与扫描排除配置
需要认证
此接口需要 Bearer Token 认证
响应
200 - OK
类型： MusicPathSetting
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
auto_create_exclude_dirs | string[] | 否 | |
exclude_dirs | string[] | 否 | |
exclude_paths | string[] | 否 | |
path | string | 否 |
内容类型
- 响应：
application/json
PUT /settings/scan-auto-create-playlists
更新「扫描后自动创建歌单」开关
控制扫描完成后是否根据音乐目录结构自动创建歌单。
需要认证
此接口需要 Bearer Token 认证
请求体
开关请求
类型： scanAutoCreatePlaylistsRequest
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
enabled | boolean | 否 |
响应
200 - 返回 enabled 字段
类型： map[string]boolean
400 - 请求格式错误
类型： map[string]string
500 - 保存配置失败
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
GET /settings/scan-auto-create-playlists
获取「扫描后自动创建歌单」开关
控制扫描完成后是否根据音乐目录结构自动创建歌单。默认启用（true）。关闭后扫描仅入库歌曲，不再自动建歌单。
需要认证
此接口需要 Bearer Token 认证
响应
200 - 返回 enabled 字段
类型： map[string]boolean
内容类型
- 响应：
application/json
PUT /settings/scan-playlist-mode
更新歌单创建方式
设置扫描后自动创建歌单的目录归并模式。directory：每个文件夹生成独立歌单；top_level：按一级子目录合并歌单；bubble_up：歌曲同时出现在所有上级文件夹歌单。
需要认证
此接口需要 Bearer Token 认证
请求体
模式请求
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
mode | string | 否 | 可选值: directory, top_level, bubble_up 示例: "directory" |
响应
200 - 返回 mode 字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
mode | string | 否 | 示例: "directory" |
400 - 请求格式错误或 mode 值非法
类型： map[string]string
500 - 保存配置失败
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
GET /settings/scan-playlist-mode
获取歌单创建方式
返回扫描后自动创建歌单的目录归并模式。directory：每个文件夹生成独立歌单；top_level：按一级子目录合并歌单；bubble_up：歌曲同时出现在所有上级文件夹歌单。默认 directory。
需要认证
此接口需要 Bearer Token 认证
响应
200 - 返回 mode 字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
mode | string | 否 | 示例: "directory" |
内容类型
- 响应：
application/json
PUT /settings/scan-title-source
更新扫描标题来源配置
tag：优先使用音频标签中的标题；filename：始终使用文件名（不含扩展名）作为标题。切换后需以「重新导入」模式扫描才能生效。
需要认证
此接口需要 Bearer Token 认证
请求体
标题来源配置
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
title_source | string | 否 | 可选值: tag, filename 示例: "tag" |
响应
200 - 返回 title_source 字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
title_source | string | 否 | 可选值: tag, filename 示例: "tag" |
400 - 请求格式错误或参数无效
类型： map[string]string
500 - 保存配置失败
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
GET /settings/scan-title-source
获取扫描标题来源配置
tag：优先使用音频标签中的标题（默认）；filename：始终使用文件名（不含扩展名）作为标题。切换后需以「重新导入」模式扫描才能生效。
需要认证
此接口需要 Bearer Token 认证
响应
200 - 返回 title_source 字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
title_source | string | 否 | 可选值: tag, filename 示例: "tag" |
内容类型
- 响应：
application/json