Navidrome

Обзор

Navidrome — музыкальный сервер для коллекции, которая лежит файлами. Он читает теги и обложки, строит библиотеку по исполнителям и альбомам, помнит оценки, плейлисты и историю прослушиваний, а слушать можно и в браузере, и в мобильном приложении. Подойдёт тем, кто годами собирал музыку и не хочет зависеть от того, что очередной трек пропадёт из подписки.

Ключевая особенность — Subsonic API: собственных мобильных приложений у проекта нет, зато совместимых клиентов десятки, от Symfonium и substreamer на Android до play:Sub на iOS и Feishin на десктопе. Сервер написан на Go, занимает один контейнер и работает на слабом железе вплоть до Raspberry Pi.

Рецепт подключает каталог с музыкой только для чтения, а базу, обложки и историю держит в отдельном Docker volume. Уровень reliable не заявлен: Navidrome использует встроенную SQLite, а в рецепте нет мониторинга и ресурсных лимитов.

Отправка анонимной статистики разработчикам в рецепте выключена (NAVIDROME_INSIGHTS=false). Включить её можно одной переменной, если хотите поддержать проект данными.

Оценка безопасности

Контейнер запускается без privileged, host network и доступа к Docker socket, с no-new-privileges; наружу открыт только веб-порт и только на 127.0.0.1. Медиатека подключена в режиме read-only, поэтому сервер не может изменить или удалить ваши файлы.

Главный риск — первый запуск: форма создания администратора не требует пароля, и до создания учётной записи порт нельзя открывать наружу. Второй — сам протокол: Subsonic API передаёт учётные данные в каждом запросе, а часть клиентов до сих пор шлёт пароль открытым текстом, поэтому публиковать сервер допустимо только по HTTPS. Контейнер работает от root, как в образе upstream; если это критично, задайте user: и самостоятельно выставьте права на volume.

Образ рецепта просканирован Trivy: критических уязвимостей не найдено. Это ожидаемо для образа, который состоит из Alpine и одного статически собранного Go-бинарника.

Пошаговая инструкция

1. Проверьте сервер Ubuntu или Debian

Для этого рецепта достаточно 1 ядра CPU, 256 МБ RAM и 2 ГБ диска под сам сервер; рекомендуется 512 МБ RAM. Это консервативная оценка рецепта: upstream не публикует формальные минимальные требования. Место под музыку считайте отдельно, плюс несколько процентов на кэш обложек. Нужны Ubuntu 22.04+ или Debian 12+ с Docker Engine и Docker Compose v2.24+.

docker --version
docker compose version

2. Подготовьте медиатеку

Navidrome читает теги, а не имена файлов, поэтому важнее всего заполненные Artist, Album, Title и номер трека. Раскладка по каталогам произвольная, но удобнее всего исполнитель/альбом:

/srv/music/Artist Name/Album Name (2019)/01 Track.mp3
/srv/music/Artist Name/Album Name (2019)/cover.jpg

Обложку Navidrome берёт из тега или из файла cover.jpg, folder.jpg либо front.jpg рядом с треками. Поддерживаются MP3, FLAC, OGG, Opus, M4A, WavPack и другие форматы, которые понимает ffmpeg внутри образа.

3. Подготовьте файлы и переменные

mkdir -p ~/services/navidrome
cd ~/services/navidrome
cp .env.example .env
chmod 600 .env
sed -i "s|^NAVIDROME_MUSIC_LOCATION=.*|NAVIDROME_MUSIC_LOCATION=/srv/music|" .env

NAVIDROME_VERSION закрепляет образ; NAVIDROME_PORT задаёт локальный порт; NAVIDROME_MUSIC_LOCATION — каталог с музыкой, он подключается только для чтения; NAVIDROME_DATA_VOLUME — volume с базой, обложками и историей прослушиваний; NAVIDROME_SCAN_INTERVAL управляет автосканированием; NAVIDROME_LOG_LEVEL и NAVIDROME_SESSION_TIMEOUT — логи и время жизни сессии; NAVIDROME_BASE_URL нужен, только если сервис публикуется в подкаталоге домена; NAVIDROME_INSIGHTS управляет отправкой анонимной статистики и по умолчанию выключен; TZ задаёт часовой пояс.

4. Создайте администратора

Форма создания администратора не защищена паролем: первый, кто её откроет, получит сервер. Поэтому первый запуск делайте через localhost или SSH-туннель.

docker compose pull
docker compose up -d
docker compose ps
ssh -L 4533:127.0.0.1:4533 user@server.example

Откройте http://localhost:4533, задайте имя пользователя и пароль. После этого начнётся первое сканирование; в журнале контейнера видно, сколько треков импортировано:

docker compose logs --tail=50 navidrome | grep -i scanner

Остальных пользователей заводит администратор в разделе Users. Мобильные и десктопные клиенты сторонние: они подключаются к тому же адресу по Subsonic API.

Запуск на VPS

На VPS оставьте bind 127.0.0.1, закройте порт 4533 снаружи и публикуйте сервис только через HTTPS reverse proxy. Проверьте состояние и API:

docker compose up -d
docker compose ps
curl --fail http://127.0.0.1:4533/ping
curl --fail "http://127.0.0.1:4533/rest/ping?v=1.16.1&c=check&f=json"

Второй запрос отвечает ошибкой авторизации — это нормально: он подтверждает, что Subsonic API работает, и показывает версию сервера.

Доступ в локальной сети

Без TLS используйте SSH-туннель или VPN. Если reverse proxy работает на другом узле доверенной LAN, замените 127.0.0.1 в compose.yaml на конкретный LAN-адрес сервера и ограничьте порт firewall адресом proxy. Не публикуйте Navidrome на 0.0.0.0 без ограничений: Subsonic API передаёт учётные данные в каждом запросе.

Домен и HTTPS

Замените music.example.com в выбранном файле из proxy/ одним доменом. proxy/Caddyfile автоматически получает сертификат; proxy/nginx.conf ожидает сертификат Certbot; proxy/traefik.yaml использует resolver letsencrypt. Для Traefik в контейнере замените 127.0.0.1 на доступный ему host gateway.

В примере Nginx отключена буферизация ответа: без этого перемотка внутри трека работает рывками. Если сервис публикуется не в корне домена, задайте тот же подкаталог в NAVIDROME_BASE_URL, иначе веб-интерфейс не найдёт свои файлы.

curl --fail https://music.example.com/ping

Резервное копирование

chmod +x backup.sh restore.sh
./backup.sh

Скрипт останавливает контейнер, архивирует volume /data и снова его запускает. Остановка обязательна: база SQLite копируется согласованно только у выключенного сервера. В архив попадают пользователи, плейлисты, оценки, история прослушиваний и кэш обложек.

Музыка в архив не входит: это ваши файлы, и копировать их нужно отдельно.

У Navidrome есть и собственный механизм — docker compose exec navidrome /app/navidrome backup create --datafolder /data создаёт снимок базы, не останавливая сервер. Он удобен перед обновлением и попадает внутрь копии, созданной backup.sh.

Восстановление

Восстановление полностью заменяет содержимое /data выбранным архивом:

./restore.sh ./backups/navidrome-YYYYMMDDTHHMMSSZ.tar.gz
docker compose ps
curl --fail http://127.0.0.1:4533/ping

Перед заменой скрипт создаёт страховочную копию текущих данных. Музыка не затрагивается, но пути в восстановленной базе должны совпадать с текущим монтированием /music, иначе треки будут отмечены как отсутствующие до следующего сканирования.

Обновление

Создайте backup и прочитайте release notes. Измените только закреплённый NAVIDROME_VERSION, затем выполните:

./backup.sh
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 navidrome

Миграции базы применяются при первом запуске новой версии. Крупные обновления иногда требуют полного пересканирования медиатеки — об этом пишут в release notes.

Откат

Понижение версии не поддерживается: после миграции старый образ не откроет базу. Верните прежний NAVIDROME_VERSION в .env и восстановите архив, снятый до обновления:

docker compose pull
./restore.sh ./backups/navidrome-before-update.tar.gz
docker compose up -d

Оценки и история прослушиваний, появившиеся после обновления, в таком архиве отсутствуют.

Остановка и полное удаление

docker compose down удаляет контейнер, но сохраняет базу. Полное необратимое удаление после проверки backup:

docker compose down
docker volume rm navidrome-data
rm -rf ~/services/navidrome

Каталог NAVIDROME_MUSIC_LOCATION остаётся нетронутым: рецепт подключает его только для чтения и никогда не удаляет.

Источники: установка в Docker, параметры конфигурации, обложки и теги, backup и restore, анонимная статистика и рекомендации по безопасности.

Диагностика

Медиатека пустая после запуска

Проверьте, что каталог виден внутри контейнера и что сканирование завершилось:

docker compose exec navidrome ls -la /music
docker compose logs --tail=100 navidrome | grep -i scanner

Пустой результат при видимом каталоге почти всегда означает отсутствие тегов: Navidrome строит библиотеку по Artist, Album и Title, а не по именам файлов. Проверить теги конкретного файла можно встроенной командой:

docker compose exec navidrome /app/navidrome inspect "/music/путь/к/файлу.mp3"

Новые файлы не появляются

По умолчанию рецепт сканирует раз в сутки (NAVIDROME_SCAN_INTERVAL). Запустить сканирование сразу можно из веб-интерфейса кнопкой обновления или командой:

docker compose exec navidrome /app/navidrome scan --datafolder /data

Нет обложек

Обложка берётся из тега либо из файла cover.jpg, folder.jpg или front.jpg рядом с треками. Убедитесь, что файл лежит в каталоге альбома и доступен для чтения. Кэш обложек живёт в volume /data и пересобирается сам.

Один альбом разбит на несколько

Так происходит со сборниками, у которых не заполнен тег Album Artist. Задайте Album Artist одинаковым для всех треков альбома (например, Various Artists) и запустите повторное сканирование.

Клиент не подключается по Subsonic

Клиенту нужен адрес сервера без /app, имя пользователя и пароль. Проверьте доступность API:

curl --fail "https://music.example.com/rest/ping?v=1.16.1&c=check&f=json"

Ответ с ошибкой авторизации означает, что API работает. Если ответа нет вообще, дело в reverse proxy или в NAVIDROME_BASE_URL.

Веб-интерфейс открывается без стилей

Так бывает, когда Navidrome опубликован в подкаталоге, а NAVIDROME_BASE_URL не задан. Укажите тот же путь, что и в reverse proxy, и перезапустите контейнер.

Перемотка внутри трека работает рывками

Reverse proxy буферизует ответ. В Nginx нужен proxy_buffering off — он уже есть в примере из proxy/. Caddy и Traefik отдают поток без буферизации.

Забыт пароль администратора

Пароль меняется командой внутри контейнера:

docker compose exec navidrome /app/navidrome user edit --datafolder /data

Команда интерактивная, поэтому запускайте её из терминала с TTY.

После обновления сервер не стартует

docker compose logs --tail=200 navidrome | grep -i "migration\|error"

Понижение версии не поддерживается: вернуться можно только восстановлением архива, снятого до обновления.