跳至主要內容

Docker 安装 Navidrome

LiuMangMang2025/12/23大约 8 分钟DockerNavidrome音乐服务器Docker Compose

Docker 安装 Navidrome

Navidrome 是一个开源的音乐流媒体服务器和流媒体播放器,兼容 Subsonic/Airsonic API,可以让你随时随地访问和播放自己的音乐收藏。

什么是 Navidrome？

主要特性

  • 🎵 支持多种音频格式（MP3、FLAC、OGG、M4A 等）
  • 📱 响应式 Web 界面，支持手机和平板
  • 🎨 自动获取专辑封面和艺术家信息
  • 🔐 多用户支持，每个用户独立的播放列表
  • 📻 智能播放列表和电台功能
  • 🌐 兼容 Subsonic API，支持第三方客户端
  • ⚡ 轻量级，低资源占用
  • 🔄 实时音乐库扫描和更新

安装前准备

1. 确保 Docker 已安装

检查 Docker 和 Docker Compose 版本：

docker --version
docker-compose --version

如果未安装，请参考 Docker 安装指南。

2. 准备目录结构

创建 Navidrome 所需的目录：

# 创建工作目录
mkdir -p ~/navidrome/{data,music}

# 进入工作目录
cd ~/navidrome

目录说明：

  • data: 存储 Navidrome 的数据库和配置文件
  • music: 存放你的音乐文件

方式一：使用 docker run 安装

基础安装

docker run -d \
  --name navidrome \
  --restart=unless-stopped \
  -p 4533:4533 \
  -v ~/navidrome/data:/data \
  -v ~/navidrome/music:/music:ro \
  -e ND_LOGLEVEL=info \
  -e ND_SESSIONTIMEOUT=24h \
  deluan/navidrome:latest

参数说明

  • -d: 后台运行容器
  • --name navidrome: 容器名称
  • --restart=unless-stopped: 自动重启策略
  • -p 4533:4533: 端口映射（主机端口:容器端口）
  • -v ~/navidrome/data:/data: 数据目录挂载
  • -v ~/navidrome/music:/music:ro: 音乐目录挂载（只读）
  • -e ND_LOGLEVEL=info: 日志级别
  • -e ND_SESSIONTIMEOUT=24h: 会话超时时间

进阶配置

如果需要更多配置选项：

docker run -d \
  --name navidrome \
  --restart=unless-stopped \
  -p 4533:4533 \
  -v ~/navidrome/data:/data \
  -v ~/navidrome/music:/music:ro \
  -e ND_LOGLEVEL=info \
  -e ND_SESSIONTIMEOUT=24h \
  -e ND_BASEURL="" \
  -e ND_SCANSCHEDULE="1h" \
  -e ND_TRANSCODINGCACHESIZE="100MB" \
  -e ND_ENABLETRANSCODINGCONFIG=true \
  -e ND_ENABLESTARRATING=true \
  -e ND_ENABLEFAVOURITES=true \
  deluan/navidrome:latest

方式二：使用 Docker Compose 安装（推荐）

1. 创建 docker-compose.yml

在 ~/navidrome 目录下创建 docker-compose.yml 文件：

vim docker-compose.yml

2. 基础配置

version: '3.8'

services:
  navidrome:
    image: deluan/navidrome:latest
    container_name: navidrome
    restart: unless-stopped
    ports:
      - "4533:4533"
    volumes:
      - ./data:/data
      - ./music:/music:ro
    environment:
      # 基础配置
      ND_LOGLEVEL: info
      ND_SESSIONTIMEOUT: 24h
      ND_BASEURL: ""

3. 完整配置（推荐）

version: '3.8'

services:
  navidrome:
    image: deluan/navidrome:latest
    container_name: navidrome
    restart: unless-stopped
    ports:
      - "4533:4533"
    volumes:
      # 数据目录
      - ./data:/data
      # 音乐目录（可以添加多个）
      - ./music:/music:ro
      # 如果有多个音乐目录，可以这样添加：
      # - /path/to/music1:/music1:ro
      # - /path/to/music2:/music2:ro
    environment:
      # 基础配置
      ND_LOGLEVEL: info                          # 日志级别: error, warn, info, debug, trace
      ND_SESSIONTIMEOUT: 24h                     # 会话超时时间
      ND_BASEURL: ""                             # 基础 URL（如果通过反向代理访问需要设置）
      
      # 扫描配置
      ND_SCANSCHEDULE: 1h                        # 自动扫描间隔（@every 1h 或 cron 表达式）
      ND_SCANINTERVAL: 90s                       # 扫描时检查文件变化的间隔
      
      # 转码配置
      ND_TRANSCODINGCACHESIZE: 100MB             # 转码缓存大小
      ND_ENABLETRANSCODINGCONFIG: "true"         # 启用转码配置
      
      # 功能开关
      ND_ENABLESTARRATING: "true"                # 启用星级评分
      ND_ENABLEFAVOURITES: "true"                # 启用收藏功能
      ND_ENABLEUSEREDITING: "true"               # 允许用户编辑个人信息
      ND_ENABLESHARING: "true"                   # 启用分享功能
      ND_ENABLEDOWNLOADS: "true"                 # 启用下载功能
      
      # 播放器配置
      ND_DEFAULTTHEME: "Dark"                    # 默认主题: Light, Dark, Auto
      ND_UILOGINBACKGROUNDURL: ""                # 登录页背景图 URL
      ND_UIWELCOMEMESSAGE: ""                    # 欢迎消息
      
      # 性能配置
      ND_IMAGECACHESIZE: 100MB                   # 封面缓存大小
      ND_AUTOIMPORTPLAYLISTS: "true"             # 自动导入播放列表
      
      # 多媒体配置
      ND_ENABLECOVERANIMATION: "true"            # 启用封面动画
      ND_ENABLEREPLAYGAIN: "true"                # 启用音量平衡
      
      # 搜索配置
      ND_SEARCHFULLSTRING: "false"               # 全字符串搜索
      ND_RECENTLYADDEDBYMODTIME: "false"         # 按修改时间显示最近添加
      
      # Spotify 集成（可选）
      # ND_SPOTIFY_ID: "your_spotify_client_id"
      # ND_SPOTIFY_SECRET: "your_spotify_secret"
      
      # Last.fm 集成（可选）
      # ND_LASTFM_ENABLED: "true"
      # ND_LASTFM_APIKEY: "your_lastfm_api_key"
      # ND_LASTFM_SECRET: "your_lastfm_secret"

    # 资源限制（可选）
    # deploy:
    #   resources:
    #     limits:
    #       cpus: '2.0'
    #       memory: 1G
    #     reservations:
    #       cpus: '0.5'
    #       memory: 512M

4. 启动服务

# 启动 Navidrome
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

# 重启服务
docker-compose restart

配置说明

环境变量详解

变量名默认值说明
ND_LOGLEVELinfo日志级别：error, warn, info, debug, trace
ND_SESSIONTIMEOUT24h会话超时时间
ND_BASEURL""基础 URL（反向代理时使用）
ND_SCANSCHEDULE1h自动扫描音乐库的时间间隔
ND_TRANSCODINGCACHESIZE100MB转码缓存大小
ND_IMAGECACHESIZE100MB图片缓存大小
ND_ENABLETRANSCODINGCONFIGtrue是否启用转码配置
ND_ENABLESTARRATINGtrue是否启用星级评分
ND_ENABLEFAVOURITEStrue是否启用收藏功能
ND_ENABLESHARINGtrue是否启用分享功能
ND_ENABLEDOWNLOADStrue是否启用下载功能
ND_DEFAULTTHEMEDark默认主题：Light, Dark, Auto

更多配置选项请参考 官方文档。

端口说明

默认端口：4533

如果端口冲突，可以修改为其他端口：

ports:
  - "8080:4533"  # 主机使用 8080 端口

初始化和使用

1. 访问 Web 界面

容器启动后，在浏览器中访问：

http://localhost:4533

或者使用服务器 IP：

http://your-server-ip:4533

2. 创建管理员账户

首次访问会提示创建管理员账户：

  1. 输入用户名
  2. 设置密码
  3. 确认密码
  4. 点击创建账户

3. 添加音乐

将音乐文件复制到 ~/navidrome/music 目录：

# 复制音乐文件
cp -r /path/to/your/music/* ~/navidrome/music/

# 或者创建软链接
ln -s /path/to/your/music ~/navidrome/music/library

Navidrome 会自动扫描并导入音乐。

4. 手动触发扫描

如果想立即扫描新添加的音乐：

  1. 登录 Web 界面
  2. 点击右上角用户头像
  3. 选择 "Settings"（设置）
  4. 在 "Library" 部分点击 "Scan Library Now"（立即扫描库）

数据管理

备份数据

# 备份数据目录
tar -czf navidrome-backup-$(date +%Y%m%d).tar.gz ~/navidrome/data

# 或者只备份数据库
cp ~/navidrome/data/navidrome.db ~/navidrome-db-backup-$(date +%Y%m%d).db

恢复数据

# 停止容器
docker-compose down

# 恢复数据
tar -xzf navidrome-backup-20231223.tar.gz -C ~/

# 重启容器
docker-compose up -d

清理缓存

# 进入容器
docker exec -it navidrome sh

# 清理缓存（在容器内执行）
rm -rf /data/cache/*

# 退出容器
exit

# 重启服务
docker-compose restart

使用第三方客户端

Navidrome 兼容 Subsonic API，可以使用多种第三方客户端：

Android 客户端

  • DSub: 功能丰富，界面友好
  • Ultrasonic: 开源免费
  • Subsonic: 官方客户端

iOS 客户端

  • play:Sub: 界面精美
  • substreamer: 功能全面
  • Amperfy: 开源免费

桌面客户端

  • Sublime Music: Linux 客户端
  • Sonixd: 跨平台客户端
  • Supersonic: 现代化界面

客户端配置

在客户端中配置服务器信息：

  • 服务器地址: http://your-server-ip:4533
  • 用户名: 你的 Navidrome 用户名
  • 密码: 你的 Navidrome 密码

高级配置

1. 使用反向代理（Nginx）

如果使用 Nginx 反向代理：

server {
    listen 80;
    server_name music.example.com;

    location / {
        proxy_pass http://localhost: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;
        
        # WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

同时在 docker-compose.yml 中设置：

environment:
  ND_BASEURL: "http://music.example.com"

2. 启用 HTTPS

使用 Let's Encrypt 和 Nginx：

# 安装 certbot
sudo apt install certbot python3-certbot-nginx

# 获取证书
sudo certbot --nginx -d music.example.com

3. 多音乐目录配置

volumes:
  - ./data:/data
  - /mnt/music1:/music:ro
  - /mnt/music2:/music2:ro
  - /mnt/audiobooks:/audiobooks:ro

4. 集成 Spotify（获取元数据）

  1. 前往 Spotify Developer Dashboard
  2. 创建应用获取 Client ID 和 Secret
  3. 在 docker-compose.yml 中添加：
environment:
  ND_SPOTIFY_ID: "your_client_id"
  ND_SPOTIFY_SECRET: "your_client_secret"

5. 集成 Last.fm（音乐信息）

  1. 前往 Last.fm API
  2. 创建应用获取 API Key 和 Secret
  3. 在 docker-compose.yml 中添加：
environment:
  ND_LASTFM_ENABLED: "true"
  ND_LASTFM_APIKEY: "your_api_key"
  ND_LASTFM_SECRET: "your_secret"

常见问题

1. 无法访问 Web 界面

检查容器状态：

docker-compose ps
docker-compose logs

检查端口是否被占用：

sudo netstat -tulpn | grep 4533

2. 音乐扫描不到

确认音乐目录挂载正确：

# 进入容器检查
docker exec -it navidrome ls -la /music

检查文件权限：

# 修改音乐目录权限
chmod -R 755 ~/navidrome/music

3. 转码不工作

确保启用了转码配置：

environment:
  ND_ENABLETRANSCODINGCONFIG: "true"

检查是否安装了 FFmpeg（Navidrome 镜像已包含）。

4. 性能优化

增加缓存大小：

environment:
  ND_TRANSCODINGCACHESIZE: 500MB
  ND_IMAGECACHESIZE: 200MB

限制扫描频率：

environment:
  ND_SCANSCHEDULE: "0 2 * * *"  # 每天凌晨2点扫描

5. 数据库锁定错误

停止容器并修复：

docker-compose down
sqlite3 ~/navidrome/data/navidrome.db "VACUUM;"
docker-compose up -d

容器管理

查看容器状态

docker-compose ps

查看实时日志

docker-compose logs -f navidrome

重启服务

docker-compose restart

更新到最新版本

# 拉取最新镜像
docker-compose pull

# 重新创建容器
docker-compose up -d

# 清理旧镜像
docker image prune

停止并删除容器

docker-compose down

完全卸载（包括数据）

# 停止并删除容器
docker-compose down -v

# 删除数据目录
rm -rf ~/navidrome

性能监控

查看资源使用

docker stats navidrome

查看容器详细信息

docker inspect navidrome

参考资源

推荐音乐格式

为了获得最佳体验，推荐使用以下格式：

  • 高质量: FLAC（无损）
  • 平衡: MP3 320kbps / AAC 256kbps
  • 移动端: MP3 192kbps / AAC 128kbps

下一步

  1. ✅ 安装并启动 Navidrome
  2. 📁 整理音乐文件，添加正确的标签信息
  3. 🎨 优化专辑封面和艺术家信息
  4. 📱 安装并配置移动客户端
  5. 🔐 配置 HTTPS 和反向代理（生产环境）
  6. 🎵 享受你的私人音乐流媒体服务！

提示: Navidrome 会根据音乐文件的 ID3 标签自动组织你的音乐库，确保你的音乐文件有正确的标签信息以获得最佳体验。

贡献者: liumangmang