Orbit
Definir Variáveis de Ambiente Por 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 permite que decida exatamente quais compilações veem quais variáveis de ambiente, para que as credenciais de produção nunca acabem num ramo de pré-visualização acessível publicamente. Este guia cobre como funcionam o escopo e a precedência, como adicionar uma variável apenas para produção, como funciona a herança de staging e como verificar o que uma compilação realmente recebeu.
Por Que Isto É Importante
Uma pré-visualização de ramo obtém um URL público. Qualquer pessoa com a ligação pode carregá-la. Se uma variável tem escopo em todos os ambientes, é injetada na compilação dessa pré-visualização e, seja qual for a operação que a pré-visualização faz com ela, fá-la com as suas credenciais de produção.
Essa é a razão inteira pela qual esta página existe. Tudo abaixo está ao serviço de uma regra: segredos de produção pertencem ao escopo de produção e em lado nenhum mais.
Como Funciona o Escopo
Cada variável tem um escopo que decide quando é injetada no momento da compilação.
| Escopo | Injetada em |
|---|---|
| Todos os ambientes (em todo o projeto) | Cada compilação deste projeto, a menos que a restrinja |
| Uma substituição de ambiente específico | Compilações apenas desse ambiente |
Quando a mesma chave existe em ambos os níveis, a mais específica vence. Uma substituição de nível de ambiente bate uma variável em todo o projeto com a mesma chave. A página de variáveis de ambiente declara isto no subtítulo da secção Todos os ambientes: as variáveis em todo o projeto estão disponíveis em cada compilação e as substituições de nível de ambiente têm precedência.
As variáveis em todo o projeto também podem ser restringidas sem se tornarem uma substituição. O controlo Available in oferece três tipos de ambiente (production, staging, preview) e pode desselecionar qualquer um deles.
Adicionar uma Variável Com um Escopo
- Abra o seu projeto em Orbit e clique no separador Env vars.
- Desloque-se para o formulário Add variable na parte inferior.
- Preencha a KEY e o value.
- Use o menu suspenso Scope:
- All environments (project-wide) injeta-a em cada compilação.
- [Environment name] only ([type] override) restringe-a a esse ambiente único.
- Se escolheu em todo o projeto, use os botões Available in para desselecionar os tipos de ambiente que esta variável não deve atingir.
- Assinale Mark as secret para algo sensível.
- Clique em Add.
Antes de confirmar, o formulário diz-lhe o que está prestes a fazer. Uma substituição mostra um aviso dizendo que se aplicará apenas às compilações desse ambiente e que as variáveis em todo o projeto ainda se aplicam noutros locais. Uma variável em todo o projeto restrita mostra exatamente em quais tipos de ambiente será injetada.
Adicionar uma Variável Apenas para Produção
Duas rotas equivalentes:
- No menu suspenso Scope, escolha o seu ambiente de produção (tem um emblema verde
production), ou - Mantenha o escopo como All environments e desselecione
stagingepreviewem Available in.
De qualquer forma, a variável está ausente quando uma compilação de pré-visualização ou staging é executada.
"Ausente" significa ausente, não vazio. O código que lê process.env.STRIPE_SECRET_KEY numa compilação de pré-visualização obtém undefined e, dependendo da forma como está escrito, pode lançar no momento da compilação ou, pior, seguir silenciosamente um ramo errado. Dê às pré-visualizações um valor de modo de teste em vez de nenhum valor.
O Padrão Seguro
O padrão que resolve isto de forma limpa para a maioria dos projetos:
- Adicione a production credential com escopo apenas para o ambiente de produção.
- Adicione uma variável com a mesma chave, mantendo um valor de teste ou sandbox, em escopo em todo o projeto.
As compilações de produção obtêm o valor com escopo de produção porque o escopo mais específico vence. As pré-visualizações e o staging obtêm o valor de teste. Nada fica indefinido em lado nenhum e nenhuma credencial de produção atinge uma pré-visualização.
Aplique-o a:
- URLs de base de dados de produção
- Chaves secretas do fornecedor de pagamentos, usando as chaves de teste do fornecedor para pré-visualizações
- Chaves de envio de correio electrónico, para que uma pré-visualização não possa enviar correio a clientes reais
- Tokens de administrador e segredos de assinatura
- Qualquer coisa com um custo por chamada
Herdar Variáveis de Produção em Staging
Se o seu ambiente de staging é próximo da produção e apenas pretende substituir alguns valores, não tem de duplicar tudo.
Em Settings, encontre Staging: environment variables e ative Inherit production env vars. As variáveis de produção são então mescladas nas compilações de staging em prioridade inferior às substituições específicas de staging, para que qualquer coisa que defina explicitamente em staging ainda vença.
A herança copia valores de produção para compilações de staging, incluindo credenciais de produção. Apenas ative se o seu ambiente de staging está protegido. O Staging suporta tanto uma palavra-passe como uma allowlist de IP, nas secções Staging: access protection e Staging: IP allowlist de Settings. Ativar herança para um ambiente de staging desprotegido recria exatamente a exposição sobre a qual esta página trata.
Ver e Editar Variáveis Existentes
O separador Env vars agrupa variáveis em:
- All environments no topo, mantendo variáveis em todo o projeto
- Uma secção colapsável por ambiente, mantendo as substituições desse ambiente, com uma contagem de quantas
Acima delas há uma caixa de pesquisa e um filtro Secrets only.
Os emblemas ao lado de cada nome de variável mostram em quais tipos de ambiente a atinge. Uma variável mostrando production e preview mas não staging faltará nas compilações de staging e essa linha de emblema é a forma mais rápida de auditar uma lista longa.
Clique no ícone de edição para alterar um valor. O valor atual de uma variável secreta não pode ser revelado, apenas substituído.
Copiar e Comparar Entre Ambientes
Copy variables between environments copia um conjunto completo de um escopo para outro. Escolha um From e um To, opcionalmente assinale Overwrite variables that already exist in the target e clique em Preview para ver quantas serão adicionadas, atualizadas e ignoradas antes de confirmar.
A página Env sync check compara produção e staging chave a chave e relata o que existe apenas num, o que tem valores diferentes e o que coincide. É a primeira paragem correta para "o staging funciona e a produção não", ou o inverso.
Valores diferentes entre produção e staging é normal e esperado para a maioria dos segredos. A página de sincronização diz isso. O que procura é uma chave presente num ambiente e ausente do outro.
Partilhar Variáveis Entre Projetos
Se vários projetos precisam da mesma credencial, use um grupo de variáveis de ambiente em vez de a colar em cada projeto. Vá para Orbit, depois Env groups, crie um grupo, adicione as variáveis e vincule os projetos que as precisam.
As variáveis do grupo são injetadas no momento da compilação e ficam no fundo da ordem de precedência: as variáveis de nível de projeto e de nível de ambiente têm precedência sobre as variáveis do grupo. Pode ter até 20 grupos numa conta.
Eliminar um grupo remove essas variáveis das compilações futuras de cada projeto vinculado. As compilações já concluídas não são afetadas.
Importar em Massa
O botão Import .env abre uma caixa de colagem. Cole um ficheiro .env, escolha um escopo e Orbit relata quantas variáveis encontrou e quantas marcará como secreto. As chaves contendo SECRET, TOKEN, KEY, PASSWORD e termos semelhantes são sinalizadas automaticamente. Há uma opção Overwrite existing variables with the same key, desativada por predefinição.
Download .env produz um modelo de nomes de variáveis apenas, sem valores, para partilhar com um colega que fornecerá o seu.
Escolha o escopo no diálogo de importação antes de clicar em Import, não depois. Importar um .env de produção inteiro em escopo em todo o projeto coloca cada credencial de produção nas suas compilações de pré-visualização numa ação e a correção é eliminá-las e adicioná-las novamente, não alterar uma configuração.
Verificar O Que Uma Compilação Realmente Recebeu
A página de detalhe de cada implementação lista as chaves de variáveis de ambiente injetadas no momento da compilação e compara-as com a sua configuração atual: adicionadas, alteradas, removidas, inalteradas. As chaves azul-petróleo vieram de uma substituição específica do ambiente, as cinzentas de nível de projeto.
Os valores nunca são armazenados ou mostrados. Pairar sobre uma chave fornece uma impressão digital SHA-256, o que é suficiente para confirmar que dois ambientes mantêm o mesmo valor sem o revelar.
Se a configuração mudou após essa implementação ser compilada, a página o diz com um aviso Environment variables updated since this deployment e recorda-lhe que a alteração não terá efeito até que reimplemente.
As alterações de variáveis nunca se aplicam à implementação que já está ativa. São injetadas quando uma compilação é executada. Depois de alterar qualquer coisa da qual a sua aplicação depende, reimplemente.
Leitura Relacionada
- Environment Variables para o básico, segredos e regras de prefixo de framework
- Branch Preview Deployments in Orbit para compreender como funcionam as pré-visualizações públicas
- Viewing Build Logs para a diferença de variáveis no momento da compilação