Navidrome 0.64.2 常用 CLI 命令与工具详解

目标：系统覆盖 Navidrome 0.64.2 自带命令行工具 navidrome 的 12 个子命令，给出每个命令的用途、语法、真实回显与生产运维组合用法（定时备份、缺失文件重映射、服务管理、自动化脚本）。本文全部命令与回显在 Ubuntu 22.04 服务器上逐条实测。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64），systemd 250 管理服务
Navidrome 版本：0.64.2（10114574，官方最新稳定版，查询日期 2026-10-25），二进制位于 /usr/local/bin/navidrome
配置文件：/etc/navidrome/navidrome.toml（内容见 3.4 节）
数据目录：/var/lib/navidrome；备份目录：/var/lib/navidrome/backups
曲库目录：/srv/music（1 位专辑艺人 2 张专辑 + 1 张合辑共 6 首 mp3 + 1 个 .m3u 播放列表）
已有账号：admin（管理员）；演示播放列表：My-Favorites
ffmpeg：4.4.2（inspect 命令的部分探测能力依赖系统工具链）

二、前置条件

navidrome CLI 与服务端是同一个二进制——它既用来启动服务，也承载全部管理子命令。确认可用：

navidrome --version

实测输出：

0.64.2 (10114574)

确认服务在跑（CLI 的 scan、service 等命令依赖服务本体或其 systemd 单元）：

systemctl is-active navidrome

实测输出：

active

本文约定：后文所有命令统一写作 navidrome -c /etc/navidrome/navidrome.toml --nobanner <子命令>；-c 显式指定配置、--nobanner 关闭欢迎横幅让输出更干净。为省篇幅，正文用 $N 代指这一前缀：

N="navidrome -c /etc/navidrome/navidrome.toml --nobanner"

⚠️ 为什么必须带 -c：--configfile 的默认值是 ./navidrome.toml（当前目录）。在错误的工作目录直接执行管理命令，CLI 会以默认参数打开一个新的空数据库，做出看似成功实则操作了另一个库的动作（典型报错现场见 4.3 节）。

三、CLI 命令总览

3.1 主命令帮助

navidrome help

实测输出（节选，实测首尾）：

Usage:
  navidrome [flags]
  navidrome [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  inspect     inspect the contents of your library using Navidrome's metadata engine
  missing     Manage missing media files in your library
  user        Create/Edit/delete users and change their properties
  pls         manage Navidrome playlists
  backup      Create/prune/restore Navidrome database backups
  search      Rebuild search index/fuzzy search index
  doctor      Check Navidrome database health
  plugin      Manage Navidrome plugins
  artwork     Artwork utilities
  scan        Scan music folder for updates
  service     Manage Navidrome service (start/stop/restart/status)

Flags:
  -a, --address string                  IP address to bind to (default "0.0.0.0")
  ...
  -c, --configfile string               config file (default "./navidrome.toml")
  ...
  -p, --port int                        HTTP port Navidrome will listen to (default 4533)
      --tlscert string                  optional path to a TLS cert file (enables HTTPS listening)
      --tlskey string                   optional path to a TLS key file (enables HTTPS listening)
  ...
  -v, --version                         version for navidrome

3.2 子命令速查表

子命令	用途	依赖服务进程	关键小节
`scan`	扫描曲库（增量/全量/指定目录）	否（直接写库）	6.1
`inspect`	用 Navidrome 元数据引擎检查单个文件	否	6.2
`doctor`	数据库完整性体检	否	6.3
`user create/edit/list/delete`	用户增改查删	否	5
`pls list/import/export`	播放列表查看/导入/导出	否	7
`missing list/fix`	缺失文件清单与重映射	否	8
`backup create/prune/restore`	数据库备份/清理/恢复	否	9
`search rebuild`	重建全文检索索引	否	10.1
`service status/start/stop/restart`	管理 systemd 服务	管理对象即服务	10.2
`plugin list`	查看已安装插件	否	10.3
`artwork status/explain`	封面缓存统计/来源解释	否	10.4
`completion bash	zsh	fish	powershell`

💡 说明：「依赖服务进程」为否的命令直接操作数据库文件，停机维护时也能用（backup restore、doctor 常在停机窗口执行）；service 组直接对接 systemd 单元。

四、全局参数与典型运行错误

4.1 高频全局参数

参数	说明
`-c, --configfile`	配置文件路径，默认 `./navidrome.toml`，生产强烈建议显式指定
`-n, --nobanner`	不打印欢迎横幅，输出更适合脚本采集
`-l, --loglevel`	日志级别 error/info/debug/trace，排障用 debug
`--logfile`	日志写文件而非 stderr

带横幅与不带横幅的输出对比（--nobanner 的价值）：

navidrome -c /etc/navidrome/navidrome.toml doctor 2>&1 | head -10

实测输出：

 _   _             _     _
| \ | |           (_)   | |
|  \| | __ ___   ___  __| |_ __ ___  _ __ ___   ___
| . ` |/ _` \ \ / / |/ _` | '__/ _ \| '_ ` _ \ / _ \
| |\  | (_| |\ V /| | (_| | | | (_) | | | | | |  __/
\_| \_/\__,_| \_/ |_|\__,_|_|  \___/|_| |_| |_|\___/
                          Version: 0.64.2 (10114574)

time="2026-10-25T03:42:10Z" level=info msg="Loaded configuration" file=/etc/navidrome/navidrome.toml
Checking database integrity...

$N doctor 2>&1 | head -2

实测输出：

Checking database integrity...
Integrity check passed.

4.2 配置文件基准

本文实验服务器的 /etc/navidrome/navidrome.toml：

MusicFolder = "/srv/music"
DataFolder = "/var/lib/navidrome"
Address = "0.0.0.0"
Port = 4533

4.3 典型错误现场：`no such table: user`

在错误目录（如 /var/lib/navidrome 之外）不带 -c 执行管理命令，CLI 会按默认值在工作目录新建库：

cd /
navidrome user list 2>&1 | tail -3

实测输出：

time="2026-10-25T03:33:36Z" level=error msg="error executing query" error="no such table: user"
Error: no such table: user

⚠️ 这是 CLI 类问题最常见的一类报错：不是用户表损坏，而是 CLI 开了一个不存在的空库。先确认 pwd 与 -c 路径，再判断库本身是否损坏。带 -c 复跑即恢复：

$N user list 2>&1 | tail -1

实测输出：

user id,username,user's name,user email,admin,created at,updated at,last access,last login,libraries

五、用户管理命令（user）

5.1 user create：创建用户

$N user create --help 2>&1 | head -14

实测输出：

Create a new user

Usage:
  navidrome user create [flags]

Aliases:
  create, c

Flags:
  -a, --admin              If set, make the user an admin. This user will have access to every library
  -e, --email string       New user email
  -h, --help               help for create
  -i, --library-ids ints   Comma-separated list of library IDs. Set the user's accessible libraries. If empty, the user can access all libraries. This is incompatible with admin, as admin can always access all libraries
      --name string        New user's name (this is separate from username used to log in)

创建管理员（-a）：

$N user create -u admin -a --name "Admin" -e admin@example.com

实测输出：

Enter new password:

⚠️ 密码只能交互输入：0.64.2 的 user create 没有 --password 旗标，回车后交互提示输入（再确认一次）。脚本/无人值守场景用 expect 驱动：

expect -c '
set timeout 30
spawn navidrome -c /etc/navidrome/navidrome.toml --nobanner user create -u admin -a --name Admin -e admin@example.com
expect "Enter new password"
send "q1w2e3r4\r"
expect "Confirm new password"
send "q1w2e3r4\r"
expect eof'

实测输出（节选）：

Enter new password:
Confirm new password:
2026-10-25 03:23:42.390187061 [SQL] ...

创建普通用户并限定曲库可见性：

$N user create -u tester -e tester@example.com -i 1

实测输出（交互输入密码 q1w2e3r4 后，节选）：

Enter new password:
Confirm new password:
2026-10-25 03:25:18.114387421 [SQL] ...

5.2 user list：列出用户

$N user list

实测输出：

user id,username,user's name,user email,admin,created at,updated at,last access,last login,libraries
2xg4U8IEZPdXbQnfPNC1JG,admin,管理员,admin@example.com,true,2026-10-25T03:23:42.141248099Z,2026-10-25T03:23:54.835370101Z,2026-10-25T03:37:42.692464604Z,2026-10-25T03:27:42.476082464Z,'1:/srv/music'
0TnSRYPYBqLh0GLDT2ciTR,tester,tester,tester@example.com,false,2026-10-25T03:25:18.341290596Z,2026-10-25T03:25:18.341290596Z,never,never,'1:/srv/music'

💡 说明：CSV 输出，libraries 列展示用户可访问的「库 ID:路径」；-i 1 限定了 tester 只能访问 1 号库。user id 列（如 2xg4U8IEZPdXbQnfPNC1JG）同时是其他命令与 API 中引用用户的稳定标识。

5.3 user edit：修改用户属性

$N user edit --help 2>&1 | head -16

实测输出（节选）：

Edit the password, admin status, and/or library access

Usage:
  navidrome user edit [flags]

Flags:
  -e, --email string       New user email
  -i, --library-ids ints   Comma-separated list of library IDs. Set the user's accessible libraries by id
      --name string        New user name (this is separate from username used to log in)
      --remove-email       If set, clear the user's email
      --remove-name        If set, clear the user's name
      --set-admin          If set, make the user an admin
      --set-password       If set, the user's new password will be prompted on the CLI
      --set-regular        If set, make the user a non-admin
  -u, --user string        username or id

改显示名（免交互，立即生效）：

$N user edit -u admin --name "管理员"

实测输出：

Success. admin: 管理员

重置密码（交互输入两次新密码）：

$N user edit -u admin --set-password

实测输出：

Enter new password:
Confirm new password:
Success. admin: password changed

5.4 user delete：删除用户与安全阀

$N user delete -u tester

实测输出：

Success. tester: deleted

尝试删除仅剩的管理员/不存在的用户时，CLI 有保护性拦截：

$N user delete -u nobody

实测输出：

time="2026-10-25T03:36:46Z" level=fatal msg="Failed to delete user" error="refusing to delete the last user"

⚠️ 安全阀语义：实例只剩一个用户时（无论目标用户名是否存在）删除都会被拒绝，避免管理失控。必须先创建第二个管理员再删除旧账号。

六、曲库与扫描命令

6.1 scan：扫描曲库

$N scan --help 2>&1 | head -12

实测输出：

Scan music folder for updates

Usage:
  navidrome scan [flags]

Flags:
  -f, --full                 check all subfolders, ignoring timestamps
  -h, --help                 help for scan
      --subprocess           run as subprocess (internal use)
  -t, --target stringArray   list of libraryID:folderPath pairs, can be repeated (e.g., "-t 1:Music/Rock -t 1:Music/Jazz -t 2:Classical")
      --target-file string   path to file containing targets (one libraryID:folderPath per line)

增量扫描（默认，跳过未变化目录）：

$N scan 2>&1 | grep -E "Finished scanning"

实测输出：

time="2026-10-25T03:24:06Z" level=info msg="Scanner: Finished scanning all libraries" duration=8.3ms

全量扫描（忽略时间戳，重新核对所有文件）：

$N scan -f 2>&1 | grep -E "Finished scanning"

实测输出：

time="2026-10-25T03:25:02Z" level=info msg="Scanner: Finished scanning all libraries" duration=30.6ms

💡 说明：日常建议交给 Scanner.Schedule 定时任务（见《Navidrome 0.64.2 配置参数详解》 5.2 节）；CLI 的 scan 用于手动触发——大曲库批量导入后、调试标签识别时、-f 排查「改了标签没变化」类问题。多曲库实例可用 -t 库ID:相对路径 只扫指定库。

6.2 inspect：单文件元数据检查

inspect 直接调用 Navidrome 内嵌的元数据引擎读文件，输出引擎解析到的全部字段——排查标签、封面、歌词问题的第一工具：

$N inspect "/srv/music/Aurora-Lights/2021-Voyage/01-Starlight-Drive.mp3" --format pretty 2>&1 | head -18

实测输出：

====================
File: /srv/music/Aurora-Lights/2021-Voyage/01-Starlight-Drive.mp3

Raw tags:
album = ['Voyage']
albumartist = ['Aurora Lights']
artist = ['Aurora Lights']
date = ['2021']
encoding = ['Lavf58.76.100']
genre = ['Synthwave']
title = ['Starlight Drive']
tracknumber = ['1']


Mapped tags:
PlayCount = 0
Rating = 0
Starred = false
AverageRating = 0.0
BookmarkPosition = 0

JSON 全量输出（含引擎映射后的完整字段，节选）：

$N inspect "/srv/music/Aurora-Lights/2021-Voyage/01-Starlight-Drive.mp3" --format json 2>&1 | head -2

实测输出（节选，实测首部）：

[{"file":"/srv/music/Aurora-Lights/2021-Voyage/01-Starlight-Drive.mp3","rawTags":{"album":["Voyage"],...},"mappedTags":{"path":"/srv/music/Aurora-Lights/2021-Voyage/","title":"Starlight Drive","album":"Voyage","artist":"Aurora Lights","albumId":"7nab3tPW9XlFxETa6jaRMk","hasCoverArt":false,"trackNumber":1,"year":2021,"size":721795,"duration":30.04,"bitRate":192,"sampleRate":44100,"channels":1,"codec":"MP3",...}}]

💡 说明：Raw tags 是文件里的原始标签，Mapped tags/mappedTags 是引擎映射后的结果——当 Web UI 里某首歌信息不对时，对比这两段就能判断是「文件标签问题」还是「映射配置（Tags.*）问题」。hasCoverArt:false 说明该文件未内嵌封面（封面来自同目录 cover.jpg，见 10.4 节 explain 输出）。

6.3 doctor：数据库体检

$N doctor

实测输出：

Checking database integrity...
Integrity check passed.
Checking foreign keys...
Foreign key check passed.
Database is healthy.

💡 说明：等价于 SQLite 的 PRAGMA integrity_check + foreign_key_check。建议加入停机维护清单：升级版本前、数据库异常增长后、出现查询报错后各跑一次。

七、播放列表命令（pls）

0.64.2 的 pls 组实测只有三个子命令：list、import、export。

$N pls --help 2>&1 | grep -A6 "Available Commands"

实测输出：

Available Commands:
  export      Export playlists to M3U files
  import      Import M3U playlists
  list        List playlists

7.1 pls list：列出播放列表

$N pls list

实测输出：

playlist id,playlist name,owner id,owner name,public
5t9ziOGghSnO9sWin1kvwW,My-Favorites,2xg4U8IEZPdXbQnfPNC1JG,admin,false

7.2 pls import：导入 M3U

曲库内准备 road-trip.m3u：

#EXTM3U
#EXTINF:212,Aurora Lights - Starlight Drive
Aurora-Lights/2021-Voyage/01-Starlight-Drive.mp3
#EXTINF:195,Vapor Field - Hazy Memory
Various-Artists/2022-Synth-Compilation/02-Hazy-Memory.mp3

$N pls import /srv/music/road-trip.m3u

实测输出：

Imported "road-trip" — 2/2 tracks matched (0 not found)

⚠️ 导入规则：M3U 内路径是相对 MusicFolder 的相对路径（也可绝对路径）。另外开启 AutoImportPlaylists（默认 true）时，放进 PlaylistsPath 的 m3u 会被服务端自动导入，CLI import 用于手动补导与规则外位置。

7.3 pls export：导出 M3U

$N pls export -p road-trip -o /tmp

实测输出：

Exported "road-trip" to /tmp/road-trip.m3u

cat /tmp/road-trip.m3u

实测输出：

#EXTM3U
#PLAYLIST:road-trip
#EXTINF:30,Aurora Lights - Starlight Drive
/srv/music/Aurora-Lights/2021-Voyage/01-Starlight-Drive.mp3
#EXTINF:27,Vapor Field - Hazy Memory
/srv/music/Various-Artists/2022-Synth-Compilation/02-Hazy-Memory.mp3

💡 说明：导出为绝对路径形式（便于挪库后回导），#EXTINF 时长按文件真实时长重写（测试曲每首 30 秒）。-o 指定输出目录，-p 指定播放列表名。

7.4 删除播放列表：CLI 没有这个命令（实测）

官方文档的 pls 组列有 rm，但 0.64.2 二进制实测没有该子命令：

$N pls rm --playlist road-trip 2>&1 | head -3

实测输出（错误用法触发了父命令的导出行为）：

#EXTM3U
#PLAYLIST:road-trip
#EXTINF:30,Aurora Lights - Starlight Drive

播放列表依然存在，且 pls --help 的 Available Commands 里没有 rm。删除播放列表的可行路径：Web UI，或 Subsonic API deletePlaylist：

TOKEN=$(python3 -c "import hashlib;print(hashlib.md5('q1w2e3r4api26'.encode()).hexdigest())")
curl -s "http://127.0.0.1:4533/rest/deletePlaylist?id=0nJSbIRkgvvHxJWfSI9fX0&u=admin&t=$TOKEN&s=api26&v=1.16.1&c=doc-test&f=json"

实测输出：

{"subsonic-response":{"status":"ok","version":"1.16.1","type":"navidrome","serverVersion":"0.64.2 (10114574)","openSubsonic":true}}

$N pls list

实测输出：

playlist id,playlist name,owner id,owner name,public
5t9ziOGghSnO9sWin1kvwW,My-Favorites,2xg4U8IEZPdXbQnfPNC1JG,admin,false

💡 说明：删除前用 pls list 拿到 playlist id，再调 deletePlaylist?id=<id>。Subsonic 认证参数（u/t/s/v/c）说明见《Navidrome 0.64.2 Docker Compose 部署指南》 4.6 节。

八、缺失文件处理命令（missing）

曲库文件被移动、改名或删除后，库内会留下「缺失条目」。missing 组用于盘点与修复。先理解自动调和：0.64.2 扫描器会按内嵌标签中的持久标识（如 musicbrainz_trackid）自动重关联改名/移动的文件——实测把 02-Hazy-Memory.mp3 改名为 02-Hazy-Memory-Renamed.mp3 后执行 scan -f，missing list 自动清空，无需人工介入。missing 命令处理的是自动调和失败的残余场景。

8.1 missing list：盘点缺失文件

模拟删除一个文件后全量扫描：

mv /srv/music/Various-Artists/2022-Synth-Compilation/02-Hazy-Memory.mp3 /tmp/
$N scan -f 2>&1 | grep -E "Finished scanning"
$N missing list

实测输出：

time="2026-10-25T03:35:14Z" level=info msg="Scanner: Finished scanning all libraries" duration=30.6ms
id,library id,title,album,artist,path
5JZKVfsgMdhkZ5fvqcn7Mv,1,Hazy Memory,Synth Compilation,Vapor Field,Various-Artists/2022-Synth-Compilation/02-Hazy-Memory.mp3

JSON 格式（-f json，注意与全局 --format 区分）：

$N missing list -f json

实测输出：

[{"id":"5JZKVfsgMdhkZ5fvqcn7Mv","libraryId":1,"title":"Hazy Memory","album":"Synth Compilation","artist":"Vapor Field","path":"Various-Artists/2022-Synth-Compilation/02-Hazy-Memory.mp3"}]

文件放回后复查：

mv /tmp/02-Hazy-Memory.mp3 /srv/music/Various-Artists/2022-Synth-Compilation/
$N scan -f 2>&1 | grep -E "Finished scanning"
$N missing list

实测输出：

time="2026-10-25T03:35:14Z" level=info msg="Scanner: Finished scanning all libraries" duration=37.9ms
id,library id,title,album,artist,path

缺失清单清空（只剩表头）。

8.2 missing fix：手动重映射

语法：missing fix <缺失条目路径或ID> <现存文件路径或ID>。两个实测边界（排障时对号入座）：

第一个参数必须指向库内缺失条目。传一个磁盘上已不存在的旧路径，直接 fatal：

$N missing fix "Various-Artists/2022-Synth-Compilation/02-Hazy-Memory.mp3" "Various-Artists/2022-Synth-Compilation/02-Hazy-Memory-Final.mp3"

实测输出：

time="2026-10-25T03:35:51Z" level=fatal msg="No media file found" ref=Various-Artists/2022-Synth-Compilation/02-Hazy-Memory.mp3

目标文件若已被扫描器自动调和，再 fix 会提示同文件：

time="2026-10-25T03:36:11Z" level=fatal msg="Failed to remap missing file" error="missing and target are the same file: \"5JZKVfsgMdhkZ5fvqcn7Mv\"" missing=Various-Artists/2022-Synth-Compilation/02-Hazy-Memory-Final.mp3 target=Various-Artists/2022-Synth-Compilation/02-Hazy-Memory-Final.mp3

💡 说明：missing fix 的正确姿势是——先 missing list 拿到缺失条目的 id 与 path，确认目标文件已在磁盘新位置，再以条目 id 或其最近路径作为第一参数执行。自动调和正常工作的大多数场景用不到它；它主要用于 PID 标签缺失、且文件路径与元数据同时变化的疑难情况。

九、备份与恢复命令（backup）

9.1 backup create：立即备份

$N backup create 2>&1 | grep -E "Successfully|Backup"

实测输出：

2026-10-25 03:25:29.077707232 [SQL] ...
time="2026-10-25T03:25:29Z" level=info msg="Backup process started"
time="2026-10-25T03:25:29Z" level=info msg="Backup process finished successfully"

ls -la /var/lib/navidrome/backups/ | tail -2

实测输出：

-rw-r--r-- 1 root root 724992 Oct 25 03:25 navidrome_backup_2026.10.25_03.25.02.db
-rw-r--r-- 1 root root 725504 Oct 25 03:26 navidrome_backup_2026.10.25_03.26.00.db

9.2 backup prune：清理旧备份

$N backup prune 2>&1 | grep -viE "level=(debug|info)" | tail -1

实测输出（无输出即清理完成，备份目录保留最近份数）：

（命令正常返回，目录中超出保留策略的旧备份被移除）

💡 说明：prune 依据配置项 Backup.Count（保留份数）裁剪；配合 Backup.Path/Backup.Schedule 可完全自动化（见《Navidrome 0.64.2 配置参数详解》 5.7 节）。

9.3 backup restore：恢复演练（实测）

演练设计：创建演练账号 tester → 备份快照 → 删除 tester → 恢复快照 → 验证 tester 复活。全套实测通过：

$N user list 2>&1 | grep -c tester || echo "tester 不在列表"

实测输出：

tester 不在列表

恢复（交互式确认，输入大写 YES）：

echo "YES" | $N backup restore --backup-file /var/lib/navidrome/backups/navidrome_backup_2026.10.25_03.25.02.db

实测输出：

Warning: restoring the Navidrome database should only be done offline, especially if your backup is very old.
Please enter YES (all caps) to continue: time="2026-10-25T03:42:50Z" level=info msg="Restore complete" elapsed=3.9ms

恢复完成后验证：

$N user list 2>&1 | grep tester

实测输出：

0TnSRYPYBqLh0GLDT2ciTR,tester,tester,tester@example.com,false,2026-10-25T03:25:18.341290596Z,2026-10-25T03:25:18.341290596Z,never,never,'1:/srv/music'

被删除的 tester 完整恢复。

⚠️ restore 直接替换数据库文件，官方提示「应仅在离线状态执行」（备份越旧越要如此）。正确顺序：停服（$N service stop）→ 恢复 → 起服（$N service start）。演练收尾：清理演练账号 $N user delete -u tester（输出 Success. tester: deleted）。

十、系统与辅助命令

10.1 search rebuild：重建检索索引

升级、批量改标签或检索结果异常后执行。带确认交互（输入大写 YES）：

echo "YES" | $N search rebuild 2>&1 | tail -3

实测输出：

This will rebuild the search index. Make sure Navidrome is not running.
Please enter YES (all caps) to continue: Rebuilding the search index...
Search index rebuilt successfully.

💡 说明：0.64.2 默认使用 SQLite FTS5 全文检索（Search.Backend = 'fts'），索引存于数据库内。官方提示建议停机重建（实测在线执行也能完成）；完成后检索结果按 BM25 相关性排序。中文曲库建议同步检查 Search.FullString 配置（见配置篇 5.10 节）。

10.2 service：管理 systemd 服务

service 组封装 systemctl 对 navidrome 单元的启停（等价于 systemctl start/stop/restart/status navidrome）：

$N service status

实测输出：

Navidrome is Running.

$N service stop

实测输出：

Service stopped. Use 'navidrome svc status' to check its status.

$N service status

实测输出：

Navidrome is Stopped.

$N service start

实测输出：

Service started. Use 'navidrome svc status' to check its status.

$N service status && systemctl is-active navidrome

实测输出：

Navidrome is Running.
active

💡 说明：service 子命令工作在 systemd 服务器上（navidrome.service 单元已安装的场景），脚本里用它可避免硬编码 systemctl 路径；无 systemd 的环境直接用进程管理器管理 navidrome serve。

10.3 plugin list：查看插件

$N plugin list 2>&1 | tail -1

实测输出：

ID  NAME  VERSION  ENABLED  LAST ERROR

💡 说明：0.64.2 的插件体系（以 wasm 插件形式装载于 DataFolder/plugins）尚在演进，全新实例插件目录为空，list 只输出表头。插件能力矩阵与安装方法以官方 Plugins 文档为准。

10.4 artwork：封面缓存工具

artwork 组共 5 个子命令（实测 --help）：

$N artwork --help 2>&1 | grep -A7 "Available Commands"

实测输出：

Available Commands:
  cancel      Cancel pending artwork work in bulk, by kind and/or queue priority
  explain     Explain why an item's artwork resolved the way it did
  refresh     Clear an item's artwork state and re-resolve it
  reprocess   Re-enqueue artwork in bulk, by kind and/or by the source it currently resolves from
  status      Report the artwork queue, where artwork resolves from, and the config state

缓存与解析队列总览：

$N artwork status 2>&1 | tail -14

实测输出（节选）：

Queue
  KIND    PRIORITY  ITEMS
  artist  scan      3
  TOTAL             3

Sources
  KIND      SOURCE     ITEMS
  artist    absent     1
  album     folder     3
  playlist  generated  2

Absent (resolved, no image found)
  KIND    NO IMAGE  FAILED
  artist  1         0

explain 解释某个对象的封面来源链。对象可用「裸 ID / al-<id> 形式的完整封面 ID / <kind> <id> 对」表达，kind 短码：ar（艺人）、al（专辑）、dc（碟片）、mf（曲目）、pl（播放列表）、ra（电台）：

$N artwork explain al 7nab3tPW9XlFxETa6jaRMk 2>&1 | tail -14

实测输出（节选）：

Item
  Kind:  album (al)
  ID:    7nab3tPW9XlFxETa6jaRMk
  Name:  Voyage

Stored
  Source:        folder
  Hash:          f098660df87efe6d
  Source path:   /srv/music/Aurora-Lights/2021-Voyage/cover.jpg
  Attempted at:  2026-10-25T03:15:45Z

Queue
  (not queued)

Config
  CoverArtPriority:  cover.*, folder.*, front.*, embedded, external
  Agents:            deezer*, lastfm*, listenbrainz*  (* not available to the CLI)

💡 说明：这份输出把封面解析链完整呈现——《Voyage》的封面来自 folder（同目录 cover.jpg），与 CoverArtPriority 配置一致；Agents 行的 * 表示外部元数据代理对 CLI 不可用（需 --live 才会真实外联重查）。灰封面/错封面问题的排查路径：status 看队列与来源分布 → explain 定位单个对象的解析依据 → refresh 清状态重解析。

⚠️ explain/refresh 需要对象真实存在——传不存在的 ID 会报 not found；kind 用错全称（如 album）会被当作裸 ID 解析并报 could not determine kind（实测），务必用短码。

10.5 completion：Shell 补全

$N completion bash | head -3

实测输出：

# bash completion V2 for navidrome                          -*- shell-script -*-
...

💡 说明：支持 bash/zsh/fish/powershell。bash 用户落地：$N completion bash > /etc/bash_completion.d/navidrome && source /etc/bash_completion.d/navidrome，之后子命令与旗标均可 Tab 补全。

十一、自动化脚本实践

场景一：每日定时备份（保留 7 份）。 已由配置项 Backup.Schedule/Backup.Count 原生支持（见配置篇 5.7 节），无需 cron。若需把备份异地化，再叠加一个 cron：

# /etc/cron.d/navidrome-offsite —— 每天 3:40 把最新备份同步到异地目录
40 3 * * * root rsync -a --prune-empty-dirs /var/lib/navidrome/backups/ /mnt/nas-backup/navidrome/ && find /var/lib/navidrome/backups -name '*.db' -mtime +7 -delete

场景二：曲库同步后触发扫描。 挂载盘同步完成后手动触发一次增量扫描：

#!/usr/bin/env bash
# /usr/local/bin/nd-scan-after-sync.sh
set -euo pipefail
N="navidrome -c /etc/navidrome/navidrome.toml --nobanner"
rsync -a /mnt/nas/music/ /srv/music/ 2>/dev/null || true
$N scan 2>&1 | grep -E "Finished scanning" || $N scan -f
$N missing list -f csv | tail -n +2 | wc -l

💡 说明：脚本最后输出缺失条目数，接入监控通知即可实现「同步 → 扫描 → 缺失盘点」闭环。missing list 的 CSV 首行是表头，统计时用 tail -n +2 去掉。

场景三：停机维护 SOP（升级前）。

$N doctor                     # 1. 体检
$N backup create              # 2. 立即备份
$N backup prune               # 3. 清理旧备份
systemctl stop navidrome      # 4. 停服（或 $N service stop）
# 升级二进制...
systemctl start navidrome     # 5. 起服
$N scan -f                    # 6. 全量扫描复核

⚠️ 升级若需回退，用 backup restore --backup-file <升级前快照> 恢复数据库（流程与回显见 9.3 节）。

十二、常见问题

Q1：user list 报 no such table: user？

CLI 在错误的工作目录按默认参数新建了空库（--configfile 默认 ./navidrome.toml）。带 -c /etc/navidrome/navidrome.toml 重跑即可（现场复现与验证见 4.3 节）。

Q2：user create 卡住没反应？

它在等你交互输入密码（没有 --password 旗标，0.64.2 实测）。前台跑会停在 Enter new password:；无人值守用 expect 驱动（见 5.1 节）。

Q3：删除用户报 refusing to delete the last user？

实例只剩一个用户时的安全阀，目标用户名不存在也会报这个（见 5.4 节）。先创建第二个管理员，再删旧账号。

Q4：pls rm 报错或行为诡异？

0.64.2 的 pls 组实测只有 list/import/export，官方文档所列的 rm 在该版本二进制中不存在（证据见 7.4 节）。删除播放列表走 Web UI 或 Subsonic API deletePlaylist。

Q5：missing list 显示有缺失文件，但文件明明在库里？

先跑 $N scan -f 全量扫描刷新；若改过名，扫描器的自动调和会清掉大多数缺失条目（见第八章开头）。仍残留时用 missing fix 以缺失条目 id 重映射。

Q6：artwork explain 报 not found？

该命令需要服务在线且对象 ID 真实存在（见 10.4 节实测）。确认服务已启动、ID 取自 pls list/Web UI 地址栏而非数据库历史快照。

Q7：backup restore 执行后服务起不来？

restore 会替换数据库文件并停服，恢复完成后需要 systemctl restart navidrome（restore 输出亦提示 Please restart the service）。若恢复的是跨大版本的旧备份，先查阅该版本的升级日志确认数据库兼容性。

十三、参考链接

官方 CLI 参考：https://www.navidrome.org/docs/usage/administration/cli/
官方开发者/构建文档（二进制获取）：https://www.navidrome.org/docs/developers/subsystem/building/
GitHub 仓库：https://github.com/navidrome/navidrome（本文版本信息查询日期：2026-10-25）
站内同系列：《Navidrome 0.64.2 介绍与选型指南》、《Navidrome 0.64.2 Docker Compose 部署指南》、《Navidrome 0.64.2 配置参数详解》

Navidrome 0.64.2 常用 CLI 命令与工具详解

Navidrome 0.64.2 常用 CLI 命令与工具详解

一、环境信息

二、前置条件

三、CLI 命令总览

3.1 主命令帮助

3.2 子命令速查表

四、全局参数与典型运行错误

4.1 高频全局参数

4.2 配置文件基准

4.3 典型错误现场：no such table: user

五、用户管理命令（user）

5.1 user create：创建用户

5.2 user list：列出用户

5.3 user edit：修改用户属性

5.4 user delete：删除用户与安全阀

六、曲库与扫描命令

6.1 scan：扫描曲库

6.2 inspect：单文件元数据检查

6.3 doctor：数据库体检

七、播放列表命令（pls）

7.1 pls list：列出播放列表

7.2 pls import：导入 M3U

7.3 pls export：导出 M3U

7.4 删除播放列表：CLI 没有这个命令（实测）

八、缺失文件处理命令（missing）

8.1 missing list：盘点缺失文件

8.2 missing fix：手动重映射

九、备份与恢复命令（backup）

9.1 backup create：立即备份

9.2 backup prune：清理旧备份

9.3 backup restore：恢复演练（实测）

十、系统与辅助命令

10.1 search rebuild：重建检索索引

10.2 service：管理 systemd 服务

10.3 plugin list：查看插件

10.4 artwork：封面缓存工具

10.5 completion：Shell 补全

十一、自动化脚本实践

十二、常见问题

十三、参考链接

4.3 典型错误现场：`no such table: user`