تخزين مفتاح API بأمان: متغير بيئة، .gitignore، إصلاح التسريب

احفظ المفتاح في متغير بيئة، لا في شفرتك، وأبقِ أي ملف .env خارج git بسطر في .gitignore. إذا كان المفتاح قد وصل بالفعل إلى مكان عام، تعامل مع المفتاح أولاً ورتّب ما بعده: تنظيف تاريخ git بينما المفتاح لا يزال في شفرتك وأدواتك لا يصلح شيئاً.

هذه هي الفكرة كلها. هذا الدليل هو النسخة العملية (الأساسيات في What is an API key): ثلاثة أوامر، وطلب واحد يعمل، وخطة قصيرة لليوم السيئ.

لماذا لا ينتمي المفتاح إلى شفرتك#

مفتاح API هو كلمة مرور تنفق أموالك. أي شخص يحمله يمكنه إرسال طلبات على رصيدك، ولا تستطيع الخدمة التمييز بينه وبينك.

الطريقة المعتادة التي يسوء بها الأمر مملة. تلصق المفتاح في سكربت لتشغيل أول طلب، فيعمل السكربت، ثم git push، ويصبح المستودع عاماً. أو ترسل ملف الإعدادات لزميل. أو تلتقط لقطة شاشة لخطأ يظهر فيه المفتاح في الزاوية. النتيجة نفسها كل مرة.

GitHub يعرف هذا النمط جيداً. فحص الأسرار لديه (GitHub docs، تم التحقق في 29 أكتوبر 2026) يبحث في تاريخ Git الكامل على جميع الفروع عن بيانات اعتماد مضمّنة، وكذلك في issues وpull requests والمناقشات وwikis وgists السرية، ويرفع تنبيهاً عند العثور على واحد. ما يعني أن حذف السطر في commitك التالي لا يغيّر شيئاً: الـ commit القديم لا يزال يحتويه.

إليك نفس السكربت قبل وبعد.

from openai import OpenAI

client = OpenAI(
    base_url="https://api.cheaptokens.dev/v1",
    api_key="<your-key>",  # pasted here: ends up in git
)

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.cheaptokens.dev/v1",
    api_key=os.environ["CHEAPTOKENS_API_KEY"],
)

النسخة الثانية يمكن أن تذهب إلى GitHub أو محادثة أو مراجعة شفرة كما هي. المفتاح يعيش على جهازك، خارج الملف.

الخطوة 1: ضع المفتاح في متغير بيئة#

متغير البيئة هو قيمة مسماة يسلّمها طرفيتك لكل برنامج تشغّله. السكربت يطلب CHEAPTOKENS_API_KEY بالاسم ولا يرى أبداً من أين جاء.

على macOS وLinux:

export CHEAPTOKENS_API_KEY="<your-key>"

على Windows PowerShell:

setx CHEAPTOKENS_API_KEY "<your-key>"

تفصيلان يوقعان الناس في الخطأ. export يدوم فقط لنافذة الطرفية تلك، لذا لإبقائه أضف السطر إلى ملف تعريف shell لديك (~/.zshrc أو ~/.bashrc). وsetx لا يغيّر النافذة التي كتبته فيها: افتح طرفية جديدة قبل أن تختبر.

الآن طلب كامل. يستخدم نقطة النهاية المتوافقة مع OpenAI، https://api.cheaptokens.dev/v1، وDeepSeek-V4-Flash بمعرّفه الكامل (deepseek-ai/DeepSeek-V4-Flash-0731؛ خذ المعرّفات من CheapTokens docs، لأن الأسماء تختلف بين المزوّدين):

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.cheaptokens.dev/v1",
    api_key=os.environ["CHEAPTOKENS_API_KEY"],
)

resp = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V4-Flash-0731",
    messages=[{"role": "user", "content": "Say hi in five words."}],
)
print(resp.choices[0].message.content)
print(resp.usage)

تحية قصيرة هي طلب من نحو 20 token دخلاً و20 خروجاً، وهو بالأسعار الحالية $0.0000023 (القائمة الكاملة في pricing page). إذا لم ترسل أول طلب بعد، فـYour first API request with CheapTokens يشرحه من الصفر.

تأتي إجابة النموذج في choices[0].message.content، وusage يعرض الـ tokens التي عدّها. المفتاح لا يظهر أبداً في الملف.

الخطوة 2: استخدم ملف .env دون إيداعه#

كتابة export في كل نافذة جديدة تصبح مملة. ملف .env يحفظ القيمة في مكان واحد، بجوار المشروع:

CHEAPTOKENS_API_KEY=<your-key>

Python يقرأه بـpython-dotenv (pip install python-dotenv):

from dotenv import load_dotenv
load_dotenv()  # fills os.environ from .env

الملف آمن فقط إذا لم يره git أبداً. أضفه إلى .gitignore قبل أول commit:

echo ".env" >> .gitignore
git check-ignore -v .env

إذا كان كل شيء صحيحاً، يطبع الأمر الثاني شيئاً مثل .gitignore:1:.env .env: يخبرك git أي قاعدة تتجاهل الملف. إذا لم يطبع شيئاً، فالقاعدة لا تعمل. على Windows، أنشئ .gitignore في محرر بسطر .env، أو استخدم Add-Content .gitignore .env: فـ>> في PowerShell يمكن أن يكتب UTF-16، وهو ما قد يتجاهله git.

فخ واحد: .gitignore يؤثر فقط على الملفات التي لا يتتبعها git بعد. إذا كان .env قد أُودع مرة، شغّل git rm --cached .env ليتوقف git عن تتبعه، واعتبر المفتاح بداخله مكشوفاً (المزيد عن ذلك أدناه). عادة مرتبة هي إيداع .env.example باسم المتغير وعنصر نائب بدلاً من القيمة، ليعرف زميلك ما يجب تعيينه.

إذا تسرّب المفتاح: ما يجب فعله، بالترتيب#

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

إرشاد GitHub نفسه (الصفحة نفسها، تم التحقق في 29 أكتوبر 2026) هو تدوير بيانات الاعتماد فوراً؛ إعادة كتابة تاريخ Git اختيارية وغالباً غير ضرورية بمجرد إبطال بيانات الاعتماد. يميل الناس إلى فعل العكس: يقضون ساعة في تنظيف التاريخ بينما المفتاح لا يزال يعمل. لا تفعل.

بعد التنظيف، أرسل طلب اختبار صغيراً واحداً، كما في الخطوة 1، وتحقق من رصيدك. إذا أجاب وكان الرصيد والطلبات طبيعيين، فالتنظيف انتهى؛ راقب الرصيد في الأيام القليلة القادمة. المفتاح الذي كان عاماً يجب اعتباره مكشوفاً حتى بعد إزالته من الشفرة، لذا راقب الرصيد وعدد الطلبات بحثاً عن أي شيء لم ترسله، ولا تعِد استخدام ذلك المفتاح في أماكن جديدة. للأماكن التي يميل المفتاح إلى العيش فيها، انظر Where to plug in your own API key.

اختبر نفسك#