Ako prevádzkovať Verdaccio vo vlastnej réžii v roku 2026: npm autentifikácia, úložisko a TLS

Prevádzka Verdaccio vo vlastnej réžii začína byť zaujímavá pri prvom redeploymente, nie pri prvom docker run. Ak npm klienti odosielajú autentifikáciu na iného hostiteľa alebo je úložisko balíkov iba na čítanie, Docker môže stále hlásiť úplne zdravý proces. Nasledujúce nasadenie je postavené na pozorovateľnom správaní: prihláste sa pomocou npm, publikujte balík so scope, nainštalujte ho z čistého projektu a overte, že sa balík z upstreamu uložil do cache.

Úloha Verdaccio je jasná: súkromný npm registry pre interné balíky. Tento opis určuje, čo musí zostať verejné, čo má zostať súkromné a čo musí záloha obnoviť.

Porty, procesy a súkromné služby

Užitočný diagram Verdaccio zobrazuje verejnú trasu, súkromný port 4873, hranicu stavu a všetky podporné požiadavky. Označte, ktoré šípky prenášajú prihlasovacie údaje a ktoré predstavujú bežnú komunikáciu používateľov. Sieťová zmluva Verdaccio pozostáva z perzistentnej konfigurácie, úložiska htpasswd a voliteľného object storage. Súkromné endpointy ponechajte v internom DNS, povoľte iba potrebné odchádzajúce volania a Verdaccio priraďte service credential s obmedzeným rozsahom.

Diagram overte jednou reálnou operáciou: prihláste sa pomocou npm, publikujte balík so scope, nainštalujte ho z čistého projektu a overte, že sa balík z upstreamu uložil do cache. Pravdepodobná záťaž pochádza z úložiska tarballov, operácií s metadátami, súbežných inštalácií a latencie voči nakonfigurovaným upstream registry; monitorujte túto cestu namiesto toho, aby ste všetky HTTP požiadavky považovali za rovnocenné.

Premeňte lokálny príkaz na kontrolovateľnú službu

Použite príkaz, ktorý sprístupní všetky dôležité voľby. Táto základná konfigurácia naviaže Verdaccio na loopback hostiteľa, pridá známe data mounts a nastaví prvú požadovanú hodnotu. Doplňte schválené connection settings pre perzistentnú konfiguráciu, úložisko htpasswd a voliteľný object storage; pre súkromné služby používajte súkromné názvy.

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

Plávajúce tagy nahraďte otestovanou verziou alebo digestom. Po spustení skontrolujte docker logs --tail 200 verdaccio a overte, že proces počúva na porte 4873. Potom vykonajte akceptačnú operáciu Verdaccio; odpoveď koreňovej stránky nedokazuje, že celý scenár funguje: prihláste sa pomocou npm, publikujte balík so scope, nainštalujte ho z čistého projektu a overte, že sa balík z upstreamu uložil do cache.

TLS je jednoduché; generované URL nie

Nastavte verejnú URL a URL npm registry na rovnaký HTTPS origin. Zvolený hostname smerujte na port kontajnera 4873, preposielajte pôvodný hostiteľ a HTTPS scheme a nezverejňujte druhý priamy origin.

Verdaccio otestujte z čistého externého klienta. Oddeľte zlyhanie ingressu od známej hranice aplikácie — npm klienti odosielajú autentifikáciu na iného hostiteľa alebo je úložisko balíkov iba na čítanie. Chyba certifikátu, DNS alebo 502 patrí do routingu; požiadavka, ktorá dorazí do Verdaccio a zlyhá neskôr, súvisí so stavom aplikácie, kapacitou alebo jej podpornou požiadavkou. Návod na TLS pre vlastnú doménu pokrýva prvú skupinu.

Obnovte Verdaccio na prázdnom hostiteľovi

Pri Verdaccio sa bezpečnosť redeploymentu začína pri tarballoch balíkov, metadátach, konfigurácii a autentifikačných súboroch. Pred bootstrapom pripojte /verdaccio/storage, zapíšte neškodné vzorové dáta a nahraďte kontajner, aby ste dokázali, že táto cesta je skutočne perzistentná. Cestu otestujte nahradením kontajnera, kým v nej existujú neškodné vzorové dáta; odhalíte tak mounty nasmerované o jeden adresár príliš vysoko alebo príliš nízko.

Ďalej otestujte disaster recovery na prázdnom hostiteľovi. V prípade potreby použite export databázy konzistentný s aplikáciou a overte, že sa vrátia súkromné tarbally, metadáta, používatelia a konfigurácia a že čistý projekt nainštaluje balík s rovnakou integritou. Návod na zálohovanie databázy overené obnovou poskytuje lepší cieľ než iba kontrola, či bol vytvorený archívny súbor.

Prihlasovacie údaje, roly a vystavené povrchy

Pri Verdaccio nie je cenným povrchom nevyhnutne landing page. Hlavnou chybou je povoliť anonymné publikovanie alebo používať zapisovateľnú konfiguráciu uplinku. Zamedzte tomu zámerne: zakážte anonymné publikovanie, obmedzte maintainerov pomocou scope a npm autentifikáciu udržujte pripojenú k presnému HTTPS hostiteľovi registry.

VERDACCIO_PUBLIC_URL je konfigurácia, nie secret; jej hodnotu ponechajte explicitnú, no chráňte samostatné credentials používané Verdaccio. Ak to image podporuje, použite neprivilegovaného používateľa kontajnera a nepripájajte nesúvisiace prihlasovacie údaje. Limity rýchlosti alebo veľkosti uplatnite na ingresse tam, kde nedôveryhodná práca môže spotrebovať úložisko tarballov, operácie s metadátami, súbežné inštalácie a latenciu voči nakonfigurovaným upstream registry.

Testy zlyhaní pre Verdaccio

Testy kapacity musia preveriť úložisko tarballov, operácie s metadátami, súbežné inštalácie a latenciu voči nakonfigurovaným upstream registry, nie opakovanú požiadavku na /. Spustite scenár „prihlás sa pomocou npm, publikuj balík so scope, nainštaluj ho z čistého projektu a over, že sa balík z upstreamu uložil do cache“ pri realistickej súbežnosti a zaznamenajte latenciu, chybovosť a rast úložiska.

Plánovanie upgradu musí zohľadniť toto riziko: syntax konfigurácie, autentifikačné pluginy a metadáta balíkov treba otestovať voči cieľovej major verzii Verdaccio. Nové vydanie otestujte s reprezentatívnym vstupom, potom zopakujte akceptačnú transakciu a porovnajte jej výsledok. Ak npm klienti odosielajú autentifikáciu na iného hostiteľa alebo je úložisko balíkov iba na čítanie, zachyťte zlyhávajúcu transakciu a preskúmajte prvú zapojenú hranicu namiesto predpokladu, že za problém zodpovedá ingress.

Overte nasadenie Verdaccio od začiatku do konca

Nerobte z prevádzky prvého používateľa akceptačný test pre Verdaccio. Pripravte neškodný vzorový stav a spustite kompletnú operáciu „prihlás sa pomocou npm, publikuj balík so scope, nainštaluj ho z čistého projektu a over, že sa balík z upstreamu uložil do cache“. Zaznamenajte presnú verejnú URL, výsledok, referenciu image a interval logov súvisiaci s testom.

Nahraďte kontajner a operáciu zopakujte bez opätovného vytvárania dát. Potom vykonajte obnovu na prázdnom hostiteľovi; podmienkou úspešnej obnovy je návrat súkromných tarballov, metadát, používateľov a konfigurácie a skutočnosť, že čistý projekt nainštaluje balík s rovnakou integritou. Pri každom priechode sledujte úložisko tarballov, operácie s metadátami, súbežné inštalácie a latenciu voči nakonfigurovaným upstream registry a definujte alert na zhoršenie transakcie, nie na neaktívne metriky kontajnera.

Jedna posledná kontrola by mala zámerne zlyhať: dočasne odoberte testovacej identite prístup k perzistentnej konfigurácii, úložisku htpasswd a voliteľnému object storage. Overte, že výsledná správa Verdaccio identifikuje príslušnú hranicu namiesto spustenia mazania dát alebo nekonečného reštartovania. Obnovte platný stav a potvrďte, že tá istá vzorová transakcia opäť uspeje. Tento krátky test ponechajte v release checklist.

Zachovajte explicitné nastavenie Verdaccio, kým Dockup rieši routing

Pri Verdaccio môže Dockup vytvoriť route a TLS certifikát, zachovať mounty, doručiť secrets a umiestniť perzistentnú konfiguráciu, úložisko htpasswd a voliteľný object storage do súkromnej siete pri nasadení do Dockup alebo na pripojené servery.

Release gate však stále predstavuje konkrétna transakcia Verdaccio: prihláste sa pomocou npm, publikujte balík so scope, nainštalujte ho z čistého projektu a overte, že sa balík z upstreamu uložil do cache. Overte aj podmienku obnovy — vrátia sa súkromné tarbally, metadáta, používatelia a konfigurácia a čistý projekt nainštaluje balík s rovnakou integritou. Tieto dve kontroly ukazujú, či nasadenie funguje a či ho možno obnoviť.

Často kladené otázky

Čo Verdaccio potrebuje na produkčné nasadenie?

Smerujte kontajner Verdaccio na porte 4873 cez jeden HTTPS origin. Sieťovou podpornou požiadavkou je perzistentná konfigurácia, úložisko htpasswd a voliteľný object storage. Verdaccio nepovažujte za pripravené, kým sa nedokážete prihlásiť pomocou npm, publikovať balík so scope, nainštalovať ho z čistého projektu a potvrdiť, že sa balík z upstreamu uložil do cache.

Ktoré dáta Verdaccio patria do zálohy?

Zachovajte /verdaccio/storage a do rovnakého recovery manifestu zahrňte tarbally balíkov, metadáta, konfiguráciu a autentifikačné súbory. Čistá obnova Verdaccio je úspešná iba vtedy, keď sa vrátia súkromné tarbally, metadáta, používatelia a konfigurácia a čistý projekt nainštaluje balík s rovnakou integritou.

Vyžaduje Verdaccio za reverse proxy HTTPS?

Pre verejný origin Verdaccio používajte HTTPS a port 4873 ponechajte na internej trase. Nastavenie Verdaccio aplikujte správne: verejnú URL a URL npm registry nastavte na rovnaký HTTPS origin. Pri Verdaccio HTTPS chráni credentials alebo obsah používateľov počas prenosu a zachováva konzistentné správanie klienta závislé od originu.

Ako testovať upgrade Verdaccio?

Obnovte aktuálny stav Verdaccio do izolovaného nasadenia, použite kandidátsku verziu a zopakujte jej akceptačnú transakciu. Venujte tomu osobitnú pozornosť, pretože syntax konfigurácie, autentifikačné pluginy a metadáta balíkov treba otestovať voči cieľovej major verzii Verdaccio. Predchádzajúci image Verdaccio si ponechajte, kým nebudete rozumieť hranici migrácie dát a rollbacku.