Как да хоствате Navidrome самостоятелно през 2026 г.: монтиране на музика, сканиране и Subsonic приложения

Ако вече сте опитвали да хоствате Navidrome самостоятелно, вероятно ви е познат този неприятен сценарий: интерфейсът се зарежда, но сканирането не открива файлове, защото пътят към музиката на хоста е монтиран неправилно. Създаването на контейнера наново рядко решава несъответствие между URL адреси, състояние и зависимости.

Този walkthrough използва един конкретен критерий за успешно завършване — сканиране на музикална библиотека само за четене, проверка на metadata и artwork, стриймване на песен през Subsonic клиент и запазване на playlist. Всяко конфигурационно решение се оценява спрямо този критерий, а не спрямо зеления badge на контейнера.

Архивирайте състоянието, което Navidrome не може да възстанови

Определете recovery point и recovery time за Navidrome чрез базата данни на Navidrome, кеша с artwork, playlist-ите и оригиналната музикална библиотека. Монтирайте /data преди bootstrap, запишете безвредни примерни данни и заменете контейнера, за да докажете, че този път действително е persistent. Named volume решава persistence при redeploy, но не решава проблеми при компрометиране или загуба на сървъра.

Изградете чиста restore среда, използвайте същата pinned версия на приложението и докажете, че потребителите, playlist-ите, историята на възпроизвеждане и metadata се възстановяват, както и че същият Subsonic клиент може да стриймва позната песен. Запишете командите, корекциите на ownership и изминалото време. Ръководството за backup е полезен стандарт: на backup се има доверие след restore, а не след upload.

Стартирайте 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

Потвърдете локалното изискване преди публичното излагане: mount на музикална библиотека само за четене плюс writable application data. Проверете потребителя на контейнера, writable paths и bound listener, преди да го изложите. Изпълнете целия сценарий — сканирайте музикална библиотека само за четене, проверете metadata и artwork, стриймвайте песен през Subsonic клиент и запазете playlist — и съхранете точната image reference, с която е постигнат резултатът.

Изберете минималната работеща топология за Navidrome

Започнете с network namespace на Navidrome: неговият web listener е на порт 4533, а не на host port, копиран от tutorial за лаптоп. Изискването към локалния runtime е mount на музикална библиотека само за четене плюс writable application data. Запишете го заедно с image и port, така че replacement host да получи същата локална capability.

След като изискването е изпълнено, стартирайте целия сценарий — сканирайте музикална библиотека само за четене, проверете metadata и artwork, стриймвайте песен през Subsonic клиент и запазете playlist. Записвайте logs и measurements за времето за сканиране на библиотеката, CPU при transcoding, кеша с artwork, concurrent streams и disk throughput. Тези данни се превръщат в първата доказано работеща архитектура и правят последващото преместване между compute в Dockup и прикачен сървър проверимо.

TLS е лесен; генерираните URL адреси — не

Задайте ND_BASEURL при обслужване от subpath; в противен случай предпочитайте отделен HTTPS host. Насочете избрания hostname към container port 4533, препратете оригиналния host и HTTPS scheme и не публикувайте втори директен origin.

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

Пет проверки, по-надеждни от health състоянието на контейнера

Преди да се появят реални потребители, създайте release worksheet за Navidrome. В него трябва да са посочени pinned image, порт 4533, canonical origin, persistent paths и собственикът на mount на музикална библиотека само за четене плюс writable application data. Добавете очаквания резултат от тази транзакция: сканиране на музикална библиотека само за четене, проверка на metadata и artwork, стриймване на песен през Subsonic клиент и запазване на playlist.

Използвайте worksheet-а след стандартен replacement и след clean restore. Възстановяването се приема само ако потребителите, playlist-ите, историята на възпроизвеждане и metadata се върнат и същият Subsonic клиент стриймва позната песен. Съберете и кратък resource trace, включващ времето за сканиране на библиотеката, CPU при transcoding, кеша с artwork, concurrent streams и disk throughput; съхранявайте го заедно с release-а, за да сравнявате бъдещите промени в capacity със същото workload.

Включете един контролиран отказ: изпратете безвреден input близо до resource или format limit, свързан с тази граница: сканирането не открива файлове, защото пътят към музиката на хоста е монтиран неправилно. Потвърдете, че Navidrome отчита проблема на правилната граница, върнете валидното състояние и изпълнете транзакцията отново. Така проверявате видимостта на грешките, а не само успеха, и предотвратявате прикриването на повреден worker, callback или database connection от интерфейс, който изглежда здрав.

Логове, които отговарят на следващия въпрос

Използвайте „сканиране на музикална библиотека само за четене, проверка на metadata и artwork, стриймване на песен през Subsonic клиент и запазване на playlist“ като smoke test на Navidrome след всяко deployment. Съпътстващите metrics са времето за сканиране на библиотеката, CPU при transcoding, кешът с artwork, concurrent streams и disk throughput; настройте alert-и там, където тези ресурси се доближават до ниво, което влошава потребителското действие.

Основният риск при промени е, че database migrations и поведението на scanner-а на Navidrome трябва да се тестват, докато оригиналните музикални файлове остават недокоснати. Безопасният release започва от възстановим snapshot и валидира всяка еднопосочна промяна на състоянието, преди да насочи traffic към нея. Когато сканирането не открива файлове, защото пътят към музиката на хоста е монтиран неправилно, оставете неуспешния контейнер достатъчно дълго, за да прочетете конфигурацията му и първата грешка.

Не давайте на Navidrome целия хост

Затворете bootstrap прозореца веднага щом съществува първият доверен администратор. Конкретният капан при Navidrome е монтирането на музикалната библиотека с права за запис без основателна причина; по-безопасната граница е музиката да се монтира само за четене, акаунтите да бъдат защитени и да се изложи само streaming услугата, а не библиотеката на хоста.

ND_BASEURL е конфигурация, а не secret; поддържайте стойността му изрично зададена, като защитите отделните credentials, използвани от Navidrome. Private networking трябва да пренася credentials на зависимостите, а roles вътре в Navidrome трябва да предоставят минимално необходимото действие. Не записвайте чувствителни request bodies и provider responses в стандартните logs.

Поддържайте Navidrome изричен, докато Dockup управлява routing-а

Routing, сертификатите, replacement-ът на услугата и прикаченото storage са разумни цели за automation. Dockup управлява тези компоненти за Navidrome и може да provision-не свързаната managed database или да се свърже с услуги на собствения сървър на клиента.

Това, което не бива да измисля, е trust policy на Navidrome. След deployment задайте ND_BASEURL при обслужване от subpath; в противен случай предпочитайте отделен HTTPS host, приложете тази граница — монтирайте музиката само за четене, защитете акаунтите и излагайте само streaming услугата, а не библиотеката на хоста — и проверете резултата от този сценарий: сканирайте музикална библиотека само за четене, проверете metadata и artwork, стриймвайте песен през Subsonic клиент и запазете playlist. Резултатът е one-click инфраструктура с application-specific acceptance test.

Често задавани въпроси

Какво е необходимо на Navidrome за deployment в production среда?

Насочете контейнера на Navidrome през порт 4533 към един HTTPS origin. Изискването към локалния runtime е mount на музикална библиотека само за четене плюс writable application data. Не обявявайте Navidrome за готов, докато не можете да сканирате музикална библиотека само за четене, да проверите metadata и artwork, да стриймвате песен през Subsonic клиент и да запазите playlist.

Кои данни на Navidrome трябва да бъдат включени в backup?

Направете /data persistent и включете базата данни на Navidrome, кеша с artwork, playlist-ите и оригиналната музикална библиотека в един и същ recovery manifest. Чистият restore на Navidrome е успешен само когато потребителите, playlist-ите, историята на възпроизвеждане и metadata се върнат и същият Subsonic клиент стриймва позната песен.

Изисква ли Navidrome HTTPS зад reverse proxy?

Използвайте HTTPS за публичния Navidrome origin и оставете порт 4533 във вътрешния route. Приложете настройката на Navidrome правилно: задайте ND_BASEURL при обслужване от subpath; в противен случай предпочитайте отделен HTTPS host. При Navidrome HTTPS защитава credentials или потребителско съдържание при пренос и поддържа последователно поведението на клиента, зависещо от origin.

Как трябва да се тества upgrade на Navidrome?

Възстановете текущото състояние на Navidrome в изолирано deployment, приложете кандидат-версията и повторете acceptance транзакцията. Обърнете специално внимание, защото database migrations и поведението на scanner-а на Navidrome трябва да се тестват, докато оригиналните музикални файлове остават недокоснати. Запазете предишния Navidrome image, докато не изясните границите на data migration и rollback.