minzgo/music-scraper

🎵 Music Scraper

专为 NAS 用户打造的音乐元数据刮削工具

自动获取音乐文件的封面、歌词、艺术家等信息，支持 6 大音乐数据源，智能匹配最佳结果。

---

✨ 功能特性

• 🎯 多数据源：企鹅、云村、酷系、苹果、开放库等 6 大音乐数据源
• 🖼️ 智能匹配：基于置信度算法自动选择最佳匹配结果
• 📱 移动端适配：赛博朋克风格 UI，支持手机/平板访问
• 📦 批量处理：支持整个文件夹自动批量刮削
• 🎵 多格式支持：MP3、FLAC、M4A、OGG、WAV、WMA、DSF、DFF、DTS 等
• 📝 歌词获取：自动下载歌词并保存为 LRC 文件，支持多源互补
• 🎤 内嵌歌词：支持将歌词直接写入音频文件元数据（MP3/FLAC/M4A/OGG/WMA/WAV/AIFF/APE/WavPack 等）
• 🔄 多源互补：首选源缺少数据时，自动从其他源补充（封面、歌词均支持）
• 🔍 自动监测：定时扫描目录，自动检测新增文件并刮削，智能扫描策略，支持 7 天扫描间隔
• 📀 本地资源优先：自动读取目录下的 CUE 文件和封面图片
• ⚡ 高性能架构：Go 语言重构，原生并发，性能大幅提升
• 📡 实时状态推送：WebSocket 实时推送扫描状态，前端 UI 响应更快
• 🛡️ 广告过滤：自动识别并清理音乐标签中的广告内容，保持元数据干净整洁
• ⚡ 熔断保护：数据源连续失败后自动熔断，避免无效请求，提升稳定性
• 🔐 登录认证：密码保护 + 两步验证（2FA），保护您的音乐库安全
• 🔗 工具箱集成：内置工具箱前端，支持硬链接输出、自动分类、重命名等（v2.0.0 新增）
• ✏️ 歌词编辑：独立歌词编辑页面，支持查看和修改内嵌歌词
• 🎧 Hi-Res 支持：DSF/DFF/DTS 高解析度音频格式支持
• ⚙️ 并发可配置：刮削并发数用户可配置（1-16），灵活调整性能

---

🚀 快速开始

拉取镜像

bash
# 推荐：自动选择合适架构
docker pull minzgo/music-scraper:latest

# 或指定架构
# x86 架构（绿联云、威联通、部分群晖）
docker pull minzgo/music-scraper:2.0.6-amd64
# ARM 架构（部分群晖、树莓派）
docker pull minzgo/music-scraper:2.0.6-arm64

运行容器

基础部署（推荐挂载数据目录）：

bash
docker run -d \
  --name music-scraper \
  -p 7301:7301 \
  -v /你的音乐目录:/app/music \
  -v /数据目录:/app/data \
  -e TZ=Asia/Shanghai \
  --restart unless-stopped \
  minzgo/music-scraper:latest

特权模式部署（设备码基于硬件信息，更稳定）：

bash
docker run -d \
  --name music-scraper \
  --privileged \
  -p 7301:7301 \
  -v /你的音乐目录:/app/music \
  -v /数据目录:/app/data \
  -e TZ=Asia/Shanghai \
  --restart unless-stopped \
  minzgo/music-scraper:latest

💡 特权模式优势：使用 --privileged 模式部署时，设备码会基于硬件信息（系统UUID、MAC地址、磁盘序列号等）生成，即使不挂载 /app/data 目录，设备码也能保持稳定不变。这对于需要稳定设备码的场景（如激活码绑定）非常有用。

Docker Compose

基础配置：

yaml
version: '3'
services:
  music-scraper:
    image: minzgo/music-scraper:latest
    container_name: music-scraper
    ports:
      - "7301:7301"
    volumes:
      - /你的音乐目录:/app/music
      - ./data:/app/data
    environment:
      - TZ=Asia/Shanghai
    restart: unless-stopped

特权模式配置（推荐，设备码更稳定）：

yaml
version: '3'
services:
  music-scraper:
    image: minzgo/music-scraper:latest
    container_name: music-scraper
    privileged: true  # 启用特权模式
    ports:
      - "7301:7301"
    volumes:
      - /你的音乐目录:/app/music
      - ./data:/app/data
    environment:
      - TZ=Asia/Shanghai
    restart: unless-stopped

刮削器 + 工具箱联合部署（完整功能）：

yaml
version: '3'
services:
  # 刮削器主服务
  music-scraper:
    image: minzgo/music-scraper:latest
    container_name: music-scraper
    privileged: true
    ports:
      - "7301:7301"
    volumes:
      # Docker socket（用于自动获取挂载映射，实现路径自动转换）
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /你的音乐目录:/app/music
      - ./scraper-data:/app/data
    environment:
      - TZ=Asia/Shanghai
      - TOOLBOX_URL=http://music-toolbox:7305  # 工具箱地址
    restart: unless-stopped
    depends_on:
      - music-toolbox

  # 工具箱服务（硬链接整理）
  music-toolbox:
    image: minzgo/music-toolbox:latest
    container_name: music-toolbox
    ports:
      - "7305:7305"
    volumes:
      # Docker socket（用于自动获取挂载映射，实现路径自动转换）
      - /var/run/docker.sock:/var/run/docker.sock:ro
      # 挂载音乐目录的父目录，确保硬链接正常工作
      # 例如：音乐在 /volume2/音乐，输出到 /volume2/整理后，则挂载 /volume2
      - /你的存储卷:/app/source:rw
      - ./toolbox-data:/app/data
    environment:
      - TZ=Asia/Shanghai
      - SCRAPER_URL=http://music-scraper:7301  # 刮削器地址（用于授权验证）
    restart: unless-stopped

💡 工具箱说明：工具箱是刮削器的配套功能，提供硬链接整理、自动分类等功能。刮削完成后可自动触发硬链接整理。

⚠️ 重要配置说明：

• TOOLBOX_URL：刮削器连接工具箱的地址，使用 Docker 服务名 http://music-toolbox:7305
• SCRAPER_URL：工具箱连接刮削器的地址，使用 Docker 服务名 http://music-scraper:7301（用于授权验证）
• Docker socket 挂载：两个服务都需要挂载 /var/run/docker.sock，用于自动获取挂载映射，实现路径自动转换
• 工具箱挂载路径：挂载音乐目录的父目录到 /app/source，例如音乐在 /volume2/音乐，则挂载 /volume2:/app/source
• 硬链接要求：源目录和目标目录必须在同一挂载点下（都在 /app/source 内），否则会自动降级为复制

访问使用

浏览器打开 http://你的IP:7301 即可使用！

---

⚙️ 配置说明

端口

数据卷

环境变量

💡 关于地址配置：

• TOOLBOX_URL：刮削器后端连接工具箱的地址，Docker Compose 部署时必须使用服务名如 http://music-toolbox:7305（Docker 内网通信）
• SCRAPER_URL：工具箱后端连接刮削器的地址，Docker Compose 部署时必须使用服务名如 http://music-scraper:7301（用于授权验证）
• TOOLBOX_EXTERNAL_URL：用户浏览器跳转到工具箱的地址，如果使用反向代理，需配置为外部可访问的地址如 http://nas.example.com/toolbox
• 如果未配置 TOOLBOX_EXTERNAL_URL，前端会自动使用 当前页面主机名:7305 作为跳转地址

⚠️ 常见错误：TOOLBOX_URL 和 SCRAPER_URL 不能配置为 localhost，因为容器内的 localhost 指向容器自身，无法连接到其他容器！

---

🏷️ 标签说明

💡 推荐使用：直接使用 latest，Docker 会自动选择适合您设备的架构

---

🔧 支持的音频格式

完全支持（读写）

• ✅ MP3 (ID3v2) - 支持元数据、封面、歌词
• ✅ FLAC (Vorbis) - 支持元数据、封面、歌词
• ✅ M4A/AAC (MP4) - 支持元数据、封面、歌词
• ✅ OGG (Vorbis/Opus) - 支持元数据、封面、歌词
• ✅ WMA (ASF) - 支持元数据、封面、歌词
• ⚠️ WAV - 有限元数据支持，支持歌词
• ✅ AIFF - 支持元数据、歌词
• ✅ APE (Monkey's Audio) - 支持元数据、歌词
• ✅ WavPack - 支持元数据、歌词

Hi-Res 音频（只读）

• 🎧 DSF (DSD Stream File) - 仅读取元数据
• 🎧 DFF (DSDIFF) - 仅读取元数据
• 🎧 DTS - 仅读取元数据

💡 Hi-Res 格式因技术限制暂不支持写入，但可以读取并显示现有元数据

---

🌐 数据源

---

💬 用户交流群

遇到问题或有建议？欢迎加入用户交流群，获取最新版本、提需求、技术交流！

---

📝 更新日志

v2.0.9 (2026-03)

✨ 新功能

• 手动刮削成功后自动触发工具箱联动整理，与自动刮削行为保持一致（解决自动刮削失败后手动补刮不触发文件整理的问题）

---

v2.0.8 (2026-03)

🔧 维护更新

• 版本号更新至 2.0.8

---

v2.0.7 (2026-03)

🔧 优化改进

• APE/WavPack 封面写入改为符合 APEv2 规范的标准格式，提升第三方播放器（foobar2000、Mp3tag 等）的封面识别兼容性
• APE/WavPack 封面读取增加智能解析，同时兼容标准格式与裸数据，并自动识别 JPEG/PNG 类型
• 音乐库统计的格式分布补全 DSF、DFF、DTS、ALAC、AIF、MP4、ASF 等格式，与系统支持的格式列表保持一致

---

v2.0.6 (2026-02)

✨ 新功能

• 工具箱新增「歌手/专辑（年份）」分类模式：在专辑名后标注年份信息，便于按时间线浏览歌手专辑
  • 目录结构示例：周杰伦/七里香（2004）/双截棍.flac
  • 年份缺失时自动降级为不带年份后缀的目录名，避免同专辑分裂到不同文件夹

---

v2.0.5 (2026-02)

🐛 Bug 修复

• 修复设置页"加入用户群"***在 Linux/Docker 环境下无法显示的问题（文件名大小写不匹配）

---

v2.0.4 (2026-02)

✨ 新功能

• 工具箱硬链接整理支持携带专辑级文件：
  • artist-album、artist-album-disc 模式：自动携带 cover.jpg、folder.jpg、.cue、.log 等专辑文件
  • keep-structure 模式：携带源目录下所有非音频文件
  • flat、genre-artist、year-artist 等模式：不携带专辑文件（避免文件冗余）

🐛 Bug 修复

• 修复自动刮削页面选择空文件夹导致的 JS 错误（Cannot read properties of null）
• 修复空文件夹时文件夹选择弹窗一直显示"加载中"的问题

🔧 优化改进

• 自动刮削页面新增刮削前验证：无音乐文件时 Toast 提示用户
• 后端 API 优化：空目录返回空数组 [] 而非 null，提升前端兼容性

---

v2.0.3 (2026-01)

✨ 新功能

• 手动刮削支持字段选择：用户可在确认弹窗中点击字段切换选中/取消状态，未选中的字段不会被写入
• 双语歌词格式选择：支持四种模式（分行显示/合并显示/仅原文/仅翻译）
• 工具箱自定义重命名格式：可视化选择器，支持按顺序点选字段标签，实时预览效果
• 工具箱自动监测状态持久化：服务重启后自动恢复监测状态

🐛 Bug 修复

• 修复「跳过已有信息」功能的多个问题：
  • 修复内嵌歌词检测字段名不匹配问题（现在正确跳过已有内嵌歌词的文件）
  • 修复封面检测逻辑（已有封面时正确跳过）
  • 修复元数据字段跳过逻辑（title/artist/album/year/genre 已有值时跳过写入）
• 修复刮削状态判定：当没有任何字段被写入时，状态改为「跳过」而非「成功」
• 修复操作记录页面不显示手动刮削记录的问题
• 修复歌手合并任务执行后统计数据（TotalArtists、ConfirmedGroups）丢失的问题
• 修复工具箱整理进度页面返回按钮跳转地址错误
• 修复工具箱分批平铺模式的计数 Bug：第二次执行时会扫描已有文件夹，从正确位置继续，避免文件夹超出限制

🔧 优化改进

• 统一音乐格式定义：提取为全局常量，消除代码重复
• 工具箱补充 4 种音乐格式支持：.wma、.alac、.mp4、.asf
• 双语歌词选项智能显示：只有歌曲有翻译歌词时才显示格式选择
• 操作记录页面性能优化：并行获取本地任务和工具箱任务，工具箱请求设置超时避免阻塞
• 统一刮削弹窗组件：task-files.html 页面改用 ScrapePanel 组件

---

v2.0.2 (2026-01)

🐛 Bug 修复

• 修复批量刮削/自动监测时 fields 参数过滤不生效的问题（只选择封面时仍写入其他标签）
• 修复自动监测时即使 fields 不包含歌词字段，仍会写入歌词的问题
• 修复手动刮削覆写模式时，数据源无数据字段无法清空的问题（如专辑、年份、流派）
• 修复覆写模式清除封面时，封面未被正确删除的问题

✨ 功能改进

• 批量刮削/自动监测：fields 参数现在正确过滤所有元数据字段和歌词写入
  • calculateFieldsWritten 函数增加 allowedFields 参数，只记录用户选择的字段
  • 歌词写入逻辑增加 fields 字段检查，未选择歌词字段时不写入
• 手动刮削覆写模式：数据源无数据时正确清空目标字段
  • 新增 clearCover 方法用于清除封面
  • writeMetadataWithMode 支持空值清空逻辑，覆写模式下空字段会清空目标文件对应字段
• Python 元数据写入器：支持空字符串删除标签
  • _write_flac、_write_mp3、_write_mp4、_write_ogg 方法支持空值删除
  • 空字符串值触发标签删除（用于覆写模式清空字段）
• 工具箱前端移除：移除工具箱独立前端文件，改为显示提示页面引导用户从刮削器入口访问

---

v2.0.1 (2026-01)

🐛 Bug 修复

• 修复自动监测保存配置时 autoScrape 被错误重置的问题（修改置信度等配置后监测失效）
• 修复工具箱自动化流程中「分批平铺」分类模式不生效的问题
• 修复工具箱未部署提示弹窗内容过长时无法滚动的问题
• 修复设置保存接口无法正确保存配置的问题
• 修复工具箱硬链接统计维度错误（改为以文件为单位统计）
• 修复工具箱多歌手解析问题（支持英文分号无空格格式如 歌手A;歌手B）
• 修复工具箱开启监控后弹窗显示错误的监控模式

✨ 功能改进

• 工具箱歌手合并/专辑合并新增「批量确认推荐」功能，一键确认所有推荐合并组
• 刮削面板 UI 重构优化
• 增强工具箱跨设备检测日志，便于诊断硬链接问题

---

v2.0.0 (2026-01) 🎉 重大更新

🚀 架构重构

• ⚡ Go 语言重构：核心服务使用 Go 语言重写，性能大幅提升
• 🔄 原生并发：Go goroutine 替代 Python gevent，无 GIL 限制
• 💾 多数据库架构：分离刮削、缓存、索引、设置等数据库，避免写锁竞争
• 🔌 Python 微服务：元数据读写保留 Python 实现，确保兼容性

🔗 工具箱深度集成

• 🧰 前端统一：工具箱前端集成到刮削器，无跨域问题
• 🔍 服务检测：智能检测工具箱部署状态，未部署时显示友好提示
• 🔗 硬链接整理：将刮削后的音乐文件以硬链接方式输出到指定目录
• 📁 自动分类：支持按歌手/专辑/流派/年份自动分类（5 种分类模式）
• ✏️ 文件重命名：支持多种重命名格式（音轨号-标题、歌手-标题等）
• 🔄 自动联动：刮削完成后自动通知工具箱进行硬链接整理
• ⚡ 跨设备支持：检测跨文件系统情况，自动降级为软链接或复制
• 📝 操作记录：记录每次整理的详细信息，支持回溯查看
• 🛡️ 死循环防护：自动排除工具箱输出目录，防止循环触发

🎧 Hi-Res 音频支持

• 🎵 DSF 格式：支持 DSD Stream File 格式读取（索尼 Hi-Res 格式）
• 🎵 DFF 格式：支持 DSDIFF 格式读取
• 🎵 DTS 格式：支持 DTS 音频格式读取
• ⚠️ Hi-Res 格式暂为只读，元数据修改后自动跳过写入

✨ 功能改进

• 🎤 歌词多源互补：歌词获取支持多源互补，首选源无歌词时自动从其他源获取
• ⚙️ 并发可配置：刮削并发数可在设置界面配置（1-16）
• ✏️ 歌词编辑页面：新增独立歌词查看/编辑页面，支持修改内嵌歌词
• ✏️ 手动编辑重构：手动编辑功能重构为独立页面，交互更流畅
• 🔍 搜索字段选择器：文件浏览器支持按标题/艺术家/专辑字段筛选搜索
• ⏰ 扫描间隔扩展：自动监测扫描间隔支持最长 7 天，支持小数分钟
• 🎯 专辑版本匹配：优化置信度算法，更好地识别专辑不同版本（Deluxe、Remaster 等）
• 🎤 多艺术家修复：修复多艺术家标签写入格式，主流播放器可正确识别分隔
• 🛡️ 广告残余清理：增强广告过滤，清理「更多打包资源」等无意义残留内容
• 🔄 授权迁移：从旧版本升级时自动迁移授权信息，无需重新激活

🐛 Bug 修复

• 修复刮削结果不一致的问题（网络请求增加重试机制）
• 修复工具箱页面登录检测问题
• 修复自动监控死循环问题
• 修复统计页面数据显示问题
• 修复元数据完整度缓存问题

使用工具箱：

1. 使用 Docker Compose 部署工具箱服务（参见联合部署配置）
2. 在刮削器首页点击「工具箱」卡片进入
3. 配置源目录和目标目录，选择分类模式
4. 可手动执行批量整理，或开启自动监控

---

v1.1.0 (2025-12)

🔐 新功能：登录认证系统

• 🔒 密码保护：支持设置登录密码，保护您的音乐库不被未授权访问
• 📱 两步验证（2FA）：支持 TOTP 验证器（Google Authenticator 等）
• 🔑 恢复码：生成一次性恢复码，防止丢失验证器后无法登录
• 🛡️ 暴力破解保护：连续失败后自动锁定
• 🔄 老用户升级：自动检测并提示设置密码，数据完全保留

---

v1.0.9 (2025-12)

✨ 新功能

• 🎨 双主题支持：新增粉色赛博朋克亮色主题「樱」，支持在设置页面切换暗夜/樱主题
• ✏️ 手动编辑元数据：支持直接编辑标题、艺术家、专辑、年份、流派，支持封面图片上传/更换
• 🎤 双语歌词合并：自动将原文歌词和翻译歌词按时间戳合并，支持网易云音乐、QQ音乐数据源

⚡ 性能优化

• 🚫 任务取消优化：改为非阻塞模式，添加「正在取消任务...」提示，更快响应取消请求

🐛 Bug 修复

• 修复第二次覆写刮削时封面丢失的问题（缓存命中后重新获取封面数据）
• 修复手动点击立即扫描触发自动刮削卡住的问题（改用标志位避免线程竞态）

v1.0.8 (2025-12)

✨ 新功能

• 🛡️ 熔断器机制：数据源连续失败后自动熔断，避免无效请求
  • 连续失败 10 次后熔断 60 秒
  • 新增 API：/api/circuit-breaker/status 和 /api/circuit-breaker/reset

⚡ 性能优化

• 🚀 并发控制优化：降低并发数，减少数据库写锁竞争
• ⏱️ 动态超时阈值：消除"卡住任务"误判问题
• 💾 刮削时暂停后台任务：刮削期间跳过缓存清理、索引更新等后台任务
• 📊 进度页面优化：结果列表改为 API 分页获取，避免前端内存溢出

v1.0.5 (2025-12)

✨ 新功能

• 🛡️ 广告过滤功能：自动识别并清理音乐标签中的广告内容
• 📄 任务文件列表页面：新增任务文件详情查看功能
• 🎨 网站图标支持：新增 favicon，提升用户体验

🎤 歌词功能增强

• 📝 扩展音频格式歌词支持：新增 WAV、AIFF、APE、WavPack 的内嵌歌词写入

v1.0.3 (2025-12)

⚡ 性能优化

• 🚀 并行 I/O 优化：动态线程池大小，根据 CPU 核心数自动调整
• 📊 建立索引性能提升：批量数据库操作、消除重复遍历，索引速度提升 2-4 倍
• 🎤 内嵌歌词支持：支持将歌词直接写入音频文件元数据
• 📡 Overview 实时状态推送：通过 WebSocket 实时推送扫描状态

v1.0.2 (2025-12)

• 🔥 自动监测：定时扫描目录，自动检测新增文件并刮削
• ⚡ 智能扫描：两阶段扫描策略，5-20 秒自适应间隔
• 🛡️ 还原保护：还原后的文件 48 小时内不会被自动刮削
• 🖼️ 本地资源优先：自动读取目录下的封面图片和 CUE 文件

v1.0.0 (2025-12)

• 首个公开发布版本

---

📖 更多信息

• GitHub: https://github.com/SimonLYU/MusicScraper
• 问题反馈: 请在 GitHub Issues 中提交

---

📄 许可证

MIT License