Verdaccio 2026 selbst hosten: npm-Authentifizierung, Storage und TLS

Verdaccio selbst zu hosten wird beim ersten Redeploy interessant, nicht beim ersten docker run. Wenn npm-Clients Authentifizierungsdaten an einen anderen Host senden oder der Package-Storage schreibgeschützt ist, kann Docker trotzdem einen vollkommen gesunden Prozess melden. Die folgende Bereitstellung orientiert sich an beobachtbarem Verhalten: mit npm anmelden, ein Scoped Package veröffentlichen, es aus einem sauberen Projekt installieren und bestätigen, dass ein Upstream-Package zwischengespeichert wird.

Die vorgesehene Aufgabe von Verdaccio ist klar: eine private npm-Registry für interne Packages. Diese Beschreibung zeigt, was öffentlich bleiben muss, was privat bleiben sollte und was ein Backup wiederherstellen muss.

Ports, Prozesse und private Services

Ein nützliches Verdaccio-Diagramm zeigt die öffentliche Route, den privaten Port 4873, die Zustandsgrenze und jede unterstützende Anforderung. Kennzeichne, welche Pfeile Zugangsdaten übertragen und welche normalen Benutzer-Traffic transportieren. Der Netzwerkvertrag für Verdaccio umfasst persistente Konfiguration, htpasswd-Storage und optionalen Object-Storage. Halte private Endpunkte im internen DNS, erlaube nur erforderliche ausgehende Verbindungen und gib Verdaccio ein eingeschränktes Service-Credential.

Belege das Diagramm mit einer echten Aktion: mit npm anmelden, ein Scoped Package veröffentlichen, es aus einem sauberen Projekt installieren und bestätigen, dass ein Upstream-Package zwischengespeichert wird. Die wahrscheinliche Belastung entsteht durch Tarball-Storage, Metadatenoperationen, parallele Installationen und die Latenz zu konfigurierten Upstream-Registries. Überwache daher diesen Pfad, statt alle HTTP-Requests gleich zu behandeln.

Den lokalen Befehl in einen überprüfbaren Service verwandeln

Verwende einen Befehl, der jede wichtige Einstellung sichtbar macht. Diese Ausgangskonfiguration bindet Verdaccio an das Loopback-Interface des Hosts, fügt die bekannten Daten-Mounts hinzu und setzt die erste erforderliche Einstellung. Ergänze die geprüften Verbindungseinstellungen für persistente Konfiguration, htpasswd-Storage und optionalen Object-Storage. Verwende für private Services private Namen.

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

Ersetze Floating Tags durch eine getestete Version oder einen Digest. Prüfe nach dem Start docker logs --tail 200 verdaccio und bestätige, dass der Prozess auf Port 4873 lauscht. Führe anschließend die Verdaccio-Abnahmeaktion aus. Eine Antwort von der Root-Seite kann nicht belegen, dass das vollständige Szenario erfolgreich ist: mit npm anmelden, ein Scoped Package veröffentlichen, es aus einem sauberen Projekt installieren und bestätigen, dass ein Upstream-Package zwischengespeichert wird.

TLS ist einfach – generierte URLs sind es nicht

Setze die öffentliche URL und die npm-Registry-URL auf denselben HTTPS-Origin. Leite den gewählten Hostnamen an Container-Port 4873 weiter, übertrage den ursprünglichen Host und das HTTPS-Schema und veröffentliche keinen zweiten direkten Origin.

Teste Verdaccio von einem sauberen externen Client aus. Trenne einen Ingress-Fehler von der bekannten Anwendungsschranke — npm-Clients senden Authentifizierungsdaten an einen anderen Host oder der Package-Storage ist schreibgeschützt. Ein Zertifikats-, DNS- oder 502-Fehler gehört zum Routing. Erreicht ein Request Verdaccio und schlägt erst später fehl, liegt die Ursache bei Application State, Kapazität oder einer unterstützenden Anforderung. Der Leitfaden für TLS mit eigener Domain behandelt die erste Gruppe.

Verdaccio auf einem leeren Host wiederherstellen

Bei Verdaccio beginnt die Sicherheit eines Redeployments mit Package-Tarballs, Metadaten, Konfiguration und Authentifizierungsdateien. Mounte /verdaccio/storage vor dem Bootstrap, schreibe harmlose Beispieldaten und ersetze den Container, um zu beweisen, dass dieser Pfad tatsächlich persistent ist. Teste den Pfad, indem du den Container ersetzt, während harmlose Beispieldaten vorhanden sind. So werden Mounts sichtbar, die um ein Verzeichnis zu hoch oder zu tief angesetzt sind.

Teste anschließend die Disaster Recovery auf einem leeren Host. Verwende bei Bedarf einen anwendungskonsistenten Datenbankexport und überprüfe, dass private Tarballs, Metadaten, Benutzer und Konfiguration zurückkehren und das saubere Projekt dasselbe Package-Integrity-Ergebnis erhält. Der Leitfaden für getestete Datenbankwiederherstellungen bietet ein belastbareres Ziel, als lediglich zu prüfen, ob eine Archivdatei erstellt wurde.

Zugangsdaten, Rollen und Angriffsflächen

Bei Verdaccio ist die wertvolle Angriffsfläche nicht unbedingt die Landingpage. Der häufigste Fehler besteht darin, anonymes Veröffentlichen zu erlauben oder eine schreibbare Uplink-Konfiguration zu verwenden. Begegne dem bewusst: Verbiete anonymes Veröffentlichen, beschränke Maintainer und verknüpfe die npm-Authentifizierung mit dem exakten HTTPS-Registry-Host.

VERDACCIO_PUBLIC_URL ist eine Konfiguration und kein Secret. Halte den Wert explizit, während du die separaten von Verdaccio verwendeten Zugangsdaten schützt. Verwende einen unprivilegierten Container-User, sofern das Image dies unterstützt, und mounte keine nicht zugehörigen Zugangsdaten. Setze am Ingress Rate- oder Größenlimits, wenn nicht vertrauenswürdige Workloads Tarball-Storage, Metadatenoperationen, parallele Installationen und die Latenz zu konfigurierten Upstream-Registries belasten können.

Fehlerübungen für Verdaccio

Kapazitätstests sollten Tarball-Storage, Metadatenoperationen, parallele Installationen und die Latenz zu konfigurierten Upstream-Registries prüfen, nicht wiederholte Requests an /. Führe das Szenario „mit npm anmelden, ein Scoped Package veröffentlichen, es aus einem sauberen Projekt installieren und bestätigen, dass ein Upstream-Package zwischengespeichert wird“ mit realistischer Parallelität aus und protokolliere Latenz, Fehlerrate und Storage-Wachstum.

Die Upgrade-Planung muss dieses Risiko berücksichtigen: Konfigurationssyntax, Authentifizierungs-Plugins und Package-Metadaten sollten gegen die Ziel-Major-Version von Verdaccio getestet werden. Teste das neue Release mit repräsentativen Eingaben, führe anschließend die Abnahmetransaktion erneut aus und vergleiche das Ergebnis. Wenn npm-Clients Authentifizierungsdaten an einen anderen Host senden oder der Package-Storage schreibgeschützt ist, erfasse die fehlschlagende Transaktion und untersuche die erste betroffene Grenze, statt automatisch den Ingress verantwortlich zu machen.

Die Verdaccio-Bereitstellung vollständig überprüfen

Mache den Traffic des ersten Benutzers nicht zum Abnahmetest für Verdaccio. Bereite harmlose Beispieldaten vor und führe die vollständige Aktion „mit npm anmelden, ein Scoped Package veröffentlichen, es aus einem sauberen Projekt installieren und bestätigen, dass ein Upstream-Package zwischengespeichert wird“ aus. Notiere die exakte öffentliche URL, das Ergebnis, die Image-Referenz und das zum Lauf gehörende Log-Intervall.

Ersetze den Container und wiederhole den Vorgang, ohne die Daten neu aufzubauen. Stelle anschließend auf einem leeren Host wieder her. Die Wiederherstellungsbedingung ist, dass private Tarballs, Metadaten, Benutzer und Konfiguration zurückkehren und das saubere Projekt dasselbe Package-Integrity-Ergebnis erhält. Beobachte bei jedem Durchlauf Tarball-Storage, Metadatenoperationen, parallele Installationen und die Latenz zu konfigurierten Upstream-Registries. Definiere einen Alert anhand einer Verschlechterung der Transaktion und nicht anhand inaktiver Container-Metriken.

Eine letzte Prüfung sollte absichtlich fehlschlagen: Verweigere der Testidentität vorübergehend den Zugriff auf persistente Konfiguration, htpasswd-Storage und optionalen Object-Storage. Überprüfe, dass die resultierende Verdaccio-Meldung die relevante Grenze identifiziert, statt eine Datenlöschung oder einen endlosen Neustart auszulösen. Stelle die gültige Bedingung wieder her und bestätige, dass dieselbe Beispieltransaktion erfolgreich ist. Nimm diese kurze Übung in die Release-Checkliste auf.

Verdaccio explizit halten, während Dockup das Routing übernimmt

Für Verdaccio kann Dockup die Route und das TLS-Zertifikat erstellen, Mounts erhalten, Secrets bereitstellen und persistente Konfiguration, htpasswd-Storage und optionalen Object-Storage in einem privaten Netzwerk platzieren – bei einer Bereitstellung auf Dockup oder auf angebundenen Servern.

Das Release-Gate bleibt trotzdem die konkrete Verdaccio-Transaktion: mit npm anmelden, ein Scoped Package veröffentlichen, es aus einem sauberen Projekt installieren und bestätigen, dass ein Upstream-Package zwischengespeichert wird. Überprüfe außerdem die Wiederherstellungsbedingung: Private Tarballs, Metadaten, Benutzer und Konfiguration kehren zurück und das saubere Projekt installiert dasselbe Package-Integrity-Ergebnis. Diese beiden Prüfungen zeigen, ob die Bereitstellung funktioniert und ob sie wiederhergestellt werden kann.

Häufig gestellte Fragen

Was benötigt Verdaccio für eine produktive Bereitstellung?

Leite den Verdaccio-Container über einen HTTPS-Origin auf Port 4873 weiter. Die unterstützende Netzwerkanforderung umfasst persistente Konfiguration, htpasswd-Storage und optionalen Object-Storage. Erkläre Verdaccio erst dann für bereit, wenn du dich mit npm anmelden, ein Scoped Package veröffentlichen, es aus einem sauberen Projekt installieren und bestätigen kannst, dass ein Upstream-Package zwischengespeichert wird.

Welche Verdaccio-Daten gehören in ein Backup?

Mache /verdaccio/storage persistent und nimm Package-Tarballs, Metadaten, Konfiguration und Authentifizierungsdateien in dasselbe Wiederherstellungsmanifest auf. Eine saubere Verdaccio-Wiederherstellung ist erst erfolgreich, wenn private Tarballs, Metadaten, Benutzer und Konfiguration zurückkehren und das saubere Projekt dasselbe Package-Integrity-Ergebnis erhält.

Benötigt Verdaccio hinter einem Reverse Proxy HTTPS?

Verwende HTTPS für den öffentlichen Verdaccio-Origin und halte Port 4873 auf der internen Route. Setze die Verdaccio-Einstellung korrekt: Die öffentliche URL und die npm-Registry-URL müssen auf denselben HTTPS-Origin zeigen. Bei Verdaccio schützt HTTPS Zugangsdaten oder Benutzerinhalte während der Übertragung und sorgt für konsistentes, vom Origin abhängiges Client-Verhalten.

Wie sollte ein Verdaccio-Upgrade getestet werden?

Stelle den aktuellen Verdaccio-Zustand in einer isolierten Bereitstellung wieder her, spiele die Kandidatenversion ein und wiederhole die Abnahmetransaktion. Gehe dabei besonders sorgfältig vor, da Konfigurationssyntax, Authentifizierungs-Plugins und Package-Metadaten gegen die Ziel-Major-Version von Verdaccio getestet werden sollten. Behalte das bisherige Verdaccio-Image, bis die Grenzen für Datenmigration und Rollback verstanden sind.