QM-Music私有云音乐服务器一键部署指南：兼容Subsonic的轻量级解决方案

April 4, 2026

本期内容将详细介绍如何搭建属于个人的音乐服务器——QM-Music。

当前，NAS设备原生的音乐服务应用，往往难以满足用户对功能与体验的深度需求。作者本人长期使用Navidrome，近期在技术社区中发现了一个新兴项目。经过实际部署和体验，其表现令人满意，因此特此分享具体的部署方法，旨在为各位音乐爱好者提供一种新的选择。下图展示的是该项目的官方界面。

QM-Music项目概览

项目的完整名称是 chenqimiao/qm-music，可以在 GitHub 平台进行搜索。

此外，还有一个与之配套的播放器项目 gitbobobo/StreamMusic，即大家可能早已熟知的“音流”播放器，它覆盖了多个终端平台。

QM-Music 是一个基于 Subsonic 协议构建的轻量级私有云音乐服务器，专门为音乐爱好者设计，提供了一个高性能的解决方案。它支持通过 Docker 进行一键式快速部署，并且能够完美兼容 Subsonic 生态下的各类客户端（例如音流、Amperfy、substreamer、feishin、music-assistant 等），从而让用户可以随时随地安全地访问其个人音乐收藏库。

🚨 免责声明：本项目仅限于个人学习与研究目的使用，不可用于任何商业性质的活动中。用户在使用过程中，必须严格遵守其所在地的法律法规。对于因违反法律法规使用本项目而产生的任何后果，本项目及其作者均不承担任何责任。本项目可能存在尚未被发现的缺陷与潜在风险（包括但不限于设备损坏、账号封禁等），使用者需自行承担由此引发的所有风险与责任。作者不对本项目的准确性、完整性、时效性及可靠性作出任何保证，也不对因使用本项目而造成的任何损失或损害负责。一旦开始使用本项目，即表示您已阅读、理解并完全接受本免责声明的所有条款。

主要功能与特色

🐳 Docker 容器化部署 - 实现快速启动，无需复杂的环境配置。

🌱 轻量级资源占用 - 运行仅需约 150MB 内存，对系统资源消耗极低。

🎧 Subsonic 协议兼容 - 支持所有遵循 Subsonic API 的客户端进行连接与使用。

⚡ 高性能媒体服务 - 提供低延迟的流媒体传输体验。

🔄 智能音频转码 - 可按需开启 libmp3lame/acc 转码功能，有效节省网络流量。

📁 广泛格式支持 - 全面兼容 MP3, FLAC, AAC, WAV 等多种主流音频格式。

🔒 完全私有化部署 - 用户对自己的音乐数据拥有完全的控制权。

🇨🇳 中文曲库优化 - 支持繁体与简体中文互搜，并对中文内容的排序与检索进行了专门优化。

根据项目规划，未来的开发路线将包括支持外置数据库、开发跨平台客户端、增强网页播放器功能以及提升单元测试覆盖率等方向。

部署前的必要准备

实际上，此部分主要涉及两个可选的 API 密钥配置，如果您不打算使用相关增强功能，可以完全跳过此步骤。

✅ Spotify (声破天) API 密钥

获取此密钥可以增强音乐元数据（如专辑封面、艺人信息）的获取能力。

✅ Last.fm API 密钥

此密钥同样用于获取更丰富的音乐元数据与收听记录统计。

详细部署步骤

本文将以威联通 (QNAP) NAS 为例，演示通过 Docker Compose 方式部署 QM-Music 的全过程。

请使用以下 Docker Compose 配置代码：

services:
  qm-music:
    container_name: qm-music
    image: qmmusic/qm-music:latest
    ports:
      - "6688:6688"
    volumes:
      - /share/media/music:/data/qm-music/music_dir  # 映射本地音乐目录
      - /share/Container/qmmusic/db:/data/qm-music/db  # 映射数据库与元数据目录
      - /share/Container/qmmusic/cache:/data/qm-music/cache  # 映射缓存文件目录
    environment:
      - QM_FFMPEG_ENABLE=true  # 启用智能音频转码（推荐移动网络用户开启）
      - TZ=Asia/Shanghai  # 请根据您所在时区进行设置
      # 非必须环境变量
      - QM_REFRESH_AUTO=true  # 开启定时刷新曲库，默认每两小时一次
      - QM_CLEAN_PLAY_HISTORY_AUTO=true  # 开启定时清理播放记录
      - QM_SAVE_PLAY_HISTORY_MONTH=24  # 设置播放记录保留月份数，默认24个月
      # Spotify 配置（非必须）
      - QM_SPOTIFY_ENABLE=true  # 开启以获得更多元数据
      - QM_SPOTIFY_CLIENT_ID=  # 如启用，请在此填写您的Client ID
      - QM_SPOTIFY_CLIENT_SECRET=  # 如启用，请在此填写您的Client Secret
      # Last.fm 配置（非必须）
      - QM_LASTFM_ENABLE=true  # 开启以获得更多元数据
      - QM_LASTFM_API_KEY=  # 如启用，请在此填写您的API Key
    restart: always

打开威联通 NAS 上的 Container Station 应用，创建一个新的应用程序，并将上述代码复制到编辑区域。

服务配置与客户端连接

部署完成后，在浏览器中输入 您的NAS内网IP:6688 即可访问 QM-Music 的 Web 管理界面。

默认的系统管理员账户和密码均为 admin。

首次登录后，系统会提示修改默认密码。修改成功后，需要使用新密码重新登录。

登录进入后台管理界面后，建议首先手动点击“刷新曲库”按钮，以便服务器扫描并导入您映射的音乐文件。

接下来以 iPhone 手机为例，展示如何通过客户端连接。在 App Store 下载“音流”(StreamMusic)应用。如图所示，在添加服务器时，填写正确的服务器地址（内网使用IP，外网使用域名）和端口号（6688）。

由于在部署时配置了 Spotify 和 Last.fm 的 API 密钥，服务器能够联网获取丰富的元数据，最终在客户端呈现的效果如下图所示，专辑封面和歌手信息均显示完整。

总结与项目评价

总体而言，QM-Music 可以看作是 Navidrome 的一个超轻量级替代方案，它在保证核心功能可用的前提下，显著降低了资源占用，实际使用体验良好。