multi-scrobbler 介绍与选型指南

目标：一文说清 multi-scrobbler 是什么、能解决什么问题、如何工作，并与同类听歌记录（scrobble）聚合方案做量化对比，帮助读者判断它是否适合自建音乐统计栈。本文全部信息来自官方文档站、GitHub 仓库与官方镜像仓库的联网溯源（查询日期 2026-10-29），不含未经核实的推测。

一、环境信息

本篇为认知与选型篇，内容以联网溯源为准，不依赖特定部署环境。溯源渠道与时效如下：

• 查询日期：2026-10-29
• 官方文档站：docs.multi-scrobbler.app（同域镜像 foxxmd.github.io/multi-scrobbler）
• 代码仓库：GitHub - FoxxMD/multi-scrobbler
• 版本事实：GitHub Releases 显示最新稳定版为 0.13.3，同期存在预发布版 0.14.0-beta.1（newreleases.io 镜像页与 GitHub Releases 双渠道核对，查询日期 2026-10-29）
• 许可事实：仓库 LICENSE 文件为 MIT License，版权行 Copyright (c) 2020 FoxxMD（raw.githubusercontent.com，查询日期 2026-10-29）
• 分发事实：官方跨平台镜像发布于 Docker Hub（foxxmd/multi-scrobbler）与 GitHub Packages（ghcr.io/foxxmd/multi-scrobbler），构建 x86-64 与 ARM64 双架构（官方安装文档，查询日期 2026-10-29）；shields.io 徽章显示 Docker Hub 拉取量约 1.1M 次（查询日期 2026-10-29）

💡 说明：scrobble 一词源自音乐社区网站 Audioscrobbler（last.fm 前身）的协议名，指把「我听了一首歌」这条播放记录提交给统计服务器记账的行为。本文中「源（Source）」指产生播放记录的服务，「目标（Client）」指接收记录的统计服务器。

二、软件概述

multi-scrobbler 是一个自托管的听歌记录聚合器，仓库一句话定位为「Scrobble plays from multiple sources to multiple clients」——从多个数据源抓取播放记录，转发到多个统计目标。它解决的问题非常具体：当你分散使用 Jellyfin、Navidrome、Spotify 等多个音乐服务时，每个服务都只看到自己那一部分的收听行为，last.fm 或 ListenBrainz 的统计因此残缺；multi-scrobbler 在中间做一次汇聚，把所有源的播放统一送到你想记账的目标。

• 作者与维护：FoxxMD（GitHub 个人维护者），MIT 许可，2020 年起持续开发（LICENSE 版权行 + Releases 历史，查询日期 2026-10-29）。
• 技术栈：TypeScript / Node.js（仓库语言标签 TypeScript；官方镜像基于 Node 运行时，安装文档要求 Node.js 环境或直接使用官方镜像）。
• 运行形态：单一常驻服务进程，内置 Web 仪表盘（官方文档：Web UI 与 API 默认监听 9078 端口），数据落 SQLite 数据库（官方配置文档：首次运行在配置目录创建 ms.db）。
• 版本节奏：以 0.x 快速迭代，2026 年 10 月窗口内连续发布 0.13.2、0.13.3 并推进 0.14.0-beta.1（Releases 页，查询日期 2026-10-29）；0.13.x 亮点包括文档站迁移至 Astro Starlight、更完整的退出信号处理（SIGINT/SIGTERM 优雅停机）、增强的 Now Playing 展示与重复 scrobble 检测文档化。

三、核心架构

multi-scrobbler 的架构可以概括为「源 → 判定 → 目标」三段流水线，全部跑在一个服务进程内（官方配置文档与各源/目标配置页，查询日期 2026-10-29）：

1. 源（Sources）：两类工作方式。
   • 轮询（Polling）源：定期调用源服务的 API 拉取「正在播放/最近播放」，如 Jellyfin、Navidrome 与其他 Subsonic 兼容服务（Airsonic 等）、Mopidy、VLC（HTTP 接口）、JRiver、MPRIS（Linux 桌面 D-Bus）、Plex/Tautulli 等；
   • 推送（Webhook）源：等待源服务主动回调，如 Plex/Tautulli Webhook、Jellyfin Webhook、WebScrobbler（浏览器扩展回调）等。
2. 播放判定与去重：内置 scrobble 阈值判定（默认播放时长 ≥30 秒且 ≥50% 进度，官方配置文档 sourceDefaults.scrobbleThresholds 默认值）、重复 scrobble 检测（0.13.x 版本说明）；所有播放连同元数据与调试信息写入 SQLite 数据库，每个源/目标建议显式设置 id 以便配置变更后数据库仍能对上账。
3. 目标（Clients）：把合格播放提交给 last.fm、ListenBrainz、Maloja、Koito 等统计服务；提交失败进入死信队列，每 5 分钟重试若干次后放弃（官方 Clients 总览：「If multi-scrobbler is unable to submit a scrobble to a Client then it places the scrobble into a queue which is retried every 5 minutes」）。
4. 横切能力：
   • 缓存：默认内存缓存 + 可选 Valkey（Redis 开源分支）二级缓存，用于认证凭据、转换规则与外部元数据 API（如 MusicBrainz）调用的加速与重启后持久化（官方配置文档 Caching 章节）；
   • 变换器（Transforms）：提交前用 MusicBrainz 等元数据源修正或补全曲目信息；
   • 通知 Webhook：scrobble 结果可推送到 Gotify、ntfy（官方 AIO 配置示例 webhooks 段）；
   • 仪表盘与 API：Web UI 提供源/目标状态、最近播放、待处理队列的实时视图，配套 HTTP API（/api/health、/api/status 等）供探活与状态查询。

💡 技术拓展：scrobble 数据的「汇聚点」有两类定位，选型前先分清——

定位	代表项目	职责
聚合器/桥接器	multi-scrobbler、web-scrobbler、rescrobbled	只做搬运：把多源播放转发到已有统计服务，自身不提供统计页面
统计服务器	Maloja、Koito、last.fm、ListenBrainz	做记账：接收 scrobble、存储并展示统计

multi-scrobbler 属于前者，且因同时支持 last.fm/ListenBrainz/Maloja/Koito 多种目标，常作为自建统计栈中的「总线」；它也能把 last.fm/ListenBrainz 既当源又当目标，实现跨账号同步。本文后续对比均基于这一定位。

四、功能特性

以下特性均可在官方文档对应页面核实（查询日期 2026-10-29）：

• 多源多目标矩阵：源覆盖 Plex/Tautulli、Jellyfin、Subsonic 兼容系（Airsonic、Navidrome）、Mopidy、MPRIS、VLC、JRiver、Spotify、Deezer、YouTube Music、last.fm、ListenBrainz、WebScrobbler 等；目标覆盖 last.fm、ListenBrainz、Maloja、Koito 等（README 源列表 + Clients/Sources 配置总览）。
• 三种配置方式：环境变量（ENV）、按类型命名的独立 JSON 文件（如 jellyfin.json、maloja.json）、全量单文件 AIO（config.json）；三者可混用但官方建议统一（配置总览 Configuration Types）。
• 敏感信息插值：JSON 配置中可用 [[ENV_NAME]] 引用环境变量，密钥不落盘；未匹配时保留原文并输出 WARN 日志（配置总览 Secrets Interpolation）。
• Now Playing 上报：向支持的目标实时上报「正在播放」（Clients 总览 Now Playing 章节）。
• 死信重试与队列：提交失败自动排队重试，仪表盘可见 deadLetterScrobbles/queued 计数（/api/status 响应字段，官方 API 文档）。
• 阈值可调：源默认值与单源覆盖均可配置播放时长/进度阈值、轮询与请求重试次数、重试倍率（AIO 配置示例 sourceDefaults）。
• 双架构官方镜像 + 加固选项：x86-64/ARM64；支持 read_only 根文件系统、PUID/PGID 权限落定、TZ 时区、BASE_URL 反代子路径部署（安装文档 Recommended Settings）。
• 自托管文档：官方文档站同时随实例提供（安装文档 Self-Hosted Docs 说明）。

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

以下为官方安装文档给出的 Docker Compose 最小示例结构（摘自官方 Installation 页 Docker Usage Example，查询日期 2026-10-29；场景为 Jellyfin 源 → Maloja 目标，端口 9078）：

services:
  multi-scrobbler:
    image: foxxmd/multi-scrobbler
    container_name: multi-scrobbler
    environment:
      - TZ=Etc/GMT
      - JELLYFIN_APIKEY=c9fae8756fbf481ebd9c5bb56bd6540c
      - JELLYFIN_URL=192.168.0.101:8096
      - JELLYFIN_USER=MyUser
      - MALOJA_URL=http://domain.tld:42010
      - MALOJA_API_KEY=1234
      - PUID=1000
      - PGID=1000
    volumes:
      - ./config:/config
    ports:
      - 9078:9078
    restart: unless-stopped

要点解读（依据官方安装文档 Recommended Settings）：

• ./config:/config：必须持久化的配置/凭据/数据库目录，否则升级即丢数据；
• 9078：仪表盘与 API 端口；
• 环境变量法适合「单一用户、一个源对一个目标」的最简场景；多源多目标、需要阈值/变换/通知等进阶配置时改用 AIO 的 config.json（配置总览的选型建议）。

完整的从零部署（目录规划、配置文件、启动验证、升级与排障）见《multi-scrobbler Docker Compose 部署指南》；此处仅作认知性预览。

六、适用场景与限制

适用场景（源自官方文档能力边界，查询日期 2026-10-29）：

• 家庭媒体服务器组合（Jellyfin/Plex + Navidrome/Airsonic）想统一上报 last.fm 或 ListenBrainz；
• 多个流媒体账号（Spotify、Deezer、YouTube Music）与本地曲库并行，需要一份合并的收听统计；
• 自建统计服务（Maloja/Koito）想同时吃进不支持直连的源；
• last.fm 与 ListenBrainz 双记账或账号迁移期间的双写。

限制与注意：

• 无传统 CLI：程序以服务进程常驻，日常管理靠 Web 仪表盘、HTTP API 与配置文件，没有「命令行执行一次」式的操作入口（官方安装文档仅有服务化运行说明）；
• 单实例定位：面向个人/家庭规模的聚合服务，数据库为单 SQLite 文件，官方文档未提供集群或分布式形态；
• 公网暴露需加固：官方明确建议公网可访问时放在私有网络并配合反向代理与认证（Installation 页 important 提示 + Securing Multi-Scrobbler 文档页）；
• 反向代理推荐：官方推荐置于 NGINX/Traefik/Caddy 之后，既解决 HTTP/1.1 下浏览器每标签页一条 SSE 连接的并发上限，也便于 TLS（安装文档 Reverse Proxy Recommended 章节）；
• 第三方凭据前置：Spotify、last.fm 等目标需预先在其开发者平台申请 API 凭据，注册流程不可自动化。

七、同类选型对比

对比对象为「scrobble 记账/搬运」生态中常见方案，事实以各自官方仓库/站点与 crates.io 页面为准（查询日期 2026-10-29）。GitHub 星数因徽章与仓库页当时不可稳定抓取，本表不列星数、以仓库链接为准。

关键差异与如何选：

• 若你的播放行为分散在多个服务/协议，需要一个不挑剔协议、能在中间做汇聚、阈值与重试可控的常驻服务，multi-scrobbler 是当前覆盖面最全的选择；
• 若只在 Linux 桌面上听歌，rescrobbled / mpris-scrobbler 更轻，无需常驻 Web 服务；
• 若诉求本身是「要一个自己的统计站」，直接上 Maloja 或 Koito，再用 multi-scrobbler 把它们接进多源体系（二者都被官方列为合法目标）；
• 版本活跃度上，multi-scrobbler 在查询窗口（2026-10）保持每月级发布节奏，且 0.14.0-beta.1 已在预发布轨道。

八、参考链接

• 官方文档站：https://docs.multi-scrobbler.app/
• GitHub 仓库：https://github.com/FoxxMD/multi-scrobbler
• 安装文档：https://foxxmd.github.io/multi-scrobbler/installation/
• 配置总览：https://foxxmd.github.io/multi-scrobbler/configuration/
• 快速开始：https://foxxmd.github.io/multi-scrobbler/quickstart/
• Docker Hub 镜像页：https://hub.docker.com/r/foxxmd/multi-scrobbler
• rescrobbled 仓库：https://github.com/InputUsername/rescrobbled
• mpris-scrobbler 仓库：https://github.com/mariusor/mpris-scrobbler
• Koito 官网：https://koito.io/
• Maloja 仓库：https://github.com/krateng/maloja
• 本专栏相关：《multi-scrobbler Docker Compose 部署指南》《multi-scrobbler 0.13.3 配置参数详解》《multi-scrobbler 0.13.3 API 使用详解》