Docker 部署 Navidrome，搭建自托管音乐库并连接移动端app

Docker 部署 Navidrome搭建自托管音乐库并连接移动端app一、为什么选择 Navidrome二、Docker 部署 Navidrome2.1 准备工作2.2 方式一docker run 单条命令快速上手2.3 方式二docker-compose.yml推荐便于管理2.4 关键参数说明三、启动 创建管理员四、用客户端连接 Navidrome4.1 iOS 用户注意HTTPS五、进阶与踩坑5.1 反向代理HTTPS 访问5.2 扫库与性能5.3 备份5.4 常见问题六、结尾附本文使用的环境版本目标读者拥有 NAS、Linux 服务器或 VPS 的自托管爱好者具备基本的 Docker 使用经验。适用平台任何能跑 Docker 的环境 —— 威联通 QNAP、群晖 Synology、绿联 UGREEN、Ubuntu / Debian / CentOS 服务器、树莓派甚至一台迷你主机。阅读时间约 10 分钟部署操作约 20 分钟。一、为什么选择 Navidrome订阅 Apple Music / Spotify 几年后很多人会意识到同一个问题无损 FLAC 本地文件越攒越多每次想听都得连数据线或开 SMB 共享流媒体平台要么不收你的小众专辑要么偷偷把音轨换成低码率 AAC。于是「自托管音乐流媒体」成了刚需。Navidrome 是一个用Go编写的开源音乐服务器主打「轻量、快、专注音乐」。它实现了 Subsonic API因此任何兼容 Subsonic 的客户端手机、电脑、Web、第三方 App都能直接接入。它和 Plex / Emby / Airsonic 不是同一个定位服务定位资源占用音乐体验维护成本Plex全能媒体服务器大流媒体同步需 Plex Pass一般高Emby全能媒体服务器大一般高AirsonicSubsonic 老牌社区分支中Java 虚拟机中中更新慢Navidrome专注音乐小Go单二进制好自动匹配歌词、艺人头像低Navidrome 没有 Plex / Emby 那种「全能压力」扫库飞快x86 和 ARM 架构都能流畅运行天然适合 Docker 部署。二、Docker 部署 Navidrome2.1 准备工作开始前先确认两件事音乐目录路径把你要听的音乐整理到一个目录里例如 Linux 服务器的/srv/music、群晖的/volume1/music、威联通的/share/Music。记住它的宿主机绝对路径稍后要作为「音乐卷」挂进容器。数据目录路径创建一个空目录存放 Navidrome 的数据库和缓存例如/srv/navidrome/data。数据卷与音乐卷要分开不要混在一起。挂载建议音乐目录以只读:ro方式挂载这样 Navidrome 不可能误删你的音乐文件是最重要的安全实践。2.2 方式一docker run 单条命令快速上手把下面两处路径换成你自己的实际路径然后直接运行dockerrun-d\--namenavidrome\--restartunless-stopped\-p4533:4533\-eND_SCANNER_ENABLEDtrue\-eND_SCANNER_SCHEDULEevery 1h\-eND_LOGLEVELinfo\-eND_DEFAULTLANGUAGEzh-cn\-eND_MUSICFOLDER/music\-v/srv/navidrome/data:/data\-v/srv/music:/music:ro\deluan/navidrome:latest运行后查看日志确认正常启动dockerlogs-fnavidrome看到Navidrome is ready!或类似启动信息即成功。2.3 方式二docker-compose.yml推荐便于管理新建一个目录写入docker-compose.ymlservices:navidrome:image:deluan/navidrome:latestcontainer_name:navidromerestart:unless-stoppedports:-4533:4533environment:ND_SCANNER_ENABLED:trueND_SCANNER_SCHEDULE:every 1hND_LOGLEVEL:infoND_DEFAULTLANGUAGE:zh-cnND_MUSICFOLDER:/musicvolumes:-/srv/navidrome/data:/data-/srv/music:/music:ro注意请把/srv/navidrome/data和/srv/music替换成你自己的实际路径。保存后在文件所在目录执行dockercompose up-d查看状态dockercomposepsdockercompose logs-fnavidrome2.4 关键参数说明参数说明4533:4533左为宿主机端口、右为容器端口。默认 Web UI 用 4533想换端口改左边即可换完记得客户端那边同步改。ND_MUSICFOLDER容器内的音乐目录路径与-v ...:/music:ro挂载点一致即可一般保持/music不用动。ND_SCANNER_ENABLED/ND_SCANNER_SCHEDULE自动扫库开关与周期。every 1h表示每 1 小时扫描一次刚拷完新专辑想立刻看到可临时改成every 5m。ND_DEFAULTLANGUAGE设为zh-cn可让中文文件名 / 艺人名匹配得更准建议保留。ND_LOGLEVEL日常用info排查问题时临时改成debug。ND_BASEURL留空即可若用反向代理挂在子路径下如https://xxx.com/music可设为/music。若需要接入 Last.fm 记录播放、Spotify 补齐封面等可额外添加ND_LASTFM_APIKEY、ND_SPOTIFY_ID、ND_SPOTIFY_SECRET详见 Navidrome 官方配置文档。三、启动 创建管理员浏览器打开http://你的服务器IP:4533首次访问会自动进入创建管理员流程填用户名 密码。注意这个密码同时就是 Subsonic API 的密码后面客户端连接时要原样填写。进入后到Settings → Music Folders确认/music被正确识别。第一次扫全库会比较慢等进度条跑完回到主页应该就能看到所有专辑了。首次元数据匹配艺人头像 / 歌词需要联网之后会缓存到/data卷NAS 或服务器无法联网时可以提前离线准备元数据。四、用客户端连接 Navidrome服务端搭好后还需要一个兼容 Subsonic 协议的客户端来播放。Navidrome 实现的是 Subsonic API所以客户端选择非常多iOS / Android / 桌面端都有对应 App。常见的几款如下客户端平台特点DSubAndroid老牌客户端功能全面SymfoniumAndroid界面现代支持离线缓存substreameriOS / Android / Web开源免费SonixdWindows / macOS / Linux跨平台桌面端归流iOS / Android / 桌面中文界面面向 NAS 自部署场景下面以「归流」为例演示连接步骤——它是一款支持 NAS 自部署服务的中文客户端音乐子系统同样走 Subsonic 协议。其他客户端的配置项大同小异可对照参考打开归流 App进入设置 → 添加服务 → 音乐服务器字段填写内容服务类型Subsonic / Navidrome服务器地址http://192.168.x.x:4533换成你服务器 / NAS 的内网 IP 或域名用户名刚才创建的 Navidrome 管理员用户名密码同一个密码点连接客户端会请求/rest/ping.view验证凭据成功即自动进入音乐主页随后自动同步全部专辑、艺人和歌单。4.1 iOS 用户注意HTTPSiOS 默认只允许 HTTPS 出口直连 HTTP 内网 IP 时系统可能拒绝。三种解法本地 ATS 例外零配置部分客户端在Info.plist中已配置NSAllowsLocalNetworking YES局域网 IP 直连可直接使用。反向代理 HTTPS用 Nginx / Caddy / Nginx Proxy Manager 配一个music.xxx.com子域名 Let’s Encrypt 证书。公网 HTTPSDDNS 反代 证书实现外网访问。局域网用户优先用方案 1需要跨网络访问时再上方案 2 / 3。五、进阶与踩坑5.1 反向代理HTTPS 访问用 Nginx 或 Caddy 反代 Navidrome示例Nginxserver { listen 443 ssl; server_name music.example.com; ssl_certificate /etc/letsencrypt/live/music.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/music.example.com/privkey.pem; location / { proxy_pass http://127.0.0.1:4533; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }推荐用 Nginx Proxy ManagerDocker 一键部署图形化配证书省去手写配置。5.2 扫库与性能scanner 周期ND_SCANNER_SCHEDULE默认 1 小时拷贝新专辑后不会立刻出现要么等要么临时改5m。数据库Navidrome 默认 SQLite10 万首歌以内基本无压力更大的库可把ND_DB指向外部 PostgreSQL详见官方文档。转码默认不转码、源文件直推。若客户端不支持 FLAC可在 Settings 开启转码但会吃 CPU家用环境一般不开。5.3 备份最关键的卷是/data本例宿主机路径为/srv/navidrome/datanavidrome.db所有扫库结果、播放计数、收藏夹都存在这里最需要备份。cache/封面 / 艺人头像缓存。备份示例tar-czfnavidrome-backup-$(date%F).tar.gz /srv/navidrome/data建议把它纳入你现有的备份计划NAS 的 HBS3 / Hybrid Backup Sync或服务器的 cron 定时任务。5.4 常见问题现象原因解决扫库后库是空的音乐目录挂载路径不对docker exec -it navidrome ls /music查看容器内是否有内容客户端连不上端口 4533 未放行检查宿主机防火墙 / 安全组放行 4533 端口iOS 报 ATS 错误URL 不在 ATS 白名单用局域网 IP或上 HTTPS 反代scanner 卡在 0%容器读不到文件权限给音乐目录加读权限或容器加user: 0参数同一首歌反复扫库文件名有变动避免频繁改名scanner 周期适当调长六、结尾至此你就拥有了一套完全自托管的音乐流媒体服务无损本地文件静静躺在你的服务器 / NAS 上手机、平板、Web 客户端随时访问不依赖任何第三方订阅、不怕平台下架、不怕音质被偷换。服务端交给 Navidrome客户端选择任何一款兼容 Subsonic 协议的 App 即可如果你更习惯中文界面、且希望在手机和电脑上统一管理多个自托管服务可以试试上文的「归流」。附本文使用的环境版本Docker20.10支持docker compose命令Navidrome 镜像deluan/navidrome:latest发布时版本号见镜像 tag相关链接Navidrome 官网https://www.navidrome.org/Navidrome 配置文档https://www.navidrome.org/docs/operators/configuration/Nginx Proxy Managerhttps://nginxproxymanager.com/