SwingMusic 3.0.0 配置参数详解

目标：本文逐项讲解 SwingMusic 3.0.0 的配置体系——settings.json 全部参数、环境变量与命令行选项的含义、默认值与实测改法，并给出家庭服务器场景的生产配置模板。全部查看与修改操作在 Ubuntu 24.04 服务器（v3.0.0，配置目录 /srv/swingmusic/config/swingmusic/，曲库 4 首）实测通过。

一、环境信息

• 操作系统：Ubuntu 24.04（x86_64）
• SwingMusic：v3.0.0（GET /notsettings 实测回显 version: 3.0.0）
• 配置文件：/srv/swingmusic/config/swingmusic/settings.json（部署路径见《SwingMusic 3.0.0 Docker Compose 部署指南》；脚本安装默认在 ~/.config/swingmusic/）
• 数据文件：同目录下 swingmusic.db（曲库元数据）+ userdata.db（用户数据，同名伴生 -wal/-shm）
• 曲库：4 首测试音频（2 张专辑：Tidal Lines、晨雾专辑；2 位艺术家：Blue Harbor、秋日山道）
• 服务端口：8154（进程内 1970）
• 演示账号：admin / q1w2e3r4

二、前置条件

1. 服务已部署并可访问（部署见《SwingMusic 3.0.0 Docker Compose 部署指南》），探活：

curl -s -o /dev/null -w 'GET / -> %{http_code}\n' http://localhost:8154/

实测输出：

GET / -> 200

2. 准备管理员登录态（本文改参操作多数要求 admin 角色）：

curl -s -X POST http://localhost:8154/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}' -c /tmp/sm-ck.txt -o /dev/null -w 'login -> %{http_code}\n'

实测输出：

login -> 200

3. 能读写配置文件（服务器本地路径 /srv/swingmusic/config/swingmusic/）。

三、参数查看与修改方式

SwingMusic 的参数有三个查看/修改入口，生效机制各不相同，实测归纳如下。

3.1 直接查看：读配置文件

settings.json 是唯一持久化层，全部参数与当前生效值一屏可见：

python3 -c "
import json
d = json.load(open('/srv/swingmusic/config/swingmusic/settings.json'))
for k in ['serverId','usersOnLogin','rootDirs','excludeDirs','artistSeparators','extractFeaturedArtists','mergeAlbums','cleanAlbumTitle','showAlbumsAsSingles','enablePeriodicScans','scanInterval','enableWatchdog','showPlaylistsInFolderView','enablePlugins','trustCloudLyrics','artistArticleAwareSorting','licenseKey']:
    print(f'{k} = {json.dumps(d.get(k), ensure_ascii=False)}')"

实测输出：

serverId = "664ef584ebbd67d8078276d7df2b7449dba23d9354811a2d842a5e2147448f2e"
usersOnLogin = true
rootDirs = ["/music"]
excludeDirs = []
artistSeparators = ["/", ";"]
extractFeaturedArtists = true
mergeAlbums = false
cleanAlbumTitle = true
showAlbumsAsSingles = false
enablePeriodicScans = false
scanInterval = 10
enableWatchdog = false
showPlaylistsInFolderView = false
enablePlugins = true
trustCloudLyrics = false
artistArticleAwareSorting = false
licenseKey = ""

serverId 是首启随机生成的 64 位十六进制服务标识（JWT 密钥由它派生），整个文件里它是唯一不应手工改动的键。

3.2 运行时修改：管理 API（推荐，立即生效且自动写回）

Web 设置页的每次保存等价于一次 PUT /notsettings/update，改完立即生效、自动写回 settings.json，部分键还会自动重建内存索引。实测把扫描间隔 10 分钟改为 15 分钟：

curl -s -b /tmp/sm-ck.txt -X PUT http://localhost:8154/notsettings/update \
  -H 'Content-Type: application/json' -d '{"key":"scanInterval","value":15}'

实测输出：

{"msg":"Config updated!"}

立即核对文件已同步写回：

grep -o '"scanInterval": [0-9]*' /srv/swingmusic/config/swingmusic/settings.json

实测输出：

"scanInterval": 15

改回默认值（恢复 10）：

curl -s -b /tmp/sm-ck.txt -X PUT http://localhost:8154/notsettings/update \
  -H 'Content-Type: application/json' -d '{"key":"scanInterval","value":10}' && \
grep -o '"scanInterval": [0-9]*' /srv/swingmusic/config/swingmusic/settings.json

实测输出：

{"msg":"Config updated!"}
"scanInterval": 10

源码标注：artistSeparators、artistSplitIgnoreList、removeProdBy、removeRemasterInfo、mergeAlbums、cleanAlbumTitle、showAlbumsAsSingles 这 7 个键被更新时会自动触发全量重扫（重建内存 Store），其余键即时生效无需重扫。

曲库根目录是独立接口（改完自动全量重扫）：

curl -s -b /tmp/sm-ck.txt http://localhost:8154/notsettings/get-root-dirs

实测输出：

{"dirs":["/music"]}

3.3 运行时查看：聚合接口

GET /notsettings 返回配置与运行时派生信息的合并视图（比文件多出 version/deviceName/deviceId/licenseInfo/plugins 等派生字段）：

curl -s -b /tmp/sm-ck.txt http://localhost:8154/notsettings | python3 -c "
import json,sys
d = json.load(sys.stdin)
print('version:', d.get('version'), '| deviceName:', d.get('deviceName'), '| deviceId:', d.get('deviceId','')[:16]+'...', '| rootDirs:', d.get('rootDirs'))"

实测输出：

version: 3.0.0 | deviceName: swingmusic-lab | deviceId: 664ef584ebbd67d8... | rootDirs: ['/music']

3.4 直改文件的方式与代价

settings.json 也可以直接编辑，但改完必须重启服务才生效（内存中的 Store 不会感知文件变化），且手工改曲库类参数不会触发自动重扫：

cd /srv/swingmusic && docker compose restart

结论：日常调参一律走 Web 设置页或 PUT /notsettings/update；只有服务无法启动（参数改坏导致起不来）时才需要手工编辑文件救援。

四、参数总览

settings.json 全部键按功能域归类如下（默认值以 v3.0.0 首启生成为准，实测与源码一致）：

💡 说明：artistSortingArticles（a/the/der/les…38 词）与 artistSplitIgnoreList（Simon & Garfunkel、Earth, Wind & Fire 等 76 组合）由官方内置并随版本维护，一般无需改动；表格只列行为，不展开全表。

五、核心参数分类详解

5.1 服务与身份（serverId / usersOnLogin / licenseKey）

serverId（64 位十六进制，只读）：首启随机生成，是全服务的信任根——JWT 登录令牌用它派生签名密钥，移动 App 配对、许可绑定也都与设备身份挂钩。实测删除或更换它会导致全部登录态失效（与删除 private.key 同效，见《SwingMusic 3.0.0 Docker Compose 部署指南》FAQ Q3）。

usersOnLogin（默认 true）：控制登录页是否直接列出全部用户头像供点选。家庭场景多人使用保持 true 最方便；对公网暴露的实例建议改 false（登录页不暴露用户名清单，登录需手输用户名）：

curl -s -b /tmp/sm-ck.txt -X PUT http://localhost:8154/notsettings/update \
  -H 'Content-Type: application/json' -d '{"key":"usersOnLogin","value":false}'

实测输出：

{"msg":"Config updated!"}

licenseKey（默认空）：Mixes 等 Premium 功能的许可键（40 字符，形如 SMX-XXXX-…，每许可最多 3 台设备）。免费实例为空串即可，付费功能状态可查：

curl -s -b /tmp/sm-ck.txt http://localhost:8154/notsettings/license/status -w '\nHTTP %{http_code}\n'

实测输出（无许可时 404，属预期）：

{"client_id":"Ov23li5bsrEqMmqdT10i","error":"No license found","redirect_url":"https://cloud.swingmx.com/auth/github/callback"}

HTTP 404

5.2 曲库目录（rootDirs / excludeDirs）

rootDirs：音乐根目录数组，扫描与文件夹视图的起点。可设多个（多磁盘场景数组追加），均为容器/服务视角路径：

curl -s -b /tmp/sm-ck.txt -X POST http://localhost:8154/notsettings/add-root-dirs \
  -H 'Content-Type: application/json' \
  -d '{"new_dirs":["/music2"],"removed":[]}'

实测输出（改完自动全量重扫）：

{"root_dirs":["/music","/music2"]}

⚠️ 注意：rootDirs 改动会立即触发全量重扫；新增目录必须真实存在且服务进程可读，指向不存在目录的条目会导致扫描批次对它报错（本文 /music2 未挂载，仅演示接口形态，验证后立即回删）。

验证后立即用同一接口回删：

curl -s -b /tmp/sm-ck.txt -X POST http://localhost:8154/notsettings/add-root-dirs \
  -H 'Content-Type: application/json' -d '{"new_dirs":[],"removed":["/music2"]}'

实测输出：

{"root_dirs":["/music"]}

回删后复查目录与曲库完好：

curl -s -b /tmp/sm-ck.txt http://localhost:8154/notsettings/get-root-dirs
curl -s -o /dev/null -w 'GET / -> %{http_code}\n' http://localhost:8154/

实测输出：

{"dirs":["/music"]}
GET / -> 200

excludeDirs：排除目录数组（相对 rootDirs 下的子路径），用于跳过不需要入库的目录（如采样、翻录废稿）。默认空数组即全扫。

5.3 艺术家拆分与专辑清洗（元数据管线）

这一组参数决定「文件名/标签里的字符串」如何变成结构化的艺术家与专辑，是 SwingMusic 曲库质量的核心：

• artistSeparators（默认 ["/", ";"]）：标签里 A/B、A;B 会拆成 A、B 两位艺术家。改此键触发全量重扫；
• artistSplitIgnoreList：内置 76 个「看起来像合作但其实是组合」的名字（如 Simon & Garfunkel、Earth, Wind & Fire、AC/DC），拆分时跳过。注意 & 和 + 不在默认分隔符里，名单主要防未来扩展误拆；
• extractFeaturedArtists（默认 true）：A feat. B 的 B 从主艺术家中剥离，只在曲目级标注；
• removeProdBy（默认 true）：剥除曲名里 Prod. by X 段；
• removeRemasterInfo（默认 true）：剥除曲名/专辑名里 (Remastered 2011)、- Live 等版本尾巴；
• mergeAlbums（默认 false）：同名专辑（不同目录/年份）是否合并为一张；开启后同曲名专辑归一，按目录组织的曲库建议保持 false；
• cleanAlbumTitle（默认 true）：专辑名去掉 (Deluxe Edition) 等修饰尾巴，og_title 字段保留原名（实测专辑接口同时返回 title 与 og_title）；
• showAlbumsAsSingles（默认 false）：单曲专辑在列表中的展示形态；
• artistArticleAwareSorting（默认 false，v3.0.0 新增）：开启后 The Beatles 按 B 排序而非 T，配合 artistSortingArticles 冠词表工作。

5.4 扫描节奏（trigger / periodic / watchdog）

💡 技术拓展：本地曲库的「新文件发现机制」常见三种——手动触发（零开销，最省资源）、周期轮询（按固定间隔全库比对，简单可靠）、文件看门狗（内核事件实时感知，最即时但有常驻开销）。SwingMusic 三种全有且可叠加，默认只开手动触发。本文实验曲库低频更新，采用「手动触发为主」；若挂载网盘目录（事件不可靠）建议用周期扫描而非看门狗。

• 手动触发（默认唯一启用的路径）：GET /notsettings/trigger-scan 或 Web 设置页扫描按钮：

curl -s -b /tmp/sm-ck.txt http://localhost:8154/notsettings/trigger-scan

实测输出：

{"msg":"Scan triggered!"}

增量行为实测实录：初版曲库 3 首入库后，用 ffmpeg 生成第 4 首 Sea Glass（带完整 ID3：title/artist/album/date/genre/track）放入 Tidal Lines 目录，触发扫描后复查：

curl -s -b /tmp/sm-ck.txt -X POST http://localhost:8154/album \
  -H 'Content-Type: application/json' -d '{"albumhash":"0a5ebd99f07e6619"}' \
  | python3 -c "import json,sys; d=json.load(sys.stdin); print('trackcount:', d['info']['trackcount'], '| tracks:', [(t['track'], t['title']) for t in d['tracks']])"

实测输出：

trackcount: 2 | tracks: [(1, 'Salt Air'), (2, 'Sea Glass')]

结论：扫描是增量的——已有文件不重扫（封面、哈希复用），新文件按 ID3 归入既有专辑（track 序号沿用标签），专辑曲目数实时更新，无需重启。检索接口同轮实测命中新曲目（/search/?q=Sea Glass&itemtype=tracks）。

• enablePeriodicScans / scanInterval（false / 10）：开启后按 scanInterval 分钟自动触发扫描（调度间隔按设置页保存时刻起算）。实测开关写回（开→文件即时同步，再关→恢复）：

curl -s -b /tmp/sm-ck.txt -X PUT http://localhost:8154/notsettings/update \
  -H 'Content-Type: application/json' -d '{"key":"enablePeriodicScans","value":true}'
grep -o '"enablePeriodicScans": [a-z]*' /srv/swingmusic/config/swingmusic/settings.json

实测输出：

{"msg":"Config updated!"}
"enablePeriodicScans": true

回关：

curl -s -b /tmp/sm-ck.txt -X PUT http://localhost:8154/notsettings/update \
  -H 'Content-Type: application/json' -d '{"key":"enablePeriodicScans","value":false}'

实测输出：

{"msg":"Config updated!"}

家庭曲库建议 scanInterval 30–60 分钟，默认 10 分钟对小机器略频；

• enableWatchdog（false）：基于文件系统事件的实时监听，音频文件变更即触发扫描。实测开启后对曲库内非音频文件的 touch 不触发扫描批次（日志无扫描行，事件按音频扩展名过滤）；网络文件系统（NFS/SMB）上事件不可靠，建议改用周期扫描。

5.5 界面与杂项（showPlaylistsInFolderView）

showPlaylistsInFolderView（默认 false）：文件夹视图里把播放列表也作为一个「目录」显示。纯文件管理习惯的实例保持 false，避免与真实目录混淆。

5.6 插件与歌词（enablePlugins / lastfm* / trustCloudLyrics）

• enablePlugins（默认 true）：插件总开关，关闭后歌词、Last.fm 接入点全部下线；
• lastfmApiKey / lastfmApiSecret：官方内置的公开接入对，用户只需在设置页发起 Last.fm 授权，授权后的会话键按用户落在 lastfmSessionKeys（结构 {"<userid>": "key"}，管理聚合接口只回显当前用户自己的键）；
• trustCloudLyrics（默认 false）：歌词插件是否直接信任云端返回的歌词文本；开启省事，关闭则要求来源可信度校验，公网实例建议保持 false。

六、生产配置模板

适用场景：家庭/小组服务器，2–4 GB 内存、机械盘或 SATA SSD、曲库 1–10 万首、低频更新（每周补几张专辑）。以下为在默认值基础上建议调整的差量模板（其余键保持默认）：

{
  "rootDirs": ["/music"],
  "excludeDirs": [],
  "usersOnLogin": false,
  "enablePeriodicScans": true,
  "scanInterval": 60,
  "enableWatchdog": false,
  "mergeAlbums": false,
  "cleanAlbumTitle": true,
  "extractFeaturedArtists": true,
  "artistArticleAwareSorting": true,
  "enablePlugins": true,
  "trustCloudLyrics": false,
  "licenseKey": ""
}

逐项理由：usersOnLogin: false 收敛登录页信息暴露；scanInterval: 60（分钟）在低频更新下把后台比对降到每小时一次；enableWatchdog: false 避免本地盘无意义的事件监听；mergeAlbums: false 尊重磁盘目录结构；artistArticleAwareSorting: true 让 The/A 开头艺术家按习惯排序；资源占用实测基线——空闲态 RSS 约 138 MiB（docker stats --no-stream 实测 MEM=138.3MiB / 15.57GiB），扫描 4 首级曲库秒级完成，万首级曲库内存 Store 预计仍在数百 MB 内。

⚠️ 注意：模板只含「与默认不同的键」；手工落盘后需 docker compose restart 生效（见 3.4），日常增改仍建议走 Web 设置页实时生效。

七、环境变量与命令行选项

7.1 环境变量

配置目录落点规则（源码 Paths 类实测归纳）：在「父目录」下建名为 swingmusic 的子目录存放全部数据；仅当父目录就是家目录时目录名改用 .swingmusic（隐藏目录）。官方镜像以 HOME=/music、数据目录 /config/swingmusic 的约定工作，首启日志实测打印 Data folder: /config/swingmusic。

7.2 命令行选项

swingmusic --help 实测回显：

usage: swingmusic [-h] [-v] [--host HOST] [--port PORT] [--debug]
                  [--config CONFIG] [--client CLIENT] [--password-reset]
                  [--test-pro-imports]

Awesome Music

options:
  -h, --help          show this help message and exit
  -v, --version       show program's version number and exit
  --host HOST         Host to run the app on. (default: 0.0.0.0)
  --port PORT         HTTP port to run the app on. Falls back to
                      $SWINGMUSIC_PORT, then 1970. (default: 1970)
  --debug             If swingmusic should start in debug mode (default:
                      False)
  --config CONFIG     The directory to setup the config folder. (default:
                      /music)
  --client CLIENT     Path to the Web UI folder. (default: None)

Tools:
  --password-reset    Reset the password. (default: False)

版本与重置两例实测：

swingmusic --version

实测输出：

swingmusic v3.0.0

swingmusic --password-reset   # 交互式输入用户名与新口令，重置指定管理员密码

⚠️ 注意：--config 指定的是配置「父目录」（实际数据落在其下 swingmusic/ 子目录）；镜像内默认值显示为 /music 是官方镜像以 HOME 约定预设的结果，脚本安装场景默认父目录为 ~/.config。

八、常见问题（FAQ）

Q1：改了 settings.json 但界面行为没变？ 原因：内存 Store 不感知文件变化，直改文件必须重启服务（见 3.4）。解决：docker compose restart 后复查；或以后直接走 Web 设置页 / PUT /notsettings/update 实时生效（实测 scanInterval 改 15 后文件即时写回，回改 10 同样即时）。

Q2：放了新歌，扫描没动静？ 默认三种发现机制只开了手动触发。解决：手动 GET /notsettings/trigger-scan（回显 {"msg":"Scan triggered!"}），或开 enablePeriodicScans。增量行为实测见 5.4——新文件按 ID3 归入既有专辑、trackcount 实时 +1，已有文件不重扫。

Q3：合作曲目被拆成两位艺术家 / 该拆的没拆？ 现象与定位：A/B 形式曲目在艺术家页出现两个独立条目，或组合名被误拆。解决：调 artistSeparators（增删分隔符）与 artistSplitIgnoreList（追加不该拆的组合名），这两个键更新会自动全量重扫重建 Store，无需重启。内置名单已覆盖 76 个知名组合，误拆大概率是名单外的新组合，追加即可。

Q4：专辑名带一长串 (Deluxe Edition) 尾巴？ 开 cleanAlbumTitle（默认已开）；若同一专辑的多个版本被展示为多张，评估 mergeAlbums: true。原始标题始终保留在 og_title 字段（实测专辑接口同时返回两者）。

Q5：忘了管理员密码？ 用自带重置工具：swingmusic --password-reset（镜像内执行 docker exec swingmusic-3.0.0-app swingmusic --password-reset），按交互提示输入用户名与新口令，完成后用新口令登录验证。

Q6：误改配置导致服务起不来？ 救援路径：停服后手工编辑 settings.json 恢复（最小化恢复——只把改坏的键改回默认值即可，键清单见第四章总览表），再启动。serverId 若被误删，所有登录态失效且需重新走初始化向导（rootDirs 会保留在库中，曲库不丢）。

九、参考链接

1. 官方仓库：https://github.com/swingmx/swingmusic （settings.py / config.py 为参数权威源，v3.0.0）
2. 官方 Web 设置页：http://<服务器IP>:8154 → Settings
3. 管理聚合接口：GET /notsettings、PUT /notsettings/update、GET /notsettings/trigger-scan（详见《SwingMusic 3.0.0 API 使用详解》）
4. 站内延伸：《SwingMusic 3.0.0 介绍与选型指南》、《SwingMusic 3.0.0 Docker Compose 部署指南》、《mStream 6.32.0 配置参数详解》、《Navidrome 0.64.2 配置参数详解》