歌单散在三个平台,听歌先要做一道选择题
手机里装着三个音乐 App:通勤歌单在网易云,华语老歌收藏在 QQ 音乐,Apple Music 里还躺着一张订阅后慢慢攒起来的专辑列表。想听歌,第一步不是选歌,而是选 App——打开错了就得退出重开,队列更是各管各的,在这个平台排好的顺序,切到另一个平台全部作废。歌单想同步?只能手动一张一张对照着搬。
MHub 的解法是把入口再收拢一层:它是一个自托管的多平台音乐播放器,把 Apple Music、网易云、QQ 音乐等平台的搜索、歌单与推荐聚合进同一个队列,在浏览器里直接播放,界面布局与交互按 Apple Music 网页版复刻,熟悉苹果生态的人几乎零学习成本。用自己的平台账号登录,听的还是自己歌单里的歌、自己订阅权益内的曲库,只是入口从三个变成了一个。
自建 MHub 的核心价值就一句话:账号和歌单还是各平台自己的,但搜索、队列与播放入口只剩一个。
本篇主线:认识 MHub 的功能全景 → 看懂架构与一首歌的数据流 → Docker 部署全流程 → 配置要点 → 反向代理与公网安全 → 日常维护 → 排障收尾。
功能全景:聚合、同步、无损、离线
MHub 是 2026 年 10 月才开源的新项目(AGPL-3.0,Rust 后端+Vue 3 前端),功能密度却不低:
- 多平台聚合:一个搜索框同时查多个平台;歌单可从各平台导入,导入时自动做跨平台匹配,把原歌单里的歌对到其他平台的曲库上;同平台导入的歌单每天自动跟随原歌单同步,原歌单加了新歌,这边自动跟上。
- 队列玩法完整:追加、替换、下一首播放、拖动排序、随机、循环一应俱全;队列播完后自动续播走 Apple Music 的 AutoPlay 电台,不可用时退回同歌手与相似歌手的歌曲接上,不会冷场。
- 无损播放:ALAC 格式在浏览器里用 WASM 解码,按采样帧精确排程到 Web Audio 输出;其余格式走原生 audio 元素。后台播放靠双 audio 元素预载接力加 Media Session 接口,锁屏、切后台都不中断,锁屏界面还能控制切歌。
- 歌词与氛围:逐字歌词、封面取色生成的流动背景、简繁转换,歌词引擎是 AMLL、简繁转换用 OpenCC。
- 离线与 PWA:音频与歌词缓存进浏览器的 IndexedDB,可安装为 PWA,缓存过的歌断网也能听。
- 可选账号体系:支持通行密钥(Passkey)登录;个人资料库用 Yjs 文档经 WebSocket 在多台设备间实时同步,断网时本地编辑、联网后自动合并;还有「接着听」,换设备从上次的位置继续。
- 可选音源网关:同机部署的其他服务(比如 Telegram 机器人)可以经回环接口共用 MHub 同一份平台账号与缓存,一首歌只下载一次,多处受益。
实际用起来,歌单导入的流程是这样的:在 MHub 里粘贴原平台的歌单链接,它先按原平台曲库把歌单原样收进来,再做一轮跨平台匹配——同一首歌在其他平台也有的话,条目上会多出可切换的来源,某个平台的版本不可用时直接换源播,不用重新搜。导入完成后,同平台那份歌单进入每日自动同步名单,原歌单的增删会跟随过来;跨平台匹配出的条目则固定在导入那一刻,算作一份跨源快照。
要先说清楚一条边界:仓库不提供任何账号、会话或媒体文件,所有平台账号都要自备;Apple Music 的播放还需要自备账号并自建 wrapper / wrapper-lite 解密服务。最终能播什么,取决于你自己的平台账号、所在地区与上游接口状态。
架构:一首歌从点击到出声经历了什么
MHub 的技术栈先摆出来,后面讲数据流时好对位:
| 层 | 技术 | 负责什么 |
|---|---|---|
| 后端 | Rust(Axum + Tokio) | 平台接口聚合、播放任务调度、解密与缓存管理 |
| 索引 | sqlx + MySQL(可选) | music_cache 表:缓存文件与 Telegram file_id 的索引 |
| 同步 | yrs(Yjs 的 Rust 实现)+ WebSocket | 资料库文档多设备实时同步与离线合并 |
| 登录 | webauthn-rs | Passkey 通行密钥认证 |
| 前端 | Vue 3 + Pinia + Vite | 播放器界面、队列状态、PWA 与离线缓存 |
| 播放 | WASM 解码 + Web Audio | ALAC 在浏览器内解码并按采样帧排程输出 |
理解它最好的方式,是跟一遍点播一首歌的完整链路:
- 建任务:你点击播放,前端按「平台+歌曲 ID+音质」向后端创建一个播放任务;同一首歌被重复点播时任务去重,不会重复下载。
- 选源:后端根据任务去对应平台取源,拿到音频流。
- 边下边解边播:音频边下载边解密边送往浏览器,首个分片解密完成即可开播,不用等整首下完;ALAC 在浏览器端由 WASM 解码并精确排程,起播延迟压得很低。
- 落盘缓存:完整文件同时写入本地缓存;如果配了 Telegram 文件仓库,后台会把文件上传给 Bot,Bot API 返回的 file_id 连同元信息记入 MySQL 的 music_cache 表做索引。
- 命中直达:下次再播同一首歌,查索引命中缓存后直接转发文件,不再走解密流程,出声更快,也少打扰上游。
这套「任务+缓存+索引」的设计,决定了 MHub 的两个性格:一是越听越快,常听的歌第二次起基本是本地速度;二是同机其他服务能通过音源网关蹭这份缓存,家里只存一份文件。音源网关的逻辑是:MHub 对外(仅限本机回环)留了一个取源接口,同机的 Telegram 机器人之类的服务要播或要发某首歌时,先问 MHub 要——命中缓存直接拿文件,没命中就由 MHub 按任务流程取源、落盘后再交付。平台账号只在 MHub 里配一份,解密流程只跑一遍,多个服务共用成果,这是它和「每个工具各配一遍账号」的玩法最不一样的地方。和本系列之前写的 Jellyfin 对比一句就能定位:Jellyfin 管的是你硬盘里已有的本地文件库,MHub 聚合的是各平台账号里的在线曲库,两者互补而不互替。
Docker 部署:首次构建要有耐心
官方推荐 Docker Compose 部署。注意第一次启动要现场编译 Rust 后端、ALAC 的 WASM 解码器与前端,耗时取决于机器性能,老机器等上十几分钟也正常,之后升级就快了。
git clone https://github.com/jizizr/mhub.gitcd mhubcp config.example.toml config.tomlcp .env.example .envdocker compose up -d --build起来后访问 http://localhost:8000,先做两个验证:
curl --fail http://localhost:8000/healthdocker compose logs --tail=100 music健康检查返回成功、日志没有报错,就可以打开页面开始配账号了。部署上有几个刻意的设计值得知道:配置文件以只读方式挂载进容器,改配置必须在宿主机上改完再重启容器;缓存放在命名卷 music-data 里;容器以非 root 用户运行、根文件系统只读,安全基线比一般的自建小服务要讲究。
首次上手的顺序建议这样走:先在配置里填好一个平台的账号并重启服务,确认搜索与播放都通;再导入一张自己常用的歌单,检查跨平台匹配的结果对不对;最后才逐个补齐其他平台与可选组件(MySQL、Telegram 仓库、Passkey 同步)。一次全配满再排障,出了问题很难定位是哪一环。
配置要点:账号与解密服务都要自备
config.toml 是主配置,.env 放环境变量类的敏感项,两个示例文件里的注释就是最好的说明书,这里只点关键处:
- 平台账号:逐个填入你自己的 Apple Music、网易云、QQ 音乐等账号凭据,用哪个平台配哪个,没配的平台不出现在搜索与歌单里。
- wrapper 解密服务:Apple Music 的音频需要解密,自建 wrapper 或 wrapper-lite 后把地址填进配置;没有这一步,Apple Music 只能浏览不能播放。
- MySQL(可选):启用后 music_cache 索引落在 MySQL 里,配合 Telegram 文件仓库使用;不用 TG 仓库的话,本地缓存索引就够了。
- Telegram 文件仓库(可选):填 Bot Token 与目标会话,缓存文件会后台上传,file_id 入库索引;这一步相当于把 Telegram 当成自家的对象存储,服务器磁盘紧张时很实用。
- 账号体系(可选):想要多设备同步就开启 Passkey 登录与 Yjs 同步;纯单人单机使用可以不开,本地模式足够。
- 监听地址:确认服务的端口映射只绑回环地址,这是后面公网安全一节的前提。Compose 里对应的写法是把端口写成带 IP 的形式:
ports: - "127.0.0.1:8000:8000"这样即使服务器有公网 IP,8000 端口也只对本机开放,外网访问只能走反向代理这一条受控通道。
再强调一次口径:AGPL-3.0 只覆盖 MHub 的代码本身,不授予任何音乐内容的权利;用自己的账号、在平台服务条款允许的范围内使用,是这个项目正确的打开方式。
反向代理与公网安全:这一节别跳过
WARNINGMHub 的音乐 API 本身没有用户鉴权,服务默认只绑回环地址是有意为之。需要从外网访问时,必须套一层带访问控制的 HTTPS 反向代理(如 Basic Auth、IP 白名单或与本系列 NPM 方案结合的访问控制),绝不能把配了自己平台账号的实例匿名暴露到公网——那等于把你的账号会话借给全互联网。另外注意:反向代理不要对音频流开启缓冲(proxy buffering),否则边下边播会被攒成整段下载,起播明显变慢。
用本系列写过的 Nginx Proxy Manager 做反代时,关键配置思路如下(自带 NPM 的高级配置里追加):
# 关闭代理缓冲,保证音频流式传输proxy_buffering off;# WebSocket 支持:跨设备同步与实时状态要用proxy_http_version 1.1;proxy_set_header Upgrade $http_upgrade;proxy_set_header Connection "upgrade";再在 NPM 里给这个站点开启访问控制列表,只放行自己的 IP 或加一道 Basic Auth,并申请好 HTTPS 证书。家里宽带没有公网 IP 的,用内网穿透或组网工具访问也完全可以,原则不变:任何路径下都要有鉴权。
日常维护:升级、备份与观察
- 升级:拉新代码后重新构建即可,
git pull && docker compose up -d --build;构建产物更新时前端与 WASM 会一并重编。 - 备份:真正要保的是两样——
config.toml与.env两个配置文件,以及命名卷 music-data(缓存与本地索引)。日常docker compose down不会动命名卷,但 docker compose down -v 会连卷一起删,缓存清零,手滑之前想清楚。系统化的备份思路可参考 备份与迁移 一篇。 - 观察:
/health端点适合接进 Uptime Kuma 之类的监控做存活探测;出问题先看docker compose logs --tail=100 music,绝大多数故障(账号失效、上游接口变化、解密服务不通)都会在日志里留下线索。 - 缓存管理:常听的歌都会落盘,music-data 卷会随使用慢慢变大;磁盘紧张时优先把 Telegram 文件仓库打开,让完整文件多一份在 TG 侧,本地卷的压力会小很多。定期看一眼卷的占用,把很久没播的缓存清掉即可,不必追求全量留存——缓存的意义是加速二播,不是收藏。
- 与下载工具分工:想把歌真正下成文件归档,用 go-music-dl 那类工具;MHub 的定位是在线聚合播放,缓存是为加速而非为归档。
和同类方案摆在一起看
| 维度 | MHub | Jellyfin | 各平台官方客户端 |
|---|---|---|---|
| 内容来源 | 自己各平台账号的在线曲库 | 自己硬盘里的本地文件 | 自家平台曲库 |
| 歌单 | 多平台导入、跨平台匹配、同平台每日同步 | 本地文件自建歌单 | 只管自家歌单 |
| 播放入口 | 一个浏览器页面、一个队列 | 一个客户端、一个本地库 | 几个 App 之间来回切 |
| 无损 | ALAC 浏览器 WASM 解码,取决于账号权益 | 取决于本地文件本身 | 取决于会员与平台策略 |
| 离线 | IndexedDB 缓存+PWA | 本地文件天然离线 | 各平台各自的下载缓存 |
| 部署成本 | 自备服务器+自备账号与解密服务 | 自备服务器+自备文件 | 零部署 |
表里最要紧的一行是第一行:MHub 不生产内容,它是你已有账号权益的一个聚合前台;文件不在你手里、想长期归档的,还是走本地库那条线。
常见问题排障
| 现象 | 排查方向 |
|---|---|
| 首次启动迟迟打不开 | 大概率还在编译,docker compose logs 看构建进度,老机器耐心等 |
| 某平台搜不到结果 | 该平台账号没配或已失效;也可能受账号地区与上游接口状态影响,重新登录账号再试 |
| Apple Music 能浏览不能播 | wrapper / wrapper-lite 解密服务没配或地址不对,先单独验证解密服务可用 |
| 起播很慢、像在整首下载 | 反向代理开了缓冲,关掉 proxy buffering;或缓存未命中且上游较慢,二播应明显变快 |
| 锁屏后播放中断 | 检查浏览器是否允许后台播放与 Media Session;双 audio 预载接力需要浏览器不冻结页面媒体 |
| 同步不生效 | 账号体系未开启或 WebSocket 被反代拦了,确认反代放行了 Upgrade 头 |
| 歌单不自动更新 | 只有同平台导入的歌单才每日跟随原歌单同步;跨平台匹配出来的歌单是静态快照 |
| 清理空间想删缓存 | 删 music-data 卷或在设置里清缓存即可,别用 down -v 误伤配置外的其他卷 |
小结
MHub 把「多平台账号、多份歌单」这个现代听歌的碎片化问题,用一个自托管聚合层解掉了:搜索、队列、歌词、同步、离线一站齐活,无损边下边播,缓存还能给同机其他服务复用。它的门槛也写在明处:账号与解密服务自备、首次构建慢、API 无鉴权决定了反代必须做对。把这三件事处理好,它就是家里服务器上很值得常驻的一个服务。
适合部署的人很明确:手里有两个以上平台的账号、歌单分散、又愿意在自己服务器上维护一套账号配置的人。如果你只用一个平台,官方客户端就是最优解,没必要多养一个服务;跨平台听歌越频繁,MHub 省下的切换成本就越值,也越能体会「所有歌只排一个队列」的好处。
选型一句话:本地文件库用 Jellyfin,在线多平台聚合用 MHub,先把鉴权与反代做对,再谈公网访问。