[其他] Music Scraper音乐刮削工具使用指南：NAS元数据管理神器与Docker部署教程

对于拥有私人音乐库的NAS用户而言，手动整理成千上万首歌曲的元数据是一项令人望而生畏的任务。从封面缺失到信息错乱，这些瑕疵会严重影响到数字音乐库的管理和欣赏体验。Music Scraper 正是为解决这一问题而生的轻量级工具，它能够自动为音乐文件匹配并补充元数据，如专辑封面、歌词、艺术家和专辑信息等，堪称NAS音乐库的“信息管家”。

核心功能解析

Music Scraper 专为NAS环境优化，采用 Docker 容器化部署，具备以下强大功能：

• 多数据源支持：整合了企鹅音乐、云村音乐、酷狗、酷沃、苹果音乐及开放数据库六大数据源，能够智能互补，确保华语、欧美、日韩等各类曲库的信息准确性。
• 智能匹配算法：内置置信度评估机制，自动筛选最准确的匹配结果，有效避免信息错配。
• 批量处理能力：支持对整个音乐文件夹进行全自动刮削，处理海量音乐文件效率极高。
• 格式兼容性广：支持 MP3、FLAC、M4A、OGG、WAV、WMA 等主流音频格式，并能将封面、歌词等信息嵌入文件内部。
• 现代化操作界面：提供适配移动端的网页UI，设计风格简洁清晰，操作直观便捷。

Docker 部署实践

Music Scraper 的部署完全基于 Docker，以下是几种常见的部署方式。

方式一：直接使用 Docker 命令运行

对于能访问 Docker Hub 的NAS设备，可以直接拉取镜像并运行容器。请根据您的NAS架构（x86/amd64 或 ARM）选择对应的镜像标签。

# 适用于 x86/amd64 架构的NAS（如多数威联通、部分群晖）
docker run -d \
  --name music-scraper \
  -p 7301:7301 \
  -v /your/music/path:/app/music \   # 请替换为您的音乐目录实际路径
  -v /your/data/path:/app/data \     # 请替换为您希望保存应用数据的目录
  -e TZ=Asia/Shanghai \
  --restart unless-stopped \
  minzgo/music-scraper:1.0.3-amd64

# 适用于 ARM 架构的NAS（如部分群晖、树莓派）
docker run -d \
  --name music-scraper \
  -p 7301:7301 \
  -v /your/music/path:/app/music \
  -v /your/data/path:/app/data \
  -e TZ=Asia/Shanghai \
  --restart unless-stopped \
  minzgo/music-scraper:1.0.3-arm64

方式二：使用 Docker Compose 部署（推荐）

使用 Docker Compose 能以声明式的方式管理容器，配置更清晰，维护更便捷。在NAS上创建 docker-compose.yml 文件并写入以下内容：

services:
  music-scraper:
    image: minzgo/music-scraper:1.0.3-amd64 # 请根据架构选择 amd64 或 arm64
    container_name: music-scraper
    restart: unless-stopped
    ports:
      - “7301:7301” # 左侧宿主机端口可按需修改
    volumes:
      - /your/music/path:/app/music # 映射音乐目录
      - /your/data/path:/app/data   # 映射数据持久化目录
    environment:
      - TZ=Asia/Shanghai
      - PORT=7301

保存文件后，在该文件所在目录下执行 docker compose up -d 命令即可启动服务。成功部署后，在浏览器中访问 http://你的NAS_IP:7301 即可进入操作界面。

使用教程与操作步骤

通过Web界面，Music Scraper 的操作流程非常直观。

1. 浏览与选择：在首页点击“浏览文件”，导航至您的音乐文件夹，可以预览文件的现有元数据。
2. 单曲刮削：选中目标歌曲，点击“刮削”按钮，从多个数据源返回的搜索结果中，选择匹配度最高的条目，勾选需要写入的元数据字段（如封面、歌词、专辑名等），确认后即可完成更新。
3. 自动批量刮削：这是核心高效功能。点击“自动刮削”，选择目标目录并配置选项：
   • 数据源：建议多选以实现信息互补。
   • 刮削字段：选择需要补充的信息类型。
   • 最低置信度：建议设置为 70% 左右以平衡准确性与覆盖率。
   • 跳过已有：启用后可避免覆盖已完善的文件。
     点击“开始刮削”，工具便会自动处理整个文件夹内的文件。
4. 查看记录与统计：通过“刮削记录”页面可追踪所有任务历史，“音乐库概览”则提供了元数据完整度、格式分布等统计信息，方便进行 数据 层面的管理。

进阶配置与注意事项

• 环境变量：可通过环境变量 PORT、MUSIC_DIR、DATA_DIR、TZ 自定义服务端口、目录和时区。
• 封面尺寸：在设置页面可选择下载封面的分辨率（300px-1000px），500px 是兼顾清晰度与文件大小的推荐值。
• 格式支持说明：绝大多数格式均支持元数据和封面内嵌。需要注意的是，WAV 格式对元数据的支持有限，且无法嵌入封面。

常见问题排查 (Q&A)

• 刮削后封面不显示？ 请检查播放器是否支持读取内嵌封面，并尝试刷新或重新扫描播放器的媒体库。
• 部分歌曲匹配失败？ 可尝试将文件名规范化为“艺术家 - 歌曲名.mp3”的格式。对于冷门歌曲，可切换或同时勾选多个数据源进行尝试。
• 刮削速度较慢？ 为避免对公共数据源造成请求压力，工具内置了访问频率限制。批量处理大量文件时请耐心等待。
• 如何备份数据？ 定期备份 Docker 容器中映射的 /app/data 目录（即您设置的持久化目录），即可保存所有刮削记录与配置。