Jak v roce 2026 provozovat Verdaccio ve vlastní infrastruktuře: npm autentizace, úložiště a TLS

Provoz Verdaccia ve vlastní infrastruktuře začne být zajímavý při prvním redeployi, ne při prvním docker run. Pokud npm klienti posílají autentizaci na jiného hostitele nebo je úložiště balíčků pouze pro čtení, Docker přesto může hlásit zcela zdravý proces. Níže uvedené nasazení je postavené na pozorovatelném chování: přihlaste se pomocí npm, publikujte balíček ve scope, nainstalujte ho z čistého projektu a ověřte, že se balíček z upstreamu uložil do cache.

Účel Verdaccia je jasný: privátní npm registry pro interní balíčky. Tento popis nám říká, co musí zůstat veřejné, co má zůstat privátní a co musí záloha obnovit.

Porty, procesy a privátní služby

Užitečný diagram Verdaccia zobrazuje veřejnou trasu, privátní port 4873, hranici stavu a všechny podpůrné požadavky. Označte, které šipky přenášejí přihlašovací údaje a které představují běžný provoz uživatelů. Síťový kontrakt Verdaccia tvoří persistentní konfigurace, úložiště htpasswd a volitelné objektové úložiště. Privátní endpointy ponechte na interním DNS, povolte pouze potřebná odchozí spojení a Verdacciu přidělte omezené oprávnění služby.

Diagram ověřte jednou skutečnou akcí: přihlaste se pomocí npm, publikujte balíček ve scope, nainstalujte ho z čistého projektu a potvrďte, že se balíček z upstreamu uložil do cache. Pravděpodobná zátěž vychází z úložiště tarballů, operací s metadaty, souběžných instalací a latence k nakonfigurovaným upstream registrům; monitorujte tuto cestu, místo abyste všechny HTTP požadavky považovali za rovnocenné.

Proměňte lokální příkaz v kontrolovatelnou službu

Použijte příkaz, který odhalí každou důležitou volbu. Tento základní příklad váže Verdaccio na loopback hostitele, přidává známé mounty s daty a předává první požadované nastavení. Doplňte schválené parametry připojení pro persistentní konfiguraci, úložiště htpasswd a volitelné objektové úložiště; pro privátní služby používejte privátní 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

Plovoucí tagy nahraďte otestovanou verzí nebo digestem. Po spuštění zkontrolujte docker logs --tail 200 verdaccio a ověřte, že proces naslouchá na portu 4873. Poté spusťte akceptační akci Verdaccia; odpověď kořenové stránky nedokazuje, že celý scénář funguje: přihlaste se pomocí npm, publikujte balíček ve scope, nainstalujte ho z čistého projektu a potvrďte, že se balíček z upstreamu uložil do cache.

TLS je snadné, generované URL nikoli

Nastavte veřejnou URL a URL npm registry na stejný HTTPS origin. Zvolený hostname směrujte na port kontejneru 4873, předávejte původní host a HTTPS schéma a nezveřejňujte druhý přímý origin.

Otestujte Verdaccio z čistého externího klienta. Oddělte selhání ingressu od známé hranice aplikace — npm klienti posílají autentizaci na jiného hostitele nebo je úložiště balíčků pouze pro čtení. Chyba certifikátu, DNS nebo 502 patří do routingu; požadavek, který dorazí do Verdaccia a selže až později, souvisí se stavem aplikace, kapacitou nebo jejím podpůrným požadavkem. Návod na TLS pro vlastní doménu pokrývá první skupinu problémů.

Obnovte Verdaccio na prázdném hostiteli

U Verdaccia začíná bezpečnost redeploye u tarballů balíčků, metadat, konfigurace a autentizačních souborů. Před bootstrapem připojte /verdaccio/storage, zapište neškodná ukázková data a nahraďte kontejner, abyste prokázali, že je tato cesta skutečně persistentní. Cestu otestujte nahrazením kontejneru v době, kdy v ní ukázková data stále existují; odhalíte tak mounty namířené o jeden adresář příliš vysoko nebo nízko.

Dále otestujte disaster recovery na prázdném hostiteli. V případě potřeby použijte export databáze konzistentní z pohledu aplikace a ověřte, že se obnoví privátní tarbally, metadata, uživatelé a konfigurace a že čistý projekt nainstaluje balíček se stejnou integritou. Návod na zálohování databáze ověřené obnovou poskytuje silnější cíl než pouhá kontrola, zda byl vytvořen soubor archivu.

Přihlašovací údaje, role a vystavené plochy

U Verdaccia není cennou plochou nutně úvodní stránka. Hlavní chybou je povolit anonymní publikování nebo používat zapisovatelnou konfiguraci uplinku. Braňte se tomu záměrně: zakažte anonymní publikování, omezte oprávnění maintainerů podle scope a ponechte npm autentizaci navázanou na přesný HTTPS host registry.

VERDACCIO_PUBLIC_URL je konfigurace, nikoli tajný údaj; její hodnotu ponechte explicitní a chraňte samostatné přihlašovací údaje používané Verdacciem. Pokud to image podporuje, použijte neprivilegovaného uživatele kontejneru a nepřipojujte nesouvisející přihlašovací údaje. Na ingressu uplatněte limity rychlosti nebo velikosti tam, kde nedůvěryhodná práce může spotřebovávat úložiště tarballů, operace s metadaty, souběžné instalace a latenci k nakonfigurovaným upstream registrům.

Testy selhání pro Verdaccio

Testy kapacity by měly zatěžovat úložiště tarballů, operace s metadaty, souběžné instalace a latenci k nakonfigurovaným upstream registrům, nikoli opakovaný požadavek na /. Spusťte scénář „přihlaste se pomocí npm, publikujte balíček ve scope, nainstalujte ho z čistého projektu a potvrďte, že se balíček z upstreamu uložil do cache“ při realistické souběžnosti a zaznamenejte latenci, chybovost a růst úložiště.

Plánování upgradu musí zohlednit toto riziko: syntaxi konfigurace, autentizační pluginy a metadata balíčků je třeba otestovat s cílovou hlavní verzí Verdaccia. Otestujte nové vydání s reprezentativním vstupem, poté zopakujte akceptační transakci a porovnejte její výsledek. Pokud npm klienti posílají autentizaci na jiného hostitele nebo je úložiště balíčků pouze pro čtení, zachyťte selhávající transakci a prozkoumejte první zapojenou hranici, místo abyste automaticky předpokládali, že je na vině ingress.

Ověřte nasazení Verdaccia od začátku do konce

Nepoužívejte první provoz uživatele jako akceptační test Verdaccia. Připravte neškodný ukázkový stav a spusťte kompletní akci „přihlaste se pomocí npm, publikujte balíček ve scope, nainstalujte ho z čistého projektu a potvrďte, že se balíček z upstreamu uložil do cache“. Poznamenejte si přesnou veřejnou URL, výsledek, referenci image a interval logů spojený s během testu.

Nahraďte kontejner a akci zopakujte bez opětovného sestavení dat. Poté proveďte obnovu na prázdném hostiteli; podmínkou úspěšné obnovy je, že se vrátí privátní tarbally, metadata, uživatelé a konfigurace a čistý projekt nainstaluje balíček se stejnou integritou. Při každém průchodu sledujte úložiště tarballů, operace s metadaty, souběžné instalace a latenci k nakonfigurovaným upstream registrům a definujte alert nad zhoršením transakce, nikoli nad metrikami nečinného kontejneru.

Jedna závěrečná kontrola by měla záměrně selhat: dočasně testovací identitě zakažte přístup k persistentní konfiguraci, úložišti htpasswd a volitelnému objektovému úložišti. Ověřte, že výsledná zpráva Verdaccia identifikuje relevantní hranici, místo aby spustila mazání dat nebo nekonečný restart. Obnovte platné podmínky a potvrďte, že stejná ukázková transakce opět uspěje. Tento krátký test zařaďte do checklistu vydání.

Ponechte Verdaccio explicitní, zatímco Dockup řeší routing

U Verdaccia může Dockup vytvořit route a TLS certifikát, zachovat mounty, doručovat secrets a umístit persistentní konfiguraci, úložiště htpasswd a volitelné objektové úložiště do privátní sítě při nasazení na Dockup nebo připojené servery.

Bránou pro vydání je stále konkrétní transakce Verdaccia: přihlaste se pomocí npm, publikujte balíček ve scope, nainstalujte ho z čistého projektu a potvrďte, že se balíček z upstreamu uložil do cache. Ověřte také podmínku obnovy — privátní tarbally, metadata, uživatelé a konfigurace se musí vrátit a čistý projekt musí nainstalovat balíček se stejnou integritou. Tyto dvě kontroly ukazují, zda nasazení funguje a zda ho lze obnovit.

Často kladené otázky

Co Verdaccio potřebuje pro produkční nasazení?

Směrujte kontejner Verdaccia na portu 4873 přes jeden HTTPS origin. Síťovým podpůrným požadavkem je persistentní konfigurace, úložiště htpasswd a volitelné objektové úložiště. Verdaccio neoznačujte za připravené, dokud se pomocí npm nepřihlásíte, nepublikujete balíček ve scope, nenainstalujete ho z čistého projektu a nepotvrdíte, že se balíček z upstreamu uložil do cache.

Která data Verdaccia patří do zálohy?

Zajistěte persistenci /verdaccio/storage a do stejného manifestu obnovy zahrňte tarbally balíčků, metadata, konfiguraci a autentizační soubory. Čistá obnova Verdaccia je úspěšná pouze tehdy, když se vrátí privátní tarbally, metadata, uživatelé a konfigurace a čistý projekt nainstaluje balíček se stejnou integritou.

Vyžaduje Verdaccio za reverse proxy HTTPS?

Pro veřejný origin Verdaccia používejte HTTPS a port 4873 ponechte na interní trase. Nastavení Verdaccia aplikujte správně: veřejnou URL a URL npm registry nastavte na stejný HTTPS origin. U Verdaccia HTTPS chrání přihlašovací údaje nebo obsah uživatelů při přenosu a udržuje konzistentní chování klienta závislé na originu.

Jak testovat upgrade Verdaccia?

Obnovte aktuální stav Verdaccia do izolovaného nasazení, použijte kandidátní verzi a zopakujte její akceptační transakci. Věnujte tomu zvláštní pozornost, protože syntaxi konfigurace, autentizační pluginy a metadata balíčků je třeba otestovat s cílovou hlavní verzí Verdaccia. Předchozí image Verdaccia ponechte k dispozici, dokud neporozumíte hranici migrace dat a rollbacku.