Cum să găzduiești singur Navidrome în 2026: mount-uri pentru muzică, scanări și aplicații Subsonic

Dacă ai încercat deja să faci self-hosting pentru Navidrome, probabil îți este familiară situația frustrantă: interfața apare, dar scanările nu găsesc niciun fișier deoarece path-ul către muzică de pe host este montat incorect. Recrearea containerului rezolvă rareori o neconcordanță între URL-uri, state și dependențe.

Acest ghid folosește un singur criteriu concret de finalizare — scanarea unei biblioteci muzicale read-only, verificarea metadatelor și a artwork-ului, redarea unei melodii printr-un client Subsonic și salvarea unui playlist. Fiecare alegere de configurare este evaluată în funcție de acest criteriu, nu în funcție de un badge verde al containerului.

Fă backup pentru starea pe care Navidrome nu o poate recrea

Definește punctul și timpul de recuperare pentru Navidrome în funcție de baza de date Navidrome, cache-ul de artwork, playlist-uri și biblioteca muzicală originală. Montează /data înainte de bootstrap, scrie date de test inofensive și înlocuiește containerul pentru a demonstra că path-ul este într-adevăr persistent. Un named volume rezolvă persistența la redeploy; nu rezolvă însă compromiterea sau pierderea serverului.

Construiește un mediu curat de restore, folosește aceeași versiune fixată a aplicației și demonstrează că utilizatorii, playlist-urile, istoricul redărilor și metadatele revin, iar același client Subsonic poate reda o melodie cunoscută. Notează comenzile, remedierile de ownership și timpul scurs. Ghidul pentru backup-uri oferă un standard util: un backup este considerat de încredere după restaurare, nu după upload.

Pornește Navidrome fără să ascunzi componentele importante

Folosește containerul ca runtime înlocuibil, nu ca sursă a adevărului.

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

Confirmă cerința locală înainte de expunere: un mount read-only către biblioteca muzicală și date de aplicație care pot fi scrise. Inspectează utilizatorul containerului, path-urile writable și listener-ul configurat înainte de a-l expune. Rulează acțiunea completă — scanează o bibliotecă muzicală read-only, verifică metadatele și artwork-ul, redă o melodie printr-un client Subsonic și salvează un playlist — și păstrează referința exactă a imaginii care a produs rezultatul.

Alege cea mai mică topologie Navidrome viabilă

Începe cu network namespace-ul Navidrome: listener-ul web este pe portul 4533, nu pe un host port copiat dintr-un tutorial pentru laptop. Cerința locală de runtime este un mount read-only către biblioteca muzicală și date de aplicație care pot fi scrise. Noteaz-o alături de imagine și port, astfel încât un host înlocuitor să primească aceeași capabilitate locală.

După ce cerința este îndeplinită, rulează scenariul complet — scanează o bibliotecă muzicală read-only, verifică metadatele și artwork-ul, redă o melodie printr-un client Subsonic și salvează un playlist. Înregistrează logurile și măsurătorile pentru durata scanării bibliotecii, CPU folosit la transcoding, cache-ul de artwork, stream-urile concurente și throughput-ul discului. Aceste dovezi devin prima arhitectură cunoscută ca funcțională și fac testabile mutările ulterioare între compute Dockup și un server atașat.

TLS este simplu; URL-urile generate nu sunt

Setează ND_BASEURL atunci când servești dintr-un subpath; în caz contrar, preferă un host HTTPS dedicat. Trimite hostname-ul ales către portul 4533 al containerului, forwardează host-ul original și schema HTTPS și evită publicarea unei a doua origini directe.

Testează Navidrome dintr-un client extern curat. Separă problemele de ingress de limita cunoscută a aplicației — scanările nu găsesc niciun fișier deoarece path-ul către muzică de pe host este montat incorect. O eroare de certificat, DNS sau 502 ține de routing; o cerere care ajunge la Navidrome și eșuează ulterior ține de state-ul aplicației, capacitate sau de cerința de care aceasta depinde. Ghidul pentru TLS automat cu domeniu personalizat acoperă primul grup.

Cinci verificări mai solide decât health-ul containerului

Înainte să apară utilizatorii reali, creează o fișă de release pentru Navidrome. Aceasta trebuie să specifice imaginea fixată, portul 4533, originea canonicală, path-urile persistente și responsabilul pentru un mount read-only către biblioteca muzicală și date de aplicație care pot fi scrise. Atașează rezultatul așteptat al acestei tranzacții: scanarea unei biblioteci muzicale read-only, verificarea metadatelor și a artwork-ului, redarea unei melodii printr-un client Subsonic și salvarea unui playlist.

Folosește fișa după o înlocuire normală și după un restore curat. Recuperarea este acceptată doar dacă utilizatorii, playlist-urile, istoricul redărilor și metadatele revin, iar același client Subsonic poate reda o melodie cunoscută. Colectează și o scurtă trasare a resurselor, care să acopere durata scanării bibliotecii, CPU folosit la transcoding, cache-ul de artwork, stream-urile concurente și throughput-ul discului; păstreaz-o alături de release, astfel încât viitoarele modificări de capacitate să fie comparate folosind aceeași sarcină.

Include un failure controlat: trimite input inofensiv în apropierea limitei de resurse sau de format asociate acestei limite: scanările nu găsesc niciun fișier deoarece path-ul către muzică de pe host este montat incorect. Confirmă că Navidrome raportează problema la limita corectă, restabilește condiția validă și rulează din nou tranzacția. Astfel verifici vizibilitatea erorilor, nu doar succesul, și previi ca o interfață care pare sănătoasă să ascundă un worker, callback sau o conexiune la baza de date defectă.

Loguri care răspund la următoarea întrebare

Folosește scanarea unei biblioteci muzicale read-only, verificarea metadatelor și a artwork-ului, redarea unei melodii printr-un client Subsonic și salvarea unui playlist drept smoke test pentru Navidrome după fiecare deployment. Măsurătorile asociate sunt durata scanării bibliotecii, CPU folosit la transcoding, cache-ul de artwork, stream-urile concurente și throughput-ul discului; configurează alerte acolo unde aceste resurse se apropie de un nivel care degradează acțiunea utilizatorului.

Principalul risc la schimbare este că migrările bazei de date Navidrome și comportamentul scannerului trebuie testate în timp ce fișierele muzicale originale rămân neatinse. Un release sigur pornește de la un snapshot care poate fi restaurat și validează orice schimbare ireversibilă de state înainte de mutarea traficului. Atunci când scanările nu găsesc niciun fișier deoarece path-ul către muzică de pe host este montat incorect, păstrează containerul eșuat suficient timp pentru a-i citi configurația și prima eroare.

Nu-i oferi lui Navidrome acces la întregul host

Închide fereastra de bootstrap imediat ce există primul administrator de încredere. Capcana concretă în cazul Navidrome este montarea read-write a bibliotecii muzicale fără un motiv justificat; limita mai sigură este să montezi muzica read-only, să protejezi conturile și să expui doar serviciul de streaming, nu biblioteca hostului.

ND_BASEURL este configurație, nu secret; păstrează-i valoarea explicită, protejând în același timp credențialele separate folosite de Navidrome. Rețeaua privată ar trebui să transporte credențialele dependențelor, iar rolurile din Navidrome ar trebui să acorde cel mai mic nivel de acces util. Nu păstra în logurile obișnuite body-urile sensibile ale request-urilor și răspunsurile providerilor.

Păstrează Navidrome explicit, iar Dockup să se ocupe de routing

Routing-ul, certificatele, înlocuirea serviciilor și storage-ul atașat sunt ținte rezonabile pentru automatizare. Dockup se ocupă de acestea pentru Navidrome și poate provisiona baza de date managed asociată sau se poate conecta la servicii de pe serverul propriu al clientului.

Ceea ce nu ar trebui să inventeze este politica de trust a Navidrome. După deployment, setează ND_BASEURL atunci când servești dintr-un subpath; în caz contrar, preferă un host HTTPS dedicat, impune această limită — montează muzica read-only, protejează conturile și expune doar serviciul de streaming, nu biblioteca hostului — și verifică rezultatul acestui scenariu: scanează o bibliotecă muzicală read-only, verifică metadatele și artwork-ul, redă o melodie printr-un client Subsonic și salvează un playlist. Rezultatul este o infrastructură one-click cu un test de acceptanță specific aplicației.

Întrebări frecvente

De ce are nevoie Navidrome pentru un deployment în producție?

Rutează containerul Navidrome pe portul 4533 printr-o singură origine HTTPS. Cerința locală de runtime este un mount read-only către biblioteca muzicală și date de aplicație care pot fi scrise. Nu considera Navidrome pregătit până când nu poți scana o bibliotecă muzicală read-only, verifica metadatele și artwork-ul, reda o melodie printr-un client Subsonic și salva un playlist.

Ce date Navidrome trebuie incluse într-un backup?

Păstrează /data și include baza de date Navidrome, cache-ul de artwork, playlist-urile și biblioteca muzicală originală în același manifest de recuperare. Un restore Navidrome curat este validat doar atunci când utilizatorii, playlist-urile, istoricul redărilor și metadatele revin, iar același client Subsonic poate reda o melodie cunoscută.

Are Navidrome nevoie de HTTPS în spatele unui reverse proxy?

Folosește HTTPS pentru originea publică Navidrome și păstrează portul 4533 pe ruta internă. Aplică corect setarea Navidrome: setează ND_BASEURL atunci când servești dintr-un subpath; în caz contrar, preferă un host HTTPS dedicat. Pentru Navidrome, HTTPS protejează credențialele sau conținutul utilizatorilor în tranzit și păstrează consecvent comportamentul clientului dependent de origine.

Cum trebuie testat un upgrade Navidrome?

Restaurează state-ul curent Navidrome într-un deployment izolat, aplică versiunea candidat și repetă tranzacția de acceptanță. Acordă o atenție deosebită acestui aspect, deoarece migrările bazei de date Navidrome și comportamentul scannerului trebuie testate în timp ce fișierele muzicale originale rămân neatinse. Păstrează imaginea Navidrome anterioară până când limitele migrării datelor și ale rollback-ului sunt înțelese.