Navidrome 0.64.2 Docker Compose 部署指南

目标：用 Docker Compose 在单台 Ubuntu 22.04 服务器上从零部署 Navidrome 0.64.2 自托管音乐流媒体服务器，完成「管理员创建 → 曲库扫描 → Subsonic API 认证 → 原格式/Opus 转码流播放 → 数据持久化」的完整验证链路。本文全部命令与回显已在 Docker Engine 29.9.2（Compose v5.6.1）环境实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64）
Docker Engine：29.9.2，Docker Compose 插件 v5.6.1
Navidrome 版本：0.64.2（2026-09-24 发布，官方最新稳定版，发布信息查询日期 2026-10-25）
官方镜像：navidrome/navidrome:0.64.2（amd64，348 MB）
测试曲库：1 位专辑艺人 2 张专辑 + 1 张合辑，共 6 首 mp3（每专辑目录含 cover.jpg 封面），外加 1 个 .m3u 播放列表文件
端口规划：Navidrome 服务宿主端口 8134（服务端口 4533）。生产环境建议直接映射 4533 或经反向代理暴露，本文端口取值仅为与实测环境保持一致，可按需替换
编排目录：/opt/navidrome/（示例路径，含 docker-compose.yml、music/、data/）
独立网络：navidrome-net（bridge，网段 10.89.60.0/24）

二、镜像选型说明

Navidrome 官方只发布单一镜像，不提供多变体，选型要点集中在仓库地址与标签策略两点：

项目	取值	说明
官方镜像仓库	`navidrome/navidrome`	Docker Hub 官方命名空间；旧路径 `deluan/navidrome` 已迁移，官方文档（2026-10-16 更新）已全面改用新地址
精确版本标签	`0.64.2`	与 GitHub Release（tag `v0.64.2`）一一对应，生产推荐，升级可控
滚动最新标签	`latest`	跟随最新稳定版，`docker compose pull` 即升级，但回显不可复现

镜像关键元数据（docker inspect 实测）：

User= | Entry=["/app/navidrome"] | WorkDir=/app | Exposed={"4533/tcp":{}} | Volumes={"/data":{},"/music":{}}

服务二进制位于容器内 /app/navidrome，默认以 root 运行（User 为空），暴露端口 4533，声明了 /data（应用数据）与 /music（曲库）两个挂载点
镜像内置 ffmpeg（实测启动日志 Found ffmpeg path=/usr/bin/ffmpeg），转码功能开箱即用，无需额外安装

💡 说明：本文全部使用 0.64.2 精确标签，保证文中回显可复现。数据目录 /data 内含 SQLite 数据库（navidrome.db）、缓存（cache/）与插件目录（plugins/），是唯一需要持久化的状态目录。

三、前置条件

服务器已安装 Docker Engine 与 Compose 插件，验证：

docker version --format 'Engine {{.Server.Version}}'

实测输出：

Engine 29.9.2

docker compose version

实测输出：

Docker Compose version v5.6.1

曲库就绪：准备一个只读的音乐目录，目录结构按 /专辑艺人/年份-专辑名/曲目录.mp3 组织，音频文件内嵌 ID3 标签（艺人、专辑、曲名、音轨号、年份）。Navidrome 依赖标签而非目录结构组织曲库（目录结构仅用于模拟文件夹浏览）。曲库目录对 Navidrome 只需读权限。
端口确认：宿主端口未被占用：

ss -ltn | grep 8134 || echo "8134 空闲"

实测输出：

8134 空闲

四、部署步骤

本章按「创建网络 → 编写编排文件 → 启动 → 创建管理员 → 扫描曲库 → Subsonic API 验证 → 播放验证」的顺序完成 0→1 部署。预期结果：服务健康运行，管理员可登录，Subsonic 兼容客户端可发现并播放曲库。

4.1 创建独立网络

为整套服务创建独立 bridge 网络并显式指定网段，避免与其他业务网段冲突：

docker network create -d bridge --subnet 10.89.60.0/24 navidrome-net

实测输出：

dc5f9929475f80a85764181c2bb25997ac5ab5843225b582485de127e457d608

💡 说明：Navidrome 单机部署并不依赖外部组件（数据库内嵌 SQLite），独立网络主要为后续与反向代理、导出器等附加服务同栈编排预留扩展位。若网段与现有网络冲突，换一个空闲 /24 即可，同步修改编排文件。

4.2 编写编排文件

创建部署目录 /opt/navidrome/，写入 docker-compose.yml：

mkdir -p /opt/navidrome && cd /opt/navidrome

docker-compose.yml 完整内容：

name: navidrome-0.64.2-stack

services:
  navidrome:
    image: navidrome/navidrome:0.64.2
    container_name: navidrome-0.64.2-web
    restart: unless-stopped
    ports:
      - "8134:4533"
    environment:
      ND_LOGLEVEL: info
      ND_SESSIONTIMEOUT: 24h
      ND_ENABLETRANSCODINGCONFIG: "true"
      ND_DEFAULTLANGUAGE: zh-Hans
    volumes:
      - "./music:/music:ro"
      - "./data:/data"
    networks:
      - navidrome-net

networks:
  navidrome-net:
    external: true

逐项说明：

name：显式指定 Compose 项目名 navidrome-0.64.2-stack，避免多套部署目录同名导致 down 误删其他在跑实例
image：精确版本标签 0.64.2，与本文回显一致
container_name：固定实例名，便于 docker logs/docker exec 定位
ports：宿主 8134 → 服务 4533
ND_LOGLEVEL：日志级别，排障时可改 debug
ND_SESSIONTIMEOUT：Web UI 空闲会话时长，默认 48h，这里收紧为 24h
ND_ENABLETRANSCODINGCONFIG：允许在 Web UI 中配置转码选项
ND_DEFAULTLANGUAGE：新浏览器首次登录的界面默认语言，中文简体为 zh-Hans
volumes：曲库 ./music 以只读（:ro）方式挂到 /music；状态目录 ./data 挂到 /data
networks：接入 4.1 创建的外部网络

4.3 启动服务

docker compose up -d

实测输出：

[+] Running 2/2
 ✔ Network navidrome-0.64.2-stack_default  Created
 ✔ Container navidrome-0.64.2-web          Started

💡 说明：Compose 会为项目自动附加一个默认网络；显式声明的 navidrome-net 为外部网络，供后续扩展服务共用。

确认运行状态：

docker compose ps

实测输出：

NAME                   IMAGE                        COMMAND            SERVICE     CREATED         STATUS         PORTS
navidrome-0.64.2-web   navidrome/navidrome:0.64.2   "/app/navidrome"   navidrome   6 seconds ago   Up 6 seconds   0.0.0.0:8134->4533/tcp, [::]:8134->4533/tcp

查看启动日志，确认版本与各组件初始化正常：

docker logs navidrome-0.64.2-web

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

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

time="2026-10-25T03:13:06Z" level=info msg="No configuration file found. Loaded configuration only from environment variables"
time="2026-10-25T03:13:06Z" level=info msg="Creating DB Schema"
time="2026-10-25T03:13:07Z" level=info msg="Starting Insight Collector"
...
time="2026-10-25T03:13:07Z" level=info msg="Found ffmpeg" path=/usr/bin/ffmpeg
time="2026-10-25T03:13:07Z" level=info msg="Mounting Native API routes" path=/api
time="2026-10-25T03:13:07Z" level=info msg="Mounting Subsonic API routes" path=/rest
time="2026-10-25T03:13:07Z" level=info msg="Mounting Public Endpoints routes" path=/share
time="2026-10-25T03:13:07Z" level=info msg="Mounting WebUI routes" path=/app

💡 说明：Mounting Subsonic API routes path=/rest 表明 Subsonic 兼容 API 已挂载，这是各类 Subsonic 客户端 App 的接入端点。No configuration file found 为正常现象——本次部署仅用环境变量注入配置（配置文件方式见第九章）。

4.4 HTTP 存活验证

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8134/ping

实测输出：

/ping 返回 200 即服务存活。此时浏览器访问 http://<服务器IP>:8134 会先进入「创建管理员账号」页面。

4.5 创建管理员账号

首个创建的账号自动成为管理员。除 Web UI 外，可用内置 HTTP API 直接创建。本文演示账号为 admin，密码 q1w2e3r4：

curl -s -X POST http://127.0.0.1:8134/auth/createAdmin \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}'

实测输出：

{"id":"38HXSLFOSYnKBAXVmdMMWK","isAdmin":true,"name":"Admin","subsonicSalt":"39a9e3","subsonicToken":"7dbca049c9d1103a599cdc08de2a6493","token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZG0iOnRydWUsImV4cCI6MTc5Mjk4NDQwMywiaWF0IjoxNzkyODk4MDAzLCJpc3MiOiJORCIsInN1YiI6ImFkbWluIiwidWlkIjoiMzhIWFNMRk9TWW5LQkFYVm1kTU1XSyJ9.CXddluWwBCUCwyk1Kh1FBUGw7GwGOrnmrJUhthPNZns","username":"admin"}

⚠️ /auth/createAdmin 仅在实例还没有任何用户时可用，首次创建后即失效（重复调用返回错误）。id 为该用户的持久化用户 ID，后续 API 调用可用返回的 token 作为 Web 凭据。

用登录接口复核账号可用：

curl -s -X POST http://127.0.0.1:8134/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}'

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

{"id":"38HXSLFOSYnKBAXVmdMMWK","isAdmin":true,"name":"Admin","subsonicSalt":"39a9e3","subsonicToken":"7dbca049c9d1103a599cdc08de2a6493","token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

4.6 Subsonic API 认证与曲库扫描验证

Subsonic API（/rest 路径）使用独立的 用户名 + token + salt 认证：token = md5(密码 + salt)。以 salt navi2026s8 为例，先算出 token：

SALT=navi2026s8
TOKEN=$(python3 -c "import hashlib;print(hashlib.md5('q1w2e3r4${SALT}'.encode()).hexdigest())")
echo $TOKEN

实测输出：

baccfaea635009180a5d06f8a1e87a3e

💡 技术拓展：Subsonic 生态的 API 认证有三种形态——

认证方式参数特点
明文密码 u + p 最老的形式，部分老客户端仍在用，明文传输有风险
认证 token u + t + s t=md5(p+s)，密码不落网线上，Subsonic 1.13 起的标准方式
API Key u + apiKey OpenSubsonic 扩展提案，Navidrome 尚未提供

Navidrome 兼容前两种；本文与主流客户端一致采用 token 方式。

认证方式	参数	特点
明文密码	`u` + `p`	最老的形式，部分老客户端仍在用，明文传输有风险
认证 token	`u` + `t` + `s`	`t=md5(p+s)`，密码不落网线上，Subsonic 1.13 起的标准方式
API Key	`u` + `apiKey`	OpenSubsonic 扩展提案，Navidrome 尚未提供

认证 ping，确认 API 层可用：

curl -s "http://127.0.0.1:8134/rest/ping?u=admin&t=$TOKEN&s=$SALT&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}}

💡 说明：openSubsonic:true 表示服务端支持 OpenSubsonic 扩展（Subsonic API v1.16.1 的社区演进版）。c 参数为客户端名（自取），v 为客户端声明的 API 版本。

触发曲库扫描并查看扫描状态：

curl -s "http://127.0.0.1:8134/rest/startScan?u=admin&t=$TOKEN&s=$SALT&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,"scanStatus":{"scanning":true,"count":6,"folderCount":3,"lastScan":"2026-10-25T03:13:09.310630817Z","scanType":"full","elapsedTime":24772221449}}}

实测曲库 6 首歌、3 个专辑目录已被识别（服务启动时也会自动执行一次初始扫描，此处 startScan 为显式触发）。

4.7 曲库内容验证

列出可检索到的艺人：

curl -s "http://127.0.0.1:8134/rest/getArtists?u=admin&t=$TOKEN&s=$SALT&v=1.16.1&c=doc-test&f=json" \
  | python3 -c "import json,sys;d=json.load(sys.stdin)['subsonic-response']['artists'];[print(a['id'],a['name'],'albums:',a['albumCount']) for a in d['index'][0]['artist']]"

实测输出：

0CT3ePFzfTDsmSXRzT1JTx Aurora Lights albums: 2

列出专辑：

curl -s "http://127.0.0.1:8134/rest/getAlbumList2?u=admin&t=$TOKEN&s=$SALT&v=1.16.1&c=doc-test&f=json&type=alphabeticalByName&size=10" \
  | python3 -c "import json,sys;al=json.load(sys.stdin)['subsonic-response']['albumList2']['album'];[print(a['id'],a['name'],'-',a['artist'],'songs:',a['songCount']) for a in al]"

实测输出：

3HpNQt3wm2zwga0RmgoozY Horizon - Aurora Lights songs: 2
7mO31oaOg73FLY4xOuBFLP Synth Compilation - Various Artists songs: 2
7nab3tPW9XlFxETa6jaRMk Voyage - Aurora Lights songs: 2

💡 说明：合辑《Synth Compilation》被正确归到 Various Artists 名下，编译内部各真实艺人（如本曲库的 Vapor Field）通过多艺人标签识别——这是 Navidrome 对「合辑/群星专辑」的经典处理。

4.8 播放与转码流验证

先取专辑内一首歌的 ID，再分别请求原格式与 Opus 转码流：

SONG=$(curl -s "http://127.0.0.1:8134/rest/getAlbum?u=admin&t=$TOKEN&s=$SALT&v=1.16.1&c=doc-test&f=json&id=7nab3tPW9XlFxETa6jaRMk" \
  | python3 -c "import json,sys;a=json.load(sys.stdin)['subsonic-response']['album'];print(a['song'][0]['id'])")
echo $SONG

实测输出：

0GJYJf4qI3HUCqQSH7qdMh

原格式流播放：

curl -s -o /dev/null -w 'HTTP %{http_code} | type=%{content_type} | bytes=%{size_download} | %{time_total}s\n' \
  "http://127.0.0.1:8134/rest/stream?u=admin&t=$TOKEN&s=$SALT&v=1.16.1&c=doc-test&f=json&id=$SONG"

实测输出：

HTTP 200 | type=audio/mpeg | bytes=721795 | 0.001914s

强制转码为 64kbps Opus：

curl -s -o /dev/null -w 'HTTP %{http_code} | type=%{content_type} | bytes=%{size_download}\n' \
  "http://127.0.0.1:8134/rest/stream?u=admin&t=$TOKEN&s=$SALT&v=1.16.1&c=doc-test&f=json&id=$SONG&format=opus&maxBitRate=64"

实测输出：

HTTP 200 | type=audio/ogg | bytes=302187

💡 说明：同一首歌两种响应——原格式 audio/mpeg 721795 字节，Opus 转码 audio/ogg 302187 字节，转码链路（调用镜像内置 ffmpeg）实测生效。弱网或移动端可在客户端设置中限制码率，由服务端实时转码。

五、数据持久化说明

所有需要落盘的状态都集中在 /data（宿主 ./data），曲库目录本身只读。重启后验证账号与曲库仍在：

docker compose restart

实测输出：

[+] Running 1/1
 ✔ Container navidrome-0.64.2-web  Started

重启后登录接口复核：

curl -s -X POST http://127.0.0.1:8134/auth/login -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}'

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

{"id":"38HXSLFOSYnKBAXVmdMMWK","isAdmin":true,"name":"Admin","subsonicSalt":"778841","subsonicToken":"213cd0410bca7ef2964c7b0325d34d8c","token":"eyJhbGciOiJIUzI1NiIsInR5cCI6...

扫描状态复核（账号、曲库计数均保留）：

curl -s "http://127.0.0.1:8134/rest/getScanStatus?u=admin&t=$TOKEN&s=$SALT&v=1.16.1&c=doc-test&f=json" | python3 -m json.tool

实测输出：

{
    "subsonic-response": {
        "status": "ok",
        "version": "1.16.1",
        "type": "navidrome",
        "serverVersion": "0.64.2 (10114574)",
        "openSubsonic": true,
        "scanStatus": {
            "scanning": false,
            "count": 6,
            "folderCount": 3,
            "lastScan": "2026-10-25T03:13:59.081321752Z",
            "scanType": "quick",
            "elapsedTime": 81321752
        }
    }
}

💡 说明：重启后服务自动做了一次快速扫描（scanType: quick），账号与曲库完整保留——数据全在 ./data/navidrome.db。data/ 目录实测内容：

artwork  cache  navidrome.db  navidrome.db-shm  navidrome.db-wal  navidrome.toml  plugins

navidrome.db（含 -shm/-wal）：SQLite 主库，账号、播放记录、收藏、播放列表等全部状态
cache/：图片缓存、转码缓存等，可删可重建
plugins/：插件目录
navidrome.toml：见第九章，配置文件方式才需要

六、环境变量表

Navidrome 的所有配置项都能以 ND_ 前缀环境变量注入（配置文件里叫什么，环境变量就全大写加 ND_ 前缀，如 MusicFolder → ND_MUSICFOLDER）。部署最常用项：

环境变量	默认值	说明
`ND_MUSICFOLDER`	`/music`	曲库目录（镜像内默认路径即 `/music`）
`ND_DATAFOLDER`	`/data`	应用数据目录（镜像内默认路径即 `/data`）
`ND_PORT`	`4533`	HTTP 监听端口
`ND_ADDRESS`	`0.0.0.0` 与 `::`	监听地址
`ND_BASEURL`	空	反向代理子路径（如 `/music`）时必设
`ND_LOGLEVEL`	`info`	日志级别：`error`/`warn`/`info`/`debug`/`trace`
`ND_SESSIONTIMEOUT`	`48h`	Web UI 空闲会话时长
`ND_SCANNER_SCHEDULE`	`0`（禁用）	定时扫描，Cron 或 `@every` 语法，如 `@every 24h`
`ND_SCANNER_WATCHERWAIT`	`5s`	文件变化后延迟扫描的等待时间，防扫描不完整文件
`ND_ENABLETRANSCODINGCONFIG`	`false`	允许用户在 UI 配置转码
`ND_TRANSCODINGCACHESIZE`	`100MB`	转码缓存大小，设 `0` 禁用
`ND_IMAGECACHESIZE`	`100MB`	封面图片缓存大小
`ND_DEFAULTLANGUAGE`	`en`	默认界面语言，中文简体 `zh-Hans`
`ND_DEFAULTTHEME`	`Dark`	默认主题
`ND_ENABLESHARING`	`true`	分享链接功能开关
`ND_ENABLEDOWNLOADS`	`true`	下载功能开关
`ND_JELLYFIN_ENABLED`	`false`	实验性 Jellyfin API 兼容层开关
`ND_PROMETHEUS_ENABLED`	`false`	Prometheus 指标端点开关
`ND_ENABLEINSIGHTSCOLLECTOR`	`true`	匿名数据收集（帮助改进项目），介意可关

⚠️ 定时扫描环境变量已改名：旧版 ND_SCANSCHEDULE 在 0.64.2 中不再生效——实测在编排文件中写 ND_SCANSCHEDULE: '@every 24h' 后，启动日志仍显示 Periodic scan is DISABLED。现行名称为 ND_SCANNER_SCHEDULE（对应配置项 Scanner.Schedule）。从旧版本升级的编排文件需要同步改名。

⚠️ 配置项优先级：官方文档标注优先级为「环境变量 > 命令行参数 > 配置文件」，但 0.64.2 实测结论相反——当同一参数同时用环境变量与命令行参数给出时，命令行参数胜出（对 Port、LogLevel 两组参数实测一致，详见《Navidrome 0.64.2 配置参数详解》第三章）。纯 Compose 场景只注入环境变量，不受此差异影响。

完整参数清单与逐项语义见《Navidrome 0.64.2 配置参数详解》。

七、配置参数说明

本文编排文件启用的 4 个参数（ND_CONFIGFILE 除外）生效行为均已在实测中核对：

ND_LOGLEVEL: info：启动日志以 info 级输出，各组件初始化、路由挂载、扫描动作均可见；排障时改为 debug 可看到数据库打开参数、生效配置转储等细节
ND_SESSIONTIMEOUT: 24h：启动日志出现 Setting Session Timeout value=24h，与注入值一致
ND_ENABLETRANSCODINGCONFIG: "true"：Web UI 的转码设置对普通用户开放
ND_DEFAULTLANGUAGE: zh-Hans：新浏览器登录时界面直接为中文

验证环境变量生效的直接手段是看启动日志回显（如 Session Timeout），或改 ND_PORT 后用 docker compose ps 观察端口映射变化。

八、配置文件挂载

除环境变量外，Navidrome 也支持 TOML 配置文件（还兼容 JSON/YAML/INI，按扩展名识别）。容器场景下推荐把配置文件放进 /data 并显式指定：

在宿主 ./data/ 下创建 navidrome.toml：

LogLevel = 'INFO'
Scanner.Schedule = '@every 24h'
TranscodingCacheSize = '150MiB'
UIWelcomeMessage = 'Welcome to my Navidrome'

在编排文件 environment 段中显式指向它：

    environment:
      ND_CONFIGFILE: /data/navidrome.toml
      ND_LOGLEVEL: info
      ...

重新拉起服务：

docker compose up -d

实测输出：

[+] Running 1/1
 ✔ Container navidrome-0.64.2-web  Started

日志确认配置加载与定时扫描生效：

docker logs --since 30s navidrome-0.64.2-web

实测输出（节选）：

                          Version: 0.64.2 (10114574)

time="2026-10-25T03:15:01Z" level=info msg="Loaded configuration" file=/data/navidrome.toml
time="2026-10-25T03:15:01Z" level=info msg="Scheduling periodic scan" schedule="@every 24h"
time="2026-10-25T03:15:01Z" level=info msg="Scheduling DB analysis check" schedule="@every 30m"
time="2026-10-25T03:15:01Z" level=info msg="Setting Session Timeout" value=24h

⚠️ 实测与官方文档不符项：官方文档称「Docker 安装会自动查找 /data 目录下的 navidrome.toml」，但 0.64.2 实测不会自动加载——把 navidrome.toml 放进挂载的 /data 后重启，日志仍提示 No configuration file found. Loaded configuration only from environment variables；在环境变量中显式加 ND_CONFIGFILE=/data/navidrome.toml 后才出现 Loaded configuration file=/data/navidrome.toml。生产部署建议始终显式设置 ND_CONFIGFILE，不要依赖自动发现。

💡 说明：优先级上环境变量高于配置文件——编排文件里已注入的 ND_LOGLEVEL 会压过配置文件中的 LogLevel。想让配置文件全面接管时，编排文件的 environment 段只保留 ND_CONFIGFILE 一项即可。

九、等价 docker run 命令

不使用 Compose 时，等价的单条启动命令：

docker run -d \
  --name navidrome-0.64.2-web \
  --restart unless-stopped \
  -p 8134:4533 \
  -e ND_LOGLEVEL=info \
  -e ND_SESSIONTIMEOUT=24h \
  -v /opt/navidrome/music:/music:ro \
  -v /opt/navidrome/data:/data \
  --network navidrome-net \
  navidrome/navidrome:0.64.2

参数与编排文件一一对应：-p 端口映射、-e 环境变量、-v 目录挂载、--network 接入外部网络。单机长期运行建议仍用 Compose，编排即文档、改动可追溯。

十、常用运维命令

以下命令均在 /opt/navidrome/（编排文件所在目录）执行。

查看实时日志：

docker logs -f --tail 100 navidrome-0.64.2-web

查看服务状态：

docker compose ps

实测输出：

NAME                   STATUS         PORTS
navidrome-0.64.2-web   Up 5 seconds   0.0.0.0:8134->4533/tcp, [::]:8134->4533/tcp

重启服务：

docker compose restart

实测输出：

[+] Running 1/1
 ✔ Container navidrome-0.64.2-web  Started

停用服务：

docker compose down

实测输出：

 Container navidrome-0.64.2-web Stopped
 Container navidrome-0.64.2-web Removing
 Container navidrome-0.64.2-web Removed

💡 说明：down 只删实例，不删 ./data 与 ./music，再次 up -d 后账号与曲库原样恢复（实测验证）。

升级到新版本：把编排文件中 image 标签改为新版本号，然后：

docker compose pull
docker compose up -d

⚠️ 升级前建议先用内置 CLI 做一次数据库备份（navidrome backup create，用法见《Navidrome 0.64.2 常用 CLI 命令与工具详解》），升级后如需回退，恢复备份即可。降级跨大版本可能涉及数据库结构变化，回退前务必确认备份可用。

十一、常见问题

Q1：设置了 ND_SCANSCHEDULE，定时扫描不生效？

0.64.2 中该环境变量已更名为 ND_SCANNER_SCHEDULE。实测旧名注入后启动日志明确显示 Periodic scan is DISABLED；改用 ND_SCANNER_SCHEDULE: '@every 24h' 后日志显示 Scheduling periodic scan schedule="@every 24h"。注意 C 成分的差异：新名是「SCANNER_SCHEDULE」两个词。

Q2：把 navidrome.toml 放进 /data 后配置没生效？

见第八章：0.64.2 实测不会自动加载 /data/navidrome.toml，需显式注入 ND_CONFIGFILE=/data/navidrome.toml，日志出现 Loaded configuration file=/data/navidrome.toml 才算加载成功。

Q3：首次打开页面没有「创建管理员」入口，或提示已初始化？

/auth/createAdmin 只在实例零用户时可用。若数据库里已有账号（比如复用了旧 data/ 目录），直接用已有管理员登录即可；忘记密码时可用内置 CLI 重置（见《Navidrome 0.64.2 常用 CLI 命令与工具详解》 user 命令一节）。

Q4：曲库扫出来了但封面是灰的？

确认专辑目录下有 cover.jpg/folder.jpg 等封面文件，或音频文件内嵌封面。Navidrome 按优先级查找封面（cover.*、folder.*、front.*、内嵌、外部源），顺序可用 CoverArtPriority 参数调整。缓存目录（data/cache/images）清掉后会自动重建。

Q5：想挂在反向代理子路径下（如 https://example.com/music）？

设置 ND_BASEURL=/music 并重定向代理到服务端口即可，BaseUrl 必须与代理对外暴露的路径完全一致。分享链接（share）功能另可配合 ND_SHAREURL 指定外网可达的基础地址。

Q6：服务器断网时启动日志报 background images 错误？

启动过程中会尝试从官方图片服务拉取登录页背景图，断网时出现 Could not get background images from image service 级别为 warning 的日志，不影响正常功能。彻底关闭外部依赖可设 ND_ENABLEEXTERNALS=false（同时会关闭匿名数据收集与外部元数据代理）。

十二、参考链接

Navidrome 官网：https://www.navidrome.org/
官方 Docker 安装文档：https://www.navidrome.org/docs/installation/docker/
官方配置选项页：https://www.navidrome.org/docs/usage/configuration/options/
官方 CLI 参考：https://www.navidrome.org/docs/usage/administration/cli/
GitHub 仓库：https://github.com/navidrome/navidrome
版本发布页：https://github.com/navidrome/navidrome/releases（本文版本信息与星数取证查询日期：2026-10-25）
站内同系列：《Navidrome 0.64.2 介绍与选型指南》、《Navidrome 0.64.2 配置参数详解》、《Navidrome 0.64.2 常用 CLI 命令与工具详解》