ما هي متغيرات البيئة والأسرار؟ دليل مبسّط

متغير البيئة (environment variable) إعداد مُسمّى، مثل DATABASE_URL أو STRIPE_SECRET_KEY، يُمرَّر إلى تطبيقك عند تشغيله بدلاً من كتابته داخل الكود. السر (secret) متغير بيئة يجب أن تبقى قيمته خاصة، مثل مفتاح API أو كلمة مرور أو مفتاح توقيع. إبقاء هذه القيم خارج الكود يتيح لك تغييرها دون تعديل التطبيق، واستخدام قيم مختلفة للاختبار وللعملاء الحقيقيين، ومنع تسربها عند مشاركة الكود أو نشره.

لماذا يهم ذلك عند البناء بالذكاء الاصطناعي

بمجرد أن يقوم تطبيقك بعمل مفيد مع خدمة أخرى، مثل استقبال دفعة أو إرسال بريد إلكتروني أو استدعاء نموذج ذكاء اصطناعي، فإنه يحتاج إلى مفتاح. وأدوات بناء التطبيقات بالذكاء الاصطناعي تطلب هذه المفاتيح بانتظام، ومكان وجود المفتاح هو ما يحدد هل تطبيقك آمن.

هناك خطآن شائعان في التطبيقات المبنية بالذكاء الاصطناعي:

• لصق المفتاح في المحادثة أو في الكود. عندها يبقى في سجل المحادثة وفي ملفات المشروع وفي أي تصدير أو مستودع. ويستطيع أي شخص يراه استخدام حسابك.
• استخدام المفتاح في المتصفح. إذا كان الكود الذي يستدعي Stripe أو OpenAI يعمل داخل الصفحة، فإن المفتاح يُرسل إلى كل زائر. والماسحات الآلية تبحث عن المفاتيح المكشوفة باستمرار.

فهم متغيرات البيئة يساعدك على ملاحظة الخطأين، وعلى طلب الإصلاح.

تشبيه من الحياة اليومية: خزنة الفندق

كود تطبيقك يشبه غرفة الفندق. الضيوف، والعاملون في التنظيف، وكل من أعطيته بطاقة الدخول، يمرّون عبرها. أنت لا تترك جواز سفرك على المكتب.

متغيرات البيئة هي خزنة الغرفة. الغرفة تعرف أن هناك خزنة وكيف تفتحها عند الحاجة، لكن جواز السفر ليس ملقى على الطاولة. وإذا انتقلت من غرفة إلى أخرى، أي من إعدادات التجربة إلى الموقع الحقيقي، تضع جواز سفر مختلفاً في خزنة الغرفة الجديدة، دون أن تعيد تأثيث الغرفة.

كيف تعمل

كودك يشير إلى اسم، لا إلى قيمة. في JavaScript على الخادم يبدو ذلك هكذا: process.env.STRIPE_SECRET_KEY. عند بدء التطبيق، تملأ المنصة التي يعمل عليها القيمة لذلك الاسم. غيّر القيمة في إعدادات المنصة، ثم أعد التشغيل أو النشر، فيستخدم التطبيق القيمة الجديدة دون أي تغيير في الكود.

مكان حفظ القيم يختلف حسب مكان التشغيل:

متغيرات عامة مقابل متغيرات سرية

ليس كل متغير بيئة سرياً. من المفيد تصنيفها في مجموعتين:

أطر العمل الحديثة تجعل هذا التقسيم صريحاً. في Vite، تُضمَّن في كود المتصفح فقط المتغيرات التي تبدأ أسماؤها بـ VITE_، وفي Next.js تكون البادئة NEXT_PUBLIC_. وهذه ميزة أمان: كل ما يحمل هاتين البادئتين ينتهي في الملفات التي يُنزّلها كل زائر، لذلك لا يجوز أبداً إعطاء سر أي منهما.

مثال عملي: زر تلخيص بالذكاء الاصطناعي

تريد زراً باسم «لخّص هذه الملاحظة» يستدعي نموذج ذكاء اصطناعي.

النسخة غير الآمنة: كود الزر، الذي يعمل في المتصفح، يستدعي مزود الذكاء الاصطناعي مباشرة ومفتاح API مكتوب داخله. تعمل الميزة في المعاينة. لكنها تعني أن أي شخص يستطيع فتح أدوات المطوّر في المتصفح، ونسخ المفتاح، وتحميل فاتورة على حسابك.

النسخة الآمنة:

1. تنشئ المفتاح لدى مزود الذكاء الاصطناعي، وتحفظه كسر باسم OPENAI_API_KEY (أو ما يشابهه) في إعدادات مشروعك.
2. يحصل الخادم على مسار، POST /api/summarise، يقرأ process.env.OPENAI_API_KEY، ويتحقق من أن المستخدم مسجّل الدخول، ثم يستدعي المزود.
3. الزر يستدعي مساره أنت، لا المزود. فلا يرى المتصفح المفتاح أبداً.
4. تضيف السر نفسه إلى إعدادات التطبيق المنشور، وتعيد النشر، فيحصل الموقع المباشر على المفتاح أيضاً.

هذا النمط، أي أن المتصفح يستدعي خادمك، والخادم يحتفظ بالمفتاح ويستدعي الخدمة، ينطبق على الدفع والبريد الإلكتروني والخرائط وكل واجهة API مدفوعة أخرى. ودليل استخدام واجهات LLM API يغطي الحالة الخاصة بالذكاء الاصطناعي بعمق أكبر.

مصطلحات أساسية

• ملف .env: ملف نصي فيه أسطر بصيغة NAME=value، يُستخدم في التطوير المحلي. أضفه إلى .gitignore حتى لا يُرفع إلى git.
• .env.example: نسخة تحتوي على الأسماء دون القيم الحقيقية، وتُرفع إلى git ليعرف الآخرون المتغيرات التي يجب ضبطها.
• التدوير (Rotate): استبدال السر بسر جديد وإلغاء القديم.
• النطاق / الصلاحيات: كثير من المزودين يتيحون إنشاء مفاتيح لا تستطيع إلا تنفيذ أشياء محددة. المفتاح الذي يرسل البريد فقط أقل خطورة من مفتاح يستطيع كل شيء.
• مفاتيح الاختبار مقابل مفاتيح الإنتاج: مزودون مثل Stripe يعطونك مفاتيح منفصلة للاختبار وللأموال الحقيقية. استخدم مفاتيح الاختبار حتى تطلق مشروعك.
• سر التوقيع (Signing secret): سر يُستخدم للتحقق من أن رسالة، مثل webhook، جاءت فعلاً من المرسل.

أخطاء شائعة وتصورات خاطئة

• "المستودع خاص، فالمفاتيح داخله لا بأس بها." المستودعات الخاصة تُشارَك وتُنسخ وتُصدَّر وتُستنسخ إلى أجهزة محمولة. والمفاتيح لا مكان لها هناك. وإذا ربطت مشروعك بـ GitHub، تأكد من عدم تضمين أي ملف .env.
• "حذفته، إذن ضاع." سجل git يحتفظ بالتاريخ، وسجل المحادثات يحتفظ بالرسائل. إذا تعرّض مفتاح للكشف يوماً، فاستبدله.
• استخدام بادئة عامة على سر. المتغير VITE_OPENAI_KEY يضع مفتاحك داخل ملف المتصفح.
• نسيان إعادة النشر. تغيير متغير في الإعدادات عادةً لا يسري إلا بعد إعادة تشغيل التطبيق أو نشره من جديد.
• مفتاح واحد لكل شيء. مفاتيح منفصلة للاختبار والإنتاج ولكل تطبيق، تتيح لك إلغاء مفتاح دون كسر البقية.
• عدم وجود حد للإنفاق. بالنسبة إلى واجهات API المدفوعة، ضع ميزانية أو حداً في لوحة تحكم المزود، تحسباً لتسرب مفتاح.

ماذا تطلب من أداة البناء بالذكاء الاصطناعي

• «اقرأ مفتاح Stripe السري من متغير بيئة اسمه STRIPE_SECRET_KEY. استخدمه على الخادم فقط.»
• «تأكد من أن أي سر لا يُستخدم في كود العميل ولا يحمل البادئة VITE_ أو NEXT_PUBLIC_.»
• «أنشئ ملف .env.example يسرد كل متغير يحتاجه التطبيق دون قيم، واجعل .env مستثنى من git.»
• «افحص ملفات الواجهة الأمامية المبنية بحثاً عن أي نص يشبه مفتاح API.»

وتجد في قائمة التحقق الأمني للتطبيقات المبنية بالذكاء الاصطناعي الأسرار إلى جانب الفحوصات الأخرى التي تستحق التشغيل قبل الإطلاق.

الأسرار في Mythex

في Mythex، الأسرار متغيرات بيئة للمشروع تُحقن في كل من بيئة المعاينة وتطبيقك المنشور. تضيفها من إعدادات المشروع ← Secrets، أو باستخدام /secrets في المحادثة، وعندما يحتاج الوكيل إلى مفتاح يعرض بطاقة أسرار في المحادثة، فتُدخل القيمة في حقل نموذج بدلاً من كتابتها في نص المحادثة. وإذا غيّرت سراً لتطبيق مباشر، فانشر من جديد حتى يلتقطه النشر. صادرات المشروع لا تتضمن الأسرار، وملفات .env المستوردة تُحذف منها الأسرار، فتعيد إضافتها في الإعدادات. راجع متغيرات البيئة والأسرار والأسرار في المحادثة في الوثائق.

الأسئلة