multi-scrobbler Docker Compose 部署指南

目标：在一台 Ubuntu 服务器上用 Docker Compose 从零部署 multi-scrobbler 0.13.3 听歌记录聚合服务，并搭建「本地统计目标（Maloja）+ 本地播放源（VLC）」的最小验证栈，完整走通「播放 → 源轮询 → scrobble 转发 → 目标入库」闭环。已在 Ubuntu 22.04 / Docker Engine 29.9.2 / Compose v5.6.1 环境实测通过，端到端 scrobble 已验证入库。

一、环境信息

• 服务器系统：Ubuntu 22.04（x86_64）
• 运行时：Docker Engine 29.9.2，Docker Compose v5.6.1
• 部署对象：multi-scrobbler 0.13.3（官方镜像 foxxmd/multi-scrobbler:0.13.3，镜像体积约 769MB）
• 验证栈配套：Maloja 3.2.4（自托管统计目标，krateng/maloja:3.2.4，约 199MB）；VLC 3.0.16 Vetinari（Ubuntu 22.04 软件源版本，作本地播放源）
• 端口规划：8147 → multi-scrobbler 仪表盘（服务内默认 9078）；8148 → Maloja（服务内默认 42010）；VLC HTTP 接口 8080 仅栈内网络访问
• 安装目录：/opt/multi-scrobbler/（compose 项目、配置、数据均在此）
• 查询日期：2026-10-29（版本与镜像信息均按当日官方仓库实况核定）

💡 说明：multi-scrobbler 本体只是一个聚合服务，没有源和目标就看不到任何效果。本文的 Maloja 与 VLC 是为验证闭环临时引入的两个角色——Maloja 是官方支持的自托管统计目标，VLC 是官方支持的轮询源；生产使用时可按需替换成 Jellyfin/Navidrome 等真实源与 last.fm/ListenBrainz 等目标，部署方式不变。

二、镜像选型说明

multi-scrobbler 官方维护两处镜像仓库（官方安装文档，2026-10-29 查询）：

两个仓库内容一致，均为 x86-64 与 ARM64 双架构。选型建议：常规网络环境用 Docker Hub；国内网络拉取 Docker Hub 失败时改用 ghcr.io/foxxmd/multi-scrobbler:0.13.3。

版本 tag 策略：官方提供 latest 与具体版本号（如 0.13.3）两种 tag。生产部署建议固定具体版本号，升级时显式改 tag 重拉，避免 latest 漂移带来的配置不兼容。当前最新稳定版为 0.13.3（0.14.0 处于 beta 预发布，不建议生产使用）。

Maloja 验证目标使用 krateng/maloja:3.2.4（其官方镜像，LinuxServer.io 基础构建）。VLC 使用 Ubuntu 22.04 官方软件源中的 vlc 与 ffmpeg 包。

三、前置条件

1. 服务器已安装 Docker Engine 与 Compose v2 插件（本文实测版本 29.9.2 / v5.6.1），验证命令：

docker info --format '{{.ServerVersion}}'
# 实测输出：29.9.2
docker compose version
# 实测输出：Docker Compose version v5.6.1

2. 端口 8147、8148 未被占用（冲突时自行改映射，容器内端口 9078/42010 不必改）：

ss -ltn | grep -E ':(8147|8148)\b' || echo '端口空闲'
# 实测输出：端口空闲

3. 服务器可访问镜像仓库（Docker Hub 或 ghcr.io）；拉取失败时的降级方案见「十一、常见问题」Q1。

4. 规划一个普通用户/组 ID 用于目录权限（本文用默认 911:911，官方镜像基于 LinuxServer.io 构建运行在 UID 911；也可通过 PUID/PGID 环境变量指定为宿主机用户）。

四、部署步骤

4.1 目录规划

mkdir -p /opt/multi-scrobbler/{config,data,music,maloja-data}
cd /opt/multi-scrobbler

各目录用途：config/ 为 multi-scrobbler 配置与数据库持久化目录（必须持久化）；data/ 为可选的独立数据目录（配合 DATA_DIR 变量使用，本文启用）；music/ 存放测试音频；maloja-data/ 为 Maloja 的持久化目录。

4.2 编写 docker-compose.yml

name: multi-scrobbler-0-13-3-stack

services:
  multi-scrobbler:
    image: foxxmd/multi-scrobbler:0.13.3
    container_name: multi-scrobbler-0-13-3-app
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./config:/config
      - ./data:/msData
    ports:
      - "8147:9078"
    networks:
      - msnet
    restart: unless-stopped

  vlc:
    image: ubuntu:22.04
    container_name: multi-scrobbler-0-13-3-vlc
    command: sleep infinity
    volumes:
      - ./music:/music:ro
    networks:
      - msnet
    restart: unless-stopped

  maloja:
    image: krateng/maloja:3.2.4
    container_name: multi-scrobbler-0-13-3-maloja
    environment:
      - MALOJA_SKIP_SETUP=yes
    volumes:
      - ./maloja-data:/config
    ports:
      - "8148:42010"
    networks:
      - msnet
    restart: unless-stopped

networks:
  msnet:
    name: multi-scrobbler-0-13-3-net
    driver: bridge

配置项解读：

• name: multi-scrobbler-0-13-3-stack：Compose 项目名显式固定，避免随目录名漂移；
• TZ=Asia/Shanghai：让 scrobble 时间戳与日志时区一致（scrobble 的记账时间按本地时区存储，错配会导致统计时间偏移）；
• ./config:/config：官方要求必须持久化的目录，配置、凭据缓存、SQLite 数据库（ms.db）都在其中；
• ./data:/msData：可选独立数据目录，需要时在环境变量加 DATA_DIR=/msData 让数据库/缓存与配置分离（官方安装文档 Storage 章节）；
• 8147:9078：宿主端口 8147 映射到仪表盘默认端口 9078，可按需更换宿主端口；
• msnet：自建 bridge 网络，三个服务以服务名互访（vlc、maloja 即为可解析的主机名）；
• maloja 的 MALOJA_SKIP_SETUP=yes：跳过首启交互式设置（官方镜像环境变量）。

4.3 准备 multi-scrobbler 配置文件

在 config/ 下创建 AIO 全量配置 config.json，内容为「一个 VLC 轮询源 → 一个 Maloja 目标」的最小闭环（各字段含义见《multi-scrobbler 0.13.3 配置参数详解》）：

{
  "debugMode": false,
  "disableWeb": false,
  "sourceDefaults": {
    "scrobbleThresholds": {
      "duration": 30,
      "percent": 50
    }
  },
  "sources": [
    {
      "type": "vlc",
      "enable": true,
      "name": "Lab VLC",
      "id": "vlc-lab",
      "clients": ["labMaloja"],
      "data": {
        "url": "vlc:8080",
        "password": "q1w2e3r4"
      }
    }
  ],
  "clients": [
    {
      "type": "maloja",
      "enable": true,
      "name": "labMaloja",
      "id": "maloja-lab",
      "data": {
        "url": "http://maloja:42010",
        "apiKey": "q1w2e3r4"
      }
    }
  ]
}

要点：sources[].clients 引用的是目标的 name；id 建议显式固定，使数据库在配置改名后仍能延续账号数据；VLC 与 Maloja 的口令/密钥此处使用演示值 q1w2e3r4，与后文两个服务的初始化保持一致。

4.4 准备测试音频（VLC 播放源用）

生成一首 150 秒、带 ID3 元数据的测试曲目（后续用它验证 scrobble 闭环）：

docker compose run --rm --entrypoint bash vlc -c \
  "ffmpeg -y -f lavfi -i 'sine=frequency=440:duration=150' -af volume=0.6 -c:a libmp3lame -b:a 128k \
   -metadata title='Neon Skyline' -metadata artist='Lab Ensemble' -metadata album='Test Sessions' \
   -id3v2_version 3 /tmp/neon-skyline.mp3 && cp /tmp/neon-skyline.mp3 /music/ 2>/dev/null || true"

⚠️ 注意：music/ 在 compose 中以只读方式挂载（:ro），若提示只读，可先在宿主机执行同样的 ffmpeg 命令生成到 music/ 目录。实测生成结果：

ls -la music/
# 实测输出：
# -rw-r--r-- 1 root root 2401292 Oct 29 22:45 neon-skyline.mp3

4.5 启动服务栈

docker compose up -d

首次启动实测输出：

 Container multi-scrobbler-0-13-3-maloja Created 
 Container multi-scrobbler-0-13-3-vlc Created 
 Container multi-scrobbler-0-13-3-vlc Starting 
 Container multi-scrobbler-0-13-3-maloja Starting 
 Container multi-scrobbler-0-13-3-app Starting 
 Container multi-scrobbler-0-13-3-vlc Started 
 Container multi-scrobbler-0-13-3-maloja Started 
 Container multi-scrobbler-0-13-3-app Started 

状态确认：

docker compose ps --format 'table {{.Name}}\t{{.Status}}\t{{.Ports}}'
# 实测输出：
# NAME                            STATUS                  PORTS
# multi-scrobbler-0-13-3-app      Up Less than a second   0.0.0.0:8147->9078/tcp, [::]:8147->9078/tcp
# multi-scrobbler-0-13-3-maloja   Up Less than a second   0.0.0.0:8148->42010/tcp, [::]:8148->42010/tcp
# multi-scrobbler-0-13-3-vlc      Up Less than a second   

三个服务均为 Up 即启动成功。若个别服务 Exited，用 docker compose logs <服务名> 查看原因（常见为端口冲突或目录权限）。

4.6 部署并启用 VLC 播放源

vlc 服务启动后是一个干净的 Ubuntu 22.04 环境，需要手动完成 VLC 的安装与 HTTP 接口启用（这也是把一台已有 Ubuntu 服务器改造成 scrobble 播放源的标准流程）：

# 进入 vlc 环境安装 VLC 与 ffmpeg（依赖包较多，视网络情况需数分钟）
docker exec -d multi-scrobbler-0-13-3-vlc bash -c \
  'apt-get update -qq && DEBIAN_FRONTEND=noninteractive apt-get install -y -qq vlc ffmpeg'

安装完成后验证版本（实测输出）：

docker exec multi-scrobbler-0-13-3-vlc bash -c 'which vlc ffmpeg'
# 实测输出：
# /usr/bin/vlc
# /usr/bin/ffmpeg
docker exec multi-scrobbler-0-13-3-vlc su vlcuser -c "vlc --version 2>/dev/null | head -2"
# 实测输出：
# VLC version 3.0.16 Vetinari (3.0.13-8-g41878ff4f2)
# Compiled by buildd on lcy02-amd64-108.buildd (Mar 13 2022 08:00:10)

⚠️ 注意：VLC 拒绝以 root 运行（直接运行会报错 VLC is not supposed to be run as root. Sorry.），必须创建普通用户后以其身份启动：

docker exec multi-scrobbler-0-13-3-vlc bash -c 'useradd -m -s /bin/bash vlcuser && su vlcuser -c "echo SU_OK"'
# 实测输出：SU_OK

以后台方式启动 VLC 并开启 HTTP 接口（口令为 4.3 配置中的 q1w2e3r4）：

docker exec -d multi-scrobbler-0-13-3-vlc bash -c \
  'su vlcuser -c "vlc -I dummy --extraintf http --http-host 0.0.0.0 --http-port 8080 --http-password q1w2e3r4 --loop /music/neon-skyline.mp3 > /tmp/vlc.log 2>&1"'

验证 HTTP 接口已监听（实测输出）：

docker exec multi-scrobbler-0-13-3-vlc bash -c '(echo > /dev/tcp/127.0.0.1/8080) && echo PORT_8080_OPEN'
# 实测输出：PORT_8080_OPEN

⚠️ 注意：无声卡的服务器上 VLC 会在日志中出现 failed to create audio output，属正常现象（解码与播放进度照常推进，不影响 scrobble）。--loop 让曲目循环播放，持续产生播放记录。vlc 服务或进程重启后需重新执行本步启动命令，长期使用建议按发行版惯例为其配置 systemd 服务。

4.7 配置 Maloja 目标端 API 密钥

Maloja 首次启动会在 maloja-data/config/apikeys.yml 自动生成随机 API 密钥并打印在日志中。为与 4.3 的配置对齐，将其改为固定演示密钥并重启：

printf 'default: q1w2e3r4\n' > /opt/multi-scrobbler/maloja-data/config/apikeys.yml
docker restart multi-scrobbler-0-13-3-maloja

⚠️ 注意：密钥文件的完整路径是 maloja-data/config/apikeys.yml（容器内 /config/config/apikeys.yml）——Maloja 的数据根目录是 /config，配置在其下 config/ 子目录，不要写到 maloja-data/apikeys.yml 顶层，否则重启后仍会重新生成随机密钥（实测踩坑）。生产环境建议改用强随机密钥。

验证 Maloja 服务正常（实测输出）：

curl -s http://127.0.0.1:8148/apis/mlj_1/serverinfo
# 实测输出：
# {"name": "Generic Maloja User", "version": ["3", "2", "4"], "versionstring": "3.2.4", "db_status": {"healthy": true, "rebuildinprogress": false, "complete": true}}

4.8 端到端验证：看到第一条 scrobble

等待 1~2 分钟（multi-scrobbler 完成源初始化与轮询、曲目播放达到阈值），查看 multi-scrobbler 日志：

docker logs --since 5m multi-scrobbler-0-13-3-app 2>&1 | grep -E 'Initialized|Connected|Scrobbled'

实测输出（节选）：

[2026-10-29 22:47:06.677 +0800] INFO   : [App] [Scrobblers] [Maloja - labMaloja] [API] [API - Maloja - labMaloja] Auth test passed!
[2026-10-29 22:47:06.677 +0800] INFO   : [App] [Scrobblers] [Maloja - labMaloja] Fully Initialized!
[2026-10-29 22:47:08.683 +0800] INFO   : [App] [Sources] [Vlc - Lab VLC] Connected successfully, found VLC 3.0.16 Vetinari
[2026-10-29 22:47:08.684 +0800] INFO   : [App] [Sources] [Vlc - Lab VLC] Fully Initialized!
[2026-10-29 22:47:08.685 +0800] INFO   : [App] [Sources] [Vlc - Lab VLC] Polling started
[2026-10-29 22:48:22.745 +0800] INFO   : [App] [Scrobblers] [Maloja - labMaloja] Scrobbled (Backlog)     => (vlc) Lab Ensemble - Neon Skyline @ 2026-10-29T22:47:08+08:00 (S)

日志显示「VLC 3.0.16 连接成功 → 源开始轮询 → scrobble 已转发」。再向 Maloja 查询入库结果（实测输出）：

curl -s -H 'Authorization: TOKEN q1w2e3r4' 'http://127.0.0.1:8148/apis/mlj_1/scrobbles?max=5'
# 实测输出：
# {"status": "ok", "list": [{"time": 1793285228, "track": {"artists": ["Lab Ensemble"], "title": "Neon Skyline", "album": {"artists": ["Lab Ensemble"], "albumtitle": "Test Sessions"}, "length": 150}, "duration": 75, "origin": "client:default"}], "pagination": {"page": 0, "perpage": 5, "next_page": null, "prev_page": null}}

list 中出现 Neon Skyline 即闭环打通。duration: 75 恰为 150 秒曲目 50% 进度阈值（sourceDefaults.scrobbleThresholds）的判定落点。同时可打开浏览器访问 http://<服务器IP>:8147/ 查看 multi-scrobbler 仪表盘（页面标题实测为 Multi Scrobbler），http://<服务器IP>:8148/ 查看 Maloja 统计页。

五、数据持久化说明

multi-scrobbler 的全部状态集中在两个位置（官方安装文档 Persistent Directories，实测目录清单一致）：

ls -la /opt/multi-scrobbler/config/
# 实测输出：
# -rw-r--r-- 1 911 911  610 Oct 29 22:24 config.json
# -rw-r--r-- 1 911 911  159 Oct 29 22:53 ms-scrobble.cache

• config.json：手工维护的 AIO 配置文件；
• ms-scrobble.cache：凭据/状态缓存文件（首次 scrobble 后自动生成）；
• SQLite 数据库 ms.db 在有 scrobble 数据后生成于配置目录，存储全部播放记录、元数据与调试信息（官方配置文档 Database 章节）；版本升级涉及库结构变更时官方会自动备份并迁移。

备份与恢复：

cd /opt/multi-scrobbler && tar -czf ms-config-backup-$(date +%F).tgz config/
ls -la ms-config-backup-*.tgz
# 实测输出（本文演示）：
# -rw-r--r-- 1 root root 541 Oct 29 23:02 ms-config-backup.tgz

恢复时停服解包回 config/ 即可。Maloja 侧同理备份 maloja-data/ 整目录（数据库在其 state/malojadb.sqlite，实测约 60KB 量级）。

⚠️ 注意：若只挂载了 config/ 而未挂载持久化目录，升级重建服务后配置、凭据与统计数据库都会丢失——这是官方文档反复强调的第一注意事项。

六、环境变量表

multi-scrobbler 支持通过环境变量完成基础配置（官方安装/配置文档，2026-10-29 查询；「实测」列为本环境验证情况）：

💡 说明：ENV 方式适合「单一用户、一个源对一个目标」的最简场景；两个以上同类型源/目标、需要阈值细调或源→目标定向转发时，应改用 JSON 配置（见《multi-scrobbler 0.13.3 配置参数详解》）。Spotify、last.fm 等需要 OAuth 的服务还支持 <前缀>_CLIENT_ID/_CLIENT_SECRET 一类变量，详见官方各源/目标配置页。

七、配置参数说明

• 配置目录：/config（Docker 形态固定），所有 JSON 配置与数据库都在此，必须 bind mount 持久化；
• AIO 配置：/config/config.json 是全量配置入口，sources/clients 数组中的每项必须带 type 字段；本文 4.3 的配置即 AIO 形态，实测 Client Added from config.json、Source Added from config.json 两条日志证明加载生效；
• 阈值参数：sourceDefaults.scrobbleThresholds（duration 秒 + percent 进度）决定「播到什么程度才记账」；本文默认值 30 秒 / 50% 实测下，150 秒曲目在 75 秒处产生 scrobble（Maloja 侧 duration: 75 印证）；
• 验证方法：修改 config.json 后重启服务 docker restart multi-scrobbler-0-13-3-app，观察日志出现对应的 Added from config.json 与 Fully Initialized!；配置语法错误会在启动日志中直接报 JSON 解析错误，改回即可。

完整参数字典、按类型分文件配置、密钥插值与生产模板见《multi-scrobbler 0.13.3 配置参数详解》。

八、配置文件挂载

⚠️ 注意：multi-scrobbler 与 Maloja 的容器内默认持久化路径都叫 /config，但它们是两个独立服务各自的挂载，宿主侧必须使用两个不同目录（本文 config/ 与 maloja-data/），不要复用同一目录。

九、等价 docker run

不使用 Compose 时，可用等价命令单条启动（其余服务同理逐个启动；本文推荐 Compose 编排以便统一管理网络与依赖）：

docker run -d \
  --name multi-scrobbler-0-13-3-app \
  --network multi-scrobbler-0-13-3-net \
  -p 8147:9078 \
  -e TZ=Asia/Shanghai \
  -v /opt/multi-scrobbler/config:/config \
  -v /opt/multi-scrobbler/data:/msData \
  --restart unless-stopped \
  foxxmd/multi-scrobbler:0.13.3

与 compose 等价性的核对要点：网络需先用 docker network create multi-scrobbler-0-13-3-net 创建；--restart unless-stopped 对应 compose 的 restart:；其余映射一一对应。

十、常用运维命令

cd /opt/multi-scrobbler

# 查看实时日志（-f 跟踪）
docker logs --since 10m multi-scrobbler-0-13-3-app

# 重启单个服务（改完 config.json 后执行）
docker restart multi-scrobbler-0-13-3-app

# 停止 / 恢复整个栈（数据目录均保留）
docker compose stop
docker compose start

# 升级版本：改 compose 中的镜像 tag 后执行
docker compose pull
docker compose up -d

升级实测（当前 0.13.3 已是最新稳定版，pull 即校验最新摘要）：

$ docker compose pull
 Image foxxmd/multi-scrobbler:0.13.3 Pulling 
 Image ubuntu:22.04 Pulling 
 Image krateng/maloja:3.2.4 Pulling 
 Image ubuntu:22.04 Pulled 
 Image foxxmd/multi-scrobbler:0.13.3 Pulled 
 Image krateng/maloja:3.2.4 Pulled 

pull 后 docker compose up -d，若有新版本会逐个 Recreate 重建；无变化时 Compose 不输出重建行，服务保持运行。升级前建议先按「五、数据持久化说明」做一次配置目录备份。

十一、常见问题

Q1：镜像拉取超时或失败？

按「官方源 → 备选官方源」顺序降级：先确认 Docker Hub 可达；失败时把 compose 中的 image: 换为 ghcr.io/foxxmd/multi-scrobbler:0.13.3 再 pull。实测本文环境官方 Docker Hub 渠道可用（docker compose pull 六行 Pulling/Pulled 回显见「十、常用运维命令」）。

Q2：multi-scrobbler 日志出现 connect ECONNREFUSED 10.89.x.x:8080，VLC 源初始化失败？

实测踩坑：multi-scrobbler 启动早于 VLC 完成安装/启动时，源初始化会失败并等待下一轮心跳（实测约 20 分钟后自动重试：日志先报 Could not initialize source automatically，VLC 就绪后下一轮 Connected successfully, found VLC 3.0.16 Vetinari）。不想等就重启聚合服务立即重连：docker restart multi-scrobbler-0-13-3-app。根治办法是保证源服务先于 multi-scrobbler 就绪（或用 compose 的 depends_on + 健康检查控制启动顺序）。

Q3：/api/health 返回 {"messages":["Source vlc - Lab VLC requires authentication."]}？

这是健康接口在报告源不可达。实测当播放源进程被停止时，/api/status 中该源状态变为 Communication Failed、authed: false（multi-scrobbler 把「连不上」与「认证失效」合并报为 requires authentication）。处理：把播放源服务重新启动，状态自动恢复 Polling。

Q4：VLC 无法启动，报 VLC is not supposed to be run as root. Sorry.？

VLC 拒绝 root 身份运行。按 4.6 步骤创建普通用户 vlcuser 并以 su vlcuser -c "..." 启动即可。

Q5：Maloja 每次重启后 API 密钥都变？

密钥文件写错了层级。Maloja 数据根挂载在容器 /config，密钥文件实际位于 /config/config/apikeys.yml（宿主 maloja-data/config/apikeys.yml）；写在数据根顶层不会被读取，重启即被随机密钥覆盖。实测详见 4.7 的 ⚠️ 注意。

Q6：scrobble 迟迟不产生？

依次核对：播放进度是否达到阈值（默认 30 秒 + 50%，150 秒曲目约 75 秒处触发）；仪表盘 http://<IP>:8147/ 中源状态是否 Polling、目标是否 Running；目标侧 queued/deadLetterScrobbles 是否增长（增长说明源侧正常、目标侧提交受阻，检查目标 API 密钥与网络）。

十二、参考链接

• 官方安装文档：https://foxxmd.github.io/multi-scrobbler/installation/
• 官方快速开始：https://foxxmd.github.io/multi-scrobbler/quickstart/
• 配置总览：https://foxxmd.github.io/multi-scrobbler/configuration/
• GitHub 仓库：https://github.com/FoxxMD/multi-scrobbler
• Docker Hub 镜像页：https://hub.docker.com/r/foxxmd/multi-scrobbler
• Maloja 仓库：https://github.com/krateng/maloja
• 本专栏相关：《multi-scrobbler 介绍与选型指南》《multi-scrobbler 0.13.3 配置参数详解》《multi-scrobbler 0.13.3 API 使用详解》