🚀 使用 Docker Compose 部署 Navidrome（轻量级音乐服务器）

一、项目简介

Navidrome 是一款开源轻量级音乐服务器，主打 本地音乐库的现代化管理与远程访问，兼容 Subsonic/Airsonic 协议（支持绝大多数音乐客户端），适合个人或家庭将本地音乐库（MP3、FLAC 等格式）转化为 “私人云音乐库”，实现多设备（手机、电脑、音箱）随时随地听歌。

核心特点：

1. 轻量高效：Go 语言开发，容器内存占用通常 < 100MB，CPU 消耗低，适配 NAS、树莓派、轻量云服务器等设备。
2. Subsonic 兼容：支持所有 Subsonic 协议客户端（如 DSub、Audinaut、VLC），无需单独开发客户端，直接复用现有工具。
3. 全格式支持：兼容 MP3、FLAC、WAV、AAC、OGG 等主流音频格式，自动识别 ID3 标签（歌手、专辑、封面）。
4. Web 界面友好：提供简洁的中文 Web 管理界面，支持音乐搜索、分类（按歌手 / 专辑 / 流派）、播放列表、用户权限管理。
5. 自动扫描与更新：可配置定时扫描音乐库（默认 1 小时），新增音乐无需手动刷新，自动同步到库中。
6. 数据安全可控：音乐文件本地存储，支持用户权限隔离（如创建只读用户），避免隐私泄露风险。
7. 转码功能：内置 FFmpeg 转码支持，可根据客户端网络情况自动调整音质（如低带宽下转码为 MP3，节省流量）。

二、部署前准备

Navidrome 依赖 Docker 环境与本地音乐 / 数据目录，需提前完成以下准备，避免启动失败或功能异常：

1. 必备工具安装

• Docker：用于运行 Navidrome 容器（验证命令：docker --version，未安装可参考 Docker 官方文档）。
• Docker Compose：用于编排容器（验证命令：docker compose version，部分 Docker 版本已内置，未安装可参考 Docker Compose 安装文档）。

2. 目录与权限准备

Navidrome 需要两个核心目录：数据目录（保存配置、用户信息、播放记录）和 音乐目录（存放本地音乐文件，只读挂载），需提前创建并设置权限：

bash

# 1. 创建部署主目录（示例路径：/opt/navidrome，可自定义）
mkdir -p /opt/navidrome && cd /opt/navidrome

# 2. 创建数据目录（对应配置中的 ./data，保存配置与用户数据）
mkdir -p data && sudo chmod -R 777 data  
# 说明：数据目录需读写权限，否则无法保存用户密码、播放记录

# 3. 确认音乐目录存在（对应配置中的 /mnt/10t/file/connect/music）
# 若目录不存在，先创建（根据实际音乐存储路径调整）：
sudo mkdir -p /mnt/10t/file/connect/music  
# 音乐目录设为只读权限（符合配置中的 :ro）：
sudo chmod -R 755 /mnt/10t/file/connect/music  

• 关键提醒：
  • 音乐目录需按 “歌手 / 专辑” 或直接存放音频文件（如 /mnt/10t/.../music/周杰伦/晴天.flac），便于 Navidrome 识别分类；
  • 若音乐目录权限不足，会导致扫描不到音乐（常见新手错误）。

3. 端口准备

Navidrome 默认通过 4533 端口提供 Web 服务与客户端连接，需开放该端口：

• Linux（UFW 防火墙）：sudo ufw allow 4533/tcp；
• 云服务器（阿里云 / 腾讯云）：在安全组添加 “允许 TCP 4533 端口入站” 规则。

三、配置 Docker Compose

1. 步骤 1：编写配置文件

在 /opt/navidrome 目录下创建 docker-compose.yml 文件，复制以下内容（与用户提供配置一致，关键项已标注）：

yaml

services:
  navidrome:
    image: deluan/navidrome:latest  # 官方最新镜像（自动更新稳定版，推荐）
    #user: 1000:1000  # 可选：指定运行用户ID（避免权限问题，新手可先注释，默认root）
    ports:
      - "4533:4533"  # 端口映射：主机 4533 → 容器 4533（Web/客户端访问端口）
    restart: unless-stopped  # 容器退出后自动重启（除非手动停止，保障服务稳定）
    environment:
      # 核心环境变量配置（新手无需修改，按需调整）
      # Optional: put your config options customization here. Examples:
      # ND_LOGLEVEL: debug
      ND_SCANSCHEDULE: 1h        # 音乐库扫描周期（1小时自动扫描新增音乐）
      ND_LOGLEVEL: info          # 日志级别（info=普通日志，debug=调试日志）
      ND_SESSIONTIMEOUT: 24h     # 用户会话超时（24小时无操作需重新登录）
      ND_BASEURL: ""             # 基础URL（无需域名时留空，反向代理时需配置）
      ND_SCANNER_EXTRACTOR: ffmpeg  # 依赖FFmpeg提取音频元数据（确保转码与标签识别）
      PND_ENABLETRANSCODINGCONFIGGID: true  # 启用转码配置（客户端可选择音质）
      ND_ENABLESHARING: true     # 启用音乐分享功能（支持生成分享链接）
      # 说明：
      # - ND_SCANSCHEDULE：扫描间隔（示例：1h）
      # - ND_LOGLEVEL：日志级别（info/debug）
      # - ND_SESSIONTIMEOUT：会话超时（示例：24h）
      # - ND_BASEURL：反向代理子路径（为空表示根路径）
      # - ND_SCANNER_EXTRACTOR：使用 ffmpeg 解析音频/元数据

    volumes:
      - "./data:/data"  # 数据持久化：主机 ./data → 容器 /data（配置、用户数据）
      #- "./music:/music:ro"
      - "/mnt/10t/file/connect/music:/music:ro"  # 音乐目录：只读挂载（ro=read-only）

2. 配置项关键说明（新手必看）

配置项	作用与注意事项
user: 1000:1000	若启动后提示 “权限不足”，取消注释并改为宿主机普通用户 ID（执行 id -u 查看当前用户 ID），避免 root 权限风险。
ND_SCANSCHEDULE: 1h	扫描周期可调整（如 6h=6 小时扫描一次，@daily= 每天扫描），频繁扫描适合经常新增音乐的场景。
ND_SCANNER_EXTRACTOR: ffmpeg	依赖 FFmpeg 提取音频标签（如封面、时长），容器已内置 FFmpeg，无需额外安装。
volumes: /music:ro	音乐目录必须设为 ro（只读），防止 Navidrome 误修改音乐文件，保障源文件安全。
ND_ENABLETRANSCODINGCONFIG: true	启用后，客户端可选择 “高 / 中 / 低” 音质（如手机流量不足时选低音质），节省带宽。

四、启动与验证

1. 启动 Navidrome 容器

在 /opt/navidrome 目录执行以下命令，启动服务（首次启动会拉取镜像，体积约 200MB，耗时取决于网络）：

bash

docker compose up -d

2. 验证部署状态

（1）检查容器是否正常运行

执行命令查看状态，若 State 为 Up，说明启动成功：

bash

docker compose ps

• 若状态为 Exited，执行以下命令查看错误日志（排查核心方法）：

  bash

  bash docker compose logs -f navidrome # 实时查看日志，按 Ctrl+C 退出

  • 常见错误：
    • permission denied on /music：音乐目录权限不足，重新执行 sudo chmod -R 755 /mnt/10t/file/connect/music；
    • port is already allocated：4533 端口被占用，修改 ports 为空闲端口（如 4534:4533），重启容器。

（2）访问 Web 管理界面

1. 打开浏览器，输入 http://服务器IP:4533（如 http://192.168.1.100:4533）；
2. 首次访问会进入 创建管理员账号 页面（非登录！），设置：
   • 用户名：自定义（如 admin）；
   • 密码：强密码（如 Navidrome@2024!）；
3. 点击「Create User」，自动登录到主界面，若显示音乐库统计（如 “0 位艺术家，0 张专辑”），说明部署成功。

（3）验证音乐库扫描

1. 在主机音乐目录（/mnt/10t/file/connect/music）放入几首测试音乐（如 MP3/FLAC 文件）；
2. 等待 1 小时（默认扫描周期），或手动触发扫描：
   • Web 界面点击右上角「设置」→「音乐库」→「立即扫描」；
3. 扫描完成后，主界面会显示艺术家、专辑数量，点击即可播放音乐，验证功能正常。

五、基础配置与使用

登录后，新手需完成 “基础设置” 与 “客户端连接”，充分利用 Navidrome 功能：

1. 步骤 1：修改核心设置（优化体验）

1. 点击右上角「设置」→「常规」：
   • 「语言」：选择「简体中文」（界面更友好）；
   • 「会话超时」：按需调整（如改为 72h=3 天无操作超时）；
2. 点击「音乐库」→ 确认「音乐库路径」为 /music（与配置一致），可修改「扫描周期」（如 30m=30 分钟扫描一次）；
3. 点击「转码」：可新增转码配置（如 “低音质” 设为 MP3 128kbps），适合手机远程访问。

2. 步骤 2：创建普通用户（权限隔离）

若多用户使用，可创建只读用户（避免误删音乐或修改配置）：

1. 点击「设置」→「用户」→「新建用户」；
2. 填写：
   • 用户名：如 family；
   • 密码：自定义；
   • 权限：勾选「只读」（仅允许听歌，无法修改设置）；
3. 点击「创建」，普通用户可通过独立账号登录。

3. 步骤 3：使用客户端连接（推荐）

Web 界面适合管理，日常听歌推荐用 Subsonic 兼容客户端（体验更好）：

（1）手机客户端（以 DSub 为例）

1. 在应用商店下载「DSub」；
2. 打开客户端，填写：
   • 服务器地址：http://服务器IP:4533；
   • 用户名 / 密码：Navidrome 账号（如 admin / 自定义密码）；
3. 连接成功后，即可浏览音乐库、下载离线播放。

（2）电脑客户端（以 Audinaut 为例）

1. 下载 Audinaut（官网）；
2. 配置服务器地址与账号，即可同步播放记录，支持桌面通知。

---

基础配置与使用

库与扫描

• 添加路径： 默认读取 /music；若需多库，可在“Admin > Settings > Music folder”调整。
• 自动与手动：
  • 自动扫描： 按 ND_SCANSCHEDULE 间隔运行。
  • 手动扫描： 在管理界面触发 Rescan，适合批量导入后立即更新。
• 文件结构建议：
  • 推荐层级： Artist/Album/Track.ext，利于识别封面与元数据。

转码与播放

• 转码提取器： ND_SCANNER_EXTRACTOR=ffmpeg 用 ffmpeg 解析与转码，适配多格式。
• 客户端兼容： 支持 Subsonic 客户端；移动端可用像 Symfonium、Substream 等。
• 码率与格式： 可在管理员设置或客户端参数中选择合适码率，节省带宽。

访问与分享

• 用户管理： 创建普通用户并限制权限，避免管理员账号日常使用。
• 分享链接： 开启 ND_ENABLESHARING=true 后，可生成分享链接（注意访问范围与时效）。
• 反向代理： 如需公网访问，建议使用 Nginx/Caddy 并配置 HTTPS 与子路径（配合 ND_BASEURL）。

---

六、维护与管理

1. 容器基础操作

操作需求	命令	说明
停止 Navidrome 服务	docker compose down	停止容器，数据保存在 ./data 目录
重启服务	docker compose restart	配置修改后需执行（如改扫描周期、语言）
查看实时日志（排错）	docker compose logs -f navidrome	查看扫描失败、客户端连接错误等日志
进入容器内部（进阶）	docker exec -it navidrome /bin/sh	可手动查看 /music 目录文件、日志

2. 数据备份（防止丢失）

Navidrome 核心数据包括 配置 / 用户数据 和 音乐文件，需分别备份：

（1）备份配置 / 用户数据（./data 目录）

bash

# 打包备份（文件名含日期，便于恢复）
tar -czf navidrome-data-backup-$(date +%Y%m%d).tar.gz ./data

（2）备份音乐文件（/mnt/10t/.../music 目录）

音乐文件体积较大，建议用 rsync 同步到外接硬盘或其他存储：

bash

# 示例：同步到外接硬盘（/mnt/backup 为外接硬盘路径）
rsync -av /mnt/10t/file/connect/music /mnt/backup

3. 更新 Navidrome 版本

bash

# 拉取最新镜像并重启（配置与数据不会丢失）
docker compose pull && docker compose up -d

4. 清理无用数据

• 清理日志：./data/logs 目录下的旧日志可定期删除（如超过 30 天的日志）；

• 清理缓存：./data/cache 存放封面缓存，删除后会重新生成（不影响核心功能）：

  bash

  bash rm -rf ./data/cache/*

七、常见问题排查

1. 访问 Web 界面提示 “无法连接”

• 原因 1：4533 端口未开放或被占用。

  解决：检查端口占用 netstat -tuln | grep 4533，释放端口或修改 ports 为空闲端口（如 4534:4533），重启容器。 - 原因 2：容器未正常启动（状态为 Exited）。

  解决：查看日志 docker compose logs navidrome，修复权限或路径问题后重启。

2. 音乐库扫描不到音乐

• 原因 1：音乐目录路径错误（配置中 volumes 挂载路径与实际不一致）。

  解决：核对 docker-compose.yml 中音乐目录路径（如 /mnt/10t/file/connect/music），确保主机目录存在且文件格式正确（MP3/FLAC）。 - 原因 2：音乐目录权限不足（容器无读取权限）。

  解决：执行 sudo chmod -R 755 /mnt/10t/file/connect/music，手动触发扫描。

3. 客户端连接提示 “认证失败”

• 原因 1：用户名 / 密码错误（首次创建的是 “管理员账号”，非默认账号）。

  解决：确认客户端输入的用户名 / 密码与 Web 界面登录账号一致。 - 原因 2：服务器地址错误（客户端输入的 IP / 端口与 Navidrome 不一致）。

  解决：客户端地址改为 http://服务器IP:4533（如 http://192.168.1.100:4533）。

4. 播放音乐提示 “转码失败”

• 原因：FFmpeg 依赖异常（虽容器内置，但可能因版本问题失效）。
• 解决：
  1. 重启容器：docker compose restart navidrome；
  2. 若仍失败，在 Web 界面「设置」→「转码」中，选择 “无转码”（仅播放原始格式）。

5. 扫描音乐时封面不显示

• 原因 1：音乐文件无内嵌封面（ID3 标签缺失）。

  解决：用音乐标签工具（如 music-tag-web）给音乐文件添加封面，重新扫描。 - 原因 2：封面缓存损坏。

  解决：删除 ./data/cache/covers 目录，手动触发扫描，重新生成封面。

通过以上步骤，新手可快速搭建 Navidrome 私人音乐服务器，实现本地音乐的多设备管理与远程访问。如需更高级功能（如反向代理配置 HTTPS、LDAP 身份认证），可参考 Navidrome 官方文档 进一步探索。

---

常见问题排查

• 访问端口冲突或打不开：
  • 可能原因： 主机已有服务占用 4533 或防火墙阻止。
  • 解决方案： 修改映射为 "8533:4533"，放行防火墙规则，重启容器。
• 音乐库为空或扫描失败：
  • 可能原因： /mnt/10t/file/connect/music 不存在、权限不足或目录不可读。
  • 解决方案： 检查路径与权限（ls -l 验证），确认卷映射写法与 :ro 不影响读取。
• 登录频繁过期：
  • 可能原因： 会话超时设置过短或代理未正确透传 Cookie。
  • 解决方案： 调整 ND_SESSIONTIMEOUT（如 24h 或更长），检查反向代理的 Cookie/Headers 配置。
• 反向代理子路径 404 或静态资源加载失败：
  • 可能原因： 未设置 ND_BASEURL 或代理未重写正确。
  • 解决方案： 设置 ND_BASEURL 为一致的子路径（如 /navidrome），在代理中添加子路径前缀与正确的 X-Forwarded-* 头。
• 转码不可用或播放异常：
  • 可能原因： ffmpeg 不可用、客户端码率/格式与服务器策略不匹配。
  • 解决方案： 保持 ND_SCANNER_EXTRACTOR=ffmpeg，在客户端或服务器端调低码率，查看日志定位错误。
• 数据目录权限错误导致设置无法保存：
  • 可能原因： ./data 不可写或属主不匹配。
  • 解决方案： 使用匹配的 user: 1000:1000 或修正权限（chown/chmod），重启后重试。

---