Music Tag Web Docker 部署指南
发布日期: 2025-11-20
一份详尽的操作指南，助您轻松在 Docker 环境中部署和管理 Music Tag Web 音乐刮削工具。
1. 简介
Music Tag Web 是一款功能强大的网页版音乐元数据编辑器。它允许用户通过浏览器方便地编辑歌曲的标题、专辑、艺术家、歌词、封面等信息。该应用支持多种主流音频格式，包括 FLAC、APE、WAV、MP3、M4A、OGG 等，是音乐收藏家和家庭媒体中心（如 Plex、Jellyfin）用户的理想工具。
通过 Docker 进行部署，可以实现环境隔离、快速迁移和简化管理，无需复杂的环境配置，尤其适合在无图形界面的服务器（Headless Server）上运行。
主要功能特性
- Web 界面管理：无需安装桌面软件，随时随地通过浏览器整理音乐库。
- 后台异步任务：所有批量刮削和文件操作都在后台执行，不影响前台操作流畅性。
- 自动刮削：能够监控新加入的音乐文件夹，并自动识别和整理元数据。
- 音乐收藏与播放：支持一键收藏，并兼容 Open Subsonic 协议，可通过网页端或第三方 Subsonic 播放器播放在线音乐。
- 云端文件支持：可与 AList 集成，管理和刮削存储在云盘中的音乐文件。
- 智能歌单：采用类似 Apple Music 的规则引擎，创建个性化的智能歌单。
2. 前置条件
在开始部署之前，请确保您的系统满足以下要求。
2.1. 硬件要求
Docker 本身对资源要求不高，但 Music Tag Web 在处理大型音乐库时会消耗一定的 CPU 和内存。以下为推荐配置：
- 最低配置：1 核 CPU，1GB 内存（适用于小型音乐库）。
- 推荐配置：2+ 核 CPU，2GB+ 内存（适用于中大型音乐库或频繁刮削的场景）。
- 存储空间：足够的磁盘空间用于存放 Docker 镜像、应用数据以及您的音乐文件。
2.2. 软件要求
- 操作系统：任何支持 Docker 的 64 位操作系统，如 Ubuntu、CentOS、Debian、Windows 10/11 Pro、macOS。
- Docker Engine：必须安装并正在运行。如果您尚未安装，请参考官方文档：安装 Docker Engine。
- Docker Compose（推荐）：强烈建议安装 Docker Compose，它能极大地简化多容器应用的定义和管理。安装 Docker Compose。
3. 部署步骤
本章节将引导您完成 Music Tag Web 的完整部署过程。我们提供两种主流的部署方式：使用 docker run 命令或使用 docker-compose。
3.1. 拉取 Docker 镜像
首先，我们需要从 Docker Hub 上拉取最新的 Music Tag Web 官方镜像。打开您的终端或 SSH 客户端，执行以下命令：
docker pull xhongc/music_tag_web:latest
该命令会下载最新版本的镜像到您的本地系统中。
3.2. 准备目录结构
为了确保应用数据（如配置、数据库）和您的音乐文件在容器重建后依然存在，我们需要将容器内的关键路径挂载到宿主机上。请先在您的服务器上创建好用于挂载的目录。
重要提示：请将下面的 /path/to/your/config 和 /path/to/your/music 替换为您服务器上的实际路径。例如，您可以设置为 /srv/docker/music-tag/config 和 /srv/music。
# 创建配置文件夹
mkdir -p /path/to/your/config
# 创建音乐文件夹 (如果尚不存在)
mkdir -p /path/to/your/music
请确保将您的音乐文件存放在您指定的音乐文件夹中。
3.3. 选择部署方式
您可以根据个人偏好选择以下任一方式进行部署。
方式 A: 使用 docker run 命令
这是一种快速启动单个容器的直接方式。复制并执行以下命令，记得替换路径占位符。
docker run -d \\
–name=music-tag-web \\
-p 8002:8002 \\
-v /path/to/your/music:/app/media:rw \\
-v /path/to/your/config:/app/data \\
–restart=unless-stopped \\
xhongc/music_tag_web:latest
| -d | 在后台（detached mode）运行容器。 |
| –name=music-tag-web | 为容器指定一个易于识别的名称。 |
| -p 8002:8002 | 将宿主机的 8002 端口映射到容器的 8002 端口。格式为 <宿主机端口>:<容器端口>。 |
| -v /path/to/your/music:/app/media:rw | 将您的音乐文件夹挂载到容器内的 /app/media 目录，并赋予读写（rw）权限。 |
| -v /path/to/your/config:/app/data | 将配置文件夹挂载到容器内的 /app/data 目录，用于持久化存储应用数据。 |
| –restart=unless-stopped | 设置重启策略。容器将在退出时自动重启，除非被手动停止。 |
方式 B: 使用 docker-compose (推荐)
Docker Compose 是管理复杂应用的首选方案。它通过一个 YAML 文件来定义所有服务、网络和卷，使部署和维护更加清晰、可复现。
创建一个名为 docker-compose.yml 的文件：
touch docker-compose.yml
使用文本编辑器（如 nano 或 vim）打开该文件，并粘贴以下内容。同样，请务必替换路径部分。
version: '3.7'
services:
music-tag:
image: xhongc/music_tag_web:latest
container_name: music–tag–web
ports:
– "8002:8002"
volumes:
– /path/to/your/music:/app/media:rw
– /path/to/your/config:/app/data
restart: unless–stopped
在包含 docker-compose.yml 文件的目录中，执行以下命令启动服务：
docker-compose up -d
4. 配置与访问
部署成功后，您可以通过浏览器访问和配置 Music Tag Web。
4.1. 访问 Web UI
在浏览器地址栏输入 http://<您的服务器IP>:8002，即可打开 Music Tag Web 的主界面。
4.2. 初始设置
首次使用时，建议访问后台管理页面进行必要的安全设置。
- 用户名: admin
- 密码: admin
5. 高级配置与管理
5.1. 管理文件权限 (PUID/PGID)
在 Linux 系统上，为了避免容器内应用因权限问题无法读写挂载的音乐文件，推荐使用 PUID 和 PGID 环境变量来指定运行应用的用户和组。
首先，获取您当前用户的 UID 和 GID。在终端中执行：
id $(whoami)
您会看到类似 uid=1000(user) gid=1000(user) 的输出。
修改您的 docker-compose.yml 文件，添加 environment 部分：
version: '3.7'
services:
music-tag:
image: xhongc/music_tag_web:latest
container_name: music–tag–web
environment:
– PUID=1000 # 替换为您的 UID
– PGID=1000 # 替换为您的 GID
– TZ=Asia/Shanghai # 可选：设置时区
ports:
– "8002:8002"
volumes:
– /path/to/your/music:/app/media:rw
– /path/to/your/config:/app/data
restart: unless–stopped
注意：虽然 xhongc/music_tag_web 镜像目前可能未直接内置 PUID/PGID 支持，但这是 Docker 社区处理权限问题的最佳实践。您可以关注其官方更新或使用支持此功能的其他基础镜像进行自定义构建。
保存文件后，重新创建容器以应用更改：
docker-compose down
docker-compose up -d
5.2. 更新容器
保持软件最新是获取新功能和安全修复的关键。更新 Music Tag Web 非常简单：
拉取最新的 Docker 镜像：
docker pull xhongc/music_tag_web:latest
如果您使用 Docker Compose，只需在 docker-compose.yml 文件所在目录执行：
docker-compose down
docker-compose up -d
Compose 会自动使用新镜像重新创建容器，由于数据已通过卷挂载，您的所有配置和音乐库信息都会保留。
如果您使用 docker run，则需要手动停止并移除旧容器，然后使用相同的 docker run 命令启动新容器：
# 停止旧容器
docker stop music-tag-web
# 移除旧容器
docker rm music-tag-web
# 使用之前的 `docker run` 命令重新创建容器
docker run -d \\
–name=music-tag-web \\
-p 8002:8002 \\
-v /path/to/your/music:/app/media:rw \\
-v /path/to/your/config:/app/data \\
–restart=unless-stopped \\
xhongc/music_tag_web:latest
6. 总结
通过本指南，您已经成功地使用 Docker 部署了 Music Tag Web。您不仅学会了基本的部署流程，还了解了数据持久化、权限管理和容器更新等关键维护操作。现在，您可以开始享受通过 Web 界面高效管理和丰富您的音乐收藏所带来的便利了。
Docker 化的部署方式为您提供了一个稳定、可移植且易于管理的应用环境。建议定期关注 Music Tag Web 的 Docker Hub 页面和其 GitHub 仓库，以获取最新的版本信息和功能更新。
© 2025 AI Expert. 本文档基于公开信息生成，仅供参考。
参考资料
[1] xhongc/music-tag-web: 音乐标签编辑器 – https://github.com/xhongc/music-tag-web [2] xhongc/music_tag_web – Docker Image – https://hub.docker.com/r/xhongc/music_tag_web
