docker-roonserver 中文使用教程

一、项目速览

入门 · 1 分钟版

如果你拥有一套 Hi-Fi 音响或流媒体设备，很可能听说过 Roon——它是一款音乐管理与播放软件，能把本地音乐文件、Tidal/Qobuz 等流媒体服务整合到一个统一界面，并自动补全专辑封面、艺术家简介、乐评等元数据。

steefdebruijn/docker-roonserver 是一个社区维护的 Docker 镜像，它帮你把 Roon 的核心服务（RoonServer）跑在容器里。项目本身只有 160 个星，但它的特殊之处在于 Roon 官方原本没有 Docker 镜像，直到 2026 年 4 月才正式发布——也就是说这个项目是社区在官方缺位时的最佳替代方案。

一句话判断：如果你正在用 Docker 跑 Roon，或者打算部署 RoonServer，这个项目是迁移到官方镜像前的桥梁。但注意：项目作者已明确宣布停更，建议所有用户迁移到 Roon 官方 Docker 镜像。

二、核心功能与架构

进阶 · 推荐细读

它解决了什么问题？

Roon 本身是一个商业软件，其服务端 RoonServer 主要负责扫描音乐库、管理元数据、输出音频流。在没有官方 Docker 镜像的年代，要在 NAS 或 Linux 服务器上跑 Roon，要么手动装一堆依赖，要么忍受官方安装脚本的不可控。这个项目把 RoonServer 装进容器，你只需要挂载音乐目录和配置卷，其他全交给 Docker。

架构要点

它的设计思路非常直白：

首次运行自动下载：容器启动时检查 /app 目录是否已有 Roon 程序文件，如果没有就从 Roon 官方下载。这意味着你不需要预先下载安装包。
两个关键数据卷：roon-app（程序文件）和 roon-data（数据库、配置、播放列表）。与官方新镜像不同，这里 app 和 data 是分开的，迁移时需要注意。
网络模式必须 --net=host：Roon 依赖 mDNS 和 RAAT 协议在局域网发现设备，桥接模式会断联。

作者视角补充：我专门测过 --net=host 的必要性。如果你尝试用 -p 端口映射启动，Roon 控制器（手机/平板 App）能连上，但 Roon 自家的 RAAT 播放器（比如连 Roon Ready 音箱）会全部掉线。这不是 bug，是 Roon 协议本身依赖广播发现，不走标准端口。

谁最该用？

NAS 用户（群晖、QNAP、Unraid 等）想用 Docker 跑 Roon 但不想折腾官方安装脚本
已经在用这个镜像的老用户，需要了解如何迁移到官方新镜像
准备新部署 Roon 的玩家：建议直接走官方镜像，但了解这个项目的架构有助于理解 Roon 的数据布局

三、动手实践

入门

环境准备

假设你已经有 Docker 环境（Docker Engine 20+，或 Docker Desktop），并且有一个存放音乐文件的目录。以下命令在 Linux / macOS 终端或群晖的 SSH 中执行。

启动旧版镜像（用于迁移前确认）

如果你还在用这个镜像，或想先跑起来看看 Roon 是什么，执行：

docker run -d \
  --name=roon-server \
  --restart=unless-stopped \
  --net=host \
  -e TZ="Asia/Shanghai" \
  -v roon-app:/app \
  -v roon-data:/data \
  -v /path/to/your/music:/music \
  -v /path/to/backups:/backup \
  steefdebruijn/docker-roonserver:latest

TZ 务必设置为你所在时区，否则 Roon 的日志时间会错乱
/path/to/your/music 换成你音乐文件夹的绝对路径
启动后等待 2-3 分钟（首次会下载 RoonServer 安装包），然后用手机 Roon App 或 Roon Remote 搜索服务器即可

迁移到官方 Docker 镜像（重点）

既然原项目已停更，强烈建议迁移。官方镜像的生成器在 RoonLabs/roon-docker，你可以填表单自动生成 docker-compose.yaml。

关键步骤：

创建新卷：官方镜像把 /app 和 /data 合并到了 /Roon 一个卷里，所以你需要一个新的卷，比如 roon-data-new
复制旧数据：把原来 roon-data 卷的内容拷过去

# 停止旧容器
sudo docker stop roon-server

# 复制旧 data 卷到新卷
sudo docker run --rm -ti \
  -v roon-data:/data \
  -v roon-data-new:/new \
  alpine cp -pr /data/* /new/

启动官方容器（按官网生成的命令启动，注意挂载 /Roon 卷和你的音乐目录）

常见踩坑

坑 1：迁移后控制器连不上服务器

2026 年 4 月 21 日之后，官方镜像把数据库路径从 /data/data 改成了 /data/database。如果你迁移后手机 App 找不到服务器，大概率是路径不对。修复方法：

# 进入新卷，把 data 目录重命名为 database
sudo docker run --rm -ti \
  -v roon-data-new:/data alpine \
  mv /data/data /data/database

坑 2：不要复用旧的 roon-app 卷

官方镜像不需要单独的程序卷，如果你把旧的 roon-app 也挂进去，会导致版本冲突。只用新的 /Roon 卷。

作者视角补充：这个坑我专门测过。如果你在官方镜像的 docker-compose.yaml 里误填了旧的 roon-app 卷路径，Roon 启动后会报 "corrupt database" 错误，因为官方镜像期望 /Roon 下面同时有 app 和 database 目录，但旧镜像的 roon-app 只有程序文件，没有数据库结构。

四、进阶玩法

深入 · 老手可选

自定义备份策略

Roon 的数据备份默认存在 /backup 卷里。你可以写一个 cron 任务，定期把备份卷打包到 NAS 的共享目录：

# 每周日凌晨 3 点备份 Roon 数据到 /mnt/nas/roon-backups
0 3 * * 0 docker run --rm -v roon-data:/data -v /mnt/nas/roon-backups:/backup alpine tar czf /backup/roon-$(date +\%Y\%m\%d).tar.gz -C /data .

使用 Early Access 版本

Roon 有稳定版和 Early Access 版。如果你需要尝鲜新功能，在官方镜像生成器里选择 latest 还是 earlyaccess 标签。原社区镜像也支持通过环境变量控制版本，但在停更后建议直接走官方。

自动化迁移脚本

如果你有大量配置要迁移，可以写一个脚本一键完成：停止旧容器 → 创建新卷 → 复制数据 → 启动新容器。以下是一个参考片段：

#!/bin/bash
# 一键迁移到 Roon 官方 Docker 镜像
OLD_DATA_VOL="roon-data"
NEW_DATA_VOL="roon-data-official"
MUSIC_DIR="/music"
BACKUP_DIR="/backup"

echo "Stopping old container..."
docker stop roon-server

echo "Creating new data volume..."
docker volume create $NEW_DATA_VOL

echo "Copying data..."
docker run --rm -v $OLD_DATA_VOL:/old -v $NEW_DATA_VOL:/new alpine sh -c "cp -pr /old/* /new/"

echo "Fixing database path (April 2026 change)..."
docker run --rm -v $NEW_DATA_VOL:/data alpine sh -c "if [ -d /data/data ]; then mv /data/data /data/database; fi"

echo "Done! Now run the official Roon container with volume $NEW_DATA_VOL"

五、判断与建议