beets Web界面镜像文档

镜像概述

概述

本镜像是一个预设配置的Web界面解决方案，基于开源音乐管理工具beets构建。beets是一款专注于音乐元数据整理和库组织的命令行工具，本镜像通过集成Web界面，将beets的强大功能以图形化方式呈现，降低使用门槛，方便用户直观管理音乐库。

主要用途

• 音乐库元数据自动化整理（艺术家、专辑、曲目信息补全）
• 音乐文件标准化命名与目录结构组织
• 专辑封面、歌词自动下载与关联
• 音乐库内容Web端浏览、搜索与筛选
• 重复音乐文件检测与清理

核心功能和特性

• 直观Web界面：替代beets原生命令行交互，提供图形化操作面板，支持点选式配置与管理
• beets核心功能集成：完整支持beets核心能力，包括：
  • 元数据自动补全（对接MusicBrainz、Discogs等数据库）
  • 音频指纹识别（通过chromaprint匹配正确元数据）
  • 自定义文件命名规则（按艺术家/专辑/曲目结构自动重命名）
  • 重复文件检测与标记
• 预设优化配置：内置经过优化的beets配置模板，减少手动配置工作量，开箱即用
• 响应式设计：适配桌面与移动设备，支持多终端访问管理
• 数据持久化：支持外部挂载音乐库和配置文件，确保数据不丢失

使用场景和适用范围

适用场景

• 个人音乐库管理：整理本地下载或收藏的音乐文件，解决元数据混乱、文件命名不统一问题
• 家庭媒体中心：作为家庭NAS或媒体服务器的音乐管理组件，提供Web访问接口
• 音乐爱好者工具：帮助音乐收藏家维护高质量、规范化的音乐库，支持无损音乐库管理
• 非命令行用户适配：为不熟悉命令行操作的用户提供图形化替代方案

适用人群

• 个人音乐收藏者（本地音乐文件管理者）
• 家庭媒体中心维护者
• 需要规范化音乐文件结构的内容创作者

使用方法和配置说明

基本部署（Docker Run）

通过以下命令快速启动镜像：

docker run -d \
  --name beets-webui \
  -p 8000:8000 \  # Web界面访问端口（容器内默认8000）
  -v /path/to/your/music:/music \  # 挂载本地音乐库目录（必填）
  -v /path/to/your/config:/config \  # 挂载配置目录（存储beets配置和Web设置，可选）
  --restart unless-stopped \
  [镜像名称]:latest

参数说明：

• /path/to/your/music：替换为本地音乐库实际路径（如/home/user/Music或/mnt/nas/music）
• /path/to/your/config：替换为本地配置目录路径（如/home/user/beets-config），首次启动会自动生成默认配置文件
• 若不挂载配置目录，将使用镜像内置默认配置，重启后配置不会保留

Docker Compose配置

创建docker-compose.yml文件实现持久化部署：

version: '3'
services:
  beets-webui:
    image: [镜像名称]:latest
    container_name: beets-webui
    ports:
      - "8000:8000"
    volumes:
      - /path/to/your/music:/music:rw  # 音乐库目录（读写权限）
      - /path/to/your/config:/config:rw  # 配置目录（读写权限）
    environment:
      - TZ=Asia/Shanghai  # 设置时区（可选，默认UTC）
      - BEETS_CONFIG_PATH=/config/custom_config.yaml  # 自定义配置文件路径（可选）
    restart: unless-stopped

启动服务：

docker-compose up -d

访问Web界面

服务启动后，通过浏览器访问 http://<主机IP>:8000 即可进入Web管理界面。首次访问将引导完成基础配置（如确认音乐库路径、选择元数据来源等）。

配置参数说明

环境变量

配置文件自定义

beets核心配置通过 /config/config.yaml 文件修改（需挂载配置目录），关键配置项示例：

directory: /music  # 音乐库路径（与MUSIC_LIBRARY一致）
plugins: fetchart lyrics lastgenre replaygain  # 启用插件（封面下载、歌词、流派、音量平衡）
paths:
  default: $albumartist/$album/$track $title  # 文件命名规则
import:
  copy: no  # 导入时是否复制文件（设为yes则保留源文件，no则移动文件）
  write: yes  # 是否将元数据写入音频文件

完整配置项参考beets官方文档

注意事项

• 权限设置：挂载的音乐库和配置目录需确保容器有读写权限（可通过chmod调整宿主机目录权限，或添加user: root参数临时解决权限问题）
• 首次导入性能：大型音乐库（1000+文件）首次导入可能耗时较长，取决于网络状况（元数据补全需联网）
• 配置备份：定期备份/config目录，避免容器重建导致配置丢失
• 网络要求：元数据补全、封面下载等功能需联网访问MusicBrainz、Discogs等服务