Sådan self-hoster du Navidrome i 2026: Musikmounts, scanninger og Subsonic-apps

Hvis du allerede har prøvet at self-hoste Navidrome, kender du sikkert den frustrerende situation: Brugerfladen vises, men scanningerne finder ingen filer, fordi musikstien på hosten er mountet forkert. At oprette containeren igen løser sjældent en uoverensstemmelse mellem URL'er, state og afhængigheder.

Denne gennemgang bruger ét konkret færdigkriterium — scan et skrivebeskyttet musikbibliotek, verificer metadata og artwork, stream et nummer gennem en Subsonic-klient, og gem en playlist. Hvert konfigurationsvalg vurderes ud fra dette kriterium i stedet for et grønt container-badge.

Tag backup af den state, Navidrome ikke kan genskabe

Definér recovery point og recovery time for Navidrome med udgangspunkt i Navidrome-databasen, artwork-cachen, playlists og det oprindelige musikbibliotek. Mount /data før bootstrap, skriv harmløse eksempeldata, og erstat containeren for at bevise, at stien faktisk er persistent. Et named volume løser persistence ved redeploy; det løser ikke kompromittering eller tab af serveren.

Opbyg et rent restore-miljø, brug den samme fastlåste applikationsversion, og bevis, at brugere, playlists, afspilningshistorik og metadata kommer tilbage, og at den samme Subsonic-klient kan streame et kendt nummer. Registrér kommandoer, rettelser af ejerskab og den forløbne tid. Backupguiden er en nyttig standard: En backup er først betroet efter en restore, ikke efter upload.

Start Navidrome uden at skjule de bevægelige dele

Brug containeren som en udskiftelig runtime, ikke som stedet, hvor sandheden findes.

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

Bekræft det lokale krav, før tjenesten eksponeres: Et skrivebeskyttet musikbiblioteks-mount samt skrivbare applikationsdata. Undersøg containerens bruger, skrivbare stier og bundne listener, før du eksponerer den. Gennemfør hele handlingen — scan et skrivebeskyttet musikbibliotek, verificer metadata og artwork, stream et nummer gennem en Subsonic-klient, og gem en playlist — og gem den nøjagtige image-reference, der gav resultatet.

Vælg den mindst mulige Navidrome-topologi, der fungerer

Start med Navidromes network namespace: Weblisteneren er port 4533, ikke en hostport kopieret fra en laptop-tutorial. Det lokale runtime-krav er et skrivebeskyttet musikbiblioteks-mount samt skrivbare applikationsdata. Registrér det sammen med image og port, så en ny host får den samme lokale funktionalitet.

Når kravet er opfyldt, skal du gennemføre det komplette scenarie — scan et skrivebeskyttet musikbibliotek, verificer metadata og artwork, stream et nummer gennem en Subsonic-klient, og gem en playlist. Registrér logs og målinger for scanningstid for biblioteket, CPU-forbrug ved transcoding, artwork-cache, samtidige streams og disk-gennemløb. Disse data bliver den første kendte gode arkitektur og gør senere flytninger mellem Dockup compute og en tilsluttet server testbare.

TLS er nemt; genererede URL'er er ikke

Indstil ND_BASEURL ved servering fra en substi; ellers bør du foretrække en dedikeret HTTPS-host. Send det valgte hostname til containerens port 4533, videresend den oprindelige host og HTTPS-scheme, og undgå at publicere en ekstra direkte origin.

Test Navidrome fra en ren ekstern klient. Adskil ingress-fejl fra den kendte applikationsgrænse — scanninger finder ingen filer, fordi musikstien på hosten er mountet forkert. En certifikat-, DNS- eller 502-fejl hører til routing; en request, der når frem til Navidrome og fejler senere, hører til applikations-state, kapacitet eller den understøttende forudsætning. Guiden til TLS med custom domain dækker den første gruppe.

Fem checks, der er stærkere end containerens health status

Før de rigtige brugere kommer til, skal du lave et release-ark for Navidrome. Det skal angive det fastlåste image, port 4533, den kanoniske origin, persistente stier og ejeren af et skrivebeskyttet musikbiblioteks-mount samt skrivbare applikationsdata. Vedlæg det forventede resultat af denne transaktion: Scan et skrivebeskyttet musikbibliotek, verificer metadata og artwork, stream et nummer gennem en Subsonic-klient, og gem en playlist.

Brug arket efter en normal udskiftning og efter en ren restore. Recovery accepteres kun, hvis brugere, playlists, afspilningshistorik og metadata kommer tilbage, og den samme Subsonic-klient kan streame et kendt nummer. Indsaml også et kort ressource-trace, der dækker scanningstid for biblioteket, CPU-forbrug ved transcoding, artwork-cache, samtidige streams og disk-gennemløb; gem det sammen med releaset, så fremtidige kapacitetsændringer sammenlignes med den samme workload.

Inkludér én kontrolleret fejl: Indsend harmløst input tæt på den ressource- eller formatgrænse, der er knyttet til denne grænse: Scanninger finder ingen filer, fordi musikstien på hosten er mountet forkert. Bekræft, at Navidrome rapporterer problemet ved den korrekte grænse, gendan den gyldige tilstand, og kør transaktionen igen. Det tester synligheden af fejl, ikke kun succes, og forhindrer, at en interface, der ser sund ud, skjuler en ødelagt worker, callback eller databaseforbindelse.

Logs, der besvarer det næste spørgsmål

Brug scanning af et skrivebeskyttet musikbibliotek, verificering af metadata og artwork, streaming af et nummer gennem en Subsonic-klient samt lagring af en playlist som Navidromes smoke test efter hver deployment. De understøttende metrics er scanningstid for biblioteket, CPU-forbrug ved transcoding, artwork-cache, samtidige streams og disk-gennemløb; sæt alarmer der, hvor ressourcerne nærmer sig et punkt, som forringer brugerhandlingen.

Den største ændringsrisiko er, at Navidromes databasemigrationer og scanneradfærd bør testes, mens de oprindelige musikfiler forbliver urørte. Et sikkert release starter fra et snapshot, der kan gendannes, og validerer alle irreversible stateændringer, før trafikken flyttes. Når scanninger finder ingen filer, fordi musikstien på hosten er mountet forkert, skal du beholde den fejlede container længe nok til at læse dens konfiguration og første fejl.

Giv ikke Navidrome hele hosten

Luk bootstrap-vinduet, så snart den første betroede administrator findes. Navidromes konkrete faldgrube er at mounte musikbiblioteket med skriveadgang uden en grund; den sikrere grænse er at mounte musik skrivebeskyttet, beskytte konti og kun eksponere streamingtjenesten i stedet for hostens bibliotek.

ND_BASEURL er konfiguration og ikke en hemmelighed; hold værdien eksplicit, mens de separate credentials, som Navidrome bruger, beskyttes. Private netværk bør transportere credentials til afhængigheder, og roller i Navidrome bør kun give den mindst mulige nyttige handling. Hold følsomme request bodies og svar fra providers ude af almindelige logs.

Hold Navidrome eksplicit, mens Dockup håndterer routing

Routing, certifikater, serviceudskiftning og tilknyttet storage er fornuftige mål for automatisering. Dockup håndterer dette for Navidrome og kan provisionere den tilhørende managed database eller oprette forbindelse til services på kundens egen server.

Det, tjenesten ikke bør opfinde, er Navidromes trust policy. Efter deployment skal du indstille ND_BASEURL ved servering fra en substi; ellers bør du foretrække en dedikeret HTTPS-host, håndhæve denne grænse — mount musik skrivebeskyttet, beskyt konti, og eksponér kun streamingtjenesten i stedet for hostens bibliotek — og verificere resultatet af dette scenarie: Scan et skrivebeskyttet musikbibliotek, verificer metadata og artwork, stream et nummer gennem en Subsonic-klient, og gem en playlist. Resultatet er infrastruktur med ét klik og en applikationsspecifik accepttest.

Ofte stillede spørgsmål

Hvad har Navidrome brug for i en produktionsdeployment?

Route Navidrome-containeren på port 4533 gennem én HTTPS-origin. Det lokale runtime-krav er et skrivebeskyttet musikbiblioteks-mount samt skrivbare applikationsdata. Kald ikke Navidrome klar, før du kan scanne et skrivebeskyttet musikbibliotek, verificere metadata og artwork, streame et nummer gennem en Subsonic-klient og gemme en playlist.

Hvilke Navidrome-data hører hjemme i en backup?

Persistér /data, og inkludér Navidrome-databasen, artwork-cachen, playlists og det oprindelige musikbibliotek i det samme recovery-manifest. En ren Navidrome-restore er kun godkendt, når brugere, playlists, afspilningshistorik og metadata kommer tilbage, og den samme Subsonic-klient kan streame et kendt nummer.

Kræver Navidrome HTTPS bag en reverse proxy?

Brug HTTPS til den offentlige Navidrome-origin, og hold port 4533 på den interne route. Anvend Navidrome-indstillingen korrekt: Indstil ND_BASEURL ved servering fra en substi; ellers bør du foretrække en dedikeret HTTPS-host. For Navidrome beskytter HTTPS credentials eller brugerindhold under transport og sikrer ensartet klientadfærd, der afhænger af origin.

Hvordan bør en Navidrome-opgradering testes?

Gendan den aktuelle Navidrome-state i en isoleret deployment, anvend kandidatversionen, og gentag dens accepttransaktion. Vær særligt opmærksom, fordi Navidromes databasemigrationer og scanneradfærd bør testes, mens de oprindelige musikfiler forbliver urørte. Behold det tidligere Navidrome-image, indtil grænsen for datamigration og rollback er forstået.