Jak samodzielnie hostować Verdaccio w 2026 roku: uwierzytelnianie npm, storage i TLS

Samodzielne hostowanie Verdaccio zaczyna mieć znaczenie przy pierwszym ponownym wdrożeniu, a nie przy pierwszym docker run. Jeśli klienci npm wysyłają dane uwierzytelniające do innego hosta albo storage pakietów jest tylko do odczytu, Docker nadal może raportować całkowicie zdrowy proces. Poniższe wdrożenie koncentruje się na obserwowalnym działaniu: zalogowaniu się za pomocą npm, opublikowaniu pakietu z zakresem, zainstalowaniu go w czystym projekcie i potwierdzeniu, że pakiet z upstreamu został zapisany w cache.

Przeznaczenie Verdaccio jest jednoznaczne: prywatny rejestr npm dla pakietów wewnętrznych. Ten opis wskazuje, co musi być publiczne, co powinno pozostać prywatne oraz co backup musi odtworzyć.

Porty, procesy i prywatne usługi

Przydatny diagram Verdaccio pokazuje publiczną trasę, prywatny port 4873, granicę stanu oraz wszystkie wymagania pomocnicze. Zaznacz, które strzałki przenoszą dane uwierzytelniające, a które zwykły ruch użytkowników. Kontrakt sieciowy Verdaccio obejmuje trwałą konfigurację, storage htpasswd i opcjonalny object storage. Prywatne endpointy umieść w wewnętrznym DNS-ie, zezwól wyłącznie na wymagane połączenia wychodzące i nadaj Verdaccio ograniczone uprawnieniami dane uwierzytelniające usługi.

Potwierdź diagram jednym rzeczywistym działaniem: zaloguj się za pomocą npm, opublikuj pakiet z zakresem, zainstaluj go w czystym projekcie i sprawdź, czy pakiet z upstreamu został zapisany w cache. Największe obciążenie prawdopodobnie będą generować storage tarballi, operacje na metadanych, równoległe instalacje oraz opóźnienia względem skonfigurowanych rejestrów upstream — monitoruj tę ścieżkę, zamiast traktować wszystkie żądania HTTP jednakowo.

Zamień lokalne polecenie w usługę, którą można kontrolować

Użyj polecenia, które ujawnia wszystkie istotne decyzje. Ta konfiguracja bazowa wiąże Verdaccio z pętlą zwrotną hosta, dodaje znane mounty danych i przekazuje pierwsze wymagane ustawienie. Dodaj zatwierdzone ustawienia połączeń dla trwałej konfiguracji, storage htpasswd i opcjonalnego object storage; dla prywatnych usług używaj prywatnych nazw.

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

Zastąp pływające tagi przetestowaną wersją lub digestem. Po uruchomieniu sprawdź docker logs --tail 200 verdaccio i potwierdź, że proces nasłuchuje na porcie 4873. Następnie wykonaj działanie akceptacyjne Verdaccio; odpowiedź strony głównej nie dowodzi, że cały scenariusz działa: zaloguj się za pomocą npm, opublikuj pakiet z zakresem, zainstaluj go w czystym projekcie i sprawdź, czy pakiet z upstreamu został zapisany w cache.

TLS jest proste, problemem są generowane URL-e

Ustaw publiczny URL i URL rejestru npm na ten sam origin HTTPS. Skieruj wybraną nazwę hosta do portu kontenera 4873, przekaż oryginalny host i schemat HTTPS oraz unikaj publikowania drugiego bezpośredniego originu.

Przetestuj Verdaccio z użyciem czystego klienta zewnętrznego. Oddziel awarię ingressu od znanej granicy aplikacji — klienci npm wysyłają dane uwierzytelniające do innego hosta albo storage pakietów jest tylko do odczytu. Błąd certyfikatu, DNS-u lub 502 należy do routingu; żądanie, które dociera do Verdaccio i zawodzi później, wskazuje na stan aplikacji, pojemność albo wymaganie pomocnicze. Poradnik dotyczący TLS dla własnej domeny obejmuje pierwszą grupę problemów.

Odtwórz Verdaccio na pustym hoście

W przypadku Verdaccio bezpieczeństwo ponownego wdrożenia zaczyna się od tarballi pakietów, metadanych, konfiguracji i plików uwierzytelniania. Zamontuj /verdaccio/storage przed bootstrapem, zapisz nieszkodliwe przykładowe dane i zastąp kontener, aby potwierdzić, że ta ścieżka rzeczywiście jest trwała. Przetestuj ją, zastępując kontener, gdy przykładowe dane nadal istnieją; ujawni to mounty wskazujące o jeden katalog za wysoko lub za nisko.

Następnie przetestuj disaster recovery na pustym hoście. W razie potrzeby użyj spójnego z aplikacją eksportu bazy danych i sprawdź, czy prywatne tarballe, metadane, użytkownicy i konfiguracja wracają, a czysty projekt instaluje pakiet o tej samej integralności. Poradnik dotyczący backupów baz danych przetestowanych przez odtworzenie wyznacza lepszy standard niż samo sprawdzenie, czy utworzono plik archiwum.

Dane uwierzytelniające, role i wystawione powierzchnie

W przypadku Verdaccio cenna powierzchnia niekoniecznie obejmuje stronę startową. Głównym błędem jest zezwolenie na anonimowe publikowanie albo użycie zapisywalnej konfiguracji uplinku. Przeciwdziałaj temu celowo: zablokuj anonimowe publikowanie, ogranicz zakres uprawnień maintainerów i przypnij uwierzytelnianie npm do dokładnego hosta rejestru HTTPS.

VERDACCIO_PUBLIC_URL jest konfiguracją, a nie sekretem; jego wartość powinna być jawna, natomiast osobne dane uwierzytelniające używane przez Verdaccio należy chronić. Korzystaj z nieuprzywilejowanego użytkownika kontenera, jeśli obraz go obsługuje, i nie montuj niezwiązanych z usługą danych uwierzytelniających. Stosuj limity liczby żądań lub rozmiaru na ingressie, gdy niezaufany ruch może zużywać storage tarballi, operacje na metadanych, równoległe instalacje oraz opóźnienia względem skonfigurowanych rejestrów upstream.

Ćwiczenia awarii dla Verdaccio

Testy pojemności powinny obejmować storage tarballi, operacje na metadanych, równoległe instalacje oraz opóźnienia względem skonfigurowanych rejestrów upstream, a nie wielokrotne żądania do /. Uruchom scenariusz „zaloguj się za pomocą npm, opublikuj pakiet z zakresem, zainstaluj go w czystym projekcie i potwierdź, że pakiet z upstreamu został zapisany w cache” przy realistycznej współbieżności oraz rejestruj opóźnienie, współczynnik błędów i przyrost storage.

Planowanie aktualizacji musi uwzględniać to ryzyko: składnię konfiguracji, pluginy uwierzytelniania i metadane pakietów należy przetestować względem docelowej głównej wersji Verdaccio. Przetestuj nowe wydanie na reprezentatywnych danych wejściowych, a następnie powtórz transakcję akceptacyjną i porównaj jej wynik. Jeśli klienci npm wysyłają dane uwierzytelniające do innego hosta albo storage pakietów jest tylko do odczytu, zarejestruj nieudaną transakcję i sprawdź pierwszą napotkaną granicę, zamiast zakładać, że odpowiada za to ingress.

Potwierdź działanie wdrożenia Verdaccio od początku do końca

Nie wykorzystuj ruchu pierwszego użytkownika jako testu akceptacyjnego Verdaccio. Przygotuj nieszkodliwy stan przykładowy i wykonaj pełne działanie: „zaloguj się za pomocą npm, opublikuj pakiet z zakresem, zainstaluj go w czystym projekcie i potwierdź, że pakiet z upstreamu został zapisany w cache”. Zapisz dokładny publiczny URL, wynik, referencję obrazu i przedział logów powiązany z uruchomieniem.

Zastąp kontener i powtórz test bez odbudowywania danych. Następnie odtwórz usługę na pustym hoście; warunkiem powodzenia jest powrót prywatnych tarballi, metadanych, użytkowników i konfiguracji oraz instalacja pakietu o tej samej integralności przez czysty projekt. Przy każdym przejściu obserwuj storage tarballi, operacje na metadanych, równoległe instalacje oraz opóźnienia względem skonfigurowanych rejestrów upstream i zdefiniuj alert dotyczący pogorszenia transakcji, a nie bezczynnych metryk kontenera.

Jedna końcowa kontrola powinna celowo zakończyć się niepowodzeniem: tymczasowo odbierz tożsamości testowej dostęp do trwałej konfiguracji, storage htpasswd i opcjonalnego object storage. Sprawdź, czy komunikat Verdaccio wskazuje właściwą granicę, zamiast uruchamiać usuwanie danych lub nieskończony restart. Przywróć poprawny stan i potwierdź, że ta sama przykładowa transakcja kończy się powodzeniem. Dodaj to krótkie ćwiczenie do checklisty wydań.

Zachowaj jawną konfigurację Verdaccio, a Dockup powierz routing

W przypadku Verdaccio Dockup może utworzyć trasę i certyfikat TLS, zachować mounty, dostarczyć sekrety oraz umieścić trwałą konfigurację, storage htpasswd i opcjonalny object storage w prywatnej sieci, wdrażając usługę zarówno na Dockup, jak i na dołączonych serwerach.

Bramką wydania nadal jest konkretna transakcja Verdaccio: zalogowanie się za pomocą npm, opublikowanie pakietu z zakresem, zainstalowanie go w czystym projekcie i potwierdzenie, że pakiet z upstreamu został zapisany w cache. Sprawdź również warunek odtworzenia — prywatne tarballe, metadane, użytkownicy i konfiguracja muszą wrócić, a czysty projekt musi zainstalować pakiet o tej samej integralności. Te dwa testy pokazują, czy wdrożenie działa i czy można je odzyskać.

Często zadawane pytania

Czego Verdaccio potrzebuje do wdrożenia produkcyjnego?

Skieruj kontener Verdaccio na porcie 4873 przez jeden origin HTTPS. Wymagania sieciowe obejmują trwałą konfigurację, storage htpasswd i opcjonalny object storage. Nie uznawaj Verdaccio za gotowe, dopóki nie zalogujesz się za pomocą npm, nie opublikujesz pakietu z zakresem, nie zainstalujesz go w czystym projekcie i nie potwierdzisz, że pakiet z upstreamu został zapisany w cache.

Które dane Verdaccio powinny znaleźć się w backupie?

Utrwal /verdaccio/storage i uwzględnij tarballe pakietów, metadane, konfigurację oraz pliki uwierzytelniania w tym samym manifeście odtwarzania. Odtworzenie czystej instalacji Verdaccio kończy się powodzeniem tylko wtedy, gdy wracają prywatne tarballe, metadane, użytkownicy i konfiguracja, a czysty projekt instaluje pakiet o tej samej integralności.

Czy Verdaccio wymaga HTTPS za reverse proxy?

Używaj HTTPS dla publicznego originu Verdaccio, a port 4873 pozostaw na trasie wewnętrznej. Zastosuj poprawnie ustawienie Verdaccio: publiczny URL i URL rejestru npm muszą wskazywać ten sam origin HTTPS. W przypadku Verdaccio HTTPS chroni dane uwierzytelniające lub treści użytkowników podczas przesyłania i zapewnia spójne działanie klienta zależne od originu.

Jak testować aktualizację Verdaccio?

Odtwórz bieżący stan Verdaccio w izolowanym wdrożeniu, zastosuj wersję kandydującą i powtórz transakcję akceptacyjną. Zwróć szczególną uwagę na to, że składnię konfiguracji, pluginy uwierzytelniania i metadane pakietów należy przetestować względem docelowej głównej wersji Verdaccio. Zachowaj poprzedni obraz Verdaccio do czasu zrozumienia granicy migracji danych i wycofania zmian.