Orbit
Impostazione delle variabili di ambiente per ambiente
Orbit lets you decide exactly which builds see which environment variables, so production credentials never end up in a publicly reachable branch preview. This guide covers how scope and precedence…
Orbit ti consente di decidere esattamente quali build vedono quali variabili di ambiente, quindi le credenziali di produzione non finiscono mai in un'anteprima di ramo accessibile pubblicamente. Questa guida copre come funzionano l'ambito e la precedenza, come aggiungere una variabile solo per la produzione, come si comporta l'ereditarietà dello staging e come verificare cosa una build ha effettivamente ricevuto.
Perché Questo Conta
Un'anteprima di ramo ottiene un URL pubblico. Chiunque abbia il link può caricarla. Se una variabile ha ambito su ogni ambiente, viene inserita nella build di quell'anteprima, e qualunque cosa l'anteprima faccia, la fa con le tue credenziali di produzione.
Questo è l'intero motivo per cui questa pagina esiste. Tutto ciò che segue è al servizio di una regola: i segreti di produzione appartengono all'ambito di produzione, e da nessun'altra parte.
Come Funziona l'Ambito
Ogni variabile ha un ambito che decide quando viene inserita al momento della build.
| Ambito | Inserito in |
|---|---|
| Tutti gli ambienti (a livello di progetto) | Ogni build di questo progetto, a meno che tu non lo limiti |
| Un override di ambiente specifico | Build di quel solo ambiente |
Quando la stessa chiave esiste a entrambi i livelli, quella più specifica vince. Un override a livello di ambiente batte una variabile a livello di progetto con la stessa chiave. La pagina Env vars lo afferma nel sottotitolo della sezione Tutti gli ambienti: le variabili a livello di progetto sono disponibili in ogni build e gli override a livello di ambiente hanno la precedenza.
Le variabili a livello di progetto possono anche essere ristrette senza diventare un override. Il controllo Available in offre tre tipi di ambiente (production, staging, preview) e puoi deselezionare uno qualsiasi di essi.
Aggiungere una Variabile Con un Ambito
- Apri il tuo progetto in Orbit e fai clic sulla scheda Env vars.
- Scorri fino al modulo Add variable in fondo.
- Compila la KEY e il value.
- Usa il dropdown Scope:
- All environments (project-wide) lo inserisce in ogni build.
- [Environment name] only ([type] override) lo limita a quel solo ambiente.
- Se hai scelto project-wide, usa i pulsanti Available in per deselezionare i tipi di ambiente a cui questa variabile non deve arrivare.
- Spunta Mark as secret per qualsiasi cosa sensibile.
- Fai clic su Add.
Prima di eseguire il commit, il modulo ti dice cosa sta per fare. Un override mostra un avviso dicendo che si applicherà solo alle build di quell'ambiente e che le variabili a livello di progetto si applicano comunque altrove. Una variabile a livello di progetto ristretta mostra esattamente quali tipi di ambiente riceveranno l'inserimento.
Aggiungere una Variabile Solo Per la Produzione
Due percorsi equivalenti:
- Nel dropdown Scope, scegli il tuo ambiente di produzione (ha un badge verde
production), oppure - Mantieni l'ambito come All environments e deseleziona
stagingepreviewsotto Available in.
In entrambi i casi, la variabile è assente quando un'anteprima o una build di staging viene eseguita.
"Assente" significa assente, non vuoto. Il codice che legge process.env.STRIPE_SECRET_KEY in una build di anteprima ottiene undefined, e a seconda di come è scritto potrebbe lanciare un'eccezione al momento della build o, peggio, seguire silenziosamente un ramo sbagliato. Dai alle anteprime un valore in modalità test piuttosto che nessun valore.
Il Modello Sicuro
Il modello che risolve questo in modo pulito per la maggior parte dei progetti:
- Aggiungi la credenziale di produzione con ambito solo all'ambiente di produzione.
- Aggiungi una variabile con la stessa chiave, contenente un valore di test o sandbox, a livello di ambito a livello di progetto.
Le build di produzione ottengono il valore con ambito di produzione perché l'ambito più specifico vince. Le anteprime e lo staging ottengono il valore di test. Nulla è indefinito da nessuna parte, e nessuna credenziale di produzione raggiunge mai un'anteprima.
Applicalo a:
- URL di database di produzione
- Chiavi segrete del provider di pagamento, utilizzando le chiavi di test del provider per le anteprime
- Chiavi di invio di posta, in modo che un'anteprima non possa inviare mail ai clienti reali
- Token di amministratore e segreti di firma
- Qualsiasi cosa con un costo per chiamata
Ereditare Variabili di Produzione nello Staging
Se il tuo ambiente di staging è vicino alla produzione e vuoi solo sovrascrivere alcuni valori, non devi duplicare tutto.
In Settings, trova Staging: environment variables e attiva Inherit production env vars. Le variabili di produzione vengono quindi unite alle build di staging con priorità inferiore rispetto agli override specifici dello staging, quindi qualsiasi cosa tu imposti esplicitamente sullo staging vince comunque.
L'ereditarietà copia i valori di produzione nelle build di staging, comprese le credenziali di produzione. Attivala solo se il tuo ambiente di staging è protetto. Lo staging supporta sia una password che un allowlist di IP, nelle sezioni Staging: access protection e Staging: IP allowlist di Settings. L'attivazione dell'ereditarietà per un ambiente di staging non protetto ricrea esattamente l'esposizione di cui parla questa pagina.
Visualizzare e Modificare le Variabili Esistenti
La scheda Env vars raggruppa le variabili in:
- All environments in alto, contenente le variabili a livello di progetto
- Una sezione comprimibile per ambiente, contenente gli override di quell'ambiente, con un conteggio di quanti
Sopra di essi c'è una casella di ricerca e un filtro Secrets only.
I badge accanto a ogni nome di variabile mostrano quali tipi di ambiente raggiunge. Una variabile che mostra production e preview ma non staging sarà assente dalle build di staging, e quella riga di badge è il modo più veloce per controllare un elenco lungo.
Fai clic sull'icona di modifica per cambiare un valore. Il valore corrente di una variabile segreta non può essere rivelato, solo sostituito.
Copiare e Confrontare Tra Ambienti
Copy variables between environments copia un intero set da un ambito a un altro. Scegli un From e un To, facoltativamente spunta Overwrite variables that already exist in the target, e fai clic su Preview per vedere quanti verranno aggiunti, aggiornati e saltati prima di eseguire il commit.
La pagina Env sync check confronta le chiavi di produzione e staging una per una e riporta cosa esiste solo in una, cosa ha valori diversi e cosa corrisponde. È la giusta prima tappa per "staging funziona e produzione no", o il contrario.
I valori che differiscono tra produzione e staging sono normali e previsti per la maggior parte dei segreti. La pagina di sincronizzazione lo dice. Quello che stai cercando è una chiave presente in un ambiente e assente dall'altro.
Condividere Variabili Tra Progetti
Se più progetti hanno bisogno della stessa credenziale, usa un env group piuttosto che incollarla in ogni progetto. Vai a Orbit, quindi Env groups, crea un gruppo, aggiungi le variabili e collega i progetti che ne hanno bisogno.
Le variabili del gruppo vengono inserite al momento della build e si trovano al bottom dell'ordine di precedenza: le variabili a livello di progetto e a livello di ambiente hanno precedenza sulle variabili del gruppo. Puoi avere fino a 20 gruppi su un account.
L'eliminazione di un gruppo rimuove quelle variabili dalle future build di ogni progetto collegato. Le build già completate non sono interessate.
Importazione in Blocco
Il pulsante Import .env apre una casella di incolla. Incolla un file .env, scegli un ambito, e Orbit riporta quante variabili ha trovato e quante contrassegnerà come segrete. Le chiavi contenenti SECRET, TOKEN, KEY, PASSWORD e termini simili sono contrassegnate automaticamente. C'è un'opzione Overwrite existing variables with the same key, disattivata per impostazione predefinita.
Download .env produce un modello dei nomi delle variabili solo, senza valori, per condividerlo con un collega che fornirà i propri.
Scegli l'ambito nel dialogo di importazione prima di fare clic su Import, non dopo. L'importazione di un intero file .env di produzione a livello di ambito a livello di progetto spinge ogni credenziale di produzione nelle tue build di anteprima in un'azione, e la correzione è eliminarle e aggiungerle di nuovo, non modificare un'impostazione.
Verificare Cosa una Build ha Effettivamente Ricevuto
La pagina dei dettagli di ogni distribuzione elenca le chiavi delle variabili di ambiente inserite al momento della build e le diffonde rispetto alla tua configurazione attuale: aggiunte, modificate, rimosse, invariate. Le chiavi azzurre provenivano da un override specifico dell'ambiente, quelle grigie da livello di progetto.
I valori non vengono mai archiviati o mostrati. Passando il mouse su una chiave si ottiene un'impronta digitale SHA-256, che è sufficiente per confermare che due ambienti contengono lo stesso valore senza rivelarlo.
Se la configurazione è cambiata dopo la build di quella distribuzione, la pagina lo dice con un avviso Environment variables updated since this deployment e ti ricorda che la modifica non avrà effetto fino a quando non ridistribuisci.
Le modifiche alle variabili non si applicano mai alla distribuzione che è già live. Vengono inserite quando una build viene eseguita. Dopo aver modificato qualsiasi cosa da cui la tua app dipende, ridistribuisci.
Letture Correlate
- Variabili di Ambiente per le nozioni di base, i segreti e le regole di prefisso del framework
- Branch Preview Deployments in Orbit per il funzionamento delle anteprime pubbliche
- Visualizzazione dei Log di Build per il diff delle variabili al momento della build