方案简介

Metadata Remote（mdrm）是一套面向无桌面环境的 headless 服务器的音频元数据 Web 编辑方案。它把编辑器打包成 81.6 MB 的 Docker 容器，通过 Gunicorn 提供生产级 Web 服务，浏览器打开即用，直接读写音频文件内嵌标签，无需数据库后端或导入流程。相比 Beets 等重量级库管理器，它"just does one thing well"。适合运行 Jellyfin/Plex 的家庭媒体服务器、NAS（TrueNAS/Unraid/Synology）、无 GUI 的 VPS 音乐库以及树莓派等轻量硬件上的音乐收藏整理与批量元数据清理。

亮点与能力

• 完整字段控制：查看并编辑全部文本元数据字段，分 Standard 与 Extended 两类，可新建/删除自定义字段，支持撤销/重做
• 批量操作：一键将修改应用到单个文件或整个文件夹，专辑封面可上传一次应用到全专辑
• 智能建议：结合文件名、目录结构、同级文件与 MusicBrainz 在线查询推断元数据，按置信度百分比排序，针对古典、合集、现场录音有专门策略
• 文件管理：浏览器内直接播放、重命名文件和文件夹，支持 MP3/FLAC/OGG/OPUS/M4A/M4B/WMA/WAV/WavPack
• 编辑历史：最多 1000 步撤销/重做，重命名文件后历史不失效，批量操作也可撤销
• 键盘优先：所有功能均可纯键盘操作，鼠标可选
• 轻量架构：81.6 MB 容器，Gunicorn 服务器支持反向代理，明暗主题切换，支持 x86_64/ARM64/ARMv7
• 封面自动修复：损坏的专辑封面自动检测并修复

组成与分工

• Docker / Docker Compose：容器化部署入口，一条命令拉起服务，多架构镜像覆盖 x86_64、ARM64、ARMv7
• Gunicorn：容器内生产级 WSGI 服务器，提供 Web 界面并支持反向代理
• Mutagen：优化的音频元数据读写库，直接修改文件内嵌标签，无需数据库
• MusicBrainz：在线元数据数据库，本地推断不足时补充查询
• 浏览器（任意设备）：唯一客户端，提供文件树、编辑、播放与历史面板

前置要求

• 一台无桌面环境的 headless 服务器（x86_64、ARM64 或 ARMv7 均可），包括 NAS、VPS、树莓派
• 已安装 Docker 与 Docker Compose（V1 或 V2）
• 服务器上存有音乐文件目录
• 无需数据库或外部依赖（"No external dependencies"）

实施步骤

1. 下载 docker-compose.yml

bash
wget https://raw.githubusercontent.com/wow-signal-dev/metadata-remote/main/docker-compose.yml

2. 修改音乐目录挂载路径

bash
nano docker-compose.yml # Change /path/to/your/music:/music

compose 文件核心内容：

yaml
version: '3.8'
services:
metadata-remote:
image: ghcr.io/wow-signal-dev/metadata-remote:latest
container_name: metadata-remote
ports:

• "8338:8338"

volumes:

• /your/music/directory:/music

environment:

• PUID=1000
• PGID=1000

restart: unless-stopped

如需多个音乐目录，可追加挂载：

yaml

- /path/to/music1:/music/Library1

- /path/to/music2:/music/Library2

3. 启动服务

bash
docker compose up -d # For Docker Compose V2 (newer installations)

OR

docker-compose up -d # For Docker Compose V1 (legacy installations)

4. 打开 Web 界面

bash
open http://localhost:8338

也可用 docker run 一键启动：

bash
docker run -d \
--name metadata-remote \
-p 8338:8338 \
-v /your/music:/music \
-e PUID=1000 \
-e PGID=1000 \
ghcr.io/wow-signal-dev/metadata-remote:latest

使用与配置要点

基本导航

• ↑↓ 导航文件/文件夹，PgUp/PgDn 翻页，Tab 切换面板
• Enter 展开文件夹 / 播放文件 / 编辑字段，双击 Enter 重命名文件夹
• Esc 取消编辑或关闭对话框，Shift+Delete 删除元数据字段，Alt+T 切换主题，? 显示帮助

编辑流程

1. 导航到任意元数据字段按 Enter 进入编辑
2. 修改后 Enter 保存或 Esc 取消
3. 导航到 "File" 或 "Folder" 按钮，保存到单文件或文件夹全部文件

智能建议

点击空字段时自动分析文件名/目录/同级文件，必要时查询 MusicBrainz，按置信度给出建议，点击即应用。

批量与封面

• "Apply to Folder" 将字段值应用到文件夹全部文件
• 封面可上传、保存、批量应用、删除，损坏封面自动修复

编辑历史

底部面板可展开时间线视图，任意顺序撤销/重做（最多 1000 步），重命名文件后历史仍有效，也可一键清空。

注意事项与常见问题

• 对比 Beets：Beets 需要数据库后端、导入流程和复杂配置，且"Must import to library""No undo"；mdrm 直接编辑文件，Setup time < 1 分钟
• Beets 的智能建议仅限 MusicBrainz，mdrm 为多源推断
• Mp3tag 与 MusicBrainz Picard 不支持 headless 服务器
• 容器需以 PUID/PGID 匹配音乐文件属主权限，否则可能无法写入标签
• 挂载路径固定为容器内 /music，多个音乐库需分别以子目录挂载
• README 环境变量部分在材料中被截断，具体变量请查阅仓库完整文档

优缺点

• ✓ 部署不到一分钟，无数据库依赖
• ✓ 全键盘操作，支持批量与撤销
• ✕ 仅限音频元数据编辑单一用途
• ✕ 依赖 Docker 环境

出处

本方案挖掘自开源项目 wow-signal-dev/metadata-remote，方案内容与实施命令均来自其 README 原文。