Apa Itu Pembolehubah Persekitaran dan Rahsia? Panduan Ringkas

Pembolehubah persekitaran ialah tetapan yang diberi nama, seperti DATABASE_URL atau STRIPE_SECRET_KEY, yang diserahkan kepada aplikasi anda semasa ia berjalan, dan bukannya ditulis dalam kod. Rahsia ialah pembolehubah persekitaran yang nilainya mesti kekal persendirian: kunci API, kata laluan atau kunci tandatangan. Menyimpan nilai-nilai ini di luar kod bermakna anda boleh menukarnya tanpa mengedit aplikasi, menggunakan nilai yang berbeza untuk ujian dan untuk pelanggan sebenar, dan mengelakkannya daripada bocor apabila anda berkongsi atau menerbitkan kod anda.

Mengapa ia penting apabila anda membina dengan AI

Sebaik sahaja aplikasi anda melakukan sesuatu yang berguna dengan perkhidmatan lain, seperti menerima pembayaran, menghantar e-mel atau memanggil model AI, ia memerlukan kunci. Pembina aplikasi AI kerap meminta kunci ini, dan di mana kunci itu berakhir menentukan sama ada aplikasi anda selamat.

Dua perkara sering silap dalam aplikasi yang dibina dengan AI:

• Kunci ditampal ke dalam sembang atau kod. Kunci itu kemudian tersimpan dalam sejarah sembang, fail projek dan mana-mana eksport atau repositori. Sesiapa yang melihatnya boleh menggunakan akaun anda.
• Kunci digunakan dalam pelayar. Jika kod yang memanggil Stripe atau OpenAI berjalan dalam halaman, kunci itu dihantar kepada setiap pelawat. Orang memang memeriksanya, dan pengimbas automatik sentiasa mencari kunci yang terdedah.

Memahami pembolehubah persekitaran membantu anda mengenal pasti kedua-dua masalah ini, dan meminta pembetulannya.

Analogi harian: peti simpanan dalam bilik hotel

Kod aplikasi anda ibarat bilik hotel. Tetamu (dan tukang bersih, dan sesiapa sahaja yang anda beri kad kunci) berjalan melaluinya. Anda tidak akan meninggalkan pasport di atas meja.

Pembolehubah persekitaran ialah peti simpanan dalam bilik itu. Bilik itu tahu bahawa peti itu wujud dan cara membukanya apabila perlu, tetapi pasport tidak terdedah. Dan jika anda berpindah ke bilik lain, daripada persediaan ujian ke laman sebenar anda, anda cuma letakkan pasport yang berbeza dalam peti simpanan bilik itu, tanpa mengubah hiasan biliknya.

Cara ia berfungsi

Kod anda merujuk kepada nama, bukan nilai. Dalam JavaScript di pelayan, ia kelihatan seperti process.env.STRIPE_SECRET_KEY. Apabila aplikasi bermula, platform tempat ia berjalan mengisi nilai untuk nama itu. Tukar nilai dalam tetapan platform, mulakan semula atau terbitkan semula, dan aplikasi menggunakan nilai baharu tanpa perubahan kod.

Di mana nilai-nilai itu disimpan bergantung pada tempat aplikasi berjalan:

Pembolehubah awam berbanding rahsia

Tidak semua pembolehubah persekitaran ialah rahsia. Adalah membantu untuk mengasingkannya kepada dua kumpulan:

Rangka kerja web menjadikan pembahagian ini jelas. Dalam Vite, hanya pembolehubah yang namanya bermula dengan VITE_ dimasukkan ke dalam kod pelayar; dalam Next.js, awalannya ialah NEXT_PUBLIC_. Ini ciri keselamatan: apa-apa yang mempunyai awalan tersebut berakhir dalam fail yang dimuat turun oleh setiap pelawat, jadi rahsia tidak boleh diberi awalan itu.

Contoh kerja: butang ringkasan AI

Anda mahu butang "Ringkaskan nota ini" yang memanggil model AI.

Versi tidak selamat: kod butang, yang berjalan dalam pelayar, memanggil pembekal AI secara terus dengan kunci API ditulis di dalamnya. Ia berfungsi dalam pratonton. Tetapi ini bermakna sesiapa sahaja boleh membuka alat pembangun pelayar, menyalin kunci itu dan menjalankan bil besar pada akaun anda.

Versi selamat:

1. Anda mencipta kunci di pembekal AI dan menyimpannya sebagai rahsia bernama OPENAI_API_KEY (atau yang serupa) dalam tetapan projek anda.
2. Bahagian belakang (backend) mempunyai laluan, POST /api/summarise, yang membaca process.env.OPENAI_API_KEY, menyemak sama ada pengguna sudah log masuk, dan memanggil pembekal.
3. Butang memanggil laluan anda, bukan pembekal. Pelayar tidak sekali-kali melihat kunci itu.
4. Anda menambah rahsia yang sama pada tetapan aplikasi yang diterbitkan dan menerbitkan semula, supaya laman langsung juga mempunyainya.

Corak itu, iaitu pelayar memanggil pelayan anda dan pelayan anda memegang kunci dan memanggil perkhidmatan, terpakai untuk pembayaran, e-mel, peta dan setiap API berbayar yang lain. Panduan menggunakan API LLM membincangkan kes AI dengan lebih mendalam.

Istilah utama

• Fail .env: fail teks baris NAMA=nilai yang digunakan semasa pembangunan tempatan. Senaraikannya dalam .gitignore supaya ia tidak dimasukkan ke dalam git.
• .env.example: salinan yang mengandungi nama tetapi tiada nilai sebenar, yang dimasukkan ke dalam git supaya orang lain tahu pembolehubah mana yang perlu ditetapkan.
• Tukar (rotate): gantikan rahsia dengan yang baharu dan batalkan yang lama.
• Skop / kebenaran: banyak pembekal membolehkan anda mencipta kunci yang hanya boleh melakukan perkara tertentu. Kunci yang hanya boleh menghantar e-mel kurang berbahaya berbanding kunci yang boleh melakukan segalanya.
• Kunci ujian berbanding kunci langsung: pembekal seperti Stripe memberi kunci berasingan untuk ujian dan untuk wang sebenar. Gunakan kunci ujian sehingga anda melancarkan.
• Rahsia tandatangan: rahsia yang digunakan untuk menyemak bahawa sesuatu mesej, seperti webhook, benar-benar datang daripada penghantarnya.

Kesilapan dan salah faham yang biasa

• "Repositori saya persendirian, jadi kunci di dalamnya tidak mengapa." Repositori persendirian sering dikongsi, di-fork, dieksport dan diklon ke komputer riba. Kunci tetap tidak patut berada di situ. Jika anda menyambungkan projek ke GitHub, semak bahawa tiada fail .env disertakan.
• "Saya dah padamnya, jadi ia sudah hilang." Git menyimpan sejarah, dan log sembang menyimpan mesej. Jika kunci pernah terdedah, tukarlah.
• Menggunakan awalan awam pada rahsia. VITE_OPENAI_KEY meletakkan kunci anda dalam bundle pelayar.
• Lupa menerbitkan semula. Menukar pembolehubah dalam tetapan biasanya hanya berkesan selepas aplikasi dimulakan semula atau diterbitkan semula.
• Satu kunci untuk semua. Kunci berasingan untuk ujian dan langsung, serta setiap aplikasi, memudahkan anda membatalkan satu kunci tanpa memutuskan yang lain.
• Tiada had perbelanjaan. Untuk API berbayar, tetapkan bajet atau had dalam papan pemuka pembekal sekiranya kunci bocor.

Apa yang perlu diminta daripada pembina AI anda

• "Baca kunci rahsia Stripe daripada pembolehubah persekitaran bernama STRIPE_SECRET_KEY. Gunakannya hanya di pelayan."
• "Pastikan tiada rahsia digunakan dalam kod bahagian pelanggan atau diberi awalan VITE_ / NEXT_PUBLIC_."
• "Cipta .env.example yang menyenaraikan setiap pembolehubah yang diperlukan aplikasi, tanpa nilai, dan pastikan .env diabaikan oleh git."
• "Semak fail frontend yang dibina untuk sebarang rentetan yang kelihatan seperti kunci API."

Senarai semak keselamatan untuk aplikasi yang dibina dengan AI kami merangkumi rahsia bersama pemeriksaan lain yang patut dijalankan sebelum melancarkan.

Rahsia di Mythex

Di Mythex, rahsia ialah pembolehubah persekitaran projek yang dimasukkan ke dalam kedua-dua sandbox pratonton dan aplikasi yang diterbitkan. Anda menambahnya di bawah tetapan projek → Rahsia atau dengan /secrets dalam sembang, dan apabila ejen memerlukan kunci, ia memaparkan kad rahsia dalam sembang, supaya nilainya dimasukkan ke dalam medan borang dan bukannya dalam transkrip mesej. Jika anda menukar rahsia untuk aplikasi langsung, terbitkan semula supaya penerbitan mengambilnya. Eksport projek tidak menyertakan rahsia, dan fail .env yang diimport dibuang supaya anda menambahnya semula dalam tetapan. Lihat pembolehubah persekitaran dan rahsia dan rahsia dalam sembang dalam dokumentasi.

Soalan lazim