Què són les variables d'entorn i els secrets? Guia senzilla

Una variable d'entorn és una configuració amb nom —com DATABASE_URL o STRIPE_SECRET_KEY— que es passa a la teva aplicació quan s'executa, en lloc d'escriure's dins del codi. Un secret és una variable d'entorn el valor de la qual ha de ser privat: una clau d'API, una contrasenya o una clau de signatura. Mantenir aquests valors fora del codi et permet canviar-los sense editar l'aplicació, fer servir uns de diferents per a les proves i per als clients reals, i evitar que es filtrin quan comparteixes o publiques el codi.

Per què importa quan construeixes amb IA

El moment en què la teva aplicació fa alguna cosa útil amb un altre servei —cobra un pagament, envia un correu, crida un model d'IA— necessita una clau. Els constructors d'aplicacions amb IA demanen aquestes claus sovint, i on acaba la clau decideix si la teva aplicació és segura.

Hi ha dues coses que sovint surten malament en les aplicacions fetes amb IA:

• La clau s'enganxa al xat o al codi. Llavors viu a l'historial del xat, als fitxers del projecte i en qualsevol exportació o repositori. Qualsevol que la vegi pot fer servir el teu compte.
• La clau s'usa al navegador. Si el codi que crida Stripe o OpenAI s'executa a la pàgina, la clau s'envia a cada visitant. La gent hi mira, i els escàners automàtics busquen claus exposades constantment.

Entendre les variables d'entorn et permet detectar les dues coses i demanar-ne la solució.

Una analogia del dia a dia: la caixa forta de l'hotel

El codi de la teva aplicació és com l'habitació de l'hotel. Els hostes (i les netejadores, i qui tingui la targeta de la porta) hi passen. No deixaries el passaport sobre l'escriptori.

Les variables d'entorn són la caixa forta de l'habitació. L'habitació sap que hi ha una caixa forta i com obrir-la quan cal, però el passaport no està per allà. I si et canvies a una habitació diferent —de la teva configuració de prova al lloc en directe— poses un passaport diferent a la caixa forta d'aquella habitació, sense redecorar res.

Com funciona

El teu codi fa referència a un nom, no a un valor. En JavaScript al servidor, això es veu com process.env.STRIPE_SECRET_KEY. Quan l'aplicació s'inicia, la plataforma on s'executa omple el valor d'aquest nom. Canvies el valor a la configuració de la plataforma, reinicies o tornes a desplegar, i l'aplicació fa servir el nou, sense canvi de codi.

D'on surten els valors depèn d'on s'executa l'aplicació:

Variables públiques contra secretes

No totes les variables d'entorn són secretes. Ajuda a classificar-les en dos grups:

Els frameworks web fan aquesta separació explícita. A Vite, només les variables els noms de les quals comencen per VITE_ s'inclouen al codi del navegador; a Next.js, el prefix és NEXT_PUBLIC_. És una funció de seguretat: tot el que porta aquests prefixos acaba als fitxers que descarrega cada visitant, així que un secret mai no ha de tenir-ne cap.

Un exemple pràctic: un botó de resum amb IA

Vols un botó «Resumeix aquesta nota» que cridi un model d'IA.

La versió insegura: el codi del botó, executat al navegador, crida el proveïdor d'IA directament amb la clau d'API escrita dins. Funciona a la previsualització. També vol dir que qualsevol pot obrir les eines de desenvolupador del navegador, copiar la clau i fer córrer una factura al teu compte.

La versió segura:

1. Crees la clau al proveïdor d'IA i la guardes com a secret, per exemple OPENAI_API_KEY (o similar), a la configuració del projecte.
2. El backend té una ruta, POST /api/summarise, que llegeix process.env.OPENAI_API_KEY, comprova que l'usuari ha iniciat sessió i crida el proveïdor.
3. El botó crida la teva ruta, no el proveïdor. El navegador mai no veu la clau.
4. Afegeixes el mateix secret a la configuració de l'aplicació publicada i tornes a desplegar, perquè el lloc en directe també el tingui.

Aquest patró —el navegador crida el teu servidor, el teu servidor guarda la clau i crida el servei— s'aplica a pagaments, correu, mapes i a qualsevol altra API de pagament. La guia per usar APIs de LLM cobreix el cas de la IA amb més profunditat.

Termes clau

• Fitxer .env: un fitxer de text amb línies NOM=valor que s'usa en el desenvolupament local. Afegeix-lo a .gitignore perquè no es pugi.
• .env.example: una còpia amb els noms però sense valors reals, que es puja al repositori perquè els altres sàpiguen quines variables han de configurar.
• Rotar: substituir un secret per un de nou i revocar l'antic.
• Abast / permisos: molts proveïdors permeten crear claus que només poden fer certes coses. Una clau que només pot enviar correus és menys perillosa que una que ho pot fer tot.
• Claus de prova contra claus reals: proveïdors com Stripe donen claus separades per a proves i per a diners reals. Fes servir les de prova fins que llancis el projecte.
• Secret de signatura: un secret que serveix per comprovar que un missatge, com un webhook, realment ve del remitent.

Errors i idees equivocades habituals

• «El meu repositori és privat, així que les claus hi estan bé.» Els repositoris privats es comparteixen, es bifurquen, s'exporten i es clonen als portàtils. Les claus no hi pertanyen. Si connectes un projecte a GitHub, comprova que no s'hi inclogui cap fitxer .env.
• «L'he esborrat, així que ja no hi és.» Git guarda l'historial, i els registres del xat guarden els missatges. Si una clau s'ha exposat alguna vegada, rota-la.
• Posar un prefix públic a un secret. VITE_OPENAI_KEY posa la teva clau al paquet del navegador.
• Oblidar de tornar a desplegar. Canviar una variable a la configuració normalment només té efecte quan l'aplicació es reinicia o es torna a publicar.
• Una sola clau per a tot. Claus separades per a proves i per a producció, i per aplicació, permeten revocar-ne una sense trencar la resta.
• Cap límit de despesa. Per a APIs de pagament, posa un pressupost o un límit al tauler del proveïdor, per si una clau es filtra.

Què demanar al teu constructor amb IA

• «Llegeix la clau secreta d'Stripe d'una variable d'entorn anomenada STRIPE_SECRET_KEY. Fes-la servir només al servidor.»
• «Assegura't que cap secret s'usi al codi del client ni tingui el prefix VITE_ / NEXT_PUBLIC_.»
• «Crea un .env.example amb totes les variables que necessita l'aplicació, sense valors, i assegura't que .env estigui ignorat per git.»
• «Revisa els fitxers del frontend compilats per veure si hi ha cap cadena que sembli una clau d'API.»

La nostra llista de comprovacions de seguretat per a aplicacions fetes amb IA cobreix els secrets juntament amb les altres comprovacions que val la pena fer abans de llançar.

Secrets a Mythex

A Mythex, els secrets són variables d'entorn del projecte que s'injecten tant a l'entorn de previsualització com a la teva aplicació publicada. Els afegeixes a configuració del projecte → Secrets o amb /secrets al xat, i quan l'agent necessita una clau mostra una targeta de secrets al xat, de manera que el valor va a un camp de formulari i no a la transcripció del missatge. Si canvies un secret d'una aplicació en directe, publica de nou perquè el desplegament el reculli. Les exportacions del projecte deixen els secrets fora, i els fitxers .env importats s'eliminen perquè els tornis a afegir a la configuració. Consulta variables d'entorn i secrets i secrets al xat a la documentació.

Preguntes