Mitä ovat ympäristömuuttujat ja salaisuudet? Selkeä opas

Ympäristömuuttuja on nimetty asetus, kuten DATABASE_URL tai STRIPE_SECRET_KEY, joka annetaan sovellukselle sen käynnistyessä sen sijaan, että se kirjoitettaisiin koodiin. Salaisuus on ympäristömuuttuja, jonka arvon täytyy pysyä yksityisenä: API-avain, salasana tai allekirjoitusavain. Kun nämä arvot pidetään koodin ulkopuolella, voit vaihtaa niitä muokkaamatta sovellusta, käyttää eri arvoja testaukseen ja oikeille asiakkaille sekä estää niiden vuotamisen, kun jaat tai julkaiset koodin.

Miksi tämä on tärkeää, kun rakennat tekoälyllä

Hetki, jolloin sovelluksesi tekee jotain hyödyllistä toisen palvelun kanssa, esimerkiksi ottaa maksun, lähettää sähköpostin tai kutsuu tekoälymallia, se tarvitsee avaimen. Tekoälysovellusrakentajat pyytävät näitä avaimia säännöllisesti, ja se, minne avain päätyy, ratkaisee, onko sovelluksesi turvallinen.

Tekoälyllä rakennetuissa sovelluksissa menee usein kaksi asiaa pieleen:

• Avain liitetään chattiin tai koodiin. Silloin se jää chat-historiaan, projektitiedostoihin ja kaikkiin vientitiedostoihin tai repositorioihin. Kuka tahansa, joka näkee ne, voi käyttää tiliäsi.
• Avainta käytetään selaimessa. Jos koodi, joka kutsuu Stripeä tai OpenAI:ta, toimii sivulla, avain lähetetään jokaiselle kävijälle. Ihmiset katsovat tätä, ja automaattiset skannerit etsivät vuotaneita avaimia jatkuvasti.

Kun ymmärrät ympäristömuuttujat, tunnistat kumpikin ongelman ja osaat pyytää korjauksen.

Arkinen vertauskuva: hotellihuoneen kassakaappi

Sovelluksesi koodi on kuin hotellihuone. Vieraat, siivoojat ja kaikki, joille annat avainkortin, kulkevat siitä läpi. Passiasi ei jätetä pöydälle.

Ympäristömuuttujat ovat huoneen kassakaappi. Huone tietää, että kassakaappi on olemassa ja miten se avataan tarvittaessa, mutta passi ei loju siellä. Ja jos siirryt toiseen huoneeseen, esimerkiksi testiympäristöstä omalle live-sivustollesi, laitat kyseisen huoneen kassakaappiin toisen passin, ilman että huonetta täytyy remontoida.

Miten se toimii

Koodisi viittaa nimeen, ei arvoon. Palvelimella JavaScriptissä se näyttää tältä: process.env.STRIPE_SECRET_KEY. Kun sovellus käynnistyy, alusta, jolla se toimii, täyttää nimelle arvon. Kun muutat arvoa alustan asetuksissa ja käynnistät sovelluksen uudelleen tai julkaiset sen, sovellus käyttää uutta arvoa ilman koodimuutoksia.

Arvot tulevat eri paikoista sen mukaan, missä sovellus toimii:

Julkiset ja salaiset muuttujat

Kaikki ympäristömuuttujat eivät ole salaisia. Kannattaa jakaa ne kahteen ryhmään:

Web-kehykset tekevät tästä jaosta näkyvän. Vitessä selaimen koodiin sisällytetään vain muuttujat, joiden nimi alkaa etuliitteellä VITE_. Next.js:ssä etuliite on NEXT_PUBLIC_. Tämä on turvaominaisuus: kaikki näillä etuliitteillä varustettu päätyy tiedostoihin, jotka jokainen kävijä lataa, joten salaisuutta ei koskaan pidä antaa näistä etuliitteistä.

Esimerkki: tekoälyllä tiivistävä painike

Haluat painikkeen „Tiivistä tämä muistio”, joka kutsuu tekoälymallia.

Epäturvallinen tapa: painikkeen koodi selaimessa kutsuu tekoälypalvelua suoraan ja API-avain on kirjoitettu siihen. Se toimii esikatselussa. Se tarkoittaa myös, että kuka tahansa voi avata selaimen kehittäjätyökalut, kopioida avaimen ja aiheuttaa laskun tililläsi.

Turvallinen tapa:

1. Luot avaimen tekoälypalveluntarjoajalla ja tallennat sen salaisuutena nimellä OPENAI_API_KEY (tai vastaavalla) projektisi asetuksiin.
2. Taustapalvelussa on reitti POST /api/summarise, joka lukee arvon process.env.OPENAI_API_KEY-muuttujasta, tarkistaa että käyttäjä on kirjautunut sisään, ja kutsuu palveluntarjoajaa.
3. Painike kutsuu omaa reittiäsi, ei palveluntarjoajaa. Selain ei näe avainta koskaan.
4. Lisäät saman salaisuuden julkaistun sovelluksen asetuksiin ja julkaiset uudelleen, jotta myös live-sivustolla on se.

Tämä malli, jossa selain kutsuu palvelintasi ja palvelimesi pitää avainta ja kutsuu palvelua, koskee maksuja, sähköpostia, karttoja ja kaikkia muita maksullisia API-rajapintoja. Opas LLM-rajapintojen käyttöön käsittelee tekoälytapausta syvemmin.

Keskeiset termit

• .env-tiedosto: tekstitiedosto, jossa on NIMI=arvo-rivejä paikallista kehitystä varten. Lisää se .gitignore-tiedostoon, ettei sitä lähetetä gitiin.
• .env.example: kopio, jossa on nimet mutta ei oikeita arvoja. Se lisätään gitiin, jotta muut tietävät, mitkä muuttujat pitää asettaa.
• Kierrätys (rotate): salaisuuden korvaaminen uudella ja vanhan peruuttaminen.
• Laajuus / oikeudet: monet palveluntarjoajat antavat avaimia, jotka voivat tehdä vain tiettyjä asioita. Avain, joka voi vain lähettää sähköpostia, on vähemmän vaarallinen kuin avain, joka voi kaiken.
• Testi- vs. live-avaimet: palveluntarjoajat, kuten Stripe, antavat erilliset avaimet testaukseen ja oikeaan rahaan. Käytä testiavaimia, kunnes julkaiset.
• Allekirjoitussalaisuus: salaisuus, jolla tarkistetaan, että viesti, kuten webhook, todella tuli lähettäjältä.

Yleisiä virheitä ja väärinkäsityksiä

• „Repositorioni on yksityinen, joten avaimet siinä ovat hyvä.” Yksityisiä repositorioita jaetaan, haarukoidaan, viedään ja kopioidaan kannettaville. Avaimet eivät kuulu sinne. Jos yhdistät projektin GitHubiin, tarkista, ettei mukana ole .env-tiedostoa.
• „Poistin sen, joten se on kadonnut.” Git säilyttää historian ja chat-lokit säilyttävät viestit. Jos avain on koskaan vuotanut, kierrätä se.
• Julkisen etuliitteen käyttö salaisuudelle. VITE_OPENAI_KEY laittaa avaimesi selaimen koodiin.
• Uudelleenjulkaisun unohtaminen. Muuttujan muutos asetuksissa tulee yleensä voimaan vasta, kun sovellus käynnistyy uudelleen tai se julkaistaan uudelleen.
• Yksi avain kaikkeen. Erilliset avaimet testiin ja live-käyttöön sekä sovelluskohtaiset avaimet mahdollistavat yhden peruuttamisen rikkomatta muuta.
• Ei kulurajaa. Maksullisissa rajapinnoissa aseta budjetti tai raja palveluntarjoajan hallintanäkymään siltä varalta, että avain vuotaa.

Mitä pyytää tekoälyrakentajalta

• „Lue Stripen salainen avain ympäristömuuttujasta nimeltä STRIPE_SECRET_KEY. Käytä sitä vain palvelimella.”
• „Varmista, ettei mitään salaisuutta käytetä asiakaspuolen koodissa tai anneta sille VITE_- tai NEXT_PUBLIC_-etuliitettä.”
• „Luo .env.example, jossa on kaikki sovelluksen tarvitsemat muuttujat ilman arvoja, ja varmista, että .env on ohitettu gitissä.”
• „Tarkista käännetyt frontend-tiedostot merkkijonoista, jotka näyttävät API-avaimilta.”

Laajemmat turvatarkistukset, myös salaisuudet, löytyvät tekoälyllä rakennettujen sovellusten turvallisuuslistalta.

Salaisuudet Mythexissä

Mythexissä salaisuudet ovat projektin ympäristömuuttujia, jotka injektoidaan sekä esikatselun hiekkalaatikkoon että julkaistuun sovellukseesi. Lisäät ne kohdassa projektiasetukset → Salaisuudet tai komennolla /secrets chatissa. Kun agentti tarvitsee avaimen, se näyttää chatissa salaisuuskortin, joten arvo menee lomakekenttään eikä keskusteluun. Jos muutat salaisuutta live-sovellukselle, julkaise uudelleen, jotta käyttöönotto ottaa sen käyttöön. Projektien viennit jättävät salaisuudet pois, ja tuodut .env-tiedostot poistetaan, joten lisäät ne uudelleen asetuksiin. Katso ympäristömuuttujat ja salaisuudet ja salaisuudet chatissa dokumentaatiosta.

Kysymykset