Så självhostar du Verdaccio 2026: npm-autentisering, lagring och TLS

Att självhosta Verdaccio blir intressant vid den första ominstallationen, inte vid det första docker run. Om npm-klienter skickar autentiseringsuppgifter till en annan värd eller om paketslagringen är skrivskyddad kan Docker fortfarande rapportera en helt frisk process. Distributionen nedan är organiserad kring observerbart beteende: logga in med npm, publicera ett scoped-paket, installera det från ett rent projekt och bekräfta att ett uppströms-paket har cachats.

Verdaccios avsedda användning är tydlig: ett privat npm-register för interna paket. Den beskrivningen visar vad som måste vara publikt, vad som bör förbli privat och vad en säkerhetskopia måste kunna återskapa.

Portar, processer och privata tjänster

Ett användbart Verdaccio-diagram visar den publika routen, den privata porten 4873, tillståndsgränsen och alla stödkrav. Markera vilka pilar som överför autentiseringsuppgifter och vilka som är vanlig användartrafik. Verdaccios nätverkskontrakt består av beständig konfiguration, htpasswd-lagring och valfri objektlagring. Håll privata endpoints på intern DNS, tillåt endast nödvändiga utgående anrop och ge Verdaccio en avgränsad tjänsteautentisering.

Bevisa diagrammet med en verklig åtgärd: logga in med npm, publicera ett scoped-paket, installera det från ett rent projekt och bekräfta att ett uppströms-paket har cachats. Den sannolika belastningen kommer från lagring av tarballs, metadataoperationer, samtidiga installationer och fördröjning till konfigurerade uppströmsregister. Övervaka därför den vägen i stället för att behandla alla HTTP-anrop som likvärdiga.

Gör det lokala kommandot till en inspekterbar tjänst

Använd ett kommando som exponerar alla viktiga val. Den här baslinjen binder Verdaccio till loopback på värden, lägger till de kända datamountarna och anger den första obligatoriska inställningen. Lägg till de granskade anslutningsinställningarna för beständig konfiguration, htpasswd-lagring och valfri objektlagring. Använd privata namn för privata tjänster.

docker run -d \
  --name verdaccio \
  --restart unless-stopped \
  -p 127.0.0.1:4873:4873 \
  -v verdaccio-data:/verdaccio/storage \
  -e VERDACCIO_PUBLIC_URL=https://app.example.com \
  verdaccio/verdaccio:latest

Ersätt flytande taggar med en testad version eller digest. Efter starten granskar du docker logs --tail 200 verdaccio och bekräftar att processen lyssnar på 4873. Kör sedan Verdaccios acceptanstest. Ett svar från startsidan kan inte bevisa att hela scenariot fungerar: logga in med npm, publicera ett scoped-paket, installera det från ett rent projekt och bekräfta att ett uppströms-paket har cachats.

TLS är enkelt – genererade URL:er är det inte

Ställ in den publika URL:en och npm-registrets URL på samma HTTPS-origin. Skicka det valda värdnamnet till containerns port 4873, vidarebefordra den ursprungliga värden och HTTPS-schemat och undvik att publicera en andra direktorigin.

Testa Verdaccio från en ren extern klient. Separera ingressproblem från den kända applikationsgränsen – npm-klienter skickar autentiseringsuppgifter till en annan värd eller så är paketslagringen skrivskyddad. Ett certifikat-, DNS- eller 502-fel hör till routingen. En begäran som når Verdaccio men misslyckas senare hör till applikationstillstånd, kapacitet eller dess stödkrav. Guiden för TLS med anpassad domän behandlar den första gruppen.

Återställ Verdaccio på en tom värd

För Verdaccio börjar säker distribution med paketens tarballs, metadata, konfiguration och autentiseringsfiler. Montera /verdaccio/storage före bootstrap, skriv ofarliga exempeldata och ersätt containern för att bevisa att sökvägen faktiskt är beständig. Testa sökvägen genom att ersätta containern medan ofarliga exempeldata finns kvar. Då upptäcks mountningar som pekar en katalog för högt eller lågt.

Testa sedan katastrofåterställning på en tom värd. Använd vid behov en applikationskonsistent databasexport och verifiera att privata tarballs, metadata, användare och konfiguration återkommer och att det rena projektet installerar samma paket med samma integritet. Guiden om databassäkerhetskopior som har återställts ger ett starkare mål än att bara kontrollera att en arkivfil skapades.

Autentiseringsuppgifter, roller och exponerade ytor

För Verdaccio är den värdefulla ytan inte nödvändigtvis startsidan. Det vanligaste misstaget är att tillåta anonym publicering eller använda en skrivbar uplink-konfiguration. Motverka det medvetet: neka anonym publicering, begränsa maintainers och se till att npm-autentiseringen är knuten till exakt rätt HTTPS-registervärd.

VERDACCIO_PUBLIC_URL är konfiguration, inte en hemlighet. Håll värdet tydligt och skydda samtidigt de separata autentiseringsuppgifter som Verdaccio använder. Använd en containeranvändare utan privilegier när imagen stöder det och montera inga orelaterade autentiseringsuppgifter. Tillämpa hastighets- eller storleksbegränsningar i ingressen där opålitlig trafik kan förbruka lagring för tarballs, metadataoperationer, samtidiga installationer och fördröjning till konfigurerade uppströmsregister.

Felövningar för Verdaccio

Kapacitetstester ska belasta lagring av tarballs, metadataoperationer, samtidiga installationer och fördröjning till konfigurerade uppströmsregister – inte bara upprepade anrop till /. Kör scenariot ”logga in med npm, publicera ett scoped-paket, installera det från ett rent projekt och bekräfta att ett uppströms-paket har cachats” med realistisk samtidighet och registrera fördröjning, felfrekvens och lagringstillväxt.

Planeringen av uppgraderingar måste ta hänsyn till följande risk: konfigurationssyntax, autentiseringsplugins och paketmetadata ska testas mot den avsedda huvudversionen av Verdaccio. Testa den nya versionen med representativa indata, kör sedan acceptanstransaktionen igen och jämför resultatet. Om npm-klienter skickar autentiseringsuppgifter till en annan värd eller om paketslagringen är skrivskyddad ska du fånga den misslyckade transaktionen och granska den första berörda gränsen i stället för att anta att ingressen är ansvarig.

Bevisa Verdaccio-distributionen från början till slut

Gör inte den första användartrafiken till Verdaccios acceptanstest. Förbered ofarligt exempeldata och kör hela åtgärden ”logga in med npm, publicera ett scoped-paket, installera det från ett rent projekt och bekräfta att ett uppströms-paket har cachats”. Anteckna den exakta publika URL:en, resultatet, image-referensen och det loggintervall som hör till körningen.

Ersätt containern och upprepa utan att bygga om data. Återställ därefter till en tom värd. Återställningsvillkoret är att privata tarballs, metadata, användare och konfiguration kommer tillbaka och att det rena projektet installerar samma paket med samma integritet. Observera lagring av tarballs, metadataoperationer, samtidiga installationer och fördröjning till konfigurerade uppströmsregister vid varje körning och definiera en alert kring försämring av transaktionen i stället för kring mätvärden för en inaktiv container.

En sista kontroll ska medvetet misslyckas: neka tillfälligt testidentiteten åtkomst till beständig konfiguration, htpasswd-lagring och valfri objektlagring. Kontrollera att det resulterande Verdaccio-meddelandet identifierar den relevanta gränsen i stället för att utlösa dataradering eller en oändlig omstart. Återställ det giltiga tillståndet och bekräfta att samma exempeltransaktion lyckas. Behåll den här korta övningen i releasechecklistan.

Håll Verdaccio tydligt medan Dockup hanterar routing

För Verdaccio kan Dockup skapa routen och TLS-certifikatet, bevara mountningar, leverera hemligheter och placera beständig konfiguration, htpasswd-lagring och valfri objektlagring i privata nätverk vid distribution till antingen Dockup eller anslutna servrar.

Releasegrinden är fortfarande den konkreta Verdaccio-transaktionen: logga in med npm, publicera ett scoped-paket, installera det från ett rent projekt och bekräfta att ett uppströms-paket har cachats. Verifiera också återställningsvillkoret – att privata tarballs, metadata, användare och konfiguration kommer tillbaka och att det rena projektet installerar samma paket med samma integritet. Dessa två kontroller visar om distributionen fungerar och om den går att återställa.

Vanliga frågor

Vad behöver Verdaccio för en produktionsdistribution?

Routa Verdaccio-containern på port 4873 genom en enda HTTPS-origin. Nätverkskravet för stöd består av beständig konfiguration, htpasswd-lagring och valfri objektlagring. Anse inte Verdaccio vara klart förrän du kan logga in med npm, publicera ett scoped-paket, installera det från ett rent projekt och bekräfta att ett uppströms-paket har cachats.

Vilka Verdaccio-data ska ingå i en säkerhetskopia?

Gör /verdaccio/storage beständig och inkludera paketens tarballs, metadata, konfiguration och autentiseringsfiler i samma återställningsmanifest. En ren Verdaccio-återställning är godkänd först när privata tarballs, metadata, användare och konfiguration kommer tillbaka och det rena projektet installerar samma paket med samma integritet.

Kräver Verdaccio HTTPS bakom en reverse proxy?

Använd HTTPS för den publika Verdaccio-originen och behåll port 4873 i den interna routen. Tillämpa Verdaccio-inställningen korrekt: ställ in den publika URL:en och npm-registrets URL på samma HTTPS-origin. För Verdaccio skyddar HTTPS autentiseringsuppgifter eller användarinnehåll under överföringen och gör klientbeteendet som är känsligt för origin konsekvent.

Hur ska en Verdaccio-uppgradering testas?

Återställ det aktuella Verdaccio-tillståndet till en isolerad distribution, tillämpa kandidatversionen och kör dess acceptanstransaktion igen. Var särskilt uppmärksam eftersom konfigurationssyntax, autentiseringsplugins och paketmetadata ska testas mot den avsedda huvudversionen av Verdaccio. Behåll den tidigare Verdaccio-imagen tills gränserna för datamigrering och rollback är förstådda.