QM-Music Docker镜像文档

镜像概述

QM-Music 是一款基于 Subsonic 协议构建的轻量级私有云音乐服务器，专为音乐爱好者设计。它提供高性能的音乐库管理能力，支持 Docker 容器化部署，可无缝兼容 Subsonic 生态系统下的各类客户端（如音流、Amperfy、substreamer、music-assistant 等），帮助用户构建安全、便捷的个人音乐访问服务，实现跨设备随时随地访问私有音乐库。

核心功能与特性

• 轻量级架构：优化的资源占用，适合个人服务器或低配置设备部署
• 高性能处理：高效的音乐文件索引与流式传输能力，支持多种音频格式
• Subsonic 协议兼容：完全兼容 Subsonic API，可对接主流 Subsonic 客户端
• Docker 一键部署：简化部署流程，无需复杂环境配置，快速启动服务
• 安全访问控制：支持用户认证机制，确保个人音乐库仅授权访问
• 跨设备访问：通过客户端实现手机、平板、电脑等多设备音乐同步播放

使用场景与适用范围

• 个人音乐库管理：集中存储与管理本地音乐文件，替代第三方音乐平台依赖
• 多设备同步播放：通过兼容客户端在手机、PC、智能音箱等设备上播放个人音乐
• 私有云音乐服务：搭建家庭或个人私有音乐云，保护音乐收藏隐私
• 轻量级服务器部署：适用于 NAS、树莓派、个人云服务器等低功耗设备

部署与使用指南

前提条件

• 已安装 Docker 及 Docker Compose（可选）
• 本地音乐文件目录（建议提前整理，支持常见音频格式如 MP3、FLAC、AAC 等）

快速启动（Docker Run）

通过以下命令快速启动 QM-Music 服务：

docker run -d \
  --name qm-music \
  -p 8080:8080 \  # 端口映射（主机端口:容器端口）
  -v /path/to/your/music:/music \  # 挂载本地音乐目录到容器
  -e MUSIC_DIR=/music \  # 指定容器内音乐文件目录（需与挂载路径一致）
  -e PORT=8080 \  # 服务监听端口
  --restart unless-stopped \
  qmmusic/qm-music

参数说明：

• -p 8080:8080：将容器内 8080 端口映射到主机 8080 端口，可根据需求修改主机端口（如 -p 9000:8080）
• -v /path/to/your/music:/music：将本地音乐目录（如 /home/user/Music）挂载到容器内 /music 目录，确保容器可访问音乐文件
• --restart unless-stopped：容器退出时自动重启（除非手动停止）

Docker Compose 配置

创建 docker-compose.yml 文件，配置如下：

version: '3'
services:
  qm-music:
    image: qmmusic/qm-music
    container_name: qm-music
    ports:
      - "8080:8080"  # 端口映射
    volumes:
      - /path/to/your/music:/music  # 本地音乐目录挂载
      - qm-music-data:/app/data  # 持久化应用数据（配置、索引等）
    environment:
      - MUSIC_DIR=/music  # 音乐文件目录
      - PORT=8080  # 服务端口
      # 如需自定义管理员账号密码，可添加：
      # - ADMIN_USER=admin  # 管理员用户名（默认：admin）
      # - ADMIN_PASSWORD=password  # 管理员密码（默认：password，建议修改）
    restart: unless-stopped

volumes:
  qm-music-data:  # 自动创建数据卷，持久化应用配置

启动服务：

docker-compose up -d

配置参数说明

访问与使用

1. 服务访问：启动后，通过浏览器访问 http://<主机IP>:<映射端口>（如 [***]）
2. 登录：使用配置的管理员用户名/密码（默认 admin/password）登录后台
3. 客户端连接：在 Subsonic 兼容客户端（如音流、Amperfy）中，配置服务器地址为 http://<主机IP>:<端口>，输入用户名/密码即可访问音乐库

注意事项

• 音乐文件权限：确保挂载的本地音乐目录对 Docker 容器有读取权限（建议设置目录权限为 755）
• 数据持久化：通过 qm-music-data 数据卷（或挂载本地目录到 /app/data）持久化应用配置与音乐索引，避免容器重建后数据丢失
• 端口冲突：若主机 8080 端口已被占用，需修改 -p 参数中的主机端口（如 -p 8888:8080）
• 性能优化：对于大型音乐库（10k+ 文件），首次启动时索引可能需要几分钟，建议耐心等待

相关链接

• GitHub 仓库
• ***使用说明
• Docker Hub 镜像