Navidrome 0.64.2 配置参数详解
Navidrome 0.64.2 全量配置方式梳理：配置文件/环境变量/命令行三通道实测优先级（与官方文档结论相反）、debug 配置转储核对法、十大功能域参数表、生产配置模板与常见配置陷阱。
Navidrome 0.64.2 配置参数详解
目标：系统梳理 Navidrome 0.64.2 自托管音乐流媒体服务器的全部配置方式与核心参数，给出参数优先级的实测证据、分类参数语义表、生产配置模板与常见配置陷阱。本文所有实测均在 Ubuntu 22.04 服务器（二进制方式安装 Navidrome 0.64.2）上完成。
一、环境信息
- 操作系统：Ubuntu 22.04.5 LTS（x86_64）
- Navidrome 版本：0.64.2（10114574，官方最新稳定版，查询日期 2026-10-25），二进制位于
/usr/local/bin/navidrome - 配置文件：
/etc/navidrome/navidrome.toml - 数据目录：
/var/lib/navidrome（内含 SQLite 数据库、缓存与备份目录） - 曲库目录：
/srv/music（1 位专辑艺人 2 张专辑 + 1 张合辑，共 6 首 mp3） - 服务端口：4533（默认）
- 依赖组件：ffmpeg 4.4.2（转码功能依赖，需在系统 PATH 或
FFmpegPath中可见）
二、前置条件
Navidrome 已按《Navidrome 0.64.2 介绍与选型指南》所述方式完成安装并能正常启动。快速自检：
navidrome --version
实测输出：
0.64.2 (10114574)
确认配置文件所在：
ls -la /etc/navidrome/navidrome.toml
实测输出：
-rw-r--r-- 1 root root 241 Oct 25 03:19 /etc/navidrome/navidrome.toml
💡 说明：本文的参数实验围绕「配置文件 + 环境变量 + 命令行参数」三种注入方式展开。示例服务器的基础配置为：
MusicFolder = "/srv/music"
DataFolder = "/var/lib/navidrome"
Address = "0.0.0.0"
Port = 4533
三、参数查看与修改方式
Navidrome 的每一个配置项都支持三种注入方式：配置文件、环境变量、命令行参数。三种方式的命名有固定映射关系。
3.1 配置文件方式
默认加载当前工作目录下的 navidrome.toml（--configfile 缺省值即 ./navidrome.toml），生产建议用 -c 显式指定路径。支持 TOML、JSON、YAML、INI 四种格式，按扩展名识别。TOML 示例：
LogLevel = 'INFO'
Scanner.Schedule = '@every 24h'
TranscodingCacheSize = '150MiB'
MusicFolder = '/srv/music'
逐项说明：LogLevel 控制日志级别；Scanner.Schedule 设置定时扫描周期（Cron 或 @every 语法）；TranscodingCacheSize 是转码缓存大小；MusicFolder 指定曲库根目录。路径含空格时用引号包裹；Windows 路径必须用单引号。
指定非默认路径的配置文件：
navidrome --configfile "/etc/navidrome/navidrome.toml"
实测输出（节选，实测首部）：
Navidrome is a self-hosted music server and streamer.
Complete documentation is available at https://www.navidrome.org/docs
time="2026-10-25T03:15:42Z" level=info msg="Loaded configuration" file=/etc/navidrome/navidrome.toml
💡 说明：
Loaded configuration file=...是配置文件被成功加载的标志性日志；若文件不存在或不可读，日志会提示No configuration file found。
3.2 环境变量方式
规则：配置项名全大写、点分层改为下划线、加 ND_ 前缀。例如 MusicFolder → ND_MUSICFOLDER、Scanner.Schedule → ND_SCANNER_SCHEDULE、Backup.Path → ND_BACKUP_PATH。容器编排与 systemd 场景最常用：
ND_PORT=4536 navidrome -c /etc/navidrome/navidrome.toml
实测输出（节选）：
time="2026-10-25T03:16:44Z" level=info msg="Loaded configuration" file=/etc/navidrome/navidrome.toml
环境变量生效的核验方式见 3.4 优先级实测（4536 端口监听）。
3.3 命令行参数方式
navidrome --help
实测输出（节选，实测首尾）：
Usage:
navidrome [flags]
navidrome [command]
Flags:
-a, --address string IP address to bind to (default "0.0.0.0")
--albumplaycountmode string how to compute playcount for albums. absolute (default) or normalized (default "absolute")
--autoimportplaylists enable/disable .m3u playlist auto-import` (default true)
--baseurl string base URL to configure Navidrome behind a proxy (ex: /music or http://my.server.com)
--cachefolder string folder to store cache data (transcoding, images...), needs write access
-c, --configfile string config file (default "./navidrome.toml")
--datafolder string folder to store application data (DB), needs write access (default ".")
--enabletranscodingcancellation enables transcoding context cancellation
--enabletranscodingconfig enables transcoding configuration in the UI
-h, --help help for navidrome
--imagecachesize string size of image (art work) cache. set to 0 to disable cache (default "100MB")
--logfile string log file path, if not set logs will be printed to stderr
-l, --loglevel string log level, possible values: error, info, debug, trace (default "info")
--musicfolder string folder where your music is stored (default "music")
-n, --nobanner don't show banner
-p, --port int HTTP port Navidrome will listen to (default 4533)
--prometheus.enabled enable/disable prometheus metrics endpoint
--prometheus.metricspath string http endpoint for prometheus metrics (default "/metrics")
--scaninterval duration how frequently to scan for changes in your music library
--sessiontimeout duration how long Navidrome will wait before closing web ui idle sessions (default 48h0m0s)
--tlscert string optional path to a TLS cert file (enables HTTPS listening)
--tlskey string optional path to a TLS key file (enables HTTPS listening)
--transcodingcachesize string size of transcoding cache (default "100MB")
--uiloginbackgroundurl string URL to a backaground image used in the Login page (default "/backgrounds")
--unixsocketperm string optional file permission for the unix socket (default "0660")
-v, --version version for navidrome
⚠️ 官方文档明确「命令行参数必须全小写」，且命令行只暴露了部分高频参数（
--help所列）。全量参数（如Scanner.*、Jellyfin.*、Plugins.*等）只能走配置文件或环境变量。--help中残留的--scaninterval、--enabletranscodingcancellation是旧名，现行配置项为Scanner.Schedule与Transcoding.EnableCancellation（见 5.2、5.3 节）。
3.4 三种方式的优先级（实测）
官方文档标注优先级为「环境变量 > 命令行参数 > 配置文件」，但 0.64.2 实测结论为：命令行参数 > 环境变量 > 配置文件。以下三组实验逐一验证。
实验一：配置文件 Port = 4533，命令行给 --port 4535：
navidrome -c /etc/navidrome/navidrome.toml --port 4535
curl -s -o /dev/null -w "port4535 HTTP %{http_code}\n" http://127.0.0.1:4535/ping
curl -s -o /dev/null -w "port4533 HTTP %{http_code}\n" --max-time 2 http://127.0.0.1:4533/ping
实测输出：
port4535 HTTP 200
port4533 HTTP 000
服务只监听 4535——命令行参数压过配置文件。
实验二：环境变量与命令行参数同给（ND_PORT=4536 + --port 4535）：
ND_PORT=4536 navidrome -c /etc/navidrome/navidrome.toml --port 4535
curl -s -o /dev/null -w "port4536 HTTP %{http_code}\n" http://127.0.0.1:4536/ping
curl -s -o /dev/null -w "port4535 HTTP %{http_code}\n" http://127.0.0.1:4535/ping
实测输出：
port4536 HTTP 000
port4535 HTTP 200
服务监听 4535——命令行参数压过环境变量（与官方文档标注顺序相反）。
实验三：环境变量单独使用（ND_PORT=4536，无命令行端口参数）：
ND_PORT=4536 navidrome -c /etc/navidrome/navidrome.toml
curl -s -o /dev/null -w "port4536 HTTP %{http_code}\n" http://127.0.0.1:4536/ping
curl -s -o /dev/null -w "port4533 HTTP %{http_code}\n" --max-time 2 http://127.0.0.1:4533/ping
实测输出：
port4536 HTTP 200
port4533 HTTP 000
环境变量压过配置文件。
用日志级别再验证一轮（ND_LOGLEVEL=debug + --loglevel trace，debug 与 trace 输出行数可区分）：
ND_LOGLEVEL=debug navidrome -c /etc/navidrome/navidrome.toml --loglevel trace
grep -c "level=trace" /tmp/t3.log
grep -c "level=debug" /tmp/t3.log
实测输出：
120
49
trace 级日志出现（120 行），说明生效的是命令行的 --loglevel trace 而非环境变量的 debug——与端口实验结论一致。
💡 结论速查：
组合 实测生效者 配置文件 vs 命令行参数 命令行参数 环境变量 vs 命令行参数 命令行参数 配置文件 vs 环境变量 环境变量 即实际优先级：命令行参数 > 环境变量 > 配置文件。对
Port、LogLevel两个参数实测一致。运维上建议同一参数只走一种方式，避免因优先级记忆错误造成「改了不生效」。
3.5 查看生效配置：debug 级配置转储
把 LogLevel 设为 debug（或启动时加 --loglevel debug）重启服务，日志会打印一份生效配置的完整转储，这是核对配置是否生效最直接的手段：
LogLevel = "debug"
navidrome -c /etc/navidrome/navidrome.toml
实测输出（节选，实测首尾）：
Prometheus: conf.prometheusOptions{Enabled:true, MetricsPath:"[REDACTED]", Password:""},
Scanner: conf.scannerOptions{
Enabled: true,
Schedule: "",
WatcherWait: 5000000000,
ScanOnStartup: true,
Extractor: "taglib",
ArtistJoiner: " • ",
ArtistSplitExceptions: {},
GenreSeparators: "",
GroupAlbumReleases: false,
FollowSymlinks: true,
IgnoreDotFolders: true,
PurgeMissing: "never",
},
Jukebox: conf.jukeboxOptions{
Enabled: false,
Devices: {
},
Default: "",
AdminOnly: true,
},
Backup: conf.backupOptions{
Count: 3,
Path: "/var/lib/navidrome/backups",
Schedule: "@every 1m",
},
转储中数值以纳秒为单位（WatcherWait: 5000000000 即 5s），路径类值与配置文件一致。注意 MetricsPath 显示为 [REDACTED]——这是日志脱敏（EnableLogRedacting，默认开启）在工作，部分路径与凭据类值会被遮蔽（见 5.6 节）。
四、参数总览
Navidrome 0.64.2 的配置项按功能域分为 10 组。下表为全量索引（完整清单见官方 Configuration Options 页，查询日期 2026-10-25）：
| 功能域 | 代表参数 | 本章小节 |
|---|---|---|
| 基础运行 | MusicFolder、DataFolder、Port、Address、BaseUrl、LogLevel、TLSCert/TLSKey | 5.1 |
| 扫描与曲库 | Scanner.Schedule、Scanner.WatcherWait、Scanner.PurgeMissing、PlaylistsPath、AutoImportPlaylists、PID.Track/Album | 5.2 |
| 转码与播放 | Transcoding.MaxConcurrent、TranscodingCacheSize、DefaultDownsamplingFormat、Jukebox.Enabled、EnableDownloads | 5.3 |
| 封面与图片 | CoverArtPriority、CoverArtQuality、ImageCacheSize、UICoverArtSize、EnableWebPEncoding | 5.4 |
| 用户与界面 | DefaultTheme、DefaultLanguage、UIWelcomeMessage、SessionTimeout、EnableUserEditing | 5.5 |
| 安全与认证 | AuthRequestLimit、AuthWindowLength、EnableLogRedacting、EnforceNonRootUser、ExtAuth.* | 5.6 |
| 备份与维护 | Backup.Path、Backup.Schedule、Backup.Count、EnableScheduledDBAnalyze | 5.7 |
| 外部集成 | LastFM.、ListenBrainz.、Deezer.*、Agents、LyricsPriority、EnableExternalServices | 5.8 |
| Jellyfin 兼容层 | Jellyfin.Enabled、Jellyfin.ServerName、Jellyfin.QuickConnect | 5.9 |
| 搜索与 Subsonic API | Search.Backend、Search.FullString、Subsonic.LegacyClients、Subsonic.MinimalClients | 5.10 |
💡 说明：表中绝大多数参数支持配置文件与环境变量两种写法（映射规则见 3.2）；少数例外（如
Tags自定义标签映射、Jukebox.Devices设备列表）官方标注「cannot be set as an environment variable」，只能写配置文件。带*的参数（如PasswordEncryptionKey、ExtAuth.UserHeader）官方注明修改行为需谨慎或仅限特定场景。
五、核心参数分类详解
5.1 基础运行参数
| 参数（配置文件） | 环境变量 | 默认值 | 说明 |
|---|---|---|---|
| MusicFolder | ND_MUSICFOLDER | ./music | 曲库根目录，可只读；多曲库时此目录成为默认库 |
| DataFolder | ND_DATAFOLDER | ./data | 应用数据目录（SQLite 库、插件），必须可写 |
| CacheFolder | ND_CACHEFOLDER | <DataFolder>/cache | 缓存目录（转码产物、图片） |
| Port | ND_PORT | 4533 | HTTP 监听端口 |
| Address | ND_ADDRESS | 0.0.0.0 与 :: | 监听地址，支持 IPv4/IPv6/Unix socket（unix:/path） |
| BaseUrl | ND_BASEURL | 空 | 反向代理子路径，如 /music；必须与对外路径完全一致 |
| LogLevel | ND_LOGLEVEL | info | 日志级别：error/warn/info/debug/trace |
| LogFile | ND_LOGFILE | 空（stderr） | 日志落盘路径 |
| TLSCert / TLSKey | ND_TLSCERT / ND_TLSKEY | 空（禁用） | 证书与私钥路径，二者同时给出即启用 HTTPS |
| SessionTimeout | ND_SESSIONTIMEOUT | 48h | Web UI 空闲会话时长 |
| UnixSocketPerm | ND_UNIXSOCKETPERM | 0660 | Unix socket 文件权限 |
SessionTimeout 生效验证：设为 24h 后启动日志出现 Setting Session Timeout value=24h（实测）。TLSCert/TLSKey 生效验证如下——生成自签证书并配置：
TLSCert = "/etc/navidrome/tls/tls.crt"
TLSKey = "/etc/navidrome/tls/tls.key"
重启后分别用 HTTPS 与明文 HTTP 请求：
curl -sk -o /dev/null -w "HTTPS %{http_code}\n" https://127.0.0.1:4533/ping
curl -s -o /dev/null -w "HTTP %{http_code}\n" --max-time 2 http://127.0.0.1:4533/ping
实测输出：
HTTPS 200
HTTP 400
HTTPS 正常响应、明文请求被拒（400）——TLS 监听生效。生产环境建议把证书签发交给反向代理或 certbot，TLSCert/TLSKey 适合内网小规模直接暴露场景。
5.2 扫描与曲库参数
| 参数 | 环境变量 | 默认值 | 说明 |
|---|---|---|---|
| Scanner.Enabled | ND_SCANNER_ENABLED | true | 扫描器总开关 |
| Scanner.Schedule | ND_SCANNER_SCHEDULE | 0（禁用） | 定时扫描计划，Cron 或 @every 语法 |
| Scanner.ScanOnStartup | ND_SCANNER_SCANONSTARTUP | true | 启动时自动扫描 |
| Scanner.WatcherWait | ND_SCANNER_WATCHERWAIT | 5s | 检测到文件变化后延迟扫描的时间，防扫描到不完整文件；0 关闭监视器 |
| Scanner.PurgeMissing | ND_SCANNER_PURGEMISSING | never | 缺失文件清理策略：never（仅标记）/always（每次扫描后清理）/full（全量扫描后清理） |
| Scanner.FollowSymlinks | ND_SCANNER_FOLLOWSYMLINKS | true | 扫描时是否跟随符号链接 |
| Scanner.IgnoreDotFolders | ND_SCANNER_IGNOREDOTFOLDERS | true | 忽略点前缀目录（如同步工具的 .stfolder） |
| Scanner.ArtistSplitExceptions | ND_SCANNER_ARTISTSPLITEXCEPTIONS | 空 | 永不拆分的艺人名列表（如 AC/DC） |
| AutoImportPlaylists | ND_AUTOIMPORTPLAYLISTS | true | 自动导入曲库内的 .m3u 播放列表 |
| PlaylistsPath | ND_PLAYLISTSPATH | 空（全库） | 播放列表检索范围，相对 MusicFolder 的路径/通配列表 |
| RecentlyAddedByModTime | ND_RECENTLYADDEDBYMODTIME | false | 「最近添加」按文件修改时间而非导入时间排序 |
| PID.Track / PID.Album | ND_PID_TRACK / ND_PID_ALBUM | 见官方文档 | 曲目/专辑唯一 ID 的标签优先级链，影响去重与合辑识别 |
定时扫描生效实测（配置 Scanner.Schedule = '@every 24h'）：
time="2026-10-25T03:15:01Z" level=info msg="Scheduling periodic scan" schedule="@every 24h"
⚠️ 命名变更陷阱：旧版环境变量
ND_SCANSCHEDULE在 0.64.2 不再生效——实测注入旧名后日志仍显示Periodic scan is DISABLED；改用ND_SCANNER_SCHEDULE后定时扫描正常调度。从旧版本迁移编排/systemd 配置时务必改名。
💡 技术拓展：曲库文件变动的感知方式有两种主流机制——
机制 原理 取舍 文件系统监视器（inotify） 内核事件推送，文件变化即时触发 实时性高，网络挂载（NFS/SMB）上不可靠 定时扫描（Schedule） 按计划周期全量/增量比对 简单可靠，实时性取决于周期 Navidrome 两者并用：默认 inotify 即时感知（配合
Scanner.WatcherWait防抖）+ 可选定时兜底。本文方案采用默认监视器 +@every 24h定时兜底，兼容 NAS 网络挂载场景。
5.3 转码与播放参数
| 参数 | 环境变量 | 默认值 | 说明 |
|---|---|---|---|
| TranscodingCacheSize | ND_TRANSCODINGCACHESIZE | 100MB | 转码产物缓存，设 0 禁用 |
| Transcoding.MaxConcurrent | ND_TRANSCODING_MAXCONCURRENT | 0（不限） | 全局并发转码上限，防 ffmpeg 打满 CPU |
| Transcoding.MaxConcurrentPerUser | ND_TRANSCODING_MAXCONCURRENTPERUSER | 0（不限） | 单用户并发转码上限 |
| Transcoding.EnableCancellation | ND_TRANSCODING_ENABLECANCELLATION | false | 客户端断开时立即终止 ffmpeg；开启省 CPU 但放弃已转码产物 |
| DefaultDownsamplingFormat | ND_DEFAULTDOWNSAMPLINGFORMAT | opus | 仅限制码率（未指定格式）时的转码目标格式 |
| AutoTranscodeDownload | ND_AUTOTRANSCODEDOWNLOAD | false | 客户端下载时按其转码配置转码；关闭则给原始文件 |
| EnableDownloads | ND_ENABLEDOWNLOADS | true | UI 下载功能开关 |
| Jukebox.Enabled | ND_JUKEBOX_ENABLED | false | 点唱机模式：服务端音频设备直接出声（依赖 mpv） |
| MPVPath | ND_MPVPATH | 空（搜 PATH） | mpv 可执行文件路径，点唱机模式依赖 |
| UIPlaybackReportInterval | ND_UIPLAYBACKREPORTINTERVAL | 1m | Web UI 上报播放进度的间隔 |
转码缓存生效验证：配置 TranscodingCacheSize = '150MiB' 后启动日志出现 Creating Transcoding cache maxSize="150 MB" path=/data/cache/transcoding（实测；大小单位支持 MB/MiB，换算后转储为同一字节数）。
💡 技术拓展：转码目标格式的常见选择——
格式 特点 适用场景 Opus 同码率音质最佳，浏览器/现代客户端支持好 默认降采样格式（Navidrome 默认值即 opus） AAC (m4a) 兼容性广，苹果生态友好 iOS 客户端、车机 MP3 兼容性最好，同码率音质最差 老设备兜底 Navidrome 默认用 Opus 作降采样格式；客户端明确指定
format参数时按客户端要求转码。
5.4 封面与图片参数
| 参数 | 环境变量 | 默认值 | 说明 |
|---|---|---|---|
| CoverArtPriority | ND_COVERARTPRIORITY | cover.*, folder.*, front.*, embedded, external | 专辑封面查找顺序 |
| ArtistArtPriority | ND_ARTISTARTPRIORITY | artist.*, album/artist.*, external | 艺人图片查找顺序 |
| DiscArtPriority | ND_DISCARTPRIORITY | disc*.*, cd*.*, cover.*, ... | 多碟专辑碟片图查找顺序 |
| CoverArtQuality | ND_COVERARTQUALITY | 75 | 缩放封面 JPEG/WebP 质量（1-100） |
| ImageCacheSize | ND_IMAGECACHESIZE | 100MB | 图片缓存大小，0 禁用 |
| EnableArtworkPrecache | ND_ENABLEARTWORKPRECACHE | true | 新入库音乐预生成封面缓存 |
| EnableArtworkUpload | ND_ENABLEARTWORKUPLOAD | true | 允许 UI 上传封面（播放列表/艺人/电台） |
| MaxImageUploadSize | ND_MAXIMAGEUPLOADSIZE | 10MB | 上传图片大小上限 |
| MaxImageSize | ND_MAXIMAGESIZE | 20MB | 读取的图片大小上限，超限跳过 |
| EnableCoverAnimation | ND_ENABLECOVERANIMATION | true | 播放器封面旋转动画 |
| EnableWebPEncoding | ND_ENABLEWEBPENCODING | false | 缩放封面编码为 WebP（更省流量，多耗 CPU，老客户端可能不支持） |
| UICoverArtSize | ND_UICOVERARTSIZE | 300 | UI 请求的封面像素尺寸，钳制在 200-1200 |
💡 说明：
CoverArtPriority中特殊值embedded表示读音频文件内嵌封面，external表示外部元数据源。高分辨率库（PNG 大图）建议调大MaxImageSize；移动流量敏感场景可开EnableWebPEncoding。
5.5 用户与界面参数
| 参数 | 环境变量 | 默认值 | 说明 |
|---|---|---|---|
| DefaultTheme | ND_DEFAULTTHEME | Dark | 新浏览器默认主题（须与 UI 中选项名一致） |
| DefaultLanguage | ND_DEFAULTLANGUAGE | en | 新浏览器默认语言，中文简体为 zh-Hans |
| DefaultUIVolume | ND_DEFAULTUIVOLUME | 100 | 默认音量（0-100） |
| UIWelcomeMessage | ND_UIWELCOMEMESSAGE | 空 | 登录页欢迎语 |
| UILoginBackgroundUrl | ND_UILOGINBACKGROUNDURL | 官方 Unsplash 背景 | 登录页背景图 URL |
| UISearchDebounceMs | ND_UISEARCHDEBOUNCEMS | 200 | 搜索框防抖毫秒数 |
| MaxSidebarPlaylists | ND_MAXSIDEBARPLAYLISTS | 100 | 侧边栏播放列表数量上限 |
| EnableUserEditing | ND_ENABLEUSEREDITING | true | 普通用户可改个人资料与密码 |
| EnableFavourites | ND_ENABLEFAVOURITES | true | 收藏（心形）功能，映射 Subsonic Star |
| EnableStarRating | ND_ENABLESTARRATING | true | 5 星评分功能 |
| EnableSharing | ND_ENABLESHARING | true | 分享链接功能 |
| DefaultShareExpiration | ND_DEFAULTSHAREEXPIRATION | 8760h（1 年） | 新分享默认有效期 |
| DefaultDownloadableShare | ND_DEFAULTDOWNLOADABLESHARE | false | 新分享默认可下载 |
| ShareURL | ND_SHAREURL | 空（服务器地址） | 分享链接的基础地址（Tailscale/内网穿透场景用） |
DefaultLanguage: zh-Hans 与 SessionTimeout: 24h 组合注入后的启动日志验证（实测）：
time="2026-10-25T03:15:01Z" level=info msg="Setting Session Timeout" value=24h
5.6 安全与认证参数
| 参数 | 环境变量 | 默认值 | 说明 |
|---|---|---|---|
| AuthRequestLimit | ND_AUTHREQUESTLIMIT | 5 | 单 IP 在时间窗内允许的登录尝试次数，0 关闭限流 |
| AuthWindowLength | ND_AUTHWINDOWLENGTH | 20s | 登录限流时间窗 |
| EnableLogRedacting | ND_ENABLELOGREDACTING | true | 日志脱敏（令牌、密码及部分敏感值打码） |
| PasswordEncryptionKey | ND_PASSWORDENCRYPTIONKEY | -（自动生成） | 库内密码加密口令；多实例共享数据目录时须一致 |
| EnforceNonRootUser | ND_ENFORCENONROOTUSER | false | 开启后以 root（UID 0）运行直接报错退出 |
| ExtAuth.UserHeader | ND_EXTAUTH_USERHEADER | Remote-User | 外部认证代理传递用户名的请求头 |
| ExtAuth.TrustedSources | ND_EXTAUTH_TRUSTEDSOURCES | 空（全拒绝） | 允许使用反代认证的来源 CIDR 列表 |
| ExtAuth.LogoutURL | ND_EXTAUTH_LOGOUTURL | 空 | 外部认证注销后的跳转地址 |
| HTTPHeaders.FrameOptions | ND_HTTPHEADERS_FRAMEOPTIONS | DENY | X-Frame-Options 响应头值 |
| Subsonic.DefaultReportRealPath | ND_SUBSONIC_DEFAULTREPORTREALPATH | false | API 返回文件真实路径（有信息泄露风险，默认关） |
登录限流默认值生效的启动日志（实测）：
time="2026-10-25T03:13:07Z" level=info msg="Login rate limit set" requestLimit=5 windowLength=20s
日志脱敏实测：debug 配置转储中 Prometheus.MetricsPath 被显示为 [REDACTED]（见 3.5 节回显），即 EnableLogRedacting=true 的效果。排障需要看全量值时可临时设 EnableLogRedacting = false，查完改回。
5.7 备份与维护参数
| 参数 | 环境变量 | 默认值 | 说明 |
|---|---|---|---|
| Backup.Path | ND_BACKUP_PATH | 空（禁用） | 自动备份落盘目录；设空串禁用 |
| Backup.Schedule | ND_BACKUP_SCHEDULE | 空（禁用） | 自动备份计划，Cron 或 @every 语法 |
| Backup.Count | ND_BACKUP_COUNT | 0（禁用） | 保留备份份数，超出自动清理最旧 |
| EnableScheduledDBAnalyze | ND_ENABLESCHEDULEDDBANALYZE | true | 每 30 分钟检查并刷新 SQLite 查询统计（ANALYZE） |
实测：配置 Backup.Path=/var/lib/navidrome/backups、Backup.Schedule='@every 1m'、Backup.Count=3 后：
启动日志：
time="2026-10-25T03:17:57Z" level=info msg="Scheduling periodic backup" schedule="@every 1m"
一个调度周期后备份目录出现备份文件：
-rw-r--r-- 1 root root 724992 Oct 25 03:18 navidrome_backup_2026.10.25_03.18.57.db
💡 说明：备份文件是完整的 SQLite 数据库快照，文件名含时间戳。自动备份只覆盖数据库，不含曲库文件本身；曲库应有文件系统级的独立备份。手动备份/恢复用内置 CLI（
navidrome backup create/restore，见《Navidrome 0.64.2 常用 CLI 命令与工具详解》 backup 一节）。
5.8 外部集成参数
| 参数 | 环境变量 | 默认值 | 说明 |
|---|---|---|---|
| Agents | ND_AGENTS | deezer,lastfm,listenbrainz | 艺人信息/图片元数据代理及优先级 |
| LastFM.Enabled | ND_LASTFM_ENABLED | true | Last.fm 集成总开关 |
| LastFM.ApiKey / LastFM.Secret | ND_LASTFM_APIKEY / ND_LASTFM_SECRET | 空 | Last.fm API 凭据（scrobble 必填） |
| ListenBrainz.Enabled | ND_LISTENBRAINZ_ENABLED | true | ListenBrainz 集成开关 |
| ListenBrainz.BaseURL | ND_LISTENBRAINZ_BASEURL | https://api.listenbrainz.org/1/ | 可指向自建 Maloja |
| Deezer.Enabled | ND_DEEZER_ENABLED | true | Deezer 集成开关 |
| EnableExternalServices | ND_ENABLEEXTERNALSERVICES | true | 全部外部集成总闸，false 时连登录背景图与匿名收集一并关闭 |
| EnableInsightsCollector | ND_ENABLEINSIGHTSCOLLECTOR | true | 匿名数据收集开关 |
| EnableGravatar | ND_ENABLEGRAVATAR | false | 用户头像用 Gravatar |
| GATrackingID | ND_GATRACKINGID | 空（禁用） | 向自己的 GA 账号上报 |
| LyricsPriority | ND_LYRICSPRIORITY | .ttml,.yaml,.yml,.elrc,.lrc,.srt,.txt,embedded | 歌词来源优先级 |
EnableInsightsCollector = false 生效验证：debug 配置转储显示 EnableInsightsCollector: false，且启动日志不再出现默认开启时的 Starting Insight Collector 行（实测）。
⚠️ 内网隔离环境（无法访问外网）建议显式关闭
EnableExternalServices：实测断网启动时日志会周期性出现Could not get background images from image service的 warning（拉取登录背景图超时），关闭后消失。
5.9 Jellyfin 兼容层参数
| 参数 | 环境变量 | 默认值 | 说明 |
|---|---|---|---|
| Jellyfin.Enabled | ND_JELLYFIN_ENABLED | false | 开启实验性 Jellyfin API，Jellyfin 音乐客户端可直连 |
| Jellyfin.ServerName | ND_JELLYFIN_SERVERNAME | Navidrome <version> | Jellyfin 客户端显示的服务器名 |
| Jellyfin.AutoDiscovery | ND_JELLYFIN_AUTODISCOVERY | false | 应答局域网 UDP 7359 自动发现 |
| Jellyfin.QuickConnect | ND_JELLYFIN_QUICKCONNECT | true | 6 位码快速登录新设备 |
| Jellyfin.ExposedPublicUsers | ND_JELLYFIN_EXPOSEDPUBLICUSERS | 空 | 客户端登录页展示的用户名列表（任何可达者可见，慎开） |
| Jellyfin.MaxConcurrentStreams | ND_JELLYFIN_MAXCONCURRENTSTREAMS | 半数连接池（至少 2） | 大列表响应并发上限 |
💡 说明：Jellyfin 兼容层解决的是「手边只有 Jellyfin 客户端」的复用诉求，功能面以音乐播放为主。已有 Subsonic 客户端的用户无需开启。
5.10 搜索与 Subsonic API 参数
| 参数 | 环境变量 | 默认值 | 说明 |
|---|---|---|---|
| Search.Backend | ND_SEARCH_BACKEND | fts | 全文检索后端：fts（FTS5 + BM25 排序）或 legacy（旧实现） |
| Search.FullString | ND_SEARCH_FULLSTRING | false | 任意子串匹配（对中文等非空格分词语言更友好） |
| Subsonic.LegacyClients | ND_SUBSONIC_LEGACYCLIENTS | DSub | 不启用 OpenSubsonic 扩展的老客户端名单 |
| Subsonic.MinimalClients | ND_SUBSONIC_MINIMALCLIENTS | SubMusic | 只回最小字段集的客户端名单 |
| Subsonic.AppendSubtitle | ND_SUBSONIC_APPENDSUBTITLE | true | 曲名副标题追加显示 |
| Subsonic.AppendAlbumVersion | ND_SUBSONIC_APPENDALBUMVERSION | true | 专辑名追加版本信息（如 Deluxe Edition） |
| Subsonic.ArtistParticipations | ND_SUBSONIC_ARTISTPARTICIPATIONS | false | 艺人页包含其参与的合辑 |
| Subsonic.EnableAverageRating | ND_SUBSONIC_ENABLEAVERAGERATING | true | API 响应包含全用户平均评分 |
| IndexGroups | ND_INDEXGROUPS | A B C ... X-Z(XYZ) [Unknown]([) | 艺人索引分组（字母快捷条） |
| IgnoredArticles | ND_IGNOREDARTICLES | The El La Los Las Le Les Os As O A | 排序忽略的冠词，可追加中文「The」等习惯前缀 |
💡 技术拓展：全文检索后端
fts与legacy的取舍——
后端 机制 特点 fts（默认） SQLite FTS5 倒排索引 + BM25 相关性排序 检索质量高，支持相关性排序 legacy 旧版字符串匹配实现 行为与老版本一致，供回归兜底 中文曲库建议保持
fts并开启Search.FullString（中文无空格分词，默认词边界匹配易漏结果）。
六、生产配置模板
适用场景：家庭/小团队自托管，8GB 内存、NVMe SSD、曲库 1-5 万首、2-5 个并发听众，曲库挂本地盘或 NAS。
# /etc/navidrome/navidrome.toml
# —— 基础运行 ——
MusicFolder = '/srv/music'
DataFolder = '/var/lib/navidrome'
Address = '0.0.0.0'
Port = 4533
LogLevel = 'info'
SessionTimeout = '24h'
# —— 扫描 ——
Scanner.Schedule = '@every 24h'
Scanner.WatcherWait = '5s'
# —— 转码与缓存（按 SSD 余量调整）——
TranscodingCacheSize = '500MiB'
ImageCacheSize = '500MiB'
Transcoding.MaxConcurrent = '2'
Transcoding.MaxConcurrentPerUser = '1'
# —— 界面 ——
DefaultLanguage = 'zh-Hans'
DefaultTheme = 'Dark'
UIWelcomeMessage = 'Welcome to my music library'
# —— 安全 ——
AuthRequestLimit = 5
AuthWindowLength = '20s'
EnableLogRedacting = true
# —— 自动备份（每晚 3 点，保留 7 份）——
Backup.Path = '/var/lib/navidrome/backups'
Backup.Schedule = '0 3 * * *'
Backup.Count = 7
# —— 内网/离线环境建议 ——
EnableExternalServices = false
EnableInsightsCollector = false
模板要点解读：
Transcoding.MaxConcurrent='2'：限制全局并发转码进程数，防止多客户端同时请求低码率流时 ffmpeg 把 2-4 核小主机打满；内网高带宽、全无损听众可省略此行Backup.Schedule='0 3 * * *'：Cron 表达式每晚 3 点备份，Count=7保留一周滚动窗口EnableExternalServices=false：家庭内网场景通常无外网出口或不愿泄露收听行为，关闭后同时停用匿名收集与登录页外网背景图- 曲库在 NFS/SMB 挂载上时，inotify 不可靠，
Scanner.Schedule兜底扫描要保留；本地盘可放宽到'@every 1h'
小内存设备（树莓派级，1-2GB 内存）：把两个缓存降为 150MiB，Transcoding.MaxConcurrent 降为 '1'，其余不变——Navidrome 空载常驻内存约几十 MB，内存压力主要来自并发转码与缓存。
七、常见问题
Q1：改了配置重启后没生效？
按 3.4 节排查注入链路：确认配置文件路径正确（Loaded configuration file=... 日志是否存在）→ 是否有环境变量或命令行参数压住了配置文件 → 用 3.5 节 debug 转储直接核对生效值。典型踩坑是 ND_SCANSCHEDULE 旧名（见 5.2 节警告）。
Q2：环境变量和配置文件都想用，到底听谁的？
实测优先级为命令行参数 > 环境变量 > 配置文件（与官方文档标注相反，证据见 3.4 节）。推荐同一参数只走一种方式：systemd/编排场景用环境变量或配置文件二选一，命令行只传 -c。
Q3：日志里出现 [REDACTED]，是配置错了吗？
不是，这是 EnableLogRedacting=true 的日志脱敏行为（见 5.6 节实测），被遮蔽的多为凭据与部分路径类值。临时排障可设 EnableLogRedacting = false 看全量值，查完务必改回。
Q4：备份目录里积累了很多备份文件？
Backup.Count 控制保留份数（默认 0 表示不清理）。设为 7 即保留最近 7 份，旧备份由服务端自动清理；也可用 navidrome backup prune 手动清理（见 CLI 篇）。
Q5：开了 HTTPS 后，明文 HTTP 请求返回 400？
TLSCert/TLSKey 同时配置后服务只提供 HTTPS 监听（实测：HTTPS 200，明文 400）。这是预期行为；需要 HTTP 与 HTTPS 并存时，用反向代理终结 TLS、Navidrome 本身保持 HTTP。
Q6：/metrics 端点 404？
Prometheus 指标端点默认关闭，需 Prometheus.Enabled = true。开启后 curl http://127.0.0.1:4533/metrics 返回 200 与指标文本（实测 8823 字节，含 db_model_totals、go_gc_duration_seconds、go_goroutines 等指标族）。生产建议配合 Prometheus.Password 开启 Basic Auth（用户名固定 navidrome）或用反向代理限制来源。
八、参考链接
- 官方配置选项页（全量参数权威清单）：https://www.navidrome.org/docs/usage/configuration/options/
- 官方自定义标签文档：https://www.navidrome.org/docs/usage/configuration/customtags/
- 官方外部认证文档：https://www.navidrome.org/docs/usage/externalauth/
- GitHub 仓库：https://github.com/navidrome/navidrome（本文版本信息查询日期：2026-10-25）
- 站内同系列：《Navidrome 0.64.2 介绍与选型指南》、《Navidrome 0.64.2 Docker Compose 部署指南》、《Navidrome 0.64.2 常用 CLI 命令与工具详解》