Как самостоятельно развернуть Navidrome в 2026 году: подключение музыки, сканирование и Subsonic-приложения

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

В этом руководстве используется один конкретный критерий готовности: просканировать библиотеку музыки в режиме read-only, проверить метаданные и обложки, воспроизвести трек через Subsonic-клиент и сохранить playlist. Каждое решение по конфигурации оценивается по этому критерию, а не по зелёному индикатору состояния контейнера.

Создайте резервную копию состояния, которое Navidrome не может восстановить самостоятельно

Определите допустимую точку и время восстановления Navidrome с учётом базы данных Navidrome, кэша обложек, playlist и исходной музыкальной библиотеки. Подключите /data до bootstrap, запишите безвредные тестовые данные и замените контейнер, чтобы убедиться, что этот путь действительно сохраняется. Именованный volume решает проблему сохранения данных при redeploy, но не защищает от компрометации или потери сервера.

Подготовьте чистое окружение для восстановления, используйте ту же зафиксированную версию приложения и убедитесь, что пользователи, playlist, история прослушивания и метаданные восстановились, а тот же Subsonic-клиент воспроизводит известный трек. Зафиксируйте команды, исправления владельцев и затраченное время. Руководство по резервному копированию задаёт полезный стандарт: резервная копия считается надёжной после восстановления, а не после загрузки.

Запустите Navidrome, не скрывая важные детали

Используйте контейнер как заменяемое runtime-окружение, а не как источник истины.

docker run -d \
  --name navidrome \
  --restart unless-stopped \
  -p 127.0.0.1:4533:4533 \
  -v navidrome-data:/data \
  -v /srv/music:/music:ro \
  -e ND_BASEURL=/ \
  deluan/navidrome:latest

До публикации сервиса подтвердите локальное требование: подключённая в режиме read-only музыкальная библиотека и доступные для записи данные приложения. Перед внешним доступом проверьте пользователя контейнера, доступные для записи пути и прослушиваемый порт. Выполните полный сценарий — просканируйте библиотеку музыки в режиме read-only, проверьте метаданные и обложки, воспроизведите трек через Subsonic-клиент и сохраните playlist — и зафиксируйте точную ссылку на image, с которым был получен результат.

Выберите минимально достаточную топологию Navidrome

Начните с network namespace Navidrome: его web listener работает на порту 4533, а не на host port, скопированном из инструкции для laptop. Локальное требование runtime — подключённая в режиме read-only музыкальная библиотека и доступные для записи данные приложения. Зафиксируйте это требование рядом с image и портом, чтобы замещающий host получил те же локальные возможности.

После выполнения требования запустите полный сценарий — просканируйте библиотеку музыки в режиме read-only, проверьте метаданные и обложки, воспроизведите трек через Subsonic-клиент и сохраните playlist. Запишите логи и показатели: время сканирования библиотеки, нагрузку CPU при transcoding, размер кэша обложек, количество одновременных потоков и пропускную способность диска. Эти данные станут первой эталонной архитектурой и позволят проверять последующие переносы между compute в Dockup и подключённым сервером.

Настроить TLS просто, а вот корректно генерировать URL — нет

Задайте ND_BASEURL при публикации через subpath; в остальных случаях предпочтительнее выделенный HTTPS-host. Направьте выбранное имя хоста на порт контейнера 4533, передавайте исходные host и HTTPS scheme и не публикуйте второй прямой origin.

Проверьте Navidrome через внешний клиент в чистом окружении. Отделяйте сбой ingress от известной границы приложения — сканирование не находит файлов, потому что путь к музыке на хосте подключён неправильно. Ошибка сертификата, DNS или 502 относится к routing; если запрос доходит до Navidrome и завершается ошибкой позже, проблема связана с состоянием приложения, capacity или его supporting requirement. Руководство по TLS для custom domain посвящено первой группе проблем.

Пять проверок, более надёжных, чем health контейнера

До появления реальных пользователей подготовьте release worksheet для Navidrome. В нём должны быть указаны зафиксированный image, порт 4533, canonical origin, постоянные пути и владелец подключённой в режиме read-only музыкальной библиотеки с доступными для записи данными приложения. Добавьте ожидаемый результат этой транзакции: просканировать библиотеку музыки в режиме read-only, проверить метаданные и обложки, воспроизвести трек через Subsonic-клиент и сохранить playlist.

Используйте worksheet после обычной замены контейнера и после чистого восстановления. Восстановление считается успешным только в том случае, если пользователи, playlist, история прослушивания и метаданные вернулись, а тот же Subsonic-клиент воспроизводит известный трек. Также соберите короткий resource trace с временем сканирования библиотеки, нагрузкой CPU при transcoding, размером кэша обложек, количеством одновременных потоков и пропускной способностью диска; храните его рядом с release, чтобы будущие изменения capacity сравнивались на той же нагрузке.

Добавьте один контролируемый сбой: отправьте безвредные данные около ограничения по ресурсам или формату, связанного с этой границей: сканирование не находит файлов, потому что путь к музыке на хосте подключён неправильно. Убедитесь, что Navidrome сообщает о проблеме на корректной границе, восстановите валидное состояние и повторите транзакцию. Так вы проверите видимость ошибок, а не только успешный результат, и не позволите внешне исправному интерфейсу скрывать неисправный worker, callback или подключение к базе данных.

Логи, которые помогают ответить на следующий вопрос

Используйте сценарий «просканировать библиотеку музыки в режиме read-only, проверить метаданные и обложки, воспроизвести трек через Subsonic-клиент и сохранить playlist» как smoke test Navidrome после каждого deployment. Сопутствующие метрики — время сканирования библиотеки, нагрузка CPU при transcoding, размер кэша обложек, количество одновременных потоков и пропускная способность диска; устанавливайте alert, когда эти ресурсы приближаются к уровню, ухудшающему пользовательское действие.

Основной риск при изменениях заключается в том, что миграции базы данных Navidrome и поведение scanner необходимо тестировать, не изменяя исходные музыкальные файлы. Безопасный release начинается с восстанавливаемого snapshot и проверки любых односторонних изменений состояния до переключения traffic. Если сканирование не находит файлов, потому что путь к музыке на хосте подключён неправильно, сохраните неисправный контейнер достаточно надолго, чтобы изучить его конфигурацию и первую ошибку.

Не предоставляйте Navidrome доступ ко всему хосту

Закройте окно bootstrap сразу после создания первого доверенного администратора. Конкретная ловушка Navidrome — подключить музыкальную библиотеку с правами записи без необходимости; более безопасная граница — подключить музыку в режиме read-only, защитить аккаунты и открыть только streaming service, а не библиотеку хоста.

ND_BASEURL — это конфигурация, а не secret; явно указывайте его значение, защищая отдельные credentials, которые использует Navidrome. Для передачи credentials зависимостей используйте private networking, а роли внутри Navidrome должны предоставлять минимально необходимые действия. Не записывайте конфиденциальные request body и ответы provider в обычные логи.

Оставьте конфигурацию Navidrome явной, а routing поручите Dockup

Routing, сертификаты, замена сервисов и подключённое storage — разумные цели для automation. Dockup выполняет эти задачи для Navidrome и может provisionить соответствующую managed database либо подключиться к сервисам на собственном сервере клиента.

При этом Dockup не должен самостоятельно придумывать trust policy Navidrome. После deployment задайте ND_BASEURL при публикации через subpath; в остальных случаях предпочтительнее выделенный HTTPS-host, установите эту границу — подключите музыку в режиме read-only, защитите аккаунты и откройте только streaming service, а не библиотеку хоста — и проверьте результат сценария: просканировать библиотеку музыки в режиме read-only, проверить метаданные и обложки, воспроизвести трек через Subsonic-клиент и сохранить playlist. В результате вы получаете инфраструктуру, разворачиваемую в один клик, с acceptance test, учитывающим особенности приложения.

Часто задаваемые вопросы

Что нужно Navidrome для deployment в production?

Направьте контейнер Navidrome через один HTTPS-origin на порт 4533. Локальное требование runtime — подключённая в режиме read-only музыкальная библиотека и доступные для записи данные приложения. Не объявляйте Navidrome готовым, пока не сможете просканировать библиотеку музыки в режиме read-only, проверить метаданные и обложки, воспроизвести трек через Subsonic-клиент и сохранить playlist.

Какие данные Navidrome нужно включить в резервную копию?

Сохраняйте /data и включайте базу данных Navidrome, кэш обложек, playlist и исходную музыкальную библиотеку в один recovery manifest. Чистое восстановление Navidrome считается успешным только после возвращения пользователей, playlist, истории прослушивания и метаданных, а также успешного воспроизведения известного трека тем же Subsonic-клиентом.

Нужен ли Navidrome HTTPS за reverse proxy?

Используйте HTTPS для публичного origin Navidrome, а порт 4533 оставьте во внутреннем маршруте. Корректно примените настройку Navidrome: задайте ND_BASEURL при публикации через subpath; в остальных случаях предпочтительнее выделенный HTTPS-host. Для Navidrome HTTPS защищает credentials и пользовательский контент при передаче и обеспечивает согласованное поведение клиентов, зависящее от origin.

Как тестировать upgrade Navidrome?

Восстановите текущее состояние Navidrome в изолированном deployment, примените candidate version и повторите acceptance transaction. Уделите этому особое внимание: миграции базы данных Navidrome и поведение scanner необходимо тестировать, не изменяя исходные музыкальные файлы. Храните предыдущий image Navidrome, пока не будут понятны границы миграции данных и rollback.