Slik selvhoster du Verdaccio i 2026: npm-autentisering, lagring og TLS

Det blir interessant å selvhoste Verdaccio ved den første redeployen, ikke ved den første docker run. Hvis npm-klienter sender autentisering til en annen vert, eller pakkelagringen er skrivebeskyttet, kan Docker fortsatt rapportere en helt frisk prosess. Deployen nedenfor er organisert rundt observerbar atferd: Logg inn med npm, publiser en pakke med scope, installer den fra et rent prosjekt og bekreft at en upstream-pakke er bufret.

Den tiltenkte oppgaven til Verdaccio er tydelig: et privat npm-register for interne pakker. Denne beskrivelsen forteller oss hva som må være offentlig, hva som bør forbli privat, og hva en sikkerhetskopi må kunne gjenopprette.

Porter, prosesser og private tjenester

Et nyttig Verdaccio-diagram viser den offentlige ruten, den private porten 4873, tilstandsgrensen og alle støttende krav. Marker hvilke piler som inneholder påloggingsinformasjon, og hvilke som er vanlig brukertrafikk. Nettverkskontrakten for Verdaccio er persistent konfigurasjon, htpasswd-lagring og valgfri objektlagring. Hold private endepunkter på intern DNS, tillat bare nødvendige utgående kall, og gi Verdaccio en avgrenset tjenestetilgang.

Bevis diagrammet med én reell handling: Logg inn med npm, publiser en pakke med scope, installer den fra et rent prosjekt og bekreft at en upstream-pakke er bufret. Den sannsynlige belastningen kommer fra lagring av tarballer, metadataoperasjoner, samtidige installasjoner og forsinkelse til konfigurerte upstream-registre. Overvåk denne banen i stedet for å behandle alle HTTP-forespørsler som like.

Gjør den lokale kommandoen til en tjeneste du kan inspisere

Bruk en kommando som synliggjør alle viktige valg. Denne grunnkonfigurasjonen binder Verdaccio til loopback på verten, legger til de kjente datamontingene og angir den første nødvendige innstillingen. Legg til de gjennomgåtte tilkoblingsinnstillingene for persistent konfigurasjon, htpasswd-lagring og valgfri objektlagring. Bruk private navn for private tjenester.

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

Bytt ut flytende tagger med en testet versjon eller digest. Etter oppstart inspiserer du docker logs --tail 200 verdaccio og bekrefter at prosessen lytter på 4873. Kjør deretter Verdaccios akseptansetest. Et svar fra rotsiden kan ikke bevise at hele scenarioet lykkes: Logg inn med npm, publiser en pakke med scope, installer den fra et rent prosjekt og bekreft at en upstream-pakke er bufret.

TLS er enkelt – genererte URL-er er ikke

Sett den offentlige URL-en og npm-registerets URL til samme HTTPS-opprinnelse. Send det valgte vertsnavnet til containerport 4873, videresend den opprinnelige verten og HTTPS-skjemaet, og unngå å publisere en ekstra direkte opprinnelse.

Test Verdaccio fra en ren ekstern klient. Skill mellom feil i ingressen og den kjente applikasjonsgrensen – npm-klienter sender autentisering til en annen vert, eller pakkelagringen er skrivebeskyttet. En sertifikat-, DNS- eller 502-feil hører til rutingen. En forespørsel som når Verdaccio og feiler senere, hører til applikasjonstilstand, kapasitet eller et støttende krav. Guiden for TLS med egendefinert domene dekker den første gruppen.

Gjenopprett Verdaccio på en tom vert

For Verdaccio starter sikker redeploy med pakkens tarballer, metadata, konfigurasjon og autentiseringsfiler. Monter /verdaccio/storage før bootstrap, skriv ufarlige eksempeldata og erstatt containeren for å bevise at banen faktisk er persistent. Test banen ved å erstatte containeren mens ufarlige eksempeldata fortsatt finnes. Dette avdekker monteringer som peker én katalog for høyt eller lavt.

Test deretter disaster recovery på en tom vert. Bruk en applikasjonskonsistent databaseeksport når det er nødvendig, og bekreft at private tarballer, metadata, brukere og konfigurasjon kommer tilbake, og at det rene prosjektet installerer samme pakkeintegritet. Guiden for databasebackup som er testet gjennom gjenoppretting gir et sterkere mål enn bare å kontrollere at en arkivfil ble opprettet.

Påloggingsinformasjon, roller og eksponerte flater

For Verdaccio er den verdifulle overflaten ikke nødvendigvis landingssiden. Den vanligste feilen er å tillate anonym publisering eller å bruke en skrivbar uplink-konfigurasjon. Motvirk dette bevisst: nekt anonym publisering, avgrens vedlikeholdere, og sørg for at npm-autentiseringen er knyttet til nøyaktig HTTPS-registervert.

VERDACCIO_PUBLIC_URL er konfigurasjon, ikke en hemmelighet. Hold verdien eksplisitt, samtidig som du beskytter den separate påloggingsinformasjonen Verdaccio bruker. Bruk en containerbruker uten privilegier når imaget støtter det, og monter ingen uvedkommende påloggingsinformasjon. Legg rate- eller størrelsesbegrensninger i ingressen der ukontrollert arbeid kan forbruke tarball-lagring, metadataoperasjoner, samtidige installasjoner og forsinkelse til konfigurerte upstream-registre.

Feilsimuleringer for Verdaccio

Kapasitetstester bør belaste tarball-lagring, metadataoperasjoner, samtidige installasjoner og forsinkelse til konfigurerte upstream-registre – ikke sende gjentatte forespørsler til /. Kjør scenarioet «Logg inn med npm, publiser en pakke med scope, installer den fra et rent prosjekt og bekreft at en upstream-pakke er bufret» med realistisk samtidighet, og registrer forsinkelse, feilrate og vekst i lagringsforbruk.

Oppgraderingsplanleggingen må ta høyde for denne risikoen: konfigurasjonssyntaks, autentiseringsplugins og pakkemetadata bør testes mot den aktuelle hovedversjonen av Verdaccio. Test den nye utgaven med representative inndata, kjør deretter akseptansetransaksjonen på nytt og sammenlign resultatet. Hvis npm-klienter sender autentisering til en annen vert, eller pakkelagringen er skrivebeskyttet, må du ta vare på den feilede transaksjonen og undersøke den første involverte grensen i stedet for å anta at ingressen er ansvarlig.

Bevis Verdaccio-deployen fra ende til ende

Ikke bruk trafikk fra den første brukeren som akseptansetest for Verdaccio. Forbered ufarlig eksempeltilstand og kjør hele handlingen «Logg inn med npm, publiser en pakke med scope, installer den fra et rent prosjekt og bekreft at en upstream-pakke er bufret». Noter den nøyaktige offentlige URL-en, resultatet, imagereferansen og loggintervallet som er knyttet til kjøringen.

Erstatt containeren og gjenta uten å bygge dataene på nytt. Gjenopprett deretter til en tom vert. Gjenopprettingskravet er at private tarballer, metadata, brukere og konfigurasjon kommer tilbake, og at det rene prosjektet installerer samme pakkeintegritet. Observer tarball-lagring, metadataoperasjoner, samtidige installasjoner og forsinkelse til konfigurerte upstream-registre i hver gjennomkjøring, og definer et varsel rundt forringelse av transaksjonen i stedet for rundt inaktive containermålinger.

Én siste kontroll bør feile med hensikt: nekt testidentiteten midlertidig tilgang til persistent konfigurasjon, htpasswd-lagring og valgfri objektlagring. Bekreft at den resulterende Verdaccio-meldingen identifiserer den relevante grensen, i stedet for å utløse sletting av data eller en endeløs omstart. Gjenopprett den gyldige tilstanden og bekreft at den samme eksempeltransaksjonen lykkes. Ta med denne korte øvelsen i release-sjekklisten.

Hold Verdaccio eksplisitt mens Dockup håndterer ruting

For Verdaccio kan Dockup opprette ruten og TLS-sertifikatet, bevare monteringer, levere hemmeligheter og plassere persistent konfigurasjon, htpasswd-lagring og valgfri objektlagring på privat nettverk, samtidig som deployen kan kjøres enten på Dockup eller tilknyttede servere.

Release-godkjenningen er fortsatt den konkrete Verdaccio-transaksjonen: Logg inn med npm, publiser en pakke med scope, installer den fra et rent prosjekt og bekreft at en upstream-pakke er bufret. Bekreft også gjenopprettingskravet – private tarballer, metadata, brukere og konfigurasjon kommer tilbake, og det rene prosjektet installerer samme pakkeintegritet. Disse to kontrollene viser om deployen fungerer, og om den kan gjenopprettes.

Vanlige spørsmål

Hva trenger Verdaccio for en produksjonsdeploy?

Rout Verdaccio-containeren på port 4873 gjennom én HTTPS-opprinnelse. Det støttende nettverkskravet er persistent konfigurasjon, htpasswd-lagring og valgfri objektlagring. Ikke erklær Verdaccio klar før du kan logge inn med npm, publisere en pakke med scope, installere den fra et rent prosjekt og bekrefte at en upstream-pakke er bufret.

Hvilke Verdaccio-data bør inngå i en sikkerhetskopi?

Gjør /verdaccio/storage persistent, og inkluder pakkens tarballer, metadata, konfigurasjon og autentiseringsfiler i det samme gjenopprettingsmanifestet. En ren Verdaccio-gjenoppretting er bare vellykket når private tarballer, metadata, brukere og konfigurasjon kommer tilbake, og det rene prosjektet installerer samme pakkeintegritet.

Krever Verdaccio HTTPS bak en reverse proxy?

Bruk HTTPS for den offentlige Verdaccio-opprinnelsen, og behold port 4873 på den interne ruten. Bruk Verdaccio-innstillingen riktig: Sett den offentlige URL-en og npm-registerets URL til samme HTTPS-opprinnelse. For Verdaccio beskytter HTTPS påloggingsinformasjon eller brukerinnhold under overføring, og sørger for at klientatferd som avhenger av opprinnelsen, forblir konsistent.

Hvordan bør en Verdaccio-oppgradering testes?

Gjenopprett den gjeldende Verdaccio-tilstanden i en isolert deploy, bruk kandidatversjonen og kjør akseptansetransaksjonen på nytt. Vær spesielt oppmerksom på at konfigurasjonssyntaks, autentiseringsplugins og pakkemetadata bør testes mot den aktuelle hovedversjonen av Verdaccio. Behold det forrige Verdaccio-imaget til grensen for datamigrering og rollback er forstått.