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 等）
• 🔄 多源互补：首选源缺少数据时，自动从其他源补充（封面、歌词均支持）
• 🔍 自动监测：定时扫描目录，自动检测新增文件并刮削，统一 watcher 监测与首次文件索引流程
• 📀 本地资源优先：自动读取目录下的 CUE 文件和封面图片
• ⚡ 高性能架构：Go 语言重构，原生并发，性能大幅提升
• 📡 实时状态推送：WebSocket 实时推送扫描状态，前端 UI 响应更快
• 🛡️ 广告过滤：自动识别并清理音乐标签中的广告内容，保持元数据干净整洁
• ⚡ 熔断保护：数据源连续失败后自动熔断，避免无效请求，提升稳定性
• 🔐 登录认证：密码保护 + 两步验证（2FA），保护您的音乐库安全
• 🔗 工具箱集成：内置工具箱前端，支持硬链接输出、按首字母分类、自动分类、重命名等
• ✏️ 歌词编辑：独立歌词编辑页面，支持查看和修改内嵌歌词
• 🎧 Hi-Res 支持：DSF/DFF/DTS 高解析度音频格式支持
• ⚙️ 并发可配置：刮削并发数用户可配置（1-16），灵活调整性能

---

🚀 快速开始

拉取镜像

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

# 或指定架构
# x86 架构（绿联云、威联通、部分群晖）
docker pull minzgo/music-scraper:2.1.2-amd64
# ARM 架构（部分群晖、树莓派）
docker pull minzgo/music-scraper:2.1.2-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

💡 如需基于硬件信息生成更稳定的设备码，可在 docker run 中额外添加 --privileged。

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:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /你的音乐目录:/app/music  # 需修改：改成你的实际音乐目录，例如 /volume2/音乐:/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:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /你的存储卷:/app/source:rw  # 需修改：改成音乐目录和输出目录的共同父目录，例如 /volume2:/app/source:rw
      - ./toolbox-data:/app/data
    environment:
      - TZ=Asia/Shanghai
      - SCRAPER_URL=http://music-scraper:7301
    restart: unless-stopped

💡 工具箱说明：工具箱是刮削器的配套功能，提供硬链接整理、自动分类等功能。刮削完成后可自动触发硬链接整理。 ⚠️ 联合部署时 TOOLBOX_URL / SCRAPER_URL 必须使用 Docker 服务名；工具箱建议挂载音乐目录的父目录到 /app/source，确保源目录和输出目录在同一挂载点下。

访问使用

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

---

⚙️ 配置说明

端口

数据卷

环境变量

⚠️ Docker Compose 中 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.1.2 (2026-05)

✨ 新功能

• Music Toolbox 新增「按首字母」分类模式：根据最终输出文件名归入 A-Z、0-9、其他目录，适合按歌名或文件名浏览整理结果
• 首字母分类支持中文拼音首字母识别，并会跳过文件名前置空格、标点和符号
• 操作记录新增分类模式与重命名格式信息，方便回溯整理任务配置
• 新增本地音乐重复文件智能去重方案文档，覆盖多键匹配与文件质量评分推荐保留策略

🔧 优化改进

• 按首字母分类模式固定合并多歌手输出，避免重复生成文件
• 自动监测移除旧 scanner，轮询逻辑统一到 watcher，并补齐首次文件索引流程
• 工具箱整理记录会保存分类模式与重命名模板，便于排查整理结果来源
• Docker 构建脚本增加常用镜像源 host 映射，提升 Docker Desktop 环境下的构建稳定性

📦 镜像发布

• 已发布 Scraper 与 Toolbox 的 2.1.2 / latest 多架构镜像，均支持 linux/amd64 与 linux/arm64

---

v2.1.1 (2026-04)

🐛 Bug 修复

• 修复企鹅乐坊（QQ 音乐）数据源因官方旧接口下线导致的搜索 / 详情全部失效问题：迁移到官方新接口（u.y.qq.com/cgi-bin/musicu.fcg，POST + JSON 协议），恢复手动刮削、自动刮削、双语歌词等所有依赖该数据源的链路

---

v2.1.0 (2026-03)

✨ 新功能

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

🐛 Bug 修复

• 修复 Docker 容器启动时挂载映射加载失败后不再重试的问题（Docker API 暂时不可用时，刮削器与工具箱间的路径转换失效）
• 修复硬链接整理生成目录权限过严的问题（从 0755 调整为 0766，方便用户管理）

🔧 优化改进

• Docker 挂载映射加载增加重试机制：启动时最多重试 5 次，且每次使用时兜底检查，提升容器启动稳定性
• 清理已废弃的 Python 老版本代码（music4docker 目录）

---

历史版本更新记录请查看 https://github.com/SimonLYU/MusicScraper/releases%E3%80%82

---

📖 更多信息

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

---

📄 许可证

MIT License