elgeeko/roon-server

Roon Server Docker 镜像文档

1. 镜像概述与主要用途

本镜像提供 Docker 容器化的 Roon Server，用于构建个人音乐中心，支持本地音乐库管理、流媒体服务集成及多设备音频输出。通过 Docker 部署可实现环境隔离、简化安装流程，并确保跨平台一致性。

2. 核心功能与特性

• 自动更新：首次启动时自动下载并安装最新版 Roon Server，应用内升级可持久化保存
• 多音源支持：
  • 本地音乐库（通过目录挂载）
  • Tidal、Qobuz 等流媒体服务
• 多输出设备：
  • 主机连接的 USB DAC 设备
  • RAAT 设备（如 Roon 客户端、Roon Bridge、RoPieee 等）
  • 主机音频外设（内置扬声器、声卡等）
• 系统兼容性：
  • 本地时区支持（确保 last.fm 标签时间准确性）
  • 缓存持久化
• 安全部署：支持非特权容器运行，兼容 macvlan 网络隔离

3. 使用场景与适用范围

• 家庭音乐服务器：整合本地音乐库与流媒体服务，通过多设备输出音频
• 隔离部署环境：需与主机系统隔离的场景（如服务器多服务共存）
• 网络模式灵活适配：
  • 简单部署：使用 host 网络模式快速启动
  • 安全隔离：通过 macvlan 网络实现独立 IP 与网络隔离
  • 受限网络：桥接模式（需额外配置多播路由）

4. 前置准备

4.1 安装主机依赖

容器需访问主机音频设备，需先安装 ALSA 音频组件：

bash
apt install alsa-utils libasound2 libasound2-data libasound2-plugins

4.2 创建持久化存储

创建 Docker 卷用于持久化 Roon Server 程序文件与配置：

bash
# Roon Server 程序文件存储卷
docker volume create roon-server-data
# 缓存与临时数据存储卷
docker volume create roon-server-cache

4.3 本地音乐库（可选）

若需挂载本地音乐库，创建目录并确保权限：

bash
mkdir -p ~/roon/music  # 示例路径，可自定义

5. 部署与使用指南

5.1 快速启动（Host 网络模式）

适用于大多数场景，支持全部功能：

bash
# 获取音频组 GID（用于设备权限）
AUDIO_GID=$(getent group audio | cut -d: -f3)

# 启动容器（含本地音频支持）
docker run \
  --name roon-server \
  --detach \
  --volume roon-server-data:/opt/RoonServer \  # 程序文件持久化
  --volume roon-server-cache:/var/roon \       # 缓存持久化
  --volume ~/roon/music:/music:ro \            # 本地音乐库（可选，只读）
  --network host \                             # Host 网络模式
  --restart unless-stopped \                   # 异常退出后自动重启
  --volume /run/udev:/run/udev:ro \            # 监听 USB 设备变化
  --device /dev/bus/usb \                      # 映射 USB 总线
  --device /dev/snd \                          # 映射音频设备
  --group-add "${AUDIO_GID:-29}" \             # 添加音频组权限
  elgeeko/roon-server

查看日志

bash
docker logs -f roon-server  # 实时查看启动日志，确认服务正常运行

5.2 详细部署步骤

5.2.1 Host 网络模式（简易模式）

无本地音频支持（仅通过 RAAT 设备输出）：

bash
docker run \
  --name roon-server \
  --detach \
  --volume roon-server-data:/opt/RoonServer \
  --volume roon-server-cache:/var/roon \
  --volume ~/roon/music:/music:ro \
  --network host \
  --restart unless-stopped \
  elgeeko/roon-server

带本地音频支持（如 USB DAC）：
使用 4.1 中的完整命令，关键参数说明：

• --volume /run/udev:/run/udev:ro：监听 USB 设备插拔事件
• --device /dev/bus/usb：允许访问 USB 设备
• --device /dev/snd：允许访问 ALSA 音频设备
• --group-add "${AUDIO_GID:-29}"：添加音频组权限（默认 GID 29）

5.2.2 macvlan 网络模式（安全隔离）

通过 macvlan 为容器分配独立 IP，实现网络隔离（需有线网络，不支持 Wi-Fi）。

创建 macvlan 网络（替换为实际网络参数）：

bash
docker network create \
  --driver macvlan \
  --subnet 192.168.1.0/24 \    # 本地子网（如 192.168.1.x）
  --gateway 192.168.1.1 \      # 网关 IP（路由器 IP）
  -o parent=eth0 \             # 主机网卡（如 eth0、enp0s3）
  roon-network                 # 网络名称（自定义）

启动容器（无本地音频）：

bash
docker run \
  --name roon-server \
  --detach \
  --volume roon-server-data:/opt/RoonServer \
  --volume roon-server-cache:/var/roon \
  --volume ~/roon/music:/music:ro \
  --network roon-network \      # 使用创建的 macvlan 网络
  --restart unless-stopped \
  --ip 192.168.1.2 \            # 分配给容器的静态 IP
  elgeeko/roon-server

启动容器（带本地音频）：
在上述命令基础上添加音频相关参数：

bash
AUDIO_GID=$(getent group audio | cut -d: -f3)
docker run \
  ...（上述参数）...
  --volume /run/udev:/run/udev:ro \
  --device /dev/bus/usb \
  --device /dev/snd \
  --group-add "${AUDIO_GID:-29}" \
  elgeeko/roon-server

5.2.3 桥接网络模式（受限场景）

桥接模式默认不支持 RAAT 设备发现（需多播路由配置），仅推荐用于仅需主机本地音频输出的场景。需手动映射端口（参考 Dockerfile 源码），并配置主机防火墙。

5. 高级配置

5.1 USB DAC 设备支持

确保容器命令包含以下参数（已在带音频支持的启动命令中集成）：

• --volume /run/udev:/run/udev:ro：监听 USB 设备变化
• --device /dev/bus/usb：USB 总线访问权限
• --device /dev/snd：ALSA 音频设备访问
• --group-add $(getent group audio | cut -d: -f3)：音频组权限

5.2 时区配置

添加以下参数确保时区正确（如北京时间）：

bash
--env TZ=Asia/Shanghai \          # 设置环境变量 TZ
--volume /etc/localtime:/etc/localtime:ro  # 挂载主机时区文件

6. 故障排除

6.1 网络或设备发现问题

若设备无法发现 Roon Server 或音频输出异常，可添加以下参数诊断（逐步测试，定位问题后移除）：

• --cap-add SYS_ADMIN：授予系统管理权限（解决挂载/命名空间操作限制）
• --security-opt apparmor:unconfined：禁用 AppArmor 限制（解决设备/文件访问被拒）
• --privileged：特权模式（绕过所有隔离限制，仅用于诊断）

7. 已知问题

• USB DAC 首次连接不显示：需重启容器；后续插拔可自动识别。
• CIFS 网络目录挂载：需以 root 用户运行容器（添加 --user root）。
• Fedora CoreOS 系统：默认文件描述符限制过低，需添加 --ulimit nofile=8192。

8. 构建镜像（可选）

从源码构建镜像：

bash
git clone <镜像源码仓库>
cd <仓库目录>
docker build . -t elgeeko/roon-server

9. 相关资源

• Docker Hub 镜像：https://hub.docker.com/repository/docker/elgeeko/roon-server
• Ansible 部署脚本：https://github.com/elgeeko1/elgeeko1-roon-server-ansible%EF%BC%88%E5%90%AB Samba 共享配置）
• Roon 官方 Linux 安装文档：Roon Labs Linux install instructions