Ortam Değişkenleri ve Gizli Anahtarlar Nedir? Sade Bir Rehber

Bir ortam değişkeni, uygulamanız çalışırken ona verilen ve kodun içine yazılmak yerine dışarıdan okunan adlandırılmış bir ayardır; örneğin DATABASE_URL veya STRIPE_SECRET_KEY gibi. Bir gizli anahtar ise değeri özel kalması gereken bir ortam değişkenidir: bir API anahtarı, bir şifre ya da bir imzalama anahtarı. Bu değerleri kodun dışında tutmak, uygulamayı düzenlemeden değiştirebilmenizi, test ve gerçek müşteriler için farklı değerler kullanabilmenizi ve kodunuzu paylaştığınızda ya da yayımladığınızda bu değerlerin sızmasını önlemenizi sağlar.

Yapay zekâyla geliştirirken neden önemli?

Uygulamanız başka bir hizmetle işe yarar bir şey yaptığı anda, örneğin ödeme aldığında, e-posta gönderdiğinde ya da bir yapay zekâ modelini çağırdığında, bir anahtara ihtiyaç duyar. Yapay zekâ uygulama oluşturucuları bu anahtarları düzenli olarak ister ve anahtarın nereye yerleştiği uygulamanızın güvenli olup olmadığını belirler.

Yapay zekâyla oluşturulan uygulamalarda sık yapılan iki hata vardır:

• Anahtar sohbete ya da koda yapıştırılır. Bu durumda anahtar sohbet geçmişinde, proje dosyalarında ve her dışa aktarmada ya da depoda kalır. Onu gören herkes hesabınızı kullanabilir.
• Anahtar tarayıcıda kullanılır. Stripe ya da OpenAI'ı çağıran kod sayfada çalışıyorsa anahtar her ziyaretçiye gönderilir. İnsanlar bakar; otomatik tarayıcılar da açığa çıkmış anahtarları sürekli arar.

Ortam değişkenlerini anlamak, bu iki hatayı fark etmenizi ve düzeltilmesini istemenizi sağlar.

Günlük bir benzetme: otel kasası

Uygulamanızın kodu bir otel odasına benzer. Misafirler (ve temizlikçiler, ve kartlı anahtar verdiğiniz herkes) bu odadan geçer. Pasaportunuzu masanın üstünde bırakmazsınız.

Ortam değişkenleri odadaki kasa gibidir. Oda kasanın var olduğunu ve gerektiğinde nasıl açılacağını bilir, ama pasaport ortalıkta durmaz. Farklı bir odaya geçtiğinizde, yani test kurulumundan canlı sitenize geçtiğinizde, odayı yeniden dekore etmeden o odanın kasasına başka bir pasaport koyarsınız.

Nasıl çalışır?

Kodunuz bir değere değil, bir ada başvurur. Sunucuda çalışan JavaScript'te bu process.env.STRIPE_SECRET_KEY gibi görünür. Uygulama başladığında, çalıştığı platform bu ad için değeri doldurur. Değeri platformun ayarlarında değiştirin, uygulamayı yeniden başlatın ya da yeniden yayınlayın, ve uygulama yeni değeri kullanır; kodda bir değişiklik gerekmez.

Değerlerin nereden geldiği, uygulamanın nerede çalıştığına bağlıdır:

Herkese açık ve gizli değişkenler

Her ortam değişkeni gizli değildir. İki gruba ayırmak yardımcı olur:

Web çerçeveleri bu ayrımı açıkça belirtir. Vite'ta yalnızca adı VITE_ ile başlayan değişkenler tarayıcı koduna dahil edilir; Next.js'te bu önek NEXT_PUBLIC_'tir. Bu bir güvenlik özelliğidir: bu önekleri taşıyan her şey ziyaretçilerin indirdiği dosyalara girer, dolayısıyla bir gizli değere asla bu önekler verilmemelidir.

Çalışılmış bir örnek: yapay zekâ özetleme düğmesi

Bir “Bu notu özetle” düğmesi istiyorsunuz ve düğme bir yapay zekâ modelini çağıracak.

Güvensiz versiyon: Tarayıcıda çalışan düğme kodu, API anahtarını içine yazarak sağlayıcıyı doğrudan çağırır. Önizlemede çalışır. Ama herkes tarayıcının geliştirici araçlarını açıp anahtarı kopyalayabilir ve hesabınızdan masraf çıkarabilir.

Güvenli versiyon:

1. Anahtarı yapay zekâ sağlayıcısında oluşturursunuz ve proje ayarlarınızda OPENAI_API_KEY (veya benzeri) adlı bir gizli değer olarak saklarsınız.
2. Backend'de POST /api/summarise adlı bir rota olur; bu rota process.env.OPENAI_API_KEY değerini okur, kullanıcının giriş yapmış olduğunu kontrol eder ve sağlayıcıyı çağırır.
3. Düğme sağlayıcıyı değil, sizin rotanızı çağırır. Tarayıcı anahtarı asla görmez.
4. Aynı gizli değeri yayımlanmış uygulamanın ayarlarına da eklersiniz ve yeniden yayınlarsınız; böylece canlı site de değeri alır.

Bu model, yani tarayıcının sunucunuzu çağırması, sunucunuzun anahtarı tutup hizmeti çağırması, ödemelere, e-postaya, haritalara ve diğer ücretli her API için geçerlidir. LLM API'lerini kullanma rehberi yapay zekâ tarafını daha derinlemesine anlatır.

Temel terimler

• .env dosyası: Yerel geliştirmede kullanılan, AD=değer satırlarından oluşan bir metin dosyası. Git'e eklenmemesi için .gitignore dosyasına yazılmalıdır.
• .env.example: Gerçek değerler olmadan yalnızca adların yer aldığı bir kopya. Diğer kişilerin hangi değişkenleri ayarlaması gerektiğini bilmesi için commit edilir.
• Döndürmek (rotate): Bir gizli değeri yenisiyle değiştirmek ve eskisini iptal etmek.
• Kapsam / izinler: Birçok sağlayıcı yalnızca belirli işleri yapabilen anahtarlar oluşturmanıza izin verir. Yalnızca e-posta gönderebilen bir anahtar, her şeyi yapabilen bir anahtardan daha az risklidir.
• Test ve canlı anahtarlar: Stripe gibi sağlayıcılar test ve gerçek para için ayrı anahtarlar verir. Lansmana kadar test anahtarlarını kullanın.
• İmzalama anahtarı: Bir mesajın, örneğin bir webhook isteğinin, gerçekten gönderenden geldiğini doğrulamak için kullanılan gizli değer.

Yaygın hatalar ve yanlış anlamalar

• “Deposu özel olduğu için içindeki anahtarlar sorun değil.” Özel depolar da paylaşılır, çatallanır, dışa aktarılır ve dizüstü bilgisayarlara klonlanır. Anahtarlar yine de orada durmamalıdır. Projenizi GitHub ile bağlıyorsanız, hiçbir .env dosyasının dahil edilmediğini kontrol edin.
• “Sildim, yani yok oldu.” Git geçmişi tutar, sohbet kayıtları da mesajları saklar. Bir anahtar bir kez açığa çıktıysa döndürün.
• Gizli bir değere herkese açık bir önek vermek. VITE_OPENAI_KEY anahtarınızı tarayıcı paketine koyar.
• Yeniden yayınlamayı unutmak. Ayarlarda bir değişken değiştirdiğinizde bu genellikle uygulama yeniden başladıktan ya da yeniden yayınlandıktan sonra geçerli olur.
• Her şey için tek anahtar. Test ve canlı için, bir de uygulama başına ayrı anahtarlar kullanmak, birini iptal ederken diğerlerinin bozulmamasını sağlar.
• Harcama sınırı olmaması. Ücretli API'ler için, anahtar sızarsa diye sağlayıcının panelinde bir bütçe veya limit belirleyin.

Yapay zekâ oluşturucunuzdan ne istemelisiniz?

• “Stripe gizli anahtarını STRIPE_SECRET_KEY adlı bir ortam değişkeninden oku. Yalnızca sunucuda kullan.”
• “Hiçbir gizli değeri istemci tarafı kodda kullanma ve ona VITE_ / NEXT_PUBLIC_ önekini verme.”
• “Uygulamanın ihtiyaç duyduğu her değişkeni değer olmadan listeleyen bir .env.example oluştur ve .env dosyasının git tarafından yok sayıldığından emin ol.”
• “Derlenmiş frontend dosyalarında API anahtarına benzeyen herhangi bir metin olup olmadığını kontrol et.”

Yayından önce yapılması gereken kontroller arasında gizli değerler de yer alır; bunları yapay zekâyla oluşturulmuş uygulamalar için güvenlik kontrol listesi rehberinde bulabilirsiniz.

Mythex'te gizli değerler

Mythex'te gizli değerler, hem önizleme ortamına hem de yayımlanmış uygulamanıza enjekte edilen proje ortam değişkenleridir. Bunları proje ayarları → Secrets altından ya da sohbette /secrets komutuyla ekleyebilirsiniz. Ajan bir anahtara ihtiyaç duyduğunda sohbette bir gizli değer kartı gösterir; böylece değer sohbet dökümüne değil, bir form alanına girer. Canlı bir uygulama için bir gizli değeri değiştirirseniz, yayının değeri almasını sağlamak için yeniden yayınlayın. Proje dışa aktarmalarında gizli değerler yer almaz ve içe aktarılan .env dosyaları temizlenir; bu yüzden değerleri ayarlardan yeniden eklemeniz gerekir. Ayrıntılar için dokümantasyondaki ortam değişkenleri ve gizli değerler ve sohbette gizli değerler sayfalarına bakın.

Sorular