Ի՞նչ են միջավայրի փոփոխականները և գաղտնիքները. պարզ ուղեցույց

Միջավայրի փոփոխականը (environment variable) անվանված արժեք է, օրինակ՝ DATABASE_URL կամ STRIPE_SECRET_KEY, որը ձեր հավելվածին տրվում է աշխատելու ժամանակ՝ կոդի մեջ գրվելու փոխարեն։ Գաղտնիքը միջավայրի փոփոխական է, որի արժեքը պետք է մնա գաղտնի՝ API բանալի, գաղտնաբառ կամ ստորագրման բանալի։ Այս արժեքները կոդից դուրս պահելով՝ կարող եք դրանք փոխել առանց հավելվածը խմբագրելու, տարբեր արժեքներ օգտագործել փորձարկման և իրական հաճախորդների համար, և կանխել դրանց արտահոսքը, երբ կիսվում կամ հրապարակում եք ձեր կոդը։

Ինչու է դա կարևոր AI-ով կառուցելիս

Հենց որ ձեր հավելվածը օգտագործում է այլ ծառայություն՝ վճարում է ընդունում, էլ․ նամակ ուղարկում կամ AI մոդել է կանչում, դրան բանալի է պետք։ AI հավելվածների կառուցիչները կանոնավոր կերպով հարցնում են այս բանալիները, և այն, թե որտեղ է բանալին հայտնվում, որոշում է, արդյոք ձեր հավելվածն անվտանգ է։

Երկու բան հաճախ սխալ է ընթանում AI-ով կառուցված հավելվածներում․

• Բանալին տեղադրվում է չատի կամ կոդի մեջ։ Այն հայտնվում է չատի պատմության, նախագծի ֆայլերի և ցանկացած արտահանման կամ պահոցի մեջ։ Ով էլ տեսնի դրանք, կարող է օգտագործել ձեր հաշիվը։
• Բանալին օգտագործվում է բրաուզերում։ Եթե Stripe-ին կամ OpenAI-ին կանչող կոդը աշխատում է էջում, բանալին ուղարկվում է յուրաքանչյուր այցելուի։ Մարդիկ նայում են, իսկ ավտոմատ սկաներները անընդհատ փնտրում են բացահայտված բանալիներ։

Միջավայրի փոփոխականները հասկանալը թույլ է տալիս տեսնել երկուսն էլ և խնդրել շտկումը։

Ամենօրյա անալոգիա՝ հյուրանոցի սեյֆը

Ձեր հավելվածի կոդը նման է հյուրանոցի սենյակին։ Հյուրերը (և մաքրողները, և բոլորը, ում տվել եք քարտը) անցնում են դրանով։ Դուք ձեր անձնագիրը սեղանին չէիք թողնի։

Միջավայրի փոփոխականները սենյակի սեյֆն են։ Սենյակը գիտի, որ սեյֆ կա և ինչպես բացել այն, երբ պետք է, բայց անձնագիրը ոչ ոքի աչքին չի ընկնում։ Եվ եթե տեղափոխվում եք այլ սենյակ՝ թեստային կարգավորումից դեպի կենդանի կայք, դուք այդ սենյակի սեյֆում մեկ այլ անձնագիր եք դնում՝ առանց սենյակը վերանորոգելու։

Ինչպես է աշխատում

Ձեր կոդը վերաբերում է անվանը, ոչ թե արժեքին։ Սերվերի վրա JavaScript-ում դա այսպես է երևում՝ process.env.STRIPE_SECRET_KEY։ Երբ հավելվածը սկսվում է, այն հարթակը, որի վրա աշխատում է, լրացնում է այդ անվան արժեքը։ Փոխեք արժեքը հարթակի կարգավորումներում, վերագործարկեք կամ նորից տեղադրեք, և հավելվածն արդեն նորն է օգտագործում՝ առանց կոդի փոփոխության։

Արժեքների աղբյուրը կախված է նրանից, թե որտեղ է աշխատում հավելվածը․

Հանրային և գաղտնի փոփոխականներ

Ոչ բոլոր միջավայրի փոփոխականներն են գաղտնի։ Օգտակար է դրանք բաժանել երկու խմբի․

Վեբ ֆրեյմվորքները այս բաժանումն ակնհայտ են դարձնում։ Vite-ում բրաուզերի կոդում ընդգրկվում են միայն VITE_ նախածանցով անունները, իսկ Next.js-ում նախածանցն է NEXT_PUBLIC_։ Սա անվտանգության գործառույթ է․ այս նախածանցներով ամեն ինչ հայտնվում է յուրաքանչյուր այցելուի ներբեռնած ֆայլերում, ուստի գաղտնիքին այդ նախածանցը երբեք չպետք է տրվի։

Աշխատած օրինակ՝ AI ամփոփման կոճակ

Ուզում եք «Ամփոփել այս նշումը» կոճակ, որը կանչում է AI մոդել։

Անապահով տարբերակ։ կոճակի կոդը, որ աշխատում է բրաուզերում, ուղղակիորեն կանչում է AI մատակարարին՝ կոդի մեջ գրված API բանալիով։ Նախադիտման մեջ աշխատում է։ Բայց ցանկացած մարդ կարող է բացել բրաուզերի մշակողական գործիքները, պատճենել բանալին և ձեր հաշվից գումար ծախսել։

Ապահով տարբերակ։

1. Մատակարարի մոտ ստեղծում եք բանալին և պահում այն որպես գաղտնիք՝ օրինակ՝ OPENAI_API_KEY անունով, ձեր նախագծի կարգավորումներում։
2. Backend-ում ավելանում է երթուղի՝ POST /api/summarise, որը կարդում է process.env.OPENAI_API_KEY-ը, ստուգում է, որ օգտատերը մուտք է գործել, և կանչում է մատակարարին։
3. Կոճակը կանչում է ձեր երթուղին, ոչ թե մատակարարին։ Բրաուզերը երբեք չի տեսնում բանալին։
4. Նույն գաղտնիքն ավելացնում եք հրապարակված հավելվածի կարգավորումներում և նորից տեղադրում, որպեսզի կենդանի կայքն էլ ունենա այն։

Այս օրինաչափությունը՝ բրաուզերը կանչում է ձեր սերվերը, սերվերը պահում է բանալին և կանչում ծառայությունը, կիրառվում է վճարումների, էլ․ փոստի, քարտեզների և յուրաքանչյուր մյուս վճարովի API-ի համար։ Ուղեցույցը LLM API-ների օգտագործման մասին ավելի խորությամբ է անդրադառնում AI դեպքին։

Հիմնական տերմիններ

• .env ֆայլ․ NAME=value տողերից բաղկացած տեքստային ֆայլ, որը օգտագործվում է տեղական մշակման մեջ։ Ավելացրեք այն .gitignore-ում, որպեսզի git-ում չհայտնվի։
• .env.example․ պատճեն՝ անուններով, բայց առանց իրական արժեքների, որը պահվում է git-ում, որպեսզի մյուսները իմանան, թե ինչ փոփոխականներ պետք է սահմանեն։
• Rotate (փոխել)․ գաղտնիքը փոխարինել նորով և չեղարկել հինը։
• Շրջանակ / թույլտվություններ․ շատ մատակարարներ թույլ են տալիս ստեղծել բանալիներ, որոնք կարող են միայն որոշ գործողություններ կատարել։ Բանալին, որը կարող է միայն էլ․ նամակ ուղարկել, պակաս վտանգավոր է, քան այն, որը ամեն ինչ կարող է։
• Թեստային և կենդանի բանալիներ․ այնպիսի մատակարարներ, ինչպիսին Stripe-ն է, տալիս են առանձին բանալիներ թեստավորման և իրական գումարի համար։ Մինչև գործարկումը օգտագործեք թեստային բանալիներ։
• Ստորագրման գաղտնիք (signing secret)․ գաղտնիք, որով ստուգվում է, որ հաղորդագրությունը, օրինակ՝ webhook, իսկապես ուղարկողից է։

Տարածված սխալներ և թյուրըմբռնումներ

• «Իմ պահոցը մասնավոր է, ուրեմն բանալիները դրանում նորմալ են։» Մասնավոր պահոցները կիսվում են, պատճենվում և բեռնվում նոութբուքներ։ Բանալիները այնտեղ տեղ չունեն։ Եթե նախագիծը միացնում եք GitHub-ին, ստուգեք, որ .env ֆայլ չկա։
• «Ես ջնջեցի այն, ուրեմն կորավ։» Git-ը պահում է պատմությունը, իսկ չատի գրառումները՝ հաղորդագրությունները։ Եթե բանալին երբևէ բացահայտվել է, փոխեք այն։
• Գաղտնիքին հանրային նախածանց տալը։ VITE_OPENAI_KEY-ը բանալին դնում է բրաուզերի փաթեթում։
• Նորից տեղադրելը մոռանալը։ Փոփոխականը կարգավորումներում փոխելուց հետո այն սովորաբար ուժի մեջ է մտնում միայն հավելվածը վերագործարկելուց կամ նորից հրապարակելուց հետո։
• Մեկ բանալի ամեն ինչի համար։ Առանձին բանալիներ թեստի և կենդանի միջավայրի, ինչպես նաև յուրաքանչյուր հավելվածի համար թույլ են տալիս մեկը չեղարկել՝ առանց մյուսները խզելու։
• Ծախսերի սահման չկա։ Վճարովի API-ների համար սահմանեք բյուջե կամ սահման մատակարարի վահանակում՝ բանալին արտահոսելու դեպքի համար։

Ինչ խնդրել AI կառուցիչից

• «Կարդա Stripe-ի գաղտնի բանալին STRIPE_SECRET_KEY անունով միջավայրի փոփոխականից։ Օգտագործիր այն միայն սերվերի վրա։»
• «Համոզվիր, որ ոչ մի գաղտնիք չի օգտագործվում կլիենտական կոդում և չունի VITE_ կամ NEXT_PUBLIC_ նախածանց։»
• «Ստեղծիր .env.example ֆայլ՝ հավելվածի բոլոր փոփոխականների անուններով, առանց արժեքների, և համոզվիր, որ .env-ը git-ի կողմից անտեսվում է։»
• «Ստուգիր կառուցված frontend ֆայլերը՝ API բանալու տեսք ունեցող տողերի համար։»

Մեր անվտանգության ստուգաթերթը AI-ով կառուցված հավելվածների համար-ը գաղտնիքները ներառում է մյուս ստուգումների հետ միասին, որոնք արժե անել գործարկումից առաջ։

Գաղտնիքներ Mythex-ում

Mythex-ում գաղտնիքները նախագծի միջավայրի փոփոխականներ են, որոնք ներմուծվում են և՛ նախադիտման սանդբոքս, և՛ հրապարակված հավելված։ Ավելացնում եք դրանք նախագծի կարգավորումներ → Secrets բաժնում կամ չատում /secrets հրամանով։ Երբ agent-ին բանալի է պետք, չատում ցուցադրվում է գաղտնիքների քարտ, այնպես որ արժեքը գնում է ձևի դաշտ, ոչ թե հաղորդագրության տեքստի մեջ։ Եթե կենդանի հավելվածի գաղտնիքը փոխում եք, նորից հրապարակեք, որպեսզի տեղակայումն այն վերցնի։ Նախագծի արտահանումները գաղտնիքները չեն ներառում, իսկ ներմուծված .env ֆայլերից դրանք հանվում են, որպեսզի դրանք նորից ավելացնեք կարգավորումներում։ Տե՛ս փաստաթղթերում միջավայրի փոփոխականները և գաղտնիքները և գաղտնիքները չատում։

Հարցեր