Navidrome на сервере: частые ошибки и решения

MAATRIX

Navidrome — self-hosted аналог Spotify для собственной музыкальной коллекции: поднял один Go-бинарник или контейнер, подключил папку с FLAC и MP3, и слушаешь через веб-плеер и Subsonic-совместимые приложения на телефоне. На практике почти сразу вылезают одни и те же грабли: библиотека не сканируется, обложки не подгружаются, поток на мобильном рвётся, а после недели работы в логах появляется «database is locked». Ниже — разбор частых проблем Navidrome на сервере по схеме «симптом — причина — решение».

С чего начинать диагностику

Прежде чем чинить что-то конкретное, посмотрите, что вообще происходит с процессом. Если Navidrome запущен как systemd-сервис:

systemctl status navidrome
journalctl -u navidrome -f

Если в Docker:

docker ps | grep navidrome
docker logs -f navidrome

Для более подробных логов временно поднимите уровень логирования — это отдельная переменная окружения ND_LOGLEVEL, значение debug показывает, какие файлы сканируются, какие пропускаются и почему:

ND_LOGLEVEL=debug

В самом веб-интерфейсе тоже есть полезная точка входа: раздел настроек с информацией о версии и статусом последнего скана, плюс кнопка ручного запуска сканирования библиотеки. Держите под рукой три источника: логи процесса, ND_LOGLEVEL=debug при необходимости и статус скана в UI — этого достаточно, чтобы отличить проблему с файлами от проблемы с сетью или с базой.

Библиотека не сканируется или новые треки не появляются

Частый сценарий: вы закинули новые альбомы в папку с музыкой, но в Navidrome они не появляются даже после перезапуска. Причин обычно три.

Первая — неверный путь или права доступа. В Docker образ Navidrome по умолчанию работает от непривилегированного пользователя, и если файлы на хосте принадлежат root с правами 700, контейнер их просто не видит. Проверьте:

docker exec navidrome ls -la /music

Если владелец — root и права закрыты, поправьте на хосте:

chown -R 1000:1000 /path/to/music
chmod -R a+rX /path/to/music

Вторая причина — расписание сканирования не настроено или отключено, и новые файлы подхватываются только при ручном запуске. Задайте автоматическое сканирование через переменную окружения или файл конфигурации navidrome.toml:

ScanSchedule = "@every 1h"

Или в docker-compose:

environment:
  ND_SCANSCHEDULE: "@every 1h"

Третья причина менее очевидна: файл с битыми или отсутствующими тегами (ID3/Vorbis Comments) может тихо пропускаться сканером — в дебажных логах ищите строки со skipping или error extracting tags. Почините теги через любой тег-редактор (например, beets или mp3tag) и перезапустите скан.

Если библиотека выглядит частично сломанной после серии экспериментов с путями, проще всего остановить сервис, сделать резервную копию базы и запустить полное пересканирование:

systemctl stop navidrome
cp /data/navidrome.db /data/navidrome.db.bak
systemctl start navidrome

Полный скан из UI (или через ND_SCANSCHEDULE с флагом принудительного полного скана в интерфейсе настроек) пересоберёт индекс с нуля — это может занять от пары минут до десятков минут в зависимости от размера библиотеки и мощности сервера.

Обложки альбомов не подгружаются

Симптом понятен сразу — вместо обложек серые заглушки-плейсхолдеры. Navidrome ищет арт по приоритету источников, и порядок поиска задаётся отдельной настройкой:

CoverArtPriority = "cover.jpg, folder.jpg, front.jpg, embedded"

Если у вас обложки встроены в сами файлы (embedded art в FLAC/MP3), а не лежат отдельным cover.jpg в папке альбома, поднимите embedded выше в списке приоритета — по умолчанию файловые обложки могут стоять раньше встроенных, и если файла с обложкой в папке нет, а встроенная почему-то не подхватывается, стоит явно проверить оба варианта на одном альбоме.

Отдельный случай — обложки автоплейлистов (Smart Playlists) и «умных» подборок: они собираются из обложек нескольких первых треков и требуют, чтобы у этих треков уже была корректно определена обложка на момент генерации. Если поменяли приоритет источников, пересоберите такие подборки заново.

Ещё одна частая ловушка — браузерный кэш. После правки конфигурации и повторного скана обложки могут не обновиться визуально, потому что браузер отдаёт закэшированный ответ с эндпоинта /rest/getCoverArt. Жёстко обновите страницу (Ctrl+Shift+R) или откройте вкладку в режиме инкогнито, прежде чем делать вывод, что проблема не решена.

Транскодирование и лаги в мобильном приложении

Мобильные Subsonic-совместимые клиенты (Symfonium, Substreamer, DSub и другие) — основной способ слушать библиотеку вне дома, и именно там чаще всего вылезают проблемы с потоком: заикания, долгий буфер, неожиданно большой расход мобильного трафика.

Первым делом проверьте, доступен ли ffmpeg внутри контейнера или системы — без него Navidrome не может транскодировать и отдаёт исходный файл как есть, что при FLAC на мобильной сети приводит именно к таким симптомам:

docker exec navidrome ffmpeg -version

Если ffmpeg не найден — используйте официальный образ deluan/navidrome, в котором он уже включён, либо установите его на хосте при запуске бинарником напрямую (apt install ffmpeg на Debian/Ubuntu).

Дальше нужно явно создать профиль транскодирования в разделе настроек интерфейса — по умолчанию для новых пользователей может быть выставлен формат «без изменений» (raw), и клиент честно качает оригинал. Создайте профиль, например Opus 128 kbps для мобильной сети или MP3 192 kbps как более совместимый вариант, и назначьте его пользователю как максимальный битрейт по умолчанию для мобильного подключения. В самом мобильном приложении отдельно проверьте настройку максимального битрейта потока — она должна соответствовать выбранному профилю, иначе клиент может запрашивать более высокое качество, чем задумано.

Доступ извне через реверс-прокси и разрывы стрима

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

Пример рабочего блока для nginx:

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;
    proxy_buffering off;
    proxy_read_timeout 3600s;
}

Ключевые моменты: proxy_buffering off, чтобы nginx не пытался сначала целиком забуферить длинный аудиофайл, и увеличенный proxy_read_timeout — стандартные 60 секунд коротки для скачивания больших FLAC-альбомов на медленном канале. Если вместо nginx используете Traefik, логика та же — важно не подрезать заголовки и не включать агрессивный буферинг; подробный разбор частых проблем реверс-прокси есть в статье про Traefik на сервере.

Отдельно проверьте BaseUrl в конфигурации, если Navidrome развёрнут в подпапке (например, https://example.com/music) — без корректно указанного базового пути статические ресурсы и API-запросы могут уходить не туда, и интерфейс будет частично не работать при полностью рабочем прокси.

Ошибка «database is locked» и повреждение базы

Navidrome хранит индекс библиотеки в SQLite — компактно и быстро для одного процесса, но чувствительно к условиям, для которых SQLite не рассчитан. Симптом «database is locked» в логах во время сканирования — почти всегда одна из двух причин.

Первая: файл базы данных лежит на сетевом хранилище (NFS, SMB-шара, некоторые сетевые тома в облаке) — SQLite плохо работает с блокировками файлов на таких файловых системах. Держите директорию с данными (ND_DATAFOLDER / том /data) на локальном диске сервера, а музыкальную библиотеку при этом можно и нужно хранить отдельно, хоть на сетевом хранилище.

Вторая: случайно запущено два экземпляра Navidrome одновременно — например, старый процесс не остановился при обновлении systemd-юнита, или контейнер перезапустился поверх ещё работающего. Проверьте:

ps aux | grep navidrome
docker ps -a | grep navidrome

Если база всё же повредилась, для начала проверьте её целостность:

sqlite3 /data/navidrome.db "PRAGMA integrity_check;"

Если результат не ok — восстановите из резервной копии. Пересобрать индекс с нуля тоже вариант: остановите сервис, удалите (предварительно скопировав) файл navidrome.db, запустите сервис заново — Navidrome создаст пустую базу и пересканирует библиотеку с нуля, но настройки плейлистов, история прослушиваний и пользовательские рейтинги при этом потеряются. Поэтому регулярный бэкап файла базы — не опция, а обязательная практика; для регулярных копий контейнеров и файловых данных подойдёт связка вроде BorgBackup в Docker Compose.

Частые вопросы