Jak hostować Navidrome samodzielnie w 2026 roku: montowanie muzyki, skanowanie i aplikacje Subsonic

Jeśli próbujesz już hostować Navidrome samodzielnie, prawdopodobnie znasz ten frustrujący stan: interfejs się wyświetla, ale skanowanie nie znajduje żadnych plików, ponieważ ścieżka z muzyką na hoście została nieprawidłowo zamontowana. Ponowne utworzenie kontenera rzadko naprawia rozbieżności między adresami URL, stanem i zależnościami.

W tym poradniku przyjmujemy jeden konkretny warunek ukończenia — zeskanowanie biblioteki muzycznej w trybie tylko do odczytu, weryfikację metadanych i okładek, odtworzenie utworu za pomocą klienta Subsonic oraz zapisanie playlisty. Każdy wybór konfiguracyjny oceniamy względem tego kryterium, a nie na podstawie zielonej ikony statusu kontenera.

Twórz backup stanu, którego Navidrome nie potrafi odtworzyć

Zdefiniuj punkt i czas odtworzenia dla Navidrome, uwzględniając bazę danych Navidrome, cache okładek, playlisty oraz oryginalną bibliotekę muzyczną. Zamontuj /data przed bootstrapem, zapisz nieszkodliwe przykładowe dane i podmień kontener, aby potwierdzić, że ta ścieżka jest rzeczywiście trwała. Named volume zapewnia trwałość po ponownym wdrożeniu, ale nie chroni przed przejęciem systemu ani utratą serwera.

Przygotuj czyste środowisko odtwarzania, użyj tej samej przypiętej wersji aplikacji i potwierdź, że wracają użytkownicy, playlisty, historia odtwarzania i metadane oraz że ten sam klient Subsonic odtwarza znany utwór. Zapisz polecenia, poprawki uprawnień i czas wykonania. Poradnik backupów przedstawia przydatny standard: backup jest wiarygodny po odtworzeniu, a nie po przesłaniu.

Uruchom Navidrome bez ukrywania istotnych elementów

Traktuj kontener jako wymienny runtime, a nie jako źródło prawdy.

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

Przed udostępnieniem usługi potwierdź lokalne wymaganie: montowanie biblioteki muzycznej tylko do odczytu oraz zapisywalne dane aplikacji. Sprawdź użytkownika kontenera, ścieżki z prawem zapisu i nasłuchujący listener przed wystawieniem usługi. Wykonaj pełną operację — zeskanuj bibliotekę muzyczną tylko do odczytu, zweryfikuj metadane i okładki, odtwórz utwór za pomocą klienta Subsonic i zapisz playlistę — oraz zachowaj dokładne odwołanie do obrazu, który dał ten rezultat.

Wybierz najmniejszą użyteczną topologię Navidrome

Zacznij od network namespace Navidrome: jego web listener działa na porcie 4533, a nie na porcie hosta skopiowanym z poradnika dotyczącego laptopa. Lokalne wymaganie runtime'u to montowanie biblioteki muzycznej tylko do odczytu oraz zapisywalne dane aplikacji. Zapisz je obok obrazu i portu, aby zastępczy host otrzymał te same możliwości lokalne.

Po spełnieniu wymagania uruchom pełny scenariusz — zeskanuj bibliotekę muzyczną tylko do odczytu, zweryfikuj metadane i okładki, odtwórz utwór za pomocą klienta Subsonic i zapisz playlistę. Zapisz logi i pomiary czasu skanowania biblioteki, użycia CPU podczas transkodowania, cache okładek, liczby równoczesnych streamów oraz przepustowości dysku. Te dane staną się pierwszą sprawdzoną architekturą i umożliwią testowanie późniejszych przenosin między infrastrukturą obliczeniową Dockup a podłączonym serwerem.

TLS jest proste — problemem są generowane adresy URL

Ustaw ND_BASEURL, gdy usługa jest serwowana z podścieżki; w przeciwnym razie preferuj dedykowany host HTTPS. Przekazuj wybraną nazwę hosta do portu kontenera 4533, przekazuj oryginalny host i schemat HTTPS oraz unikaj publikowania drugiego bezpośredniego originu.

Przetestuj Navidrome z czystego zewnętrznego klienta. Oddziel awarię ingressu od znanej granicy aplikacji — skanowanie nie znajduje żadnych plików, ponieważ ścieżka z muzyką na hoście została nieprawidłowo zamontowana. Błąd certyfikatu, DNS lub 502 należy do routingu; żądanie, które dociera do Navidrome i kończy się błędem później, dotyczy stanu aplikacji, jej wydajności lub wymaganej zależności. Poradnik dotyczący TLS dla własnej domeny obejmuje pierwszą grupę problemów.

Pięć testów skuteczniejszych niż health check kontenera

Przed pojawieniem się rzeczywistych użytkowników przygotuj checklistę wydania dla Navidrome. Musi ona zawierać przypięty obraz, port 4533, kanoniczny origin, trwałe ścieżki oraz właściciela montowania biblioteki muzycznej tylko do odczytu i zapisywalnych danych aplikacji. Dołącz oczekiwany rezultat tej transakcji: zeskanowanie biblioteki muzycznej tylko do odczytu, weryfikację metadanych i okładek, odtworzenie utworu za pomocą klienta Subsonic oraz zapisanie playlisty.

Użyj checklisty po zwykłej podmianie oraz po czystym odtworzeniu. Odzyskiwanie uznaje się za zakończone powodzeniem tylko wtedy, gdy wracają użytkownicy, playlisty, historia odtwarzania i metadane, a ten sam klient Subsonic odtwarza znany utwór. Zbierz również krótki ślad zasobów obejmujący czas skanowania biblioteki, użycie CPU podczas transkodowania, cache okładek, liczbę równoczesnych streamów i przepustowość dysku; przechowuj go obok wydania, aby przyszłe zmiany wydajności porównywać przy tym samym obciążeniu.

Uwzględnij jedną kontrolowaną awarię: prześlij nieszkodliwe dane wejściowe w pobliżu limitu zasobów lub formatu związanego z tą granicą: skanowanie nie znajduje żadnych plików, ponieważ ścieżka z muzyką na hoście została nieprawidłowo zamontowana. Potwierdź, że Navidrome zgłasza problem na właściwej granicy, przywróć prawidłowy warunek i ponownie wykonaj transakcję. Pozwala to sprawdzić widoczność błędów, a nie tylko sukces, i zapobiega sytuacji, w której zdrowo wyglądający interfejs ukrywa uszkodzonego workera, callback lub połączenie z bazą danych.

Logi, które odpowiadają na następne pytanie

Po każdym wdrożeniu użyj jako smoke testu Navidrome operacji: zeskanuj bibliotekę muzyczną tylko do odczytu, zweryfikuj metadane i okładki, odtwórz utwór za pomocą klienta Subsonic oraz zapisz playlistę. Powiązane metryki to czas skanowania biblioteki, użycie CPU podczas transkodowania, cache okładek, liczba równoczesnych streamów i przepustowość dysku; ustaw alerty tam, gdzie te zasoby zbliżają się do poziomu pogarszającego działanie użytkownika.

Główne ryzyko zmiany polega na tym, że migracje bazy danych Navidrome i działanie skanera należy testować, pozostawiając oryginalne pliki muzyczne nietknięte. Bezpieczne wydanie zaczyna się od snapshotu możliwego do odtworzenia i obejmuje weryfikację każdej jednokierunkowej zmiany stanu przed przekierowaniem ruchu. Gdy skanowanie nie znajduje żadnych plików, ponieważ ścieżka z muzyką na hoście została nieprawidłowo zamontowana, pozostaw uszkodzony kontener wystarczająco długo, aby odczytać jego konfigurację i pierwszy błąd.

Nie udostępniaj Navidrome całego hosta

Zamknij okno bootstrapu, gdy tylko pojawi się pierwszy zaufany administrator. Konkretną pułapką w Navidrome jest montowanie biblioteki muzycznej z prawem zapisu bez uzasadnionej przyczyny; bezpieczniejsza granica to montowanie muzyki tylko do odczytu, ochrona kont oraz udostępnianie wyłącznie usługi streamingu, a nie biblioteki hosta.

ND_BASEURL jest konfiguracją, a nie sekretem; jego wartość powinna być jawna, natomiast osobne dane uwierzytelniające używane przez Navidrome należy chronić. Prywatna sieć powinna przenosić dane uwierzytelniające zależności, a role w Navidrome powinny przyznawać najmniejszy użyteczny zakres działań. Nie zapisuj poufnych treści żądań ani odpowiedzi dostawców w standardowych logach.

Zachowaj jawność konfiguracji Navidrome, a routing powierz Dockup

Routing, certyfikaty, podmiana usług i podłączona pamięć masowa to rozsądne cele automatyzacji. Dockup obsługuje je dla Navidrome i może provisionować powiązaną zarządzaną bazę danych lub łączyć się z usługami działającymi na własnym serwerze klienta.

Nie powinien jednak wymyślać zasad zaufania Navidrome. Po wdrożeniu ustaw ND_BASEURL, gdy usługa jest serwowana z podścieżki; w przeciwnym razie preferuj dedykowany host HTTPS, wyegzekwuj tę granicę — montuj muzykę tylko do odczytu, chroń konta i udostępniaj wyłącznie usługę streamingu, a nie bibliotekę hosta — oraz zweryfikuj rezultat tego scenariusza: zeskanuj bibliotekę muzyczną tylko do odczytu, zweryfikuj metadane i okładki, odtwórz utwór za pomocą klienta Subsonic i zapisz playlistę. Rezultatem jest infrastruktura wdrażana jednym kliknięciem z testem akceptacyjnym właściwym dla aplikacji.

Najczęściej zadawane pytania

Czego Navidrome potrzebuje do wdrożenia produkcyjnego?

Przekieruj kontener Navidrome działający na porcie 4533 przez jeden origin HTTPS. Lokalne wymaganie runtime'u to montowanie biblioteki muzycznej tylko do odczytu oraz zapisywalne dane aplikacji. Nie uznawaj Navidrome za gotowe, dopóki nie możesz zeskanować biblioteki muzycznej tylko do odczytu, zweryfikować metadanych i okładek, odtworzyć utworu za pomocą klienta Subsonic oraz zapisać playlisty.

Które dane Navidrome powinny należeć do backupu?

Zachowaj /data i uwzględnij bazę danych Navidrome, cache okładek, playlisty oraz oryginalną bibliotekę muzyczną w tym samym manifeście odtwarzania. Czyste odtworzenie Navidrome kończy się powodzeniem tylko wtedy, gdy wracają użytkownicy, playlisty, historia odtwarzania i metadane, a ten sam klient Subsonic odtwarza znany utwór.

Czy Navidrome wymaga HTTPS za reverse proxy?

Używaj HTTPS dla publicznego originu Navidrome, a port 4533 pozostaw na trasie wewnętrznej. Zastosuj ustawienie Navidrome prawidłowo: ustaw ND_BASEURL, gdy usługa jest serwowana z podścieżki; w przeciwnym razie preferuj dedykowany host HTTPS. W przypadku Navidrome HTTPS chroni dane uwierzytelniające lub treści użytkowników podczas transmisji i zapewnia spójne działanie klienta zależne od originu.

Jak testować aktualizację Navidrome?

Odtwórz bieżący stan Navidrome w izolowanym wdrożeniu, zastosuj wersję kandydującą i ponownie wykonaj transakcję akceptacyjną. Zwróć szczególną uwagę na to, że migracje bazy danych Navidrome i działanie skanera należy testować, pozostawiając oryginalne pliki muzyczne nietknięte. Zachowaj poprzedni obraz Navidrome, dopóki nie poznasz granic migracji danych i rollbacku.