A Verdaccio saját üzemeltetése 2026-ban: npm-hitelesítés, tárhely és TLS

A Verdaccio saját üzemeltetése nem az első docker run parancsnál válik érdekessé, hanem az első újratelepítésnél. Ha az npm-kliensek egy másik hostra küldik a hitelesítési adatokat, vagy a csomagtároló csak olvasható, a Docker ettől még teljesen egészséges folyamatot jelezhet. Az alábbi telepítés a megfigyelhető működés köré épül: jelentkezz be npm-mel, publikálj egy scoped csomagot, telepítsd egy tiszta projektből, majd ellenőrizd, hogy egy upstream csomag gyorsítótárba került.

A Verdaccio feladata egyértelmű: privát npm registry belső csomagokhoz. Ez a meghatározás megmutatja, minek kell nyilvánosnak maradnia, minek kell privátnak lennie, és mit kell egy biztonsági mentésnek helyreállítania.

Portok, folyamatok és privát szolgáltatások

Egy hasznos Verdaccio-diagram bemutatja a nyilvános útvonalat, a privát 4873-as portot, az állapothatárt és minden támogató követelményt. Jelöld, mely nyilak továbbítanak hitelesítési adatokat, és melyek szokásos felhasználói forgalmat. A Verdaccio hálózati szerződését a perzisztens konfiguráció, a htpasswd-tároló és az opcionális object storage alkotja. A privát végpontokat belső DNS-en tartsd, csak a szükséges kimenő kapcsolatokat engedélyezd, és adj a Verdaccionak hatókörhöz kötött szolgáltatási hitelesítő adatot.

A diagramot egy valódi művelettel igazold: jelentkezz be npm-mel, publikálj egy scoped csomagot, telepítsd egy tiszta projektből, majd ellenőrizd, hogy egy upstream csomag gyorsítótárba került. A várható terhelést a tarballok tárolása, a metaadatműveletek, a párhuzamos telepítések és a konfigurált upstream registryk késleltetése okozza; ezt az útvonalat figyeld, ne kezeld egyformán az összes HTTP-kérést.

A helyi parancsból jól vizsgálható szolgáltatás

Olyan parancsot használj, amely minden fontos beállítást láthatóvá tesz. Ez az alapkonfiguráció a Verdacciont a host loopback interfészére köti, hozzáadja az ismert adatcsatolásokat, és megadja az első szükséges beállítást. Egészítsd ki a felülvizsgált kapcsolati beállításokkal a perzisztens konfigurációhoz, a htpasswd-tárolóhoz és az opcionális object storage-hoz; privát szolgáltatásokhoz privát neveket használj.

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

A lebegő tageket cseréld tesztelt verzióra vagy digestre. Indítás után vizsgáld meg a docker logs --tail 200 verdaccio kimenetét, és erősítsd meg, hogy a folyamat a 4873-as porton figyel. Ezután hajtsd végre a Verdaccio elfogadási műveletét; a gyökéroldal válasza nem bizonyítja a teljes forgatókönyv sikerét: jelentkezz be npm-mel, publikálj egy scoped csomagot, telepítsd egy tiszta projektből, majd ellenőrizd, hogy egy upstream csomag gyorsítótárba került.

A TLS egyszerű; a generált URL-ek már nem

A nyilvános URL-t és az npm registry URL-jét ugyanarra a HTTPS-originre állítsd be. A kiválasztott hostnevet továbbítsd a konténer 4873-as portjára, add tovább az eredeti hostot és a HTTPS-sémát, és ne tegyél közzé egy második közvetlen origint.

A Verdacciót tiszta, külső kliensről teszteld. Válaszd külön a beléptetési hibát és az ismert alkalmazási határt — az npm-kliensek egy másik hostra küldik a hitelesítési adatokat, vagy a csomagtároló csak olvasható. A tanúsítvány-, DNS- vagy 502-es hiba az útválasztáshoz tartozik; az a kérés, amely eléri a Verdacciót, majd később hibázik, az alkalmazás állapotához, kapacitásához vagy egy támogató követelményhez kapcsolódik. A custom-domain TLS guide az első csoporttal foglalkozik.

A Verdaccio helyreállítása üres hoston

A Verdaccio esetében az újratelepítés biztonsága a csomag-tarballokkal, a metaadatokkal, a konfigurációval és a hitelesítési fájlokkal kezdődik. A bootstrap előtt csatold a /verdaccio/storage könyvtárat, írj bele ártalmatlan mintaadatokat, majd cseréld le a konténert annak bizonyítására, hogy az útvonal valóban perzisztens. Az útvonalat úgy teszteld, hogy a konténert akkor cseréled le, amikor még léteznek benne ártalmatlan mintaadatok; így kiderül, ha a mount egy könyvtárszinttel túl magasra vagy túl alacsonyra mutat.

Ezután teszteld a katasztrófa utáni helyreállítást egy üres hoston. Ahol szükséges, használj alkalmazás-konzisztens adatbázis-exportot, és ellenőrizd, hogy a privát tarballok, a metaadatok, a felhasználók és a konfiguráció visszaállnak, valamint a tiszta projekt ugyanazzal a csomintegritással telepíti a csomagot. A restore-tested database backup guide erősebb célt határoz meg annál, mint pusztán ellenőrizni, hogy létrejött-e egy archívumfájl.

Hitelesítő adatok, szerepkörök és kitett felületek

A Verdaccio esetében az értékes támadási felület nem feltétlenül a kezdőoldal. A fő hiba az anonim publikálás engedélyezése vagy írható uplink-konfiguráció használata. Ezt tudatosan előzd meg: tiltsd le az anonim publikálást, korlátozd a maintainer jogosultságokat, és az npm-hitelesítést pontosan a HTTPS registry-hosthoz rendeld.

A VERDACCIO_PUBLIC_URL konfiguráció, nem titkos érték; az értékét tartsd explicit módon megadva, miközben védd a Verdaccio által használt külön hitelesítő adatokat. Használj nem privilegizált konténerfelhasználót, ha az image támogatja, és ne csatolj oda nem tartozó hitelesítő adatokat. Az ingressen alkalmazz sebesség- vagy méretkorlátokat ott, ahol a nem megbízható műveletek felhasználhatják a tarballtárhelyet, a metaadatműveleteket, a párhuzamos telepítéseket és a konfigurált upstream registryk késleltetését.

Hibagyakorlatok a Verdacciohoz

A kapacitásteszteknek a tarballok tárolását, a metaadatműveleteket, a párhuzamos telepítéseket és a konfigurált upstream registryk késleltetését kell terhelniük, nem pedig a / ismételt lekérését. Futtasd a „jelentkezz be npm-mel, publikálj egy scoped csomagot, telepítsd egy tiszta projektből, majd ellenőrizd, hogy egy upstream csomag gyorsítótárba került” forgatókönyvet reális párhuzamosság mellett, és rögzítsd a késleltetést, a hibaarányt, valamint a tárhely növekedését.

A frissítési tervnek számolnia kell ezzel a kockázattal: a konfigurációs szintaxist, a hitelesítési pluginokat és a csomagmetaadatokat a célzott Verdaccio major verzióval kell tesztelni. Teszteld az új kiadást reprezentatív bemenettel, majd ismételd meg az elfogadási tranzakciót, és hasonlítsd össze az eredményét. Ha az npm-kliensek egy másik hostra küldik a hitelesítési adatokat, vagy a csomagtároló csak olvasható, rögzítsd a hibás tranzakciót, és vizsgáld meg az első érintett határt ahelyett, hogy automatikusan az ingresszt tennéd felelőssé.

A Verdaccio-telepítés végponttól végpontig történő igazolása

Ne az első felhasználói forgalmat használd a Verdaccio elfogadási tesztjeként. Készíts elő ártalmatlan mintaállapotot, és futtasd le a teljes műveletet: „jelentkezz be npm-mel, publikálj egy scoped csomagot, telepítsd egy tiszta projektből, majd ellenőrizd, hogy egy upstream csomag gyorsítótárba került”. Jegyezd fel a pontos nyilvános URL-t, az eredményt, az image-referenciát és a futtatáshoz kapcsolódó naplózási időszakot.

Cseréld le a konténert, és ismételd meg a tesztet az adatok újraépítése nélkül. Ezután állítsd helyre egy üres hoston; a helyreállítás feltétele, hogy a privát tarballok, a metaadatok, a felhasználók és a konfiguráció visszatérjenek, a tiszta projekt pedig ugyanazzal a csomintegritással telepítse a csomagot. Minden futtatás során figyeld a tarballtárolást, a metaadatműveleteket, a párhuzamos telepítéseket és a konfigurált upstream registryk késleltetését, és a riasztást a tranzakció romlásához igazítsd, ne az üresjárati konténermetrikákhoz.

Egy utolsó ellenőrzésnek szándékosan hibáznia kell: ideiglenesen vond meg a tesztazonosító hozzáférését a perzisztens konfigurációtól, a htpasswd-tárolótól és az opcionális object storage-tól. Ellenőrizd, hogy a keletkező Verdaccio-üzenet azonosítja-e az érintett határt, ahelyett hogy adattörlést vagy végtelen újraindulást okozna. Állítsd vissza az érvényes állapotot, és erősítsd meg, hogy ugyanaz a minta-tranzakció sikeresen lefut. Ezt a rövid gyakorlatot tartsd meg a kiadási ellenőrzőlistában.

Tartsd explicit módon a Verdacciót, miközben a Dockup kezeli az útválasztást

A Verdaccio esetében a Dockup létrehozhatja az útvonalat és a TLS-tanúsítványt, megőrizheti a mountokat, átadhatja a titkokat, valamint a perzisztens konfigurációt, a htpasswd-tárolót és az opcionális object storage-t privát hálózatra helyezheti, miközben a telepítés Dockupra vagy csatolt szerverekre történik.

A kiadási kapu továbbra is a konkrét Verdaccio-tranzakció: jelentkezz be npm-mel, publikálj egy scoped csomagot, telepítsd egy tiszta projektből, majd ellenőrizd, hogy egy upstream csomag gyorsítótárba került. Ellenőrizd a helyreállítás feltételét is — a privát tarballok, a metaadatok, a felhasználók és a konfiguráció térjenek vissza, a tiszta projekt pedig ugyanazzal a csomintegritással telepítse a csomagot. Ez a két ellenőrzés megmutatja, hogy a telepítés működik-e, és helyreállítható-e.

Gyakran ismételt kérdések

Mire van szüksége a Verdaccionak production telepítéshez?

A Verdaccio konténerét a 4873-as porton, egyetlen HTTPS-origin mögött irányítsd. A hálózati támogató követelmény a perzisztens konfiguráció, a htpasswd-tároló és az opcionális object storage. Ne tekintsd késznek a Verdacciót addig, amíg nem tudsz bejelentkezni npm-mel, nem tudsz publikálni egy scoped csomagot, nem tudod telepíteni egy tiszta projektből, és nem tudod megerősíteni, hogy egy upstream csomag gyorsítótárba került.

Mely Verdaccio-adatoknak kell szerepelniük a biztonsági mentésben?

Tedd perzisztenssé a /verdaccio/storage könyvtárat, és ugyanabba a helyreállítási manifestbe vedd fel a csomag-tarballokat, a metaadatokat, a konfigurációt és a hitelesítési fájlokat. A tiszta Verdaccio-helyreállítás csak akkor sikeres, ha a privát tarballok, a metaadatok, a felhasználók és a konfiguráció visszatérnek, a tiszta projekt pedig ugyanazzal a csomintegritással telepíti a csomagot.

Szüksége van a Verdaccionak HTTPS-re reverse proxy mögött?

A nyilvános Verdaccio-originhez használj HTTPS-t, a 4873-as portot pedig hagyd a belső útvonalon. A Verdaccio beállítását megfelelően alkalmazd: a nyilvános URL-t és az npm registry URL-jét ugyanarra a HTTPS-originre állítsd. A Verdaccio esetében a HTTPS védi a hitelesítő adatokat vagy a felhasználói tartalmakat átvitel közben, és egységesen kezeli az origintől függő kliensviselkedést.

Hogyan kell tesztelni egy Verdaccio-frissítést?

Állítsd helyre a jelenlegi Verdaccio-állapotot egy elkülönített telepítésben, alkalmazd a jelölt verziót, majd ismételd meg az elfogadási tranzakcióját. Fordíts különös figyelmet arra, hogy a konfigurációs szintaxist, a hitelesítési pluginokat és a csomagmetaadatokat a célzott Verdaccio major verzióval kell tesztelni. Tartsd meg az előző Verdaccio-image-et addig, amíg nem tisztázod az adat-migráció és a visszaállítás határát.