Meelo v3.13.1 介绍与选型指南

目标：评估自托管音乐服务器 Meelo 的定位、架构与核心能力，并与 Navidrome、koel、Funkwhale 做量化对比，帮助"想把本地音乐库搬上自己的服务器"的读者完成选型。本文所有结论均基于 v3.13.1 在 Ubuntu 24.04 实测环境部署验证（部署全过程见 《Meelo v3.13.1 Docker Compose 部署指南》）。

一、环境信息

本文结论来自以下实测环境，选型对比中的第三方数据均标注实查日期：

• 操作系统：Ubuntu 24.04.5 LTS（内核 7.0.0-38-generic，x86_64，6 核 CPU / 15 GiB 内存）
• 部署形态：官方 Docker Compose 全栈，共 9 个服务（server / scanner / matcher / front / db / meilisearch / transcoder / mq / nginx）
• Meelo 版本：v3.13.1（经 /api/settings 实测回显 "version":"v3.13.1" 确认）
• 依赖组件版本（官方 compose 固定）：PostgreSQL（postgres:alpine3.14）、Meilisearch v1.5、RabbitMQ 4.3-alpine、Kyoo Transcoder 5.2.1、Nginx 1.31.3-alpine
• 版本情报查询日期：2026-10-29（GitHub Releases Atom 源与 GitHub API 实查）

二、软件概述

Meelo 是一个面向"音乐收藏者"的开源自托管音乐服务器（Self-Hosted Music Server），由 Arthi-chaud 个人主导开发，2022 年 5 月开源，采用 GPL-3.0 许可证，主语言为 TypeScript。官方 README 对它的定位是："与 Plex、Jellyfin、Koel、Black Candy 类似，但专注于灵活性、浏览与收听体验，专为音乐收藏者设计"。

它要解决的核心痛点是：当你有上万首本地音乐文件（专辑多版本、B 面曲、合辑、现场版、混音版、MV）时，通用播放器会把这些"重复内容"平铺成一片混乱，而 Meelo 通过借鉴 MusicBrainz 的元数据模型（专辑有 Release 多版本、歌曲有 Track 与 Version 概念）把曲库组织成"数据库式"的可浏览结构。

💡 技术拓展：自托管音乐服务器并非只有一种产品形态，选型前应认清三类——

类型	代表产品	特点	适用人群
轻量曲库流播	Navidrome、mStream	单二进制/低资源，通过 Subsonic API 对接手机 App	曲库结构简单、追求省资源
个人曲库 Web 应用	koel、Black Candy	Web 风格播放器，功能聚焦听歌本身	个人使用、界面优先
元数据深度整理	Meelo、Funkwhale、LMS	多版本专辑、B 面、合辑、外部元数据源	音乐收藏者、曲库杂乱者

本文实测对象为第三类中的 Meelo：它的差异化卖点不是"轻"，而是"把收藏家的曲库整理清楚"。

版本节奏方面（GitHub Releases Atom 实查，2026-10-29）：最新稳定版 v3.13.1 发布于 2026-09-30，此前 v3.13.0（2026-09-30）、v3.12.0（2026-09-16）、v3.11.1（2026-08-19）、v3.11.0（2026-07-02），约每 1～2 个月一个功能版本，社区活跃度处于健康状态（仓库最近一次推送为 2026-10-29 当天）。

社区规模实查（GitHub API，2026-10-29）：1445 stars、42 forks、64 个未关闭 issue。相比 Navidrome（24424 stars）、koel（17322 stars），Meelo 是一个体量较小但迭代速度快的项目——它 2022 年才创建，4 年半走完了别人 10 年的功能路。

三、核心架构

Meelo 不是单体应用，而是一套 9 服务的微服务架构（官方 docker-compose.yml 实测，全部服务均已在本环境部署并运行验证）。官方 Wiki 的架构图可归纳为下表：

💡 技术拓展：音频"转码"在自托管音乐服务器中有两种主流策略——

策略	原理	优点	缺点
原始流（direct）	文件字节原样透传（支持 HTTP Range 断点续传）	零 CPU 开销、无损	浏览器不认的格式播不了
转码流（HLS）	服务端 ffmpeg 实时切片转码，浏览器拉 m3u8 分段	任何格式都能播、可控码率	吃 CPU、有首包延迟

Meelo 的策略是"仅必要时转码"：实测直接请求 MP3 走 direct 原始流（HTTP 200，audio/mpeg，下载字节与源文件 MD5 完全一致）；请求 master.m3u8 时由 Kyoo Transcoder 生成 HLS 播放列表（audio/0/original 与 audio/0/128k 两档音质）。这与 Navidrome"可配置默认转码"的策略不同。

数据流（实测路径）：音频文件放入曲库目录 → scanner 扫描解析（ID3 标签或路径正则）→ 注册到 server → server 写 Postgres + 索引 Meilisearch + 发事件到 RabbitMQ → matcher 消费事件去 MusicBrainz 补全元数据 → 用户经 nginx 访问 front，播放时经 server 代理到 transcoder。

这套架构带来的好处是职责清晰、单服务可独立重启（实测 scanner 扫描失败不影响 API 服务）；代价是部署复杂度显著高于单体方案——这也是选型时必须量化的点（见七、）。

四、功能特性

以下特性均在实测环境中验证或经官方文档核实（标注实测的条目有真实命令与回显，完整过程见 B2 部署指南与 《Meelo v3.13.1 API 使用详解》）：

• 多版本专辑（Releases）：同一专辑可存多个发行版本，浏览页只显示主版本（官方特性，数据模型实测确认：专辑对象含 masterId 字段指向主版本）
• B 面与稀有曲：识别 B-Sides/Rare tracks 并在专辑页、艺人页单独展示（官方特性）
• 歌曲版本分组：现场版、混音版、Remaster 归组展示，浏览时不重复刷屏（官方特性）
• MV 是一等公民：区分 MV、访谈、幕后、预告片等视频类型（官方特性）
• 自动 Featuring/对唱检测（官方特性）
• 曲库扫描与文件监听（实测）：扫描任务经消息队列异步执行，实测回显 {"message":"Task added to queue"} HTTP 202；扫描器对新文件有文件系统事件监听（实测新曲落盘后自动补扫并注册成功）
• 元数据双来源（实测 + 官方文档）：settings.json 的 metadata.source 可选 embedded（文件内嵌标签）或 path（路径正则），order 可选 only/preferred 决定是否互补回退
• 外部元数据提供商（实测确认默认启用 MusicBrainz）：GET /api/external-providers 回显 {"count":1,"items":[{"name":"MusicBrainz","slug":"musicbrainz"}]}
• 全文搜索（实测）：GET /api/search?query=neon 直接返回歌曲/专辑/艺人混合结果，底层为 Meilisearch
• 播放统计（实测）：PUT /api/songs/{slug}/played 记录播放，GET /api/songs/history 返回历史
• 多用户与权限（实测）：管理员/普通用户/禁用状态，注册开关 enableUserRegistration 可控
• Scrobble 外发：ListenBrainz 开箱即用，LastFM 填 API Key 即可（官方文档）
• 歌词：嵌入标签、.lrc 文件与外部源下载（官方文档）
• 移动 App：Android（Release 页 APK）与 iOS（TestFlight）官方客户端（官方文档）
• 任意格式支持（实测转码链路）：MP3/FLAC/APE 等均可靠转码播放，transcoder 对纯音频文件实测生成 HLS 音频分段

五、快速开始（最小可用示例）

本节给出从零到"听到第一首歌"的最短路径，验证 Meelo 的核心闭环。完整参数解释、排障实录见 《Meelo v3.13.1 Docker Compose 部署指南》。

1. 准备 4 个官方配置文件（docker-compose.yml、nginx.conf.template、env.example 改名 .env、settings.json），填好 .env 中的端口、目录与密钥；
2. 启动全栈并确认 9 个服务健康（实测回显）：

docker compose up -d        # 启动全栈
docker compose ps           # 期望 9 个服务 Up，server/scanner/mq/meilisearch/db 显示 (healthy)

3. 浏览器访问 http://<服务器IP>:8140，注册首个管理员账号（实测用户名 root、密码 q1w2e3r4），创建曲库；
4. 用 ffmpeg 合成一条测试音频放入曲库目录（无版权风险）：

docker run --rm -v /opt/meelo/data:/out jrottenberg/ffmpeg:5-alpine -y \
  -f lavfi -i "sine=frequency=440:duration=25" \
  -codec:a libmp3lame -b:a 128k \
  -metadata "title=Hello Meelo" -metadata "artist=Aiko Taylor" \
  -metadata "album=Demo (2026)" \
  "out/Aiko Taylor/Demo (2026)/1 - Hello Meelo.mp3"

5. 触发扫描并验证入库（实测回显，scanner 走 JWT 鉴权）：

curl -s -X POST -H "Authorization: Bearer $TOKEN" http://localhost:8140/scanner/scan/1
# {"message":"Task added to queue","version":""}          ← HTTP 202，任务入队
curl -s -H "Authorization: Bearer $TOKEN" http://localhost:8140/scanner/tasks
# {"current_task":"Scan library 'demo-library'","progress":0,"pending_tasks":[]}
curl -s -H "Authorization: Bearer $TOKEN" "http://localhost:8140/api/songs?query=Hello"
# count: 1  - Hello Meelo | aiko-taylor-hello-meelo       ← 注册成功

6. 播放验证：Web 界面点击歌曲即播；接口侧实测原始流返回 200 且字节与源文件一致，HLS 转码流返回标准 m3u8 播放列表。

整个闭环（启动→注册→建库→入库→扫描→播放）在实测环境约 15 分钟可走通，其中镜像拉取占大头。

六、适用场景与限制

适用场景（按实测能力归纳）：

• 音乐收藏者的整理需求：多版本专辑、B 面、合辑、MV 混杂的大曲库，需要 MusicBrainz 级别的元数据模型来组织；
• 多用户家庭/小团队场景：多用户、独立播放历史、注册开关可控；
• 格式杂乱的曲库：APE/FLAC/WAV 混存时靠转码兜底，浏览器兼容性不再是问题；
• 想保留数据主权又要现代 Web/App 体验：GPL-3.0 自托管，官方移动端。

限制（实测与官方文档确认）：

• 部署重：9 个服务、4 个外部依赖（Postgres/Meilisearch/RabbitMQ/Kyoo Transcoder），内存占用与运维复杂度显著高于 Navidrome 单二进制方案；实测健康检查依赖链长，首次启动时 server 曾因镜像内 Corepack 联网拉取 yarn 失败而重启 6 次后自愈（详见 B2 排障实录）；
• 无官方 CLI 管理工具：日常管理与集成只能走 REST API 或 Web 界面（API 完整可用，65 个端点，见 D5 篇）；
• 匹配依赖外网：matcher 需访问 MusicBrainz 等外部源，纯内网环境会缺失歌词/艺人图/外部流派（本地嵌入标签的解析不受影响）；
• 社区体量小：1445 stars，遇到问题的检索资料少于 Navidrome/koel，需要阅读 Wiki 与源码；
• 不支持 Subsonic/Airsonic 协议（实测确认 API 中无该端点）：第三方 Subsonic App 无法直连，只能用官方移动 App 或 Web 界面——这是它与 Navidrome 生态差的最大来源。

七、同类选型对比

7.1 竞品对比表

以下数据均为 2026-10-29 实查（GitHub API / 官方 Releases），功能列基于各项目官方文档与本次实测：

表格解读（如何选型）：三条分界线决定选择——① 曲库是否"复杂"（多版本/合辑/B 面/MV）：是 → Meelo 的模型优势无可替代；② 是否要用第三方手机 App：是 → 只有 Navidrome（Subsonic 生态）；③ 能承受多重的部署：资源紧张选 Navidrome，团队已有 Postgres/Redis 基础设施时 koel 顺路，愿意为元数据整理付出运维成本选 Meelo。

7.2 选型建议（如果…则…）

• 如果你的曲库有大量多版本专辑、合辑、现场/混音版本、MV，且希望系统自动整理 → 选 Meelo，它的 Song Group/Release/B-Sides 模型是四者中唯一的；
• 如果你只是想"把 MP3 挂上去，用手机 App 随时听" → 选 Navidrome，部署 5 分钟、资源占用个位数百分比，不要为用不到的元数据模型买单；
• 如果你偏好 Web 应用形态与 PHP 技术栈、团队要二次开发 Laravel 生态 → 选 koel；
• 如果你要的是联邦化音频社区（跨实例关注/分享，类 Funkwhale 实例 federation）而非个人曲库 → 选 Funkwhale；
• 如果选 Meelo，建议同时接受两点：部署按 B2 篇的 9 服务清单走官方 compose（不要自己精简服务）；管理/集成走 REST API（见 《Meelo v3.13.1 API 使用详解》）。

八、参考链接

• 官方仓库：https://github.com/Arthi-chaud/Meelo （stars/forks 数据实查日期 2026-10-29）
• Releases（版本节奏来源）：https://github.com/Arthi-chaud/Meelo/releases
• 官方 Wiki（部署与设置权威文档）：https://github.com/Arthi-chaud/Meelo/wiki
• 架构说明：https://github.com/Arthi-chaud/Meelo/wiki/Architecture
• 竞品参考：https://github.com/navidrome/navidrome 、https://github.com/koel/koel 、https://dev.funkwhale.audio/Funkwhale
• 本系列实测文档：《Meelo v3.13.1 Docker Compose 部署指南》、《Meelo v3.13.1 配置参数详解》、《Meelo v3.13.1 API 使用详解》