Salta al contenuto principale
Versione: 6.x

Migliori Pratiche

La guida seguente è un elenco delle migliore pratiche raccolte e che raccomandiamo solitamente a tutti gli utenti. Non considerare questa guida come obbligatoria, puoi selezionare qualcuna di esse a seconda delle tue esigenze.

Suggerisci le tue migliori pratiche alla community di Verdaccio.

Registro Privato​

È possibile aggiungere utenti e gestire quali utenti possono accedere a quali pacchetti.

È raccomandabile definire un prefisso per i tuoi pacchetti privati, per esempio local-* o @my-company/* con scope, così che tutti i tuoi elementi privati appariranno così: local-foo. In questo modo si possono separare chiaramente i pacchetti pubblici da quelli privati.

 packages:
   '@my-company/*':
     access: $all
     publish: $authenticated
    'local-*':
     access: $all
     publish: $authenticated
   '@*/*':
     access: $all
     publish: $authenticated
   '**':
     access: $all
     publish: $authenticated

Ricorda sempre, l'ordine dell'accesso ai pacchetti è importante, i pacchetti sono sempre considerati dall'alto verso il basso.

Utilizzo dei pacchetti pubblici da npmjs.org​

Se qualche pacchetto non esiste nell'archivio, il server proverà a recuperarlo da npmjs.org. Se npmjs.org non funziona, fornirà solo i pacchetti presenti nella cache come se non ne esistessero altri. Verdaccio scaricherà solo ciò che è necessario (= richiesto dai client) e questa informazione verrà memorizzata nella cache, così se il client chiederà la stessa cosa una seconda volta, potrà essere soddisfatto senza doverla chiedere a npmjs.org.

Esempio:

Se fai una richiesta express@4.0.1 da questo server che va a buon fine una volta, sarà possibile farla un'altra volta (con tutte le sue dipendenze) in ogni momento, anche con npmjs.org non funzionante. Però diciamo che express@4.0.0 non verrà scaricato fino a che non sia effettivamente necessario per qualcuno. E se npmjs.org è offline, questo server direbbe che solo express@4.0.1 (= solo quello che è nella cache) viene pubblicato, ma nient'altro.

Sovrascrivi i pacchetti pubblici​

Se desideri utilizzare una versione modificata di qualche pacchetto pubblico foo, puoi pubblicarla direttamente sul tuo server locale, così quando scrivi npm install foo, considererà di installare la tua versione.

Ci sono due opzioni qui:

  1. Desideri creare un fork separato e interrompere la sincronizzazione con la versione pubblica.

    Se si vuole fare ciò, si dovrebbe modificare il file di configurazione affinché verdaccio non faccia più richieste a npmjs riguardo a questi pacchetti. Aggiungi una voce separata per questo pacchetto a config.yaml, rimuovi npmjs dalla lista proxy e riavvia il server.

    packages:
      '@my-company/*':
        access: $all
        publish: $authenticated
        # comment it out or leave it empty
        # proxy:

    Quando pubblichi il tuo pacchetto in locale, dovresti probabilmente iniziare con la stringa di versione superiore a quella esistente, così che non vada in conflitto con il pacchetto esistente nella cache.

  2. Si vuole temporaneamente utilizzare la propria versione, ma tornare alla pubblica appena questa sia aggiorna,.

    Per evitare conflitti delle versioni, dovresti usare un suffisso personalizzato rilasciato prima della successiva versione della patch. Per esempio, se un pacchetto pubblico ha la versione 0.1.2, puoi fare l'upload di 0.1.3-my-temp-fix.

     npm version 0.1.3-my-temp-fix
     npm publish --tag fix --registry http://localhost:4873

    In questo modo il tuo pacchetto verrà utilizzato fino a che il suo manutentore originale aggiorna il suo pacchetto pubblico alla 0.1.3.

Security​

La sicurezza nasce nel tuo ambiente.

Lettura aggiunta:

Accesso forte al pacchetto con $authenticated​

Di default tutti i pacchetti che pubblici su Verdaccio sono accessibili per tutti gli utenti. Di default tutti i pacchetti che pubblichi su Verdaccio sono accessibili a chiunque, ti raccomandiamo vivamente di proteggere il tuo registro da utenti esterni non autorizzati che aggiornano la proprietà access a $authenticated.

packages:
  '@my-company/*':
    access: $authenticated
    publish: $authenticated
  '@*/*':
    access: $authenticated
    publish: $authenticated
  '**':
    access: $authenticated
    publish: $authenticated

In questo modo, nessuno sarà in grado di utilizzare il registro fino a quando non sarà autorizzato e i pacchetti privati non verranno visualizzati nell'Interfaccia Utente.

Rimuovi il proxy per aumentare la sicurezza dei pacchetti privati​

L'utilizzo di HTTPS è una raccomandazione comune, per questa ragione raccomandiamo di leggere la sezione SSL per rendere Verdaccio sicuro o di utilizzare un HTTPS reverse proxy oltre a Verdaccio.

packages:
  '@*/*':
    access: $authenticated
    publish: $authenticated
    proxy: npmjs
  '**':
    access: $authenticated
    publish: $authenticated
    proxy: npmjs

Ciò significa che persino se un pacchetto privato come @my-company/auth è pubblicato localmente, il server guarderà al registro pubblico. Se questa non è la tua intenzione, rimuovi la proprietà proxy e usa una configurazione come la seguente:

packages:
  '@my-company/*':
    access: $authenticated
    publish: $authenticated
    unpublish: $authenticated
  '@*/*':
    access: $authenticated
    publish: $authenticated
    proxy: npmjs
  '**':
    access: $authenticated
    publish: $authenticated
    proxy: npmjs

Questo eviderà di scaricare gli archivi tar e di fondere inutilmente i meta-dati dai registri esterni.

Server​

Connessioni Assicurate​

Usare HTTPS è un consiglio comune. Per questo consigliamo di leggere la sezione SSL per rendere Verdaccio sicuro o in alternativa di usare un proxy invero HTTPS su Verdaccio.

Token in Scadenza​

Da verdaccio@3.x i token non hanno alcuna data di scadenza. Per questo abbiamo introdotto nella prossima verdaccio@4.x la funzionalità di JWT PR#896

security:
  api:
    jwt:
      sign:
        expiresIn: 15d
        notBefore: 0
  web:
    sign:
      expiresIn: 1h

Usare questa configurazione sovrascriverà il sistema corrente e potrai controllare quanto a lungò il token sarà valido.

Usare JWT migliora inoltre le prestazioni con i plugin d'autenticazione. Utilizzare JWT migliora inoltre la prestazione con i plugin di autenticazione, il vecchio sistema realizzerà una decompressione e convaliderà le credenziali in ciascuna richiesta, mentre JWT dipenderà dalla firma del token evitando l'overhead per il plugin.

Come nota a margine, in npmjs il token non scade mai.

Limite di Frequenza​

Dalla versione v5.4.0 gli endpoint critici sono stati abilitati dal limite di frequenza predefinito. I seguenti comandi sono considerati endpoint dell'utente:

  • npm token tutte le varianti
  • npm login/adduser
  • npm profile tutte le varianti supportate
  • Endpoint /sec/login del sito web dell'utente.

L'elenco di endpoint precedente è limitato a 100 richieste per 15 minuti, che è abbastanza per un uso di base, se devi aumentare questi livelli, sei pregato di controllare le opzioni di configurazione userRateLimit.

userRateLimit:
  windowMs: 50000 <- (minutes * 60 * 1000)
  max: 1000 (number of request peer windowMs)

Gli endpoint del sito web come, ricerca, pacchetti, barra laterale e dettagli sono protetti di default a 5.000 richieste per 2 minuti, configurabili anche tramite le opzioni dell'UI web.

Consigliamo di personalizzare questi valori per adattare le tue necessità ed evitare ogni tipo di attacco (DDoS) o di forza bruta agli endpoint critici.

Gli endpoint dell'API della CLI usati da, ad esempio, npm install non sono limitati a questo punto poiché non sono considerati critici, ma se troi qualsiasi buon motivo, sei pregato di aprire una discussione.