متغيرات البيئة في Docker: الإعدادات وملفات env والأسرار
متغيرات البيئة في Docker قيم تُمرَّر إلى عملية التطبيق لتحديد إعداداتها، مثل اسم البيئة أو عنوان قاعدة البيانات. تسمح لك باستخدام الصورة نفسها بإعدادات مختلفة دون تعديل الشيفرة كل مرة. لكنها لا تصبح مخزنًا سريًا محميًا بمجرد وضع كلمة المرور في متغير.
سنتدرّب بقيم غير حساسة، ثم نفصل بين إعداد التشغيل وأسرار الوصول وملف .env. إذا كنت جديدًا على الحاويات، ابدأ من مقدمة Docker بالعربية. الأمثلة موضوعة للتعلم، ولم تُنفّذ في محرك Docker أثناء إعداد المقال.
لماذا نخرج الإعدادات من الصورة؟
لأن الصورة قد تُستخدم في التطوير والاختبار والنشر، بينما تختلف عناوين الخدمات وبعض الخيارات. تضمين كل إعداد داخل الصورة يجبرك على إعادة البناء لتغييرات لا تمس التطبيق نفسه.
مثلًا، يمكن أن يعمل التطبيق محليًا باسم بيئة development وفي الاختبار باسم test. يقرأ التطبيق المتغير APP_ENV ويختار السلوك الذي صُمم له. Docker يمرر القيمة فقط؛ لا يضيف تلقائيًا منطقًا إلى برنامج لا يعرف هذا المتغير.
كيف تمرّر قيمة باستخدام -e؟
استخدم -e أو –env عند إنشاء الحاوية. المثال التالي يطبع قيمة تدريبية ثم ينهي الحاوية المؤقتة:
docker run --rm -e APP_ENV=learning alpine:3.22 sh -c 'printf "%s\n" "$APP_ENV"'
المتوقع ظهور learning. وضع الأمر داخل اقتباس مفرد يمنع صدفة المضيف في Bash وPowerShell من توسيع $APP_ENV قبل وصوله إلى الحاوية. إذا استخدمت طرفية أخرى فقد تحتاج صيغة اقتباس تناسبها.
يمكن تمرير أكثر من قيمة:
docker run --rm -e APP_ENV=learning -e APP_NAME=Geek4Arab alpine:3.22 sh -c 'printf "%s: %s\n" "$APP_NAME" "$APP_ENV"'
هذه أسماء اخترناها للتمرين. لا تفترض أن تغيير APP_NAME سيغيّر عنوان أي تطبيق جاهز؛ يجب أن يوثّق التطبيق دعم هذا المتغير.
كيف تستخدم –env-file؟
احفظ القيم في ملف نصي ثم مرر مساره عند إنشاء الحاوية. أنشئ ملفًا باسم training.env في مجلد التمرين:
APP_ENV=learning
APP_NAME=Geek4Arab
DB_HOST=db
DB_PORT=3306
ثم شغّل:
docker run --rm --env-file training.env alpine:3.22 sh -c 'printf "%s:%s\n" "$DB_HOST" "$DB_PORT"'
المتوقع ظهور db:3306. لا يُنشئ هذا المثال قاعدة بيانات ولا يختبر الاتصال بها؛ إنه يختبر وصول النص إلى العملية. فصل هذين الاختبارين يمنع اعتبار طباعة اسم المضيف دليلًا على أن الشبكة تعمل.
استخدم صيغة KEY=value الواضحة في ملفات docker run. لا تنقل افتراضات الاقتباس والتوسيع من ملفات Compose أو الصدفة دون مراجعة؛ صيغ الملفات ليست متطابقة في كل الأدوات.
هل تعديل الملف يغير حاوية موجودة؟
لا. القيم تُضبط عند إنشاء الحاوية. تعديل training.env على جهازك ثم تنفيذ docker restart لا يعيد قراءة الملف لتكوين بيئة جديدة.
أعد إنشاء الحاوية بالإعدادات المطلوبة، مع المحافظة على بياناتها الدائمة. وفي Compose، استخدام up -d بعد تغيير الإعدادات قد يعيد إنشاء الخدمات المتأثرة. لا تعتمد على restart لتطبيق تغييرات ملف التكوين.
الفرق بين ENV وARG وإعداد التشغيل
ENV يضع قيمة افتراضية في إعداد الصورة ويمكن استبدالها عند التشغيل. ARG يمرر قيمة إلى عملية البناء ضمن نطاقها، ولا يصبح تلقائيًا متغير تشغيل داخل الحاوية النهائية.
| الوسيلة | أين تُستخدم؟ | مثال مناسب |
|---|---|---|
| ARG | أثناء البناء | خيار بناء غير سري |
| ENV | قيمة افتراضية في الصورة | وضع تشغيل افتراضي |
| docker run -e | عند إنشاء الحاوية | عنوان خدمة في بيئة محددة |
| –env-file | مجموعة قيم عند الإنشاء | إعدادات محلية للتمرين |
لا تستخدم ARG أو ENV لإدخال أسرار إلى البناء. قد تظهر القيم أو آثارها في بيانات البناء وطبقاته وسجلاته. للأسرار المطلوبة أثناء البناء توجد آليات مخصصة مثل Build secrets، وهي تختلف عن أسرار التشغيل.
ما الفرق بين .env وenv_file في Compose؟
ملف .env الذي يقرأه Compose يُستخدم عادةً لتعويض المتغيرات داخل ملف التكوين. لا يعني وجود قيمة فيه أنها دخلت إلى الحاوية تلقائيًا. أما env_file داخل تعريف الخدمة فيحدد ملفًا تُمرر قيمه إلى بيئة تلك الخدمة.
مثال مختصر للتعويض والتمرير الصريح:
services:
app:
image: alpine:3.22
environment:
APP_ENV: ${APP_ENV:-learning}
command: ["printenv", "APP_ENV"]
أرسلنا APP_ENV صراحةً داخل environment، مع قيمة افتراضية عند عدم توفيرها. أما مجرد كتابة APP_ENV في .env دون الرجوع إليها في التكوين أو تمرير الملف، فلا يكفي كي يقرأها التطبيق.
كيف تحمي الأسرار؟
افصل القيم العامة عن كلمات المرور والرموز. احتفظ بملف مثال مثل .env.example يحتوي أسماء المتغيرات وقيمًا تدريبية، واستبعد الملف الفعلي من Git ومن سياق بناء الصورة.
قد يرى من يملك صلاحيات إدارة Docker بعض إعدادات الحاوية، وقد يطبع التطبيق البيئة في سجل تشخيص. لذلك لا تعرض المتغيرات كلها عبر env أو inspect أثناء دعم مشروع حقيقي. استخدم آلية أسرار تناسب منصة النشر والتطبيق، مع صلاحيات محدودة وتدوير عند التسرب.
حتى Compose secrets لا يحوّل الجهاز تلقائيًا إلى خزنة مشفرة. يوفّر طريقة لربط ملفات أسرار بالخدمات، بينما تبقى حماية المصدر وصلاحيات المضيف مسؤولية مستقلة. ويجب أن يدعم التطبيق قراءة السر من ملف أو يُهيّأ لذلك.
أخطاء شائعة في متغيرات البيئة في Docker
قد تكون القيمة موجودة لكن التطبيق يقرأ اسمًا مختلفًا، أو يتوقع رقمًا ويحصل على نص غير صالح. وقد تُفسّر القيمة false بطريقة غير متوقعة إذا لم يحوّلها البرنامج إلى نوع منطقي.
راجع أسماء المتغيرات كما يوثقها التطبيق، ثم افحص قيمة غير حساسة محددة. إذا نجح التمرير وبقي الاتصال بقاعدة البيانات معطلًا، انتقل إلى تشخيص الشبكة واسم الخدمة والمنفذ. لا تغيّر كلمة المرور مرارًا قبل معرفة مرحلة الفشل.
تمرين عملي للمراجعة
غيّر APP_ENV في ملف التدريب، ثم شغّل حاوية مؤقتة جديدة واقرأ هذه القيمة وحدها. أنشئ ملف .env.example بالقيم العامة فقط، وسجّل أي متغير يحتاجه التطبيق فعلًا. هكذا تتحول متغيرات البيئة في Docker إلى إعداد واضح يمكن مراجعته، بدل مجموعة نصوص مجهولة المصدر والوظيفة.
أسئلة شائعة
هل ملف .env يدخل الحاوية تلقائيًا؟
لا في الحالة العامة. يجب تمرير القيم صراحةً أو استخدام env_file في تعريف الخدمة بحسب الأداة.
هل restart يقرأ env-file من جديد؟
لا يعيد إنشاء إعدادات الحاوية. أنشئ حاوية جديدة بالقيم المعدلة.
هل كلمات المرور داخل ENV آمنة؟
لا تُعد ENV خزنة أسرار. قد تُكشف عبر صلاحيات الإدارة أو السجلات، فلا تضع أسرارًا في صورة موزعة.
هل Docker يحدد نوع القيمة؟
متغيرات البيئة نصوص. التطبيق مسؤول عن تفسير الأرقام والقيم المنطقية والتحقق من صلاحيتها.
المصادر والمراجعة التقنية
استُلهم ترتيب موضوعات السلسلة من ملاحظات Narayan Prasad (@code.withnarayan). الشرح العربي والأمثلة والرسوم هنا إعداد مستقل، مع الرجوع إلى الوثائق الرسمية لتصحيح وتوسيع المفاهيم.
مقالات ومعرفة تقنية باللغة العربية.
