Cum găzduiești singur Verdaccio în 2026: autentificare npm, stocare și TLS

Găzduirea proprie a Verdaccio devine interesantă la primul redeploy, nu la primul docker run. Dacă clienții npm trimit datele de autentificare către o altă gazdă sau stocarea pachetelor este read-only, Docker poate raporta în continuare un proces perfect sănătos. Implementarea de mai jos este organizată în jurul comportamentului observabil: autentifică-te cu npm, publică un pachet cu scope, instalează-l dintr-un proiect curat și confirmă că un pachet upstream este pus în cache.

Rolul destinat Verdaccio este explicit: registry npm privat pentru pachete interne. Această descriere ne arată ce trebuie să rămână public, ce ar trebui să rămână privat și ce trebuie să reconstruiască un backup.

Porturi, procese și servicii private

O diagramă utilă pentru Verdaccio afișează ruta publică, portul privat 4873, limita stării și fiecare cerință auxiliară. Marchează ce săgeți transportă credențiale și care reprezintă trafic obișnuit al utilizatorilor. Contractul de rețea pentru Verdaccio constă în configurație persistentă, stocare htpasswd și stocare obiectuală opțională. Păstrează endpointurile private în DNS intern, permite doar apelurile outbound necesare și oferă Verdaccio o credențială de serviciu cu scope limitat.

Dovedește diagrama printr-o acțiune reală: autentifică-te cu npm, publică un pachet cu scope, instalează-l dintr-un proiect curat și confirmă că un pachet upstream este pus în cache. Presiunea probabilă vine din stocarea tarballurilor, operațiunile asupra metadatelor, instalările concurente și latența către registry-urile upstream configurate; monitorizează acest traseu în loc să tratezi toate requesturile HTTP ca fiind echivalente.

Transformă comanda locală într-un serviciu inspectabil

Folosește o comandă care expune fiecare alegere importantă. Această configurație de bază leagă Verdaccio de loopback-ul gazdei, adaugă mounturile de date cunoscute și furnizează prima setare necesară. Adaugă setările de conexiune verificate pentru configurația persistentă, stocarea htpasswd și stocarea obiectuală opțională; folosește nume private pentru serviciile private.

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

Înlocuiește tagurile flotante cu o versiune testată sau cu un digest. După pornire, inspectează docker logs --tail 200 verdaccio și confirmă că procesul ascultă pe 4873. Apoi execută acțiunea de acceptanță pentru Verdaccio; un răspuns de la pagina principală nu poate demonstra că întregul scenariu reușește: autentifică-te cu npm, publică un pachet cu scope, instalează-l dintr-un proiect curat și confirmă că un pachet upstream este pus în cache.

TLS este simplu; URL-urile generate nu sunt

Setează URL-ul public și URL-ul registry-ului npm la aceeași origine HTTPS. Direcționează hostname-ul ales către portul 4873 al containerului, transmite hostul și schema HTTPS originale și evită publicarea unei a doua origini directe.

Testează Verdaccio dintr-un client extern curat. Separă problema de ingress de limita cunoscută a aplicației — clienții npm trimit datele de autentificare către o altă gazdă sau stocarea pachetelor este read-only. O eroare de certificat, DNS sau 502 ține de rutare; un request care ajunge la Verdaccio și eșuează ulterior ține de starea aplicației, capacitate sau o cerință auxiliară. Ghidul pentru TLS cu domeniu personalizat acoperă primul grup.

Restaurează Verdaccio pe o gazdă goală

Pentru Verdaccio, siguranța redeploy-ului începe cu tarballurile pachetelor, metadatele, configurația și fișierele de autentificare. Montează /verdaccio/storage înainte de bootstrap, scrie date de test inofensive și înlocuiește containerul pentru a demonstra că acea cale este într-adevăr persistentă. Testează calea înlocuind containerul cât timp există date de test inofensive; astfel poți descoperi mounturi orientate cu un director prea sus sau prea jos.

Apoi testează recuperarea în caz de dezastru pe o gazdă goală. Folosește, acolo unde este necesar, un export al bazei de date consistent cu aplicația și verifică faptul că tarballurile private, metadatele, utilizatorii și configurația revin, iar proiectul curat instalează același pachet cu aceeași integritate. Ghidul pentru backupuri de baze de date testate prin restaurare oferă un obiectiv mai solid decât simpla verificare a creării unui fișier arhivă.

Credențiale, roluri și suprafețe expuse

Pentru Verdaccio, suprafața valoroasă nu este neapărat pagina de start. Greșeala principală este să permiți publicarea anonimă sau să folosești o configurație uplink cu drept de scriere. Contracarează deliberat acest risc: interzice publicarea anonimă, definește scope-uri pentru maintaineri și păstrează autentificarea npm atașată exact hostului registry HTTPS.

VERDACCIO_PUBLIC_URL este configurație, nu secret; păstrează-i valoarea explicită, protejând în același timp credențialele separate folosite de Verdaccio. Folosește un utilizator de container fără privilegii atunci când imaginea oferă această opțiune și nu monta credențiale care nu au legătură cu serviciul. Aplică limite de rată sau de dimensiune la ingress, acolo unde activitatea neîncrezătoare poate consuma stocarea tarballurilor, operațiunile asupra metadatelor, instalările concurente și latența către registry-urile upstream configurate.

Exerciții de simulare a defecțiunilor pentru Verdaccio

Testele de capacitate ar trebui să exercite stocarea tarballurilor, operațiunile asupra metadatelor, instalările concurente și latența către registry-urile upstream configurate, nu un request repetat către /. Rulează scenariul „autentifică-te cu npm, publică un pachet cu scope, instalează-l dintr-un proiect curat și confirmă că un pachet upstream este pus în cache” la un nivel realist de concurență și înregistrează latența, rata de eroare și creșterea stocării.

Planificarea upgrade-ului trebuie să țină cont de acest risc: sintaxa configurației, pluginurile de autentificare și metadatele pachetelor trebuie testate cu versiunea majoră țintă de Verdaccio. Testează noua versiune cu date reprezentative, apoi repetă tranzacția de acceptanță și compară rezultatul. Dacă clienții npm trimit datele de autentificare către o altă gazdă sau stocarea pachetelor este read-only, capturează tranzacția eșuată și inspectează prima limită implicată, în loc să presupui că ingress-ul este responsabil.

Demonstrează implementarea Verdaccio de la un capăt la altul

Nu transforma traficul primului utilizator în test de acceptanță pentru Verdaccio. Pregătește o stare de test inofensivă și rulează acțiunea completă „autentifică-te cu npm, publică un pachet cu scope, instalează-l dintr-un proiect curat și confirmă că un pachet upstream este pus în cache”. Notează URL-ul public exact, rezultatul, referința imaginii și intervalul de loguri asociat rulării.

Înlocuiește containerul și repetă testul fără să reconstruiești datele. Apoi recuperează serviciul pe o gazdă goală; condiția de recuperare este ca tarballurile private, metadatele, utilizatorii și configurația să revină, iar proiectul curat să instaleze același pachet cu aceeași integritate. Observă stocarea tarballurilor, operațiunile asupra metadatelor, instalările concurente și latența către registry-urile upstream configurate la fiecare trecere și definește o alertă în jurul degradării tranzacției, nu în jurul metricilor unui container inactiv.

O ultimă verificare ar trebui să eșueze intenționat: interzice temporar identității de test accesul la configurația persistentă, stocarea htpasswd și stocarea obiectuală opțională. Verifică dacă mesajul rezultat de la Verdaccio identifică limita relevantă, în loc să declanșeze ștergerea datelor sau o repornire nesfârșită. Restabilește condiția validă și confirmă că aceeași tranzacție de test reușește. Păstrează acest exercițiu scurt în checklistul de release.

Păstrează Verdaccio explicit, în timp ce Dockup gestionează rutarea

Pentru Verdaccio, Dockup poate crea ruta și certificatul TLS, poate păstra mounturile, poate livra secretele și poate plasa configurația persistentă, stocarea htpasswd și stocarea obiectuală opțională într-o rețea privată, implementând serviciul fie în Dockup, fie pe servere atașate.

Criteriul de release rămâne tranzacția concretă pentru Verdaccio: autentifică-te cu npm, publică un pachet cu scope, instalează-l dintr-un proiect curat și confirmă că un pachet upstream este pus în cache. Verifică și condiția de restaurare — tarballurile private, metadatele, utilizatorii și configurația revin, iar proiectul curat instalează același pachet cu aceeași integritate. Aceste două verificări arată dacă implementarea funcționează și dacă poate fi recuperată.

Întrebări frecvente

De ce are nevoie Verdaccio pentru o implementare în producție?

Direcționează containerul Verdaccio de pe portul 4873 printr-o singură origine HTTPS. Cerința de rețea auxiliară constă în configurație persistentă, stocare htpasswd și stocare obiectuală opțională. Nu considera Verdaccio pregătit până când nu te poți autentifica cu npm, nu poți publica un pachet cu scope, nu îl poți instala dintr-un proiect curat și nu poți confirma că un pachet upstream este pus în cache.

Ce date Verdaccio trebuie incluse într-un backup?

Persistă /verdaccio/storage și include tarballurile pachetelor, metadatele, configurația și fișierele de autentificare în același manifest de recuperare. O restaurare Verdaccio curată este reușită doar atunci când tarballurile private, metadatele, utilizatorii și configurația revin, iar proiectul curat instalează același pachet cu aceeași integritate.

Are Verdaccio nevoie de HTTPS în spatele unui reverse proxy?

Folosește HTTPS pentru originea publică Verdaccio și păstrează portul 4873 pe ruta internă. Aplică setarea Verdaccio corect: setează URL-ul public și URL-ul registry-ului npm la aceeași origine HTTPS. Pentru Verdaccio, HTTPS protejează credențialele sau conținutul utilizatorilor în tranzit și menține consecvent comportamentul clientului dependent de origine.

Cum ar trebui testat un upgrade Verdaccio?

Restaurează starea curentă Verdaccio într-o implementare izolată, aplică versiunea candidat și repetă tranzacția de acceptanță. Acordă o atenție deosebită acestui aspect, deoarece sintaxa configurației, pluginurile de autentificare și metadatele pachetelor trebuie testate cu versiunea majoră țintă de Verdaccio. Păstrează imaginea anterioară Verdaccio până când limitele migrației datelor și ale rollback-ului sunt înțelese.