扫描管理
接口列表
| 方法 | 路径 | 说明 |
|---|---|---|
POST | /scan | 扫描并导入本地音乐 |
POST | /scan/cancel | 取消扫描 |
GET | /scan/dir-names | 获取所有目录名称 |
GET | /scan/directories | 获取子目录列表 |
POST | /scan/fingerprints | 触发批量指纹计算 |
POST | /scan/fingerprints/cancel | 中断指纹计算 |
GET | /scan/fingerprints/failed | 获取指纹计算失败的歌曲列表 |
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-auto-fingerprint | 更新「扫描后自动计算音频指纹」开关 |
GET | /settings/scan-auto-fingerprint | 获取「扫描后自动计算音频指纹」开关 |
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
获取所有目录名称
递归收集音乐目录下所有唯一的目录名称，按字母排序返回，用于排除目录名称的自动补全。 结果带 60 秒进程内缓存；万首级曲库首次遍历可能较慢，客户端超时后重试会直接命中缓存。
需要认证
此接口需要 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 时清空已有指纹后重新计算全部；传入 retry_failed=true 时仅重置失败项的「已尝试」标记后重试（已算好的指纹保留，适用于 ffmpeg 能力升级后恢复失败歌曲）。两者同时传入时 recompute_all 优先。
需要认证
此接口需要 Bearer Token 认证
请求体
计算选项
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
recompute_all | boolean | 否 | |
retry_failed | boolean | 否 | RetryFailed 仅重置失败项的「已尝试」标记后重试，已算好的指纹保留。 |
响应
200 - 任务已启动
类型： map[string]any
400 - chromaprint 不可用
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
POST /scan/fingerprints/cancel
中断指纹计算
停止正在运行的批量指纹计算任务并杀掉其 ffmpeg 子进程。指纹任务不挂在扫描的取消通道上（扫描「完成」后该通道已关闭），所以需要独立的取消入口。任务不在运行时返回 cancelled=false。
需要认证
此接口需要 Bearer Token 认证
响应
200 - 返回 cancelled 字段
类型： map[string]boolean
内容类型
- 响应：
application/json
GET /scan/fingerprints/failed
获取指纹计算失败的歌曲列表
返回所有指纹计算失败的本地歌曲，包含失败原因。用于在重复检测页面展示失败详情。
需要认证
此接口需要 Bearer Token 认证
响应
200 - 成功返回 {items: [...], total: N}
类型： map[string]any
500 - 服务器错误
类型： map[string]string
内容类型
- 响应：
application/json
GET /scan/fingerprints/progress
获取指纹计算进度
查询当前指纹计算任务的进度
需要认证
此接口需要 Bearer Token 认证
响应
200 - 计算进度
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
computed | integer | 否 | |
failed | integer | 否 | |
status | string | 否 | idle, running, done, cancelled |
total | integer | 否 |
内容类型
- 响应：
application/json
GET /scan/fingerprints/status
获取指纹计算状态
返回 ffmpeg chromaprint 可用性、本地歌曲指纹计算统计（含尝试失败数）以及「扫描后自动计算指纹」开关状态
需要认证
此接口需要 Bearer Token 认证
响应
200 - 指纹状态
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
auto_enabled | boolean | 否 | AutoEnabled 扫描后是否自动计算指纹（config scan_auto_fingerprint） |
chromaprint_available | boolean | 否 | ChromaprintAvailable ffmpeg 是否带 chromaprint muxer，false 时无法计算指纹 |
computed | integer | 否 | Computed 已有指纹的数量 |
failed | integer | 否 | Failed 尝试过但失败的数量（无音轨 / 文件损坏 / 超时），不会自动重试， |
| 需要「重新计算全部」才会再试 | |||
missing | integer | 否 | Missing 尚未尝试过计算的数量（= total - computed - failed） |
total | integer | 否 | Total 本地歌曲总数 |
500 - 查询指纹统计失败
类型： map[string]string
内容类型
- 响应：
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-auto-fingerprint
更新「扫描后自动计算音频指纹」开关
开启后每次扫描结束会在后台为缺失指纹的本地歌曲计算 chromaprint 指纹（并发按 CPU 自适应，单文件采样前 120 秒，失败只尝试一次）。大音乐库开启前请留意 CPU 开销。
需要认证
此接口需要 Bearer Token 认证
请求体
开关请求
类型： scanAutoFingerprintRequest
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
enabled | boolean | 否 |
响应
200 - 返回 enabled 字段
类型： map[string]boolean
400 - 请求格式错误
类型： map[string]string
500 - 保存配置失败
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
GET /settings/scan-auto-fingerprint
获取「扫描后自动计算音频指纹」开关
控制扫描完成后是否自动为缺失指纹的本地歌曲计算 chromaprint 音频指纹。默认关闭（false）：指纹只服务于「重复歌曲检测」和插件歌词/封面搜索，属按需功能，全库自动计算会长时间占用 CPU。关闭时可在重复检测页手动触发 POST /scan/fingerprints。
需要认证
此接口需要 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