Skip to content

🚀 使用 Docker Compose 部署 Music Tag Web

🚀 使用 Docker Compose 部署 Music Tag Web

Music Tag Web 是一款功能强大的Web版音乐标签编辑器，支持批量修改音乐文件的元数据（如标题、专辑、艺术家、歌词、封面等）。它具备音乐指纹识别能力，即使文件缺少元数据，也能通过音频内容进行识别和匹配。通过 Docker 部署，你可以轻松搭建属于自己的音乐标签管理服务，高效整理本地音乐库。

📖 项目简介

Music Tag Web 是一款由国内开发者制作的绿色无广告工具，其主要功能包括：

  • 广泛的音频格式支持：支持 FLAC、APE、WAV、AIFF、WV、TTA、MP3、M4A、OGG、MPC、OPUS、WMA、DSF、DFF、MP4 等主流音频格式。
  • 批量自动刮削（修改）：可联网根据音频标题、艺术家、专辑数据批量自动获取并写入音频的详细信息，包括封面、歌词等。支持从网易云音乐、QQ音乐、咪咕音乐、酷狗音乐等主流平台获取信息。
  • 智能文件整理：支持根据艺术家、专辑等信息对音乐文件进行自定义多级分组整理。
  • 音乐格式转换与整轨切割：集成 ffmpeg，支持多种音乐格式转换，以及将整轨音乐文件分割成独立的曲目。
  • 其他实用功能：支持繁简体转换、歌词翻译、文本替换、元数据补充、专辑封面管理等功能。

⚙️ 部署前准备

  1. 环境要求

    • 确保你的系统（可以是个人电脑、服务器或 NAS）已安装 Docker 和 Docker Compose。
    • 建议为 Docker 分配至少 2GB 内存以保证流畅运行。
    • 准备足够的存储空间来存放音乐文件和应用程序配置。

  2. 创建目录结构 建议创建一个独立的工作目录，例如 music-tag-web，以便管理所有相关文件。

mkdir -p music-tag-web
cd music-tag-web

根据你提供的 `docker-compose.yml` 文件，你需要确保以下目录存在或被正确创建：
*   `/mnt/10t/file/connect/music`：用于存放你的音乐文件。此目录将被映射到容器内的 `/app/media` 目录。
*   `./config`：在工作目录下用于持久化保存 Music Tag Web 的应用程序配置和数据库。此目录将被映射到容器内的 `/app/data` 目录。

🔧 配置 Docker Compose

  1. 在你创建的工作目录（例如 music-tag-web）下，创建一个名为 docker-compose.yml 的文件。
  2. 将你提供的配置内容复制到文件中。为了更清晰，这里对你的配置进行了简要注释：
services:
  music-tag:
    image: xhongc/music_tag_web:latest  # 官方最新镜像（自动更新功能）
    container_name: music-tag-web  # 容器名称，便于管理（如停止/查看日志）
    ports:
      - "8002:8002"  # 端口映射：主机 8002 → 容器 8002（Web 界面访问端口）
      #- "8001:8001"   # 注释：v1 版本端口，当前用 v2 无需启用
    volumes:
      #- ./music:/app/media:rw
      #- /home/compose/navidrome/music:/app/media:rw

      # 核心：音乐文件目录（主机音乐路径 → 容器 /app/media，rw=读写权限，必须！）
      - /mnt/10t/file/connect/music:/app/media:rw
      # 配置目录（主机 ./config → 容器 /app/data，保存工具设置）
      - ./config:/app/data
    restart: unless-stopped  # 容器退出后自动重启（除非手动停止，保障服务稳定）


#默认账号密码 admin/admin ，第一次登录修改默认密码。

关键配置说明：

  • image：指定使用的 Docker 镜像，这里为官方最新版 xhongc/music_tag_web:latest。
  • ports：端口映射。格式为 "宿主机端口:容器端口"。这里将容器内的 8002 端口服务映射到宿主机的 8002 端口。如果宿主机 8002 端口已被占用，你可修改冒号前的端口，例如 "8080:8002"，然后通过 http://宿主机IP:8080 访问。
  • volumes：卷映射，用于持久化数据。
    • /mnt/10t/file/connect/music:/app/media:rw：将你存放音乐的宿主机目录映射到容器内的 /app/media 目录。Music Tag Web 将会扫描此目录下的音乐文件。:rw 表示读写权限。
    • ./config:/app/data：将容器内的配置和数据目录映射到宿主机当前目录下的 config 文件夹。这一点很重要，可以防止容器删除后你的设置和数据库丢失。
  • restart: unless-stopped：设置容器在异常退出时自动重启，确保服务高可用。

🚀 启动与验证

  1. 启动 Music Tag Web 服务 在 docker-compose.yml 文件所在目录下，执行以下命令来启动服务： bash docker compose up -d 参数 -d 表示在后台运行容器。

  2. 验证服务状态

    • 你可以使用以下命令查看容器是否正常运行： bash docker compose ps 如果状态显示为 Up，则表明容器已成功启动。
    • 你也可以查看容器的启动日志来排查可能的问题： bash docker compose logs music-tag-web

  3. 访问 Web 界面

    • 打开浏览器，输入 http://你的服务器IP地址:8002 访问 Music Tag Web 的首页。
    • 输入 http://你的服务器IP地址:8002/admin 进入管理后台。
    • 初始账户和密码均为 admin。首次登录后，请务必按照系统提示修改默认密码，以增强安全性。

🛠️ 基础配置与使用

  1. 基本操作流程

    • 访问界面：登录后，你会看到映射的 /app/media 目录下的音乐文件列表。
    • 选择文件或文件夹：勾选文件或文件夹左侧的复选框，上方会显示可用的操作按钮。
    • 自动刮削：点击"自动刮削"，建议模式选择"标准"，来源可根据喜好选择（如网易、QQ、咪咕、酷狗等）。勾选"刮削后整理"（如果不需要移动文件，注意相关设置）。
    • 查看结果：刮削完成后，你可以在"操作记录"中查看详细的报告，成功与否都会有记录。

  2. 开启后台自动刮削 如果你希望新添加进特定文件夹的音乐能被自动刮削，可以开启后台刮削功能：

    • 进入 Web 界面的"系统设置" -> "后台刮削"。
    • 开启"后台刮削"，后台会默认每3分钟检查目标目录（容器内的 /app/media/download/，此路径目前固定不可修改）并进行自动刮削。
    • 设置"修改范围"和"刮削模式"。
    • 如果开启了"刮削后整理"，刮削完成后会在 download 目录下生成 completed 和 failed 两个文件夹，并可将 completed 中的文件整理移动到其他目录。
    • 这样，你只需将音乐直接下载或放到宿主机上映射为 /app/media/download 的目录（根据你的配置，可能是 /mnt/10t/file/connect/music/download），即可实现自动刮削和整理。

  3. 文件整理注意事项

    • 使用"整理"功能时，请注意此功能会直接移动文件。如果你需要保种（例如从 PT 网站下载的音乐），建议搭配硬链接使用，避免影响做种。
    • 你可以设置整理到映射目录下的特定文件夹，例如 /app/media/music（对应宿主机 /mnt/10t/file/connect/music/music）。

  4. 与其他音乐服务器配合

    • Music Tag Web 完善音乐元数据后，可以搭配专门的音乐服务器（如 Navidrome）使用，以获得更好的播放和管理体验。
    • 确保 Music Tag Web 和音乐服务器（如 Navidrome）映射的音乐路径是统一的。
    • 一些支持 Subsonic 协议的客户端（如"音流"App）也可以直接连接 Music Tag Web，将其作为音乐服务器使用。协议选择 Subsonic，地址填写 http://你的服务器IP:8002，账户密码为你的 Music Tag Web 账户密码。

🔄 维护与管理

  1. 服务管理

    • 停止服务：在 docker-compose.yml 所在目录执行 docker compose down。
    • 重启服务：执行 docker compose restart。
    • 更新服务：想要更新到最新版本时，可以执行以下命令： bash docker compose down # 停止当前容器 docker compose pull # 拉取最新的镜像 docker compose up -d # 重新启动容器

  2. 数据备份

    • 定期备份你所配置的 ./config 目录。这个目录包含了 Music Tag Web 所有的配置、数据库和操作记录。
    • 同样，确保你的音乐源文件（即映射到 /app/media 的目录）有可靠的备份。

  3. 日志查看

    • 如果需要排查问题，可以查看 Music Tag Web 的日志： bash docker compose logs music-tag-web # 查看最新日志 docker compose logs -f music-tag-web # 实时跟踪日志

❓ 常见问题排查

  1. 容器启动失败或无法访问 Web 界面

    • 检查端口冲突：确认宿主机的 8002 端口未被其他程序占用。如果占用，修改 docker-compose.yml 中的宿主机端口映射。
    • 检查目录权限：确保宿主机上映射的目录（尤其是音乐目录 /mnt/10t/file/connect/music）对 Docker 容器有读写权限。你提供的配置中已使用 :rw 明确指定读写权限，但宿主机路径本身的权限也需确保。
    • 查看容器日志：使用 docker compose logs music-tag-web 查看具体错误信息。

  2. Music Tag Web 扫描不到音乐文件

    • 检查路径映射：确保在 docker-compose.yml 中，音乐目录正确映射到了容器内的 /app/media。
    • 检查文件格式：确认你的音乐文件是 Music Tag Web 支持的格式。
    • 手动触发扫描：在 Web 界面中，尝试手动刷新或检查文件列表。

  3. 自动刮削失败或识别不准

    • 更换数据源：尝试更换不同的音乐平台（如网易云、QQ音乐等）作为刮削源，因为不同平台的版权和数据库有差异。
    • 检查网络连接：确保容器所在环境能够正常访问外网，因为刮削需要从互联网获取数据。
    • 手动补充信息：对于自动刮削失败的文件，可以尝试手动编辑标签信息，或利用"元数据补充"功能从文件名中提取信息。

  4. 关于多音乐文件夹的管理

    • 根据用户反馈，在容器内同时映射多个音乐文件夹到 /app/media 可能会遇到问题。
    • 建议：将所有的音乐文件都集中存放在一个主目录（例如你配置中的 /mnt/10t/file/connect/music），然后在这个主目录下使用子文件夹进行分类。Music Tag Web 会递归扫描子文件夹。

希望这篇教程能帮助你顺利搭建并熟练使用 Music Tag Web，让你的本地音乐库变得井井有条！如果在使用过程中遇到更具体的问题，可以查阅官方文档或社区讨论。