Lyrion Music Server 9.1.1 配置参数详解

目标：讲清 Lyrion Music Server 9.1.1 配置体系的三种载体（Web 设置页、CLI pref 命令、server.prefs 文件）及其等价关系，逐类详解核心参数的实测值、默认行为与生效方式，并给出可直接落地的生产配置模板。本文所有参数值与命令回显均在真实部署环境实测取得。

一、环境信息

项目	值	说明
组件版本	Lyrion Music Server 9.1.1	CLI `version ?` 实测回显
配置根目录	/config	服务端主程序以 `--prefsdir /config/prefs --logdir /config/logs --cachedir /config/cache` 启动
主配置文件	/config/prefs/server.prefs	全部服务端参数的单文件存储
日志配置文件	/config/prefs/log.conf	日志类别与级别的持久化配置
媒体库数据库	/config/cache/library.db（SQLite）	`dbsource` 参数实测值 `dbi:SQLite:dbname=/config/cache/library.db`
媒体库目录	/music	`audiodir` 实测值
播放列表目录	/playlist	`playlistdir` 实测值
Web/CLI 端口	9000 / 9090	`httpport` 实测值 9000；9090 固定
目录视角约定	配置值均为服务端自身视角路径	若按《Lyrion Music Server 9.1.1 Docker Compose 部署指南》部署，/config、/music、/playlist 分别对应宿主挂载的 config、music、playlist 目录

二、前置条件

已按《Lyrion Music Server 9.1.1 Docker Compose 部署指南》完成部署，服务端可达（Web 9000 端口与 CLI 9090 端口）。
配置目录对服务端运行账号可写（server.prefs 由服务端首次启动自动生成，实测部署层 PUID/PGID 对齐后无权限问题）。
具备任一修改通道的访问条件：浏览器（Web 设置页）或 telnet 客户端（9090）。

三、参数查看与修改方式

LMS 的参数有三种等价载体，改动最终都落到同一个 server.prefs 文件：

载体	适用场景	生效特点
Web 设置页（9000 端口）	日常维护，有界面引导与校验	大部分即改即生效，目录类改动会引导重扫
CLI `pref` 命令（9090 端口）	批量部署、自动化脚本	写入即持久化到 server.prefs
server.prefs 文件	审计、迁移、备份恢复	服务端启动时读入；运行中手改文件不会被读回

3.1 CLI 查询语法与 URL 编码

查询格式为 pref <键名> ?，实测（telnet 9090）：

$ telnet 127.0.0.1 9090
pref language ?
pref language EN
pref audiodir ?
pref audiodir %2Fmusic
pref playlistdir ?
pref playlistdir %2Fplaylist
pref httpport ?
pref httpport 9000

三个要点：

路径类参数的回显是 URL 编码形态（%2F 即 /），对照 Web 设置页时先解码。
键名不需要任何前缀，pref audiodir ? 直接可查。
写入格式为 pref <键名> <值>，例如 pref remotestreamtimeout 30。

3.2 文件侧审计

server.prefs 为键值文本文件，宿主侧直接可读，适合做配置基线核对：

$ grep -E '^(audiodir|playlistdir|httpport|language|dbsource)' config/prefs/server.prefs
audiodir: /music
playlistdir: /playlist
httpport: 9000
language: EN
dbsource: dbi:SQLite:dbname=/config/cache/library.db

文件格式为 键名: 值，与 CLI 查询结果一一对应。修改配置优先走前两种载体；直接改文件仅建议在服务端停止时进行，避免运行中写回覆盖。

四、参数总览

以下为实测环境 server.prefs 中与部署和运维直接相关的参数总览（值为实测环境实际值；「默认未显式配置」表示该键在实测文件中不存在，服务端按内置默认运行）：

参数	实测值	作用	修改后生效方式
audiodir	/music	媒体库根目录	保存后提示重扫
playlistdir	/playlist	播放列表保存目录	即时生效
cachedir	/config/cache	缓存（含媒体库数据库）目录	需重启
librarycachedir	/config/cache	库缓存目录	需重启
dbsource	dbi:SQLite:dbname=/config/cache/library.db	数据库连接源	需重启
dbusername	slimserver	数据库连接用户名（SQLite 下仅形式参数）	需重启
dbpassword	空	数据库连接口令（SQLite 下留空）	需重启
httpport	9000	Web/音频流监听端口	需重启
language	EN	界面语言	即时生效
scannerPriority	0	扫描进程优先级（0 为正常）	下次扫描生效
groupdiscs	1	多碟专辑合并为一张	重扫生效
playtrackalbum	1	播放曲目时定位到整张专辑	即时生效
persistPlaylists	1	播放器队列持久化	即时生效
saveShuffled	0	随机播放列表是否保存	即时生效
remotestreamtimeout	15	远端流（电台/插件）连接超时秒数	即时生效
authorize	0	Web 访问鉴权开关	需重启
coverArt	空	全局封面覆盖	即时生效
log.player.streaming	DEBUG	日志类别覆盖（实测为排查写入）	多数日志类需重启

总览表之外的其余键大多为 Web 界面各设置页的细项（浏览模式、电台开关、插件配置等），遵循同样的 pref 读写方式，此处不逐项罗列。

五、核心参数分类详解

5.1 媒体库与存储（audiodir / playlistdir / cachedir / dbsource）

四个参数构成存储坐标系：audiodir 告诉服务端「曲库在哪」，playlistdir 决定「播放列表存哪」，cachedir/librarycachedir 决定「编目数据写哪」，dbsource 则是数据库的连接源。实测部署的完整链路：

$ grep -E '^(audiodir|playlistdir|cachedir|librarycachedir|dbsource)' config/prefs/server.prefs
audiodir: /music
playlistdir: /playlist
cachedir: /config/cache
librarycachedir: /config/cache
dbsource: dbi:SQLite:dbname=/config/cache/library.db

配套实测的媒体库核对结果：曲库目录 11 个文件中 10 个有效入编（info total songs ? 回显 10），1 个扫描后被移除的文件在 scanned_files 表留失效记录但不计数。这印证了 audiodir 与库数据的关系：库内容是 audiodir 的一次编目快照，目录变更不会自动反映，必须触发重扫。

修改 audiodir 的标准流程（实测验证过「改后库空」的坑，见 7.2 节）：

$ telnet 127.0.0.1 9090
pref audiodir /newmusic
pref audiodir /newmusic
wipecache
rescan done
info total songs ?
info total songs 0

wipecache 清空库缓存后必须再触发 rescan 才会按新目录重建（上例回显为库计数归零的中间态，重扫完成后按新目录计数）。

技术拓展：SQLite 嵌入式数据库 dbsource 的实测值表明 9.1.1 默认使用进程内嵌的 SQLite 存储媒体库（文件 library.db），连接用户名/口令参数仅作形式保留。这是 LMS 开箱即用的关键——无外部数据库依赖；代价是缓存目录所在分区需要足够的 IOPS，曲库数万级时首次扫描与全量重建对磁盘压力明显。把 cachedir 指到快速磁盘是把大库扫描时间从分钟级压到十秒级最有效的手段。

5.2 服务端口与语言（httpport / language）

httpport 是 Web 与音频流的内部监听端口，实测 9000。它与部署层端口映射的关系：配置值是服务端自身视角，宿主访问端口由部署层的映射决定（本环境 9000 映射到宿主 8129）。改这个参数必须重启服务端，且要同步调整部署层映射，否则 Web 与推流地址会错位（故障形态见《Docker Compose 部署指南》11.2 节）。

language 实测 EN，控制 Web 界面语言与部分日志文案。写入即生效（刷新页面可见），无需重启：

pref language ZH_CN
pref language ZH_CN

5.3 扫描行为（scannerPriority / groupdiscs）

参数	实测值	语义
scannerPriority	0	扫描进程的 CPU 优先级；正值调低优先级（大库扫描不挤占播放），0 为正常
groupdiscs	1	多碟专辑（同一专辑名不同碟号）合并展示

实测环境 11 文件小库，扫描数秒完成，两个参数均用默认即可。大曲库（万级以上）的建议：scannerPriority 设 5-10，把扫描让位给在线播放；groupdiscs 保持 1，避免多碟专辑在浏览页碎成多张。

失效扫描记录的自动清账行为（11 文件 → 10 曲目计数）在扫描章节已实测，属于「全量重扫时清理 scanned_files 失效条目」的默认机制，无需额外配置。

5.4 播放与流媒体（remotestreamtimeout / persistPlaylists / playtrackalbum / saveShuffled）

$ telnet 127.0.0.1 9090
pref remotestreamtimeout ?
pref remotestreamtimeout 15
pref persistPlaylists ?
pref persistPlaylists 1

remotestreamtimeout 15：远端流（网络电台、在线插件）建立连接的超时秒数。实测环境默认 15；弱网环境调到 30-60 可显著减少「电台播放失败」，本地局域网客户端推流不受此参数影响。
persistPlaylists 1：每个播放器的当前队列在服务端持久化（实测产物为 prefs/clientplaylist_045382816739.m3u，以播放器 ID 命名），播放器断连重连后队列不丢。
playtrackalbum 1：播放单曲时以整张专辑上下文排队，符合专辑聆听习惯。
saveShuffled 0：随机播放生成的临时列表不落盘，避免污染播放列表目录。

5.5 访问控制（authorize）

实测值 authorize: 0，即 Web 界面与控制面无鉴权。这与 LMS「信任局域网」的产品模型一致；需要口令保护时在 Web 设置页开启（对应 authorize: 1 并写入口令项），示例管理口令 q1w2e3r4，生产环境务必使用强口令。开启后需重启服务端生效。口径提醒：无论是否开鉴权，都不应把 9000/9090 直接暴露公网。

5.6 日志体系（log.conf 与 log.* 参数）

日志配置分两层：prefs/log.conf 文件为持久化基线，log.<类别> 参数为运行时覆盖。实测环境为排查播放链路问题，通过 CLI 写入过六类 DEBUG 级别并已持久化：

$ grep -E '^log\.' config/prefs/server.prefs
log.control.command: DEBUG
log.network.asynchttp: DEBUG
log.network.http: DEBUG
log.network.protocol.slimproto: DEBUG
log.player.audio: DEBUG
log.player.source: DEBUG
log.player.streaming: DEBUG

日志类别按组件层级命名，常用的有：player.source（转码链路选择）、player.streaming（音频流推送）、player.audio（解码输出）、network.protocol.slimproto（播放器协议交互）、control.command（CLI 命令处理）、scan.*（扫描各阶段）。排障时按问题域打开对应类别的 DEBUG 即可，粒度远比整库调级精细。

六、生产配置模板

模板一：家用服务器，2-4 个房间播放点，本地曲库约 5 万首。核心诉求是扫描不抢播放资源、断电后队列不丢、远端电台稳定：

audiodir: /music
playlistdir: /playlist
cachedir: /config/cache
scannerPriority: 5
remotestreamtimeout: 30
persistPlaylists: 1
playtrackalbum: 1
authorize: 1
language: EN

等价的一组 CLI 命令（一次执行完即持久化）：

$ telnet 127.0.0.1 9090
pref audiodir /music
pref playlistdir /playlist
pref scannerPriority 5
pref remotestreamtimeout 30
pref persistPlaylists 1
pref playtrackalbum 1
pref authorize 1

模板二：自动化验证环境（本文实测形态）。核心诉求是链路可观测、不落任何真实音频输出、随时可重扫重建：

audiodir: /music
playlistdir: /playlist
scannerPriority: 0
remotestreamtimeout: 15
persistPlaylists: 1
authorize: 0
log.player.source: DEBUG
log.player.streaming: DEBUG
log.network.protocol.slimproto: DEBUG

两份模板的差异点一目了然：扫描优先级与远端超时按曲库规模和网络环境调；日志开关只保留在验证环境，生产环境调 DEBUG 前先评估磁盘写入量。

七、常见问题（排障实录）

7.1 通过 CLI 写入日志级别后没有日志输出

现象：执行 pref log.player.streaming DEBUG 回显正常，随后触发播放，logs/server.log 中没有任何 streaming 级别的新增行。

排查：先核对参数确已写入：

$ telnet 127.0.0.1 9090
pref log.player.streaming ?
pref log.player.streaming DEBUG
$ grep streaming config/prefs/server.prefs
log.player.streaming: DEBUG

判定与处置：参数已持久化但当前进程未重新加载日志配置——多数日志类别的级别变更需重启服务端生效。实测执行服务端重启后再次触发播放，streaming 类日志按 DEBUG 输出。

经验：pref 写入只保证「记住了」，不保证「当前进程立刻执行」；配置类变更后先判断该键的生效方式（见第四节总览表），需要重启的批量化处理，避免逐项试错。

7.2 修改 audiodir 后浏览页变空

现象：把 audiodir 指到新目录后，浏览页专辑/曲目清零。

定位：媒体库是 audiodir 的编目快照（缓存在 cachedir 的 library.db），改指向不会自动重编。

处置：触发一次全量重建（Web 设置页「清除缓存并重新扫描」，或 CLI wipecache 后 rescan），完成后用 info total songs ? 验证计数。若新目录含子目录多、文件量大，期间 Web 会出现「正在扫描」横幅，等待即可。

7.3 远端电台频繁播放失败

现象：本地曲目播放正常，网络电台随机性失败。

处置：pref remotestreamtimeout 30 后观察；仍失败则打开 log.network.http 与 log.remotestream 的 DEBUG 并重启，按超时/连拒的具体报错分类处理。内网隔离环境该类功能本身不可用，不属于参数问题。

7.4 多实例端口冲突

同机部署第二套 LMS 验证环境时，httpport 必须错开（如 9100），SLIM 协议 3483 同样不能共存（后启动方注册失败）。建议每套实例用独立网络与独立端口集，配置值与映射同步规划。

八、参考链接

官方文档与 Wiki：https://lyrion.org（配置参考在 Wiki 的 Server Settings 章节）
源码仓库：https://github.com/LMS-Community/slimserver
服务端内置 CLI 参考：http://<服务器地址>:9000/html/docs/cli-api.html
本专栏相关篇目：《Lyrion Music Server 9.1.1 介绍与选型指南》《Lyrion Music Server 9.1.1 Docker Compose 部署指南》《Lyrion Music Server 9.1.1 CLI 命令详解》