لحماية مفتاح LLM API، احفظه في مدير أسرار واستدعِ النموذج من خادمك فقط، لا من متصفح أو تطبيق أبدًا. خصّص لكل تطبيق أو مهمة مفتاحًا خاصًا، ودوّر المفاتيح وفق جدول، واقصرها على عناوين IP خوادمك بقائمة مسموحة، وإذا تسرّب مفتاح فألغِه أولًا ثم تحقّق ثانيًا.
يتناول هذا المقال العادات التي تحفظ المفاتيح آمنة، مع الضوابط المحددة التي توفرها BroadNet Inference. ولخطوات البوابة خطوةً بخطوة، راجع دليل مفاتيح API وقوائم عناوين IP المسموحة؛ وللميزانيات والحماية من الحلقات الخارجة عن السيطرة، راجع التحكم في إنفاق LLM API.
أين تحفظ مفتاح LLM API؟
احفظ المفاتيح في مدير أسرار أو في الأسرار المشفّرة لمنصتك، ولا تضعها في الشيفرة أبدًا. تغطي ورقة OWASP المرجعية لإدارة الأسرار الخيارات بالتفصيل. ولاحظ تحذيرها من أن متغيرات البيئة “are generally accessible to all processes and may be included in logs or system dumps” (الترجمة: «متاحة عمومًا لجميع العمليات وقد تُدرج في السجلات أو تفريغات النظام»)، لذا تفضّل OWASP ملفات الأسرار المركّبة أو جلب الأسرار من مخزن أسرار متى أمكنك الاختيار. ومتغير البيئة الذي يُملأ من مدير الأسرار عند بدء التشغيل هو الحل الوسط الشائع.
import os
from openai import OpenAI
client = OpenAI(
base_url="https://inference.broadnet.ai/v1",
api_key=os.environ["BROADNET_API_KEY"], # fails loudly if missing
)
استخدم os.environ[...]، لا os.getenv(...) مع قيمة احتياطية مكتوبة في الشيفرة؛ فالقيمة الاحتياطية هي الطريق المعتاد لوصول المفاتيح إلى Git. وللتطوير المحلي، لا بأس بملف .env إذا كان مدرجًا في .gitignore منذ الإيداع الأول. فعّل فحص الأسرار وحماية الدفع لدى مستضيف Git الذي تستخدمه. ففي GitHub، تمنع حماية الدفع عمليات الدفع التي تحتوي على صيغ أسرار معروفة قبل أن تصل إلى المستودع؛ وحماية الدفع للمستخدمين مفعّلة افتراضيًا، أما حماية الدفع على مستوى المستودع فمعطّلة افتراضيًا ويجب أن يفعّلها مسؤول المستودع أو مالك المؤسسة.
هل يمكن وضع مفتاح API في تطبيق متصفح أو جوال؟
لا. كل ما يُرسل إلى جهاز العميل يمكن استخراجه. فشيفرة الواجهة الأمامية وحزم التطبيقات علنية، مهما صُغّرت أو مُوّهت. استدعِ نموذج اللغة من خادمك، وتحقّق من هوية مستخدميك هناك، وطبّق حدودك الخاصة لكل مستخدم قبل تمرير الطلب.
والأمر نفسه ينطبق على أدوات سطح المكتب التي تسلّمها لغيرك. إذا احتاج زميل إلى وكيل برمجة، فامنحه مفتاحًا خاصًا به على حسابه بدلًا من مشاركة مفتاح واحد.
لماذا تخصّص لكل تطبيق أو مهمة مفتاحًا خاصًا؟
على BroadNet Inference يمكن أن يضم الحساب حتى عشرة مفاتيح فعّالة. استخدمها:
| تسمية المفتاح | يستخدمه |
|---|---|
prod-api |
الخادم الخلفي للإنتاج |
prod-worker |
المهام المجمّعة |
staging |
بيئة الاختبار المرحلي (staging) |
agent-ci |
وكيل البرمجة في CI |
dev-laptop-<name> |
التطوير المحلي |
عندما يتسرّب أحدها، تلغي ذلك المفتاح وحده وتستمر البقية في العمل. والتسميات تجعل الاستخدام مقروءًا أيضًا: ترى ما ينفقه كل تطبيق أو مهمة. سمِّ المفاتيح بحسب ما يستخدمها، لا بحسب من أنشأها.
كيف تحمي قوائم عناوين IP المسموحة المفتاح؟
تعني قائمة عناوين IP المسموحة أن المفتاح المسروق يفشل في أي مكان خارج بنيتك التحتية. وعلى BroadNet Inference:
- تقبل القائمة المسموحة للحساب حتى 32 مدخلًا، عنوان IPv4 أو IPv6 أو نطاق CIDR واحد في كل سطر.
- القائمة الفارغة تعني عدم وجود قيود.
- ترث المفاتيح الجديدة قائمة الحساب، إلا إذا أنشأت مفتاحًا بقائمة
allowed_ipsخاصة به، فتحلّ محل القائمة الموروثة لذلك المفتاح. - الطلب الآتي من عنوان خارج القائمة يُرفض بالخطأ 403 (“refused by model, route or IP policy”، أي «مرفوض بسبب سياسة النموذج أو المسار أو عنوان IP»).
أنشئ مفتاحًا بقائمة خاصة به عبر API البوابة:
curl -X POST https://inference.broadnet.ai/portal/keys \
-H "Authorization: Bearer $BROADNET_PORTAL_CREDENTIAL" \
-H "Content-Type: application/json" \
-d '{"label":"prod-worker","allowed_ips":["203.0.113.7","198.51.100.0/24"]}'
تحتوي الاستجابة على المفتاح الخام مرة واحدة فقط. احفظه في مدير الأسرار فورًا؛ إذ لا يمكن قراءته مرة أخرى. الخطوات الكاملة في دليل قوائم عناوين IP المسموحة.
تناسب القوائم المسموحة الخوادم ذات عناوين IP الصادرة الثابتة: خادم VPS، أو بوابة NAT، أو عنوان IP ثابت للمكتب. أما الحواسيب المحمولة على شبكات متغيرة، فاستخدم لها مفتاحًا منفصلًا بلا قائمة، وأبقِ الرصيد المعرَّض للخطر عبره صغيرًا.
لماذا تفصل مفاتيح الاستدلال عن بيانات اعتماد الإدارة؟
تستخدم BroadNet نوعين من بيانات الاعتماد:
| بيانات الاعتماد | ما يمكنها فعله | أين تحفظها |
|---|---|---|
| مفتاح الاستدلال | طلبات النماذج إلى /v1/* |
حيث يعمل التطبيق |
| بيانات اعتماد البوابة | إنشاء المفاتيح وإلغاؤها، وتعديل عناوين IP المسموحة، وإجراء المشتريات | في أدوات الأتمتة أو الإدارة لديك فقط |
يقول التوثيق إن كل بيانات اعتماد للبوابة تُعامَل على أنها صلاحية كاملة على الحساب. لا تنشر بيانات اعتماد البوابة بجوار تطبيقك أبدًا. فإذا اختُرق خادم تطبيقك، ينبغي أن يحصل المهاجم على مفتاح استدلال واحد، لا على التحكم في الحساب.
كم مرة يجب تدوير مفاتيح API؟
توصي OWASP بالتدوير المنتظم “so that any stolen credentials will only work for a short time.” (الترجمة: «حتى لا تعمل أي بيانات اعتماد مسروقة إلا لوقت قصير.») ومفاتيح BroadNet تصلح لعام واحد من إنشائها، لذا سيحتاج كل مفتاح إلى استبدال على أي حال. اجعل التدوير روتينًا:
- أنشئ مفتاحًا جديدًا بنمط التسمية نفسه والقائمة المسموحة نفسها.
- انشره إلى جانب القديم، أو بدّل السر وأعد التشغيل.
- راقب انتقال الحركة إلى المفتاح الجديد.
- ألغِ المفتاح القديم عبر
DELETE /portal/keys/{alias}.
ولأن الحساب يمكن أن يضم حتى عشرة مفاتيح فعّالة، يمكنك تشغيل المفتاحين القديم والجديد معًا لبضع دقائق دون توقف. ودوّر أسرع المفاتيح التي كان بإمكان عضو مغادر في الفريق الوصول إليها.
ماذا تفعل عندما يتسرّب مفتاح؟
عندما يتسرّب مفتاح، ألغِه أولًا وتحقّق ثانيًا. على BroadNet Inference تتوقف الطلبات الجديدة خلال خمس ثوانٍ من الإلغاء أو تعديل القائمة المسموحة؛ ويشرح التوثيق أن قرارات التفويض قد تبقى في ذاكرة تخزين مؤقت متماثلة طوال تلك المدة المحدودة.
بعد الإلغاء:
- افحص استخدام المفتاح في صفحة الحساب أو عبر
GET /portal/usage؛ - اعرف كيف تسرّب (سجل الإيداعات، أو سجلات CI، أو لقطة شاشة متداولة)؛
- دوّر أي أسرار أخرى محفوظة في المكان نفسه.
المفتاح الملغى أو المحظور يعيد 401 أو 403؛ راجع دليل الأخطاء حتى لا تعاملها أنظمة المراقبة لديك على أنها أخطاء عابرة.
كيف تتسرّب المفاتيح عبر السجلات؟
السجلات مصدر تسريب يسهل إغفاله. احجب ترويسة Authorization في سجلات تصحيح HTTP، وأدوات الإبلاغ عن الأخطاء، وسجلات الوصول في الوكيل (proxy). وعندما تتواصل مع الدعم، أرسل X-Request-ID والطابع الزمني والمسار ورمز الحالة والاسم المستعار للمفتاح (alias)، لا المفتاح نفسه أبدًا. ويقول توثيق BroadNet إن البوابة لا تخزّن سوى قيمة التجزئة لكل مفتاح، لذا لا يمكنها أن تعرض لك مفتاحًا ضائعًا أيضًا.
كيف تحدّ من ضرر تسريب لم تكتشفه بعد؟
حتى مع كل العادات السابقة، افترض أن مفتاحًا قد يتسرّب يومًا ما. قلّص نطاق الضرر:
- أبقِ رصيد الدفع حسب الاستخدام عند مستوى تقبل خسارته، واشحنه عند الحاجة.
- استخدم خطة بسعر ثابت للوكلاء كثيفي الاستخدام: فجلسة الخطة سعرها ثابت، لذا لا يستطيع مفتاح خطة مسروق أن يراكم فاتورة لكل رمز (توكن). راجع ما المعنى الحقيقي لعبارة «غير محدود».
- اضبط تنبيهات للإنفاق أو معدلات الطلبات غير المعتادة لكل مفتاح؛ تمنحك حاسبة تكلفة LLM API رقمًا شهريًا معتادًا تقيس عليه التنبيهات. ويغطي مقالنا عن التحكم في إنفاق LLM API الميزانيات والتنبيهات.
ما ضوابط المفاتيح التي توفرها BroadNet Inference؟
| الضابط | BroadNet Inference |
|---|---|
| يُعرض المفتاح مرة واحدة ويُخزَّن مُجزّأً (hash) | نعم |
| المفاتيح الفعّالة لكل حساب | حتى 10 |
| عمر المفتاح | عام واحد |
| قائمة عناوين IP المسموحة | حتى 32 مدخلًا من IPv4 أو IPv6 أو CIDR |
| قائمة مسموحة لكل مفتاح | نعم، allowed_ips عند الإنشاء |
| سريان الإلغاء | خلال خمس ثوانٍ |
| بيانات اعتماد إدارة منفصلة | بيانات اعتماد البوابة |
المفاتيح تحمي حسابك؛ وعدم الاحتفاظ بالبيانات يحمي ما ترسله عبره. اقرأ عن الاثنين قبل الإطلاق.
