Navidrome 部署与配置完全指南

1. 项目选型与服务器评估

  • 需求：在 1核1G 云服务器上，Docker 部署音频类服务，要求资源占用低，能离线播放文件夹内音乐。

  • 推荐：

    • Navidrome：轻量级音乐服务器，内存占用约 100-200MB，完美支持 1核1G 配置。适合管理 MP3/FLAC 等格式的个人音乐库。
    • Audiobookshelf：专门针对有声书/播客，同样轻量，支持进度同步。如有需要可作为备选。
  • 结论：选择 Navidrome，功能匹配，资源占用极低。

2. Docker 部署配置 (最终优化版)

核心优化 (针对 1核1G 服务器)

  • 关闭自动扫描：改为手动扫描，避免周期性消耗 CPU。
  • 关闭启动扫描：加快容器启动速度。
  • 限制日志级别：设置为 warn 或 error，减少磁盘 I/O。
  • 禁止外部服务：ND_ENABLEEXTERNALSERVICES: "false"，彻底断网运行。
  • 关闭匿名统计：ND_ENABLEINSIGHTSCOLLECTOR: "false"。
  • 资源限制：mem_limit: 512M, cpus: '0.5'，防止资源争抢。
  • 降低封面质量：ND_COVERARTQUALITY: "40"，减少内存占用。
  • 限制扫描线程：ND_DEVSCANNERTHREADS: "1"，避免单核 CPU 堵塞。

最终 docker-compose.yml

version: "3"
services:
  navidrome:
    image: deluan/navidrome:latest
    container_name: navi
    environment:
      ND_UIWELCOMEMESSAGE: "ZP-MUSIC"
      ND_DEFAULTLANGUAGE: "zh-Hans"          # 正确设置网页界面语言
      # 扫描设置
      ND_SCANSCHEDULE: "0"                   # 彻底关闭自动扫描
      ND_SCANONSTARTUP: "false"               # 关闭启动扫描
      ND_FORCEFULLSCANONSTARTUP: "false"      # 关闭强制全量扫描
      # 性能优化
      ND_COVERARTQUALITY: "40"               # 降低封面质量
      ND_DEVSCANNERTHREADS: "1"              # 限制扫描线程数
      # 网络与日志
      ND_LOGLEVEL: "error"                   # 只记录错误，日志量极少
      ND_ENABLEEXTERNALSERVICES: "false"     # 禁止所有外部服务 (Last.fm等)
      ND_ENABLEINSIGHTSCOLLECTOR: "false"    # 禁止匿名统计
      ND_SESSIONTIMEOUT: "24h"               # 登录超时
      TZ: "Asia/Shanghai"
    volumes:
      - "./data:/data"
      - "./music:/music:ro"                  # 音乐文件夹，只读挂载
    mem_limit: 512M                          # 内存硬限制
    cpus: '0.5'                              # CPU硬限制
    restart: unless-stopped

常用管理命令

操作命令
启动docker-compose up -d
停止docker-compose down
查看状态docker-compose ps
查看日志docker-compose logs -f
重启docker-compose restart
手动扫描网页右上角头像 → “扫描” 或 docker exec -it navi navidrome scan

3. 重要配置问题澄清

网页界面语言设置

  • 错误变量：ND_LANGUAGE: "zh" 不会改变网页界面语言，该变量用于 Last.fm 等外部服务的元数据语言。
  • 正确变量：ND_DEFAULTLANGUAGE: "zh-Hans" 或 ND_DEFAULTLANGUAGE: "zh"。
  • 备选：也可以直接通过浏览器的语言设置让界面显示中文。

日志关闭

  • 没有完全关闭的值。
  • 最低记录级别：设置为 error，只记录错误，产生的日志量极少，适合长期运行。

WebSocket 支持

  • 是否需要：前端播放控制和状态同步需要 WebSocket。
  • 是否需要额外配置：不需要。因为使用直接端口映射（4533:4533）访问，WebSocket 开箱即用。如果未来使用 Nginx 反代，则需显式配置 Upgrade 头。

4. 音乐文件管理

标签乱码问题 (如 °ÙÄ곪Ƭ...)

  • 原因：文件的 ID3 标签为 GBK/Big5 等旧编码，而 Linux/Navidrome 默认读取 UTF-8 编码。

  • 解决方案：在服务器上批量转换标签编码。

    # 安装工具
sudo apt update
sudo apt install python3-mutagen

# 进入音乐目录，转换所有 MP3 文件标签从 GBK 到 UTF-8
cd /path/to/your/music
find . -iname "*.mp3" -exec mid3iconv -e gbk --remove-v1 {} \;
  • 注意：此命令不会修改文件名，只修改文件内部的元数据标签。

文件名空格处理

  • 命令未找到：如遇 -bash: rename: command not found，先安装 sudo apt install rename。

  • 推荐命令：精确修改文件扩展名，避免误操作。

    # 只修改 .mp3 文件中的空格为下划线
rename 's/ /_/g' *.mp3

  • 备选方案：无需安装的纯 Shell 循环。

    for file in *\ *; do mv "$file" "${file// /_}"; done

文件名与标签的关系

  • 网页显示来源：Navidrome 优先读取文件内部标签（歌名、艺人、专辑），而不是文件名。
  • 结论：能正常列出文件名（如 一半.mp3）不代表网页上的歌名不显示为乱码。必须确保标签编码正确。

标签编辑工具推荐

  • 首选 (不占服务器资源)：Mp3tag (Windows 免费软件) 或 MusicTag。可通过 SMB/SFTP 连接服务器直接编辑，功能强大，适合批量操作。
  • 不推荐服务器端工具：xhongc/music-tag-web 等容器资源占用高（>600MB 内存），不适合 1核1G 服务器。

5. “电台”功能深度解析

  • 本质：

    • 添加网络电台：收听外部公共广播流 (如 BBC、北京交通广播)，不是让别人收听你的音乐库。
    • 智能播放列表：从自己的音乐库中按规则自动生成歌单，像一个自动更新的私人频道。

  • 他人权限：

    • 不能修改你添加的电台或你的音乐内容。
    • 即使将账号分享给他人，对方也只能播放你的音乐或创建个人播放列表，无法删除或修改文件。
  • 分享音乐给他人：需使用 “分享” (Sharing) 功能 (ND_ENABLESHARING: true)，可生成单首歌曲或专辑的公开链接，无需对方登录。

添加网络电台示例 (北京交通广播)

  1. 找到稳定的官方直播流地址：mms://alive.rbc.cn/fm1039 (或尝试 http 协议)。
  2. Navidrome 网页 → 左侧菜单“电台” → “新增”。
  3. 填写名称和URL，保存即可。
  4. 注意：带动态 key/time 参数的 .m3u8 地址通常有时效性，不适合长期使用。

6. 其他重要提示

  • SWAP 配置：1核1G 服务器强烈建议配置 2GB SWAP，防止内存不足时服务崩溃。
  • 防火墙：开放 4533 端口 (TCP)。
  • 支持的音频格式：MP3, FLAC, AAC, WAV 等主流格式。浏览器直接播放 MP3/FLAC 不消耗服务器 CPU。ALAC/APE 等格式会触发实时转码，增加 CPU 负载，建议提前转为 FLAC。
  • 分享功能权限：当前版本中，开启分享后所有用户都有权创建和管理分享链接，无法单独限制，谨慎启用。

这份笔记涵盖了我们讨论的所有关键技术点，你可以直接作为部署和使用的参考文档。如果后续有其他问题，随时可以继续交流。

标签: none

添加新评论