DevOps والتشغيل الأدلة التقنية

متغيرات البيئة Environment Variables: تطبيق واحد لكل البيئات

كيف يقرأ تطبيقك إعداده من الخارج ويتحقق منه عند التشغيل، فتنتقل Image واحدة بين كل البيئات دون أي سر في الكود.

متغيرات البيئة Environment Variables: تطبيق واحد لكل البيئات

إذا فتحت مستودع أي مشروع عمره أكثر من سنة فغالب الظن أنك سوف تجد ملفاً اسمه config.prod.js أو settings_production.py وفيه عنوان قاعدة بيانات الإنتاج، وبجانبه باسورد كتبه أحد الزملاء «مؤقتاً» قبل ثلاث سنوات، وفي مكان ما من الكود سطر يقول if ENV == "production" يغير سلوك التطبيق بطريقة لا يعرفها إلا من كتبها. وكل هذا يعمل، إلى أن يأتي اليوم الذي يرسل فيه التطبيق في الإنتاج طلبات الدفع إلى بيئة الاختبار Sandbox لأن أحداً نسخ ملف الإعداد الخطأ، أو تظهر صفحة الخطأ التفصيلية للعملاء لأن وضع التصحيح Debug بقي يعمل، أو يحتاج فريق جديد أن يشغل المشروع على جهازه فيكتشف أن المستودع كله لا يعمل دون ملف لا يملكه إلا شخص واحد في الشركة.

والمشكلة في كل هذه الحالات ليست في الكود نفسه، وإنما في الإعداد Configuration: القيم التي تختلف من مكان تشغيل إلى آخر، وأين تحفظ، ومن يقرؤها، ومتى تتغير. وفي هذا المقال سوف نتابع فريق متجر إلكتروني صغير لديه تطبيق واحد يعمل في ثلاث بيئات: بيئة التطوير dev، وبيئة الاختبار قبل الإنتاج staging، وبيئة الإنتاج prod، ونحاول أن نصل معه إلى الشكل الذي يصفه عنوان المقال: كود واحد، و Image واحدة، وإعداد يأتي من الخارج، ولا يوجد أي سر داخل المستودع. وقد شرحنا في مقال البيئات وGitOps لماذا تحتاج الفرق أكثر من بيئة وكيف تنقل الإصدار بينها، وفي قائمة تحقق المطور قبل النشر ذكرنا باختصار أن الأسرار لا مكان لها داخل ال Image، أما هنا فسوف ندخل في التفاصيل: كيف يقرأ التطبيق إعداده، وبأي ترتيب، وكيف يتحقق منه، وما الذي يحدث فعلاً عندما تكتب سطراً في ملف .env.

وسوف نناقش في هذا المقال ما يلي:

  • ما هو الإعداد، وما الذي ليس إعداداً، ولماذا تفشل الحلول الأولى التي تجربها الفرق.
  • منهج The Twelve-Factor App ومتغيرات البيئة Environment Variables، وكيف تعمل داخل نظام التشغيل.
  • طبقات الإعداد وترتيب الأولوية Precedence، والتحقق من الإعداد عند التشغيل Fail Fast.
  • مختبر حقيقي: تطبيق واحد في ثلاث بيئات مع Docker Compose، ومشكلة حقيقية واجهتنا مع علامة $ جعلت مفتاح الدفع ناقصاً دون أي خطأ.
  • الأسرار Secrets: لماذا لا تضعها في متغيرات البيئة إذا استطعت، وأين تضعها.
  • تغيير الإعداد كتغيير الكود، والأخطاء الشائعة، وقائمة تحقق تستخدمها في مشروعك.

ما هو الإعداد Configuration؟ وما الذي ليس إعداداً

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

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

وهناك نوع ثالث يحتاج معاملة خاصة وهو الأسرار Secrets: الباسورد، ومفاتيح ال API، والشهادات الخاصة Private Keys، والتوكن الذي يفتح خدمة خارجية. وهي إعداد بالتعريف السابق لأنها تختلف بين البيئات، ولكن الفرق أن تسربها ضرر بحد ذاته، فلو عرف شخص عنوان قاعدة البيانات فهذا لا يعني شيئاً كثيراً، ولكن لو عرف الباسورد فهذه مشكلة أمنية حقيقية. ولذلك سوف نعامل الأسرار في هذا المقال كفئة منفصلة لها مكانها الخاص وطريقة قراءتها الخاصة.

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

الحلول الأولى ولماذا تفشل: من الثابت في الكود Hardcoded إلى ملف لكل بيئة

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

القيم الثابتة في الكود Hardcoded Values

في الأسبوع الأول كتب المطور عنوان قاعدة البيانات والباسورد مباشرة في الكود، لأن التطبيق كان يعمل على جهازه فقط. ثم جاء وقت النشر على السيرفر، فغير القيم يدوياً قبل البناء، ثم نسي أن يرجعها، فدخلت قيم الإنتاج إلى Git مع أول Commit بعد النشر. وهنا ظهرت مشكلتان في وقت واحد: الأولى أن كل من يملك نسخة من المستودع يملك باسورد قاعدة بيانات الإنتاج، وتاريخ Git يحتفظ بها حتى لو حذفت السطر بعد ذلك كما شرحنا في مقال اكتشاف الأسرار المسربة، والثانية أن تشغيل التطبيق في أي مكان آخر يحتاج تعديل الكود، أي أن الكود الذي يعمل في الإنتاج ليس هو الكود الذي اختبرته.

ملف إعداد لكل بيئة داخل المستودع Config File per Environment

الحل الطبيعي التالي هو أن تفصل القيم في ملفات: config.dev.json وconfig.staging.json وconfig.prod.json، والتطبيق يختار الملف بحسب متغير واحد. وهذا أفضل بكثير من الحل السابق لأن الكود لم يعد يتغير بين البيئات، ولكنه يترك مشكلتين: الأسرار ما زالت داخل المستودع لأن ملف الإنتاج فيه باسورد الإنتاج، وكل بيئة جديدة تحتاج ملفاً جديداً في الكود، فإذا أردت بيئة معاينة Preview لكل طلب دمج، كما في مقال البيئات، فأنت تحتاج ملفاً لكل طلب، وهذا غير عملي إطلاقاً. وهناك مشكلة ثالثة أقل وضوحاً، وهي أن هذه الملفات تكبر مع الوقت وتتباعد عن بعضها، فيضيف أحدهم قيمة جديدة في ملف dev وينسى أن يضيفها في ملف prod، ولا يكتشف أحد ذلك حتى يصل الإصدار إلى الإنتاج.

شروط البيئة داخل الكود if env == prod

وأسوأ الطرق على الإطلاق هي الشروط التي تتحقق من اسم البيئة داخل الكود، مثل أن تكتب «إذا كنا في الإنتاج فأرسل البريد فعلاً، وإلا فاطبعه في السجل». وقد تبدو هذه الطريقة من الوهلة الأولى منطقية، ولكن كل شرط من هذا النوع يصنع مساراً في الكود لا يعمل إلا في بيئة واحدة، وبالتالي لا يختبر أبداً قبل أن يصل إلى الإنتاج، فالمسار الذي يرسل البريد فعلاً لم يعمل في staging ولا مرة واحدة. والحل الأنسب هو أن يصبح السلوك نفسه إعداداً له اسم واضح، مثل MAIL_TRANSPORT=smtp أو MAIL_TRANSPORT=log، فتستطيع أن تشغل المسار الحقيقي في staging متى أردت، ويبقى الكود واحداً لا يعرف أصلاً في أي بيئة يعمل.

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

منهج Twelve-Factor App: لماذا متغيرات البيئة Environment Variables؟

في سنة 2011 نشر فريق Heroku وثيقة قصيرة اسمها The Twelve-Factor App جمع فيها ما تعلمه من تشغيل آلاف التطبيقات على منصته، والعامل الثالث فيها عنوانه الإعداد Config، ونصه أن التطبيق يجب أن يحفظ الإعداد في البيئة، أي في متغيرات البيئة، وأن يفصل الإعداد عن الكود فصلاً صارماً. وتقترح الوثيقة اختباراً بسيطاً تعرف به هل فصلت الإعداد بشكل صحيح: هل تستطيع أن تجعل الكود مفتوح المصدر الآن، في هذه اللحظة، دون أن تكشف أي باسورد أو مفتاح؟ فإذا كانت الإجابة لا فالإعداد ما زال في الكود.

والسبب في اختيار متغيرات البيئة تحديداً أنها موجودة في كل نظام تشغيل وكل لغة برمجة، ولا تحتاج مكتبة ولا صيغة ملف، ويصعب أن تدخل إلى Git بالخطأ لأنها ليست ملفاً في المستودع أصلاً، وتستطيع أن تغيرها لكل عملية دون أن تلمس الكود. وتنتقد الوثيقة كذلك فكرة تجميع الإعداد في مجموعات باسم البيئة مثل development وtest وproduction، والسبب أن عدد هذه المجموعات يزيد مع كل بيئة جديدة ومع كل مطور له إعداده الخاص، أما المتغيرات المستقلة فكل متغير منها مستقل عن الآخر ولا يحتاج أن تعرف كل التركيبات مسبقاً. وفي العامل العاشر تطلب الوثيقة أن تبقى بيئة التطوير قريبة من الإنتاج قدر الإمكان، وهذا لا يتحقق إلا إذا كان الفرق بين البيئات محصوراً في الإعداد.

وقد يتساءل البعض: هل ما زالت هذه الوثيقة صالحة بعد Docker وKubernetes؟ والإجابة نعم في الفكرة الأساسية، فال Image الواحدة التي تنتقل بين البيئات لا تعمل إلا إذا جاء الإعداد من الخارج، ولكن التجربة أضافت إليها تفصيلاً مهماً وهو أن متغيرات البيئة ليست المكان الأفضل للأسرار، كما سوف نرى في المختبر، ولذلك تعامل أغلب الفرق اليوم القاعدة على أنها «الإعداد من الخارج»، ومتغيرات البيئة هي الطريقة الافتراضية لذلك وليست الطريقة الوحيدة.

كيف تعمل متغيرات البيئة داخل كل عملية Process؟

متغيرات البيئة ليست شيئاً سحرياً، وإنما قائمة من النصوص بالشكل NAME=value يحملها كل Process في ذاكرته. وعندما ينشئ Process آخر، مثل أن تشغل الطرفية برنامجاً، فإن نظام Linux ينسخ هذه القائمة إلى ال Process الجديد عبر استدعاء النظام execve، ولذلك يرث كل Process بيئة الذي أنشأه، ويستطيع أن يغيرها لنفسه ولمن ينشئهم بعده، ولكنه لا يستطيع أن يغير بيئة الذي أنشأه. وتظهر بيئة كل Process كما بدأ بها في الملف /proc/<pid>/environ، وهذا الملف يقرؤه صاحب ال Process والمستخدم root.

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

طبقات الإعداد Configuration Layers مع ترتيب الأولوية Precedence

إذا جعلت كل الإعداد متغيرات بيئة فسوف تجد بعد فترة أن ملف البيئة أصبح خمسين سطراً، أغلبها قيم لا تتغير بين البيئات أصلاً، مثل المنفذ داخل ال Container وحجم الرفع وعدد المحاولات. ولذلك تستخدم أغلب الأطر Frameworks الناضجة طبقات، كل طبقة تغطي التي قبلها: قيم افتراضية داخل الكود، ثم ملف إعداد مشترك داخل ال Image، ثم متغيرات البيئة التي تختلف بين البيئات، ثم الأسرار من ملفات خاصة. والصورة التالية تبين الطبقات الأربع كما بنيناها في المختبر، مع ما يطبعه التطبيق عند التشغيل:

أربعة صناديق من اليمين إلى اليسار: القيم الافتراضية Defaults داخل الكود مثل port 8080 وdebug false وmax_upload_mb 10، ثم ملف الإعداد settings.toml داخل ال Image وفيه max_upload_mb 20، ثم متغيرات البيئة مثل APP_DEBUG وAPP_DATABASE_URL وAPP_MAX_UPLOAD_MB=50، ثم ملفات الأسرار مثل APP_DATABASE_PASSWORD_FILE، وتحتها مخرج التطبيق يبين أن max_upload_mb جاءت من متغير البيئة وport من الملف والباسورد من ملف السر
كل طبقة تغطي التي قبلها، والتطبيق يطبع مصدر كل قيمة

والفكرة المهمة في الصورة ليست الطبقات نفسها، فهي موجودة في أغلب الأطر، وإنما السهم الذي يقول من يغطي من، والعمود الأخير الذي يقول من أين جاءت كل قيمة. والسبب أن أصعب سؤال في مشاكل الإعداد هو «من أين جاءت هذه القيمة؟»، فإذا كان التطبيق يقرأ من أربعة أماكن ولا يخبرك من أيها جاءت القيمة النهائية، فسوف تقضي ساعة تبحث في الملفات وأنت تظن أنك غيرت القيمة بينما هناك طبقة أعلى تغطيها. ولذلك لاحظ أن التطبيق في المختبر يطبع لكل قيمة مصدرها بجانبها، مع إخفاء الأسرار، وهذا سطر واحد في الكود يوفر عليك ساعات.

وترتيب الأولوية الذي اخترناه هو الترتيب الشائع: الأقرب إلى لحظة التشغيل يغلب، فالقيمة الافتراضية كتبها المطور قبل أشهر، وملف الإعداد دخل مع ال Image، ومتغير البيئة كتبه من يشغل التطبيق الآن، وملف السر يغلب الجميع لأنه المكان الوحيد الذي نريد أن تأتي منه الأسرار. وإذا كان إطار العمل الذي تستخدمه يعتمد ترتيباً آخر، مثل Spring Boot الذي لديه أكثر من عشرة مصادر مرتبة، فالمهم أن تعرف الترتيب وأن يعرفه الفريق كله، لا أن تختار ترتيباً معيناً.

التحقق عند التشغيل Fail Fast Validation

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

والحل أن يتحقق التطبيق من كل إعداده في أول لحظة، قبل أن يفتح المنفذ ويستقبل أي طلب، وهذا ما يسمى Fail Fast. والتحقق الجيد يفعل أربعة أشياء: يتأكد أن كل قيمة مطلوبة موجودة، ويحول كل قيمة إلى نوعها الصحيح Type، ويتحقق من القواعد التي تربط القيم ببعضها، مثل «لا يعمل وضع التصحيح في الإنتاج»، ويجمع كل المشاكل ويطبعها مرة واحدة، لأن التطبيق الذي يخبرك بمشكلة واحدة في كل تشغيل يجعلك تنشر خمس مرات لتصلح خمس قيم. وفي Kubernetes وDocker Compose يتحول هذا الفشل المبكر تلقائياً إلى نشر فاشل يراه الفريق، بدل تطبيق يعمل ظاهرياً وهو معطل.

القيمة «false» التي تساوي True

وأشهر خطأ في تحويل الأنواع هو القيم المنطقية Boolean، لأن متغيرات البيئة نصوص كما ذكرنا، والنص «false» ليس فارغاً، وبالتالي فإن أغلب اللغات تعتبره صحيحاً True إذا حولته بالطريقة المباشرة. والمثال التالي يبين ذلك في Python:

docker run --rm -e DEBUG=false python:3.13-slim python -c 'import os; print("DEBUG =", repr(os.environ["DEBUG"]), "->", bool(os.environ["DEBUG"]))'

والمخرج سوف يكون كما يلي:

DEBUG = 'false' -> True

أي أن من كتب DEBUG=false في ملف الإنتاج ليغلق وضع التصحيح قد فتحه فعلياً، وصفحة الخطأ التفصيلية التي تعرض الكود والمتغيرات أصبحت ظاهرة لكل زائر. والحل أن تكتب دالة تحويل صريحة تقبل قيماً محددة فقط، مثل 1 وtrue وyes وon للصحيح، و0 وfalse وno وoff للخطأ، وترفض أي شيء آخر برسالة واضحة، بدل أن تخمن. وهذا ما تفعله الدالة parse في تطبيق المختبر، ويفعله كذلك أغلب مكتبات الإعداد المعروفة مثل pydantic-settings في Python وenvalid في Node.js.

ونفس الفكرة تنطبق على الأرقام، فالقيمة 20MB ليست رقماً، والتطبيق الذي يحولها بطريقة متسامحة قد يقرأ 20 أو يقرأ صفراً بحسب اللغة، والأفضل أن يرفضها. وتنطبق كذلك على العناوين URLs، فالعنوان الذي ينقصه https:// قد يعمل في مكتبة ويفشل في أخرى، والأفضل أن يرفضه التحقق قبل أن يصل إلى أي مكتبة.

المختبر Lab: تطبيق واحد في ثلاث بيئات مع Docker Compose

الآن سوف نقوم ببناء ما وصفناه: تطبيق Python صغير يقرأ إعداده من الطبقات الأربع، ويتحقق منه، ويطبع مصدر كل قيمة، ثم نشغله في البيئات الثلاث من Image واحدة، ونرى ماذا يحدث عندما يكون الإعداد ناقصاً أو خاطئاً. والتطبيق لا يحتاج أي مكتبة خارجية، فكل ما فيه من مكتبة Python القياسية، ومنها tomllib لقراءة ملف الإعداد بصيغة TOML.

ملفات المختبر Lab Files

شكل المجلد كما يلي، ولاحظ أن مجلد secrets وملف .env لا يدخلان Git في المشروع الحقيقي، وإنما ينشآن على كل سيرفر:

lab/
  app.py              # the application and its config loader
  settings.toml       # shared, non-secret settings (baked into the image)
  Dockerfile
  compose.yaml
  .env                # which environment this server runs (not in Git)
  config/dev.env      # per-environment settings
  config/staging.env
  config/prod.env
  secrets/dev_db_password.txt       # one secret file per environment (not in Git)
  secrets/staging_db_password.txt
  secrets/prod_db_password.txt

والملف الأهم هو app.py، وفيه جدول يصف كل إعداد: اسمه، ونوعه، وقيمته الافتراضية، وهل هو مطلوب، وهل هو سر:

# Config loader for the lab: defaults -> settings.toml -> environment (APP_*) -> secret files (*_FILE).
# Every value is typed and validated at startup; all problems are reported together and the process exits 1.
import os, sys, tomllib, json
from urllib.parse import urlparse
from http.server import ThreadingHTTPServer, BaseHTTPRequestHandler

SCHEMA = {
    #  name               type    default                  required  secret
    "env":              ("str",  "dev",                    False,    False),
    "port":             ("int",  8080,                     False,    False),
    "debug":            ("bool", False,                    False,    False),
    "database_url":     ("url",  None,                     True,     False),
    "database_password":("str",  None,                     True,     True),
    "payment_api_key":  ("str",  None,                     True,     True),
    "payment_base_url": ("url",  "https://sandbox.pay.example.com", False, False),
    "max_upload_mb":    ("int",  10,                       False,    False),
}
TRUE, FALSE = {"1", "true", "yes", "on"}, {"0", "false", "no", "off"}

def parse(kind, raw):
    if kind == "int":
        return int(raw)
    if kind == "bool":
        v = str(raw).strip().lower() if not isinstance(raw, bool) else raw
        if isinstance(v, bool): return v
        if v in TRUE: return True
        if v in FALSE: return False
        raise ValueError(f"not a boolean: {raw!r}")
    if kind == "url":
        u = urlparse(raw)
        if not (u.scheme and u.netloc): raise ValueError(f"not a URL: {raw!r}")
        return raw
    return str(raw)

def load():
    values, sources, errors = {}, {}, []
    for k, (_, default, _, _) in SCHEMA.items():
        if default is not None:
            values[k], sources[k] = default, "default"
    path = os.environ.get("APP_CONFIG_FILE", "/app/settings.toml")
    if os.path.exists(path):
        with open(path, "rb") as f:
            for k, v in tomllib.load(f).items():
                values[k], sources[k] = v, f"file:{os.path.basename(path)}"
    for k in SCHEMA:
        env = "APP_" + k.upper()
        if env in os.environ:
            values[k], sources[k] = os.environ[env], f"env:{env}"
        if env + "_FILE" in os.environ:
            p = os.environ[env + "_FILE"]
            try:
                with open(p) as f: values[k], sources[k] = f.read().strip(), f"secret:{p}"
            except OSError as e:
                errors.append(f"{env}_FILE: cannot read {p} ({e.strerror})")
    for k, (kind, _, required, _) in SCHEMA.items():
        if k not in values or values[k] in ("", None):
            if required: errors.append(f"{k}: required, set APP_{k.upper()} or APP_{k.upper()}_FILE")
            continue
        try:
            values[k] = parse(kind, values[k])
        except ValueError as e:
            errors.append(f"{k}: {e} (from {sources[k]})")
    if values.get("env") == "prod" and values.get("debug") is True:
        errors.append("debug: must be false when env=prod")
    if values.get("env") == "prod" and "sandbox" in str(values.get("payment_base_url", "")):
        errors.append("payment_base_url: sandbox URL in prod")
    return values, sources, errors

def masked(values, sources):
    out = {}
    for k, v in values.items():
        secret = SCHEMA[k][3]
        out[k] = {"value": ("****" + str(v)[-2:]) if secret else v, "source": sources[k]}
    return out

values, sources, errors = load()
if errors:
    print(f"config: {len(errors)} problem(s), refusing to start:", file=sys.stderr)
    for e in errors: print("  -", e, file=sys.stderr)
    sys.exit(1)
print("config ok:")
for k, v in masked(values, sources).items():
    print(f"  {k:<18} = {str(v['value']):<34} <- {v['source']}", flush=True)
if "--check" in sys.argv: sys.exit(0)

class H(BaseHTTPRequestHandler):
    def log_message(self, *a): pass
    def do_GET(self):
        body = json.dumps(masked(values, sources) if self.path == "/config" else {"status": "ok", "env": values["env"]}).encode()
        self.send_response(200); self.send_header("Content-Type", "application/json"); self.end_headers(); self.wfile.write(body)

ThreadingHTTPServer(("0.0.0.0", values["port"]), H).serve_forever()

في الكود أعلاه لاحظ التالي:

  • الجدول SCHEMA هو التوثيق الوحيد للإعداد، فمن يريد أن يعرف ماذا يحتاج التطبيق يقرؤه في مكان واحد، وكل إعداد جديد يضاف هنا أولاً.
  • الدالة load تمر على الطبقات بالترتيب، وكل طبقة تكتب فوق التي قبلها، وتحفظ في sources من أين جاءت القيمة.
  • كل متغير له شكلان: APP_DATABASE_PASSWORD بالقيمة نفسها، وAPP_DATABASE_PASSWORD_FILE بمسار ملف فيه القيمة، والثاني يغلب الأول، وهذا هو الاصطلاح الذي تستخدمه Images رسمية كثيرة كما سيأتي.
  • القيم المقروءة من الملفات تمر على strip()، والسبب أن أغلب المحررات تضيف سطراً جديداً في آخر الملف، فيصبح الباسورد dev-pass-1\n وتفشل المصادقة Authentication دون سبب واضح.
  • القاعدتان في آخر load تربطان القيم ببعضها: لا يعمل وضع التصحيح في الإنتاج، ولا يستخدم الإنتاج عنوان بوابة الدفع التجريبي. وهذه القواعد هي المكان الوحيد الذي يستخدم فيه الكود اسم البيئة.
  • عند وجود أي مشكلة يطبع التطبيق كل المشاكل ويخرج برمز الخروج 1، قبل أن يفتح المنفذ.

والملف المشترك settings.toml فيه القيم التي لا تختلف بين البيئات، وال Dockerfile ينسخه مع التطبيق، ولا يحتوي ال Image أي اسم بيئة ولا أي سر:

# Non-secret settings shared by every environment (baked into the image)
port = 8080
max_upload_mb = 20
FROM python:3.13-slim
WORKDIR /app
COPY app.py settings.toml ./
USER nobody
CMD ["python", "app.py"]

أما compose.yaml فهو واحد لكل البيئات، ويأخذ اسم البيئة من المتغير APP_ENV:

name: dvo-env
services:
  app:
    image: dvo-env-app:1.0.0
    build: .
    container_name: dvo-env-${APP_ENV:?set APP_ENV in .env}
    env_file:
      - config/${APP_ENV}.env
    environment:
      APP_ENV: ${APP_ENV}
      APP_DATABASE_PASSWORD_FILE: /run/secrets/db_password
    secrets:
      - db_password
    ports:
      - "127.0.0.1:${HOST_PORT:-18080}:8080"
secrets:
  db_password:
    file: ./secrets/${APP_ENV}_db_password.txt

في الإعداد أعلاه لاحظ التالي:

  • هناك نوعان مختلفان من المتغيرات في هذا الملف، وخلطهما هو مصدر أغلب المشاكل. النوع الأول ${APP_ENV} و${HOST_PORT}، وهذا استبدال Interpolation يقوم به Compose نفسه قبل أن ينشئ أي Container، ويأخذ قيمه من الطرفية أو من ملف .env بجانب ملف Compose. والنوع الثاني ما في env_file وenvironment، وهذه متغيرات تصل إلى داخل ال Container ويقرؤها التطبيق.
  • الصيغة ${APP_ENV:?message} تجعل Compose يرفض العمل إذا كان المتغير غير موجود أو فارغاً، وهذا Fail Fast على مستوى Compose نفسه.
  • ملف البيئة يختار بالاسم: config/${APP_ENV}.env، وملف السر كذلك، فيكفي أن تغير سطراً واحداً في .env لتنتقل بين البيئات.
  • الباسورد لا يمر عبر متغير بيئة أبداً، وإنما يصل ملفاً إلى /run/secrets/db_password، والتطبيق يعرف مكانه من APP_DATABASE_PASSWORD_FILE.
  • المنفذ مربوط على 127.0.0.1 فقط، لأن هذا مختبر ولا نريد أن يصل إليه أحد من الشبكة.

وملفات البيئات الثلاث كما يلي، ولاحظ أن ملف الإنتاج ينقصه مفتاح بوابة الدفع عن قصد:

# config/dev.env
APP_DEBUG=true
APP_DATABASE_URL=postgres://app@db-dev:5432/shop
APP_PAYMENT_API_KEY=sk_test_dev_51x9

# config/staging.env
APP_DEBUG=false
APP_DATABASE_URL=postgres://app@db-staging:5432/shop
APP_PAYMENT_API_KEY=sk_test_staging_77q2

# config/prod.env
APP_DEBUG=false
APP_DATABASE_URL=postgres://app@db-prod:5432/shop
APP_PAYMENT_BASE_URL=https://api.pay.example.com

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

على اليمين ال Image dvo-env-app:1.0.0 التي تحتوي الكود وsettings.toml بلا أسرار وبلا اسم بيئة، ومنها أسهم إلى ثلاث بيئات: dev مع config/dev.env وAPP_DEBUG=true وdb-dev ومفتاح اختبار، وstaging مع config/staging.env وdb-staging ومفتاح اختبار، وprod مع config/prod.env وdb-prod ومفتاح حقيقي وملف باسورد على سيرفر الإنتاج فقط، وتحتها أن ملف .env يختار البيئة بالمتغير APP_ENV
Image واحدة، والذي يتغير بين البيئات هو الإعداد فقط

التشغيل Run في بيئة dev ثم بيئة staging

نبدأ ببيئة التطوير، فنكتب في .env اسم البيئة والمنفذ، ثم نبني ونشغل:

printf 'APP_ENV=dev\nHOST_PORT=18080\n' > .env
docker compose up -d --build
docker logs dvo-env-dev

والمخرج سوف يكون كما يلي:

config ok:
  env                = dev                                <- env:APP_ENV
  port               = 8080                               <- file:settings.toml
  debug              = True                               <- env:APP_DEBUG
  payment_base_url   = https://sandbox.pay.example.com    <- default
  max_upload_mb      = 20                                 <- file:settings.toml
  database_url       = postgres://app@db-dev:5432/shop    <- env:APP_DATABASE_URL
  database_password  = ****-1                             <- secret:/run/secrets/db_password
  payment_api_key    = ****x9                             <- env:APP_PAYMENT_API_KEY

ولنقرأ المخرج سطراً سطراً لأن كل سطر يبين طبقة مختلفة:

  • env جاءت من متغير البيئة APP_ENV الذي وضعه Compose من قسم environment.
  • port جاءت من الملف المشترك، فالقيمة الافتراضية في الكود هي 8080 أيضاً، ولكن الملف كتب فوقها بنفس القيمة، ولذلك يظهر المصدر الملف وليس default.
  • debug قيمتها True بالنوع الصحيح، أي أن النص true في الملف تحول إلى قيمة منطقية عبر الدالة parse.
  • payment_base_url هي الوحيدة التي بقيت من القيم الافتراضية، وهي عنوان بيئة الاختبار، وهذا مقصود: القيمة الافتراضية لأي شيء خطير يجب أن تكون الخيار الآمن، فإذا نسي أحد هذا الإعداد في dev فلن يرسل طلبات دفع حقيقية.
  • max_upload_mb قيمتها 20 من الملف، وقد غطت القيمة الافتراضية 10.
  • database_password جاءت من ملف السر، ويظهر منها آخر حرفين فقط، وهذا يكفي لتعرف أي باسورد قرأ التطبيق دون أن تكشفه في السجل.

ثم ننتقل إلى staging بتغيير سطرين في .env فقط، دون أي تعديل في الكود ولا في ملف Compose:

sed -i 's/APP_ENV=dev/APP_ENV=staging/; s/18080/18081/' .env
docker compose up -d
docker logs dvo-env-staging
config ok:
  env                = staging                            <- env:APP_ENV
  port               = 8080                               <- file:settings.toml
  debug              = False                              <- env:APP_DEBUG
  payment_base_url   = https://sandbox.pay.example.com    <- default
  max_upload_mb      = 20                                 <- file:settings.toml
  database_url       = postgres://app@db-staging:5432/shop <- env:APP_DATABASE_URL
  database_password  = ****-2                             <- secret:/run/secrets/db_password
  payment_api_key    = ****q2                             <- env:APP_PAYMENT_API_KEY

وهنا تظهر فائدة الطباعة بمصادرها، فلو سألك أحد «هل staging تتصل بقاعدة بيانات staging فعلاً؟» فالإجابة في السجل، والباسورد آخره -2 وليس -1، أي أنه ملف staging وليس ملف dev. ولاحظ أن ال Image هي نفسها dvo-env-app:1.0.0، ولم نبن شيئاً جديداً.

الإنتاج يرفض أن يبدأ Fail Fast

الآن ننتقل إلى الإنتاج، وملف الإنتاج كما ذكرنا ينقصه مفتاح بوابة الدفع:

sed -i 's/APP_ENV=staging/APP_ENV=prod/; s/18081/18082/' .env
docker compose up -d
docker logs dvo-env-prod
docker ps -a --filter name=dvo-env-prod --format '{{.Names}} {{.Status}}'
config: 1 problem(s), refusing to start:
  - payment_api_key: required, set APP_PAYMENT_API_KEY or APP_PAYMENT_API_KEY_FILE
dvo-env-prod Exited (1) 4 seconds ago

وهذا هو السلوك الذي نريده بالضبط: ال Container خرج برمز 1 خلال ثوان، والرسالة تقول ما الناقص وكيف تضيفه، ولم يصل أي طلب إلى تطبيق نصف مهيأ. وفي خط CI/CD حقيقي، مثل الذي بنيناه في مقال Gitea Actions، تستطيع أن تشغل التحقق نفسه خطوة قبل النشر، بالخيار --check الذي يتحقق ويطبع ويخرج دون أن يفتح المنفذ.

ثم جربنا ما يحدث إذا كانت هناك أكثر من مشكلة، فشغلنا التطبيق مرة واحدة بقيمتين خاطئتين فوق ملف الإنتاج، عبر الخيار -e في docker compose run:

docker compose run --rm --no-deps -e APP_DEBUG=yes -e APP_MAX_UPLOAD_MB=20MB app
config: 3 problem(s), refusing to start:
  - payment_api_key: required, set APP_PAYMENT_API_KEY or APP_PAYMENT_API_KEY_FILE
  - max_upload_mb: invalid literal for int() with base 10: '20MB' (from env:APP_MAX_UPLOAD_MB)
  - debug: must be false when env=prod

ثلاث مشاكل في رسالة واحدة، وكل واحدة تقول من أين جاءت القيمة الخاطئة. ولاحظ أن APP_DEBUG=yes قيمة صحيحة النوع، فالدالة parse قبلتها وحولتها إلى True، ولكن قاعدة الربط بين القيم رفضتها لأن البيئة هي الإنتاج. ولاحظ كذلك أن -e غطت القيمتين في config/prod.env، وهذا يقودنا إلى ترتيب الأولوية في Compose نفسه.

من يغلب في Docker Compose؟ Compose Precedence

تذكر أننا قلنا إن التطبيق له ترتيب أولوية بين طبقاته الأربع، ولكن قبل أن تصل القيمة إلى التطبيق أصلاً فإن Compose له ترتيبه الخاص، وتوثيق Docker يذكره في صفحة ترتيب أولوية متغيرات البيئة من الأعلى إلى الأدنى كما يلي:

  1. القيمة التي تمررها بالخيار -e في docker compose run.
  2. القيمة في environment أو env_file إذا كانت مأخوذة بالاستبدال من الطرفية أو من ملف .env.
  3. القيمة المكتوبة مباشرة في environment داخل ملف Compose.
  4. القيمة في ملف env_file.
  5. القيمة المكتوبة في ال Image نفسها بالتعليمة ENV في Dockerfile.

ولكي ترى النتيجة النهائية دون أن تشغل شيئاً استخدم الأمر docker compose config، فهو يطبع ملف Compose بعد كل الاستبدالات وبعد دمج env_file مع environment:

docker compose config
    environment:
      APP_DATABASE_PASSWORD_FILE: /run/secrets/db_password
      APP_DATABASE_URL: postgres://app@db-prod:5432/shop
      APP_DEBUG: "false"
      APP_ENV: prod
      APP_PAYMENT_API_KEY: sk_live_9f$$Kq2w
      APP_PAYMENT_BASE_URL: https://api.pay.example.com

وهذا المخرج من خطوة لاحقة بعد أن أضفنا مفتاح الدفع، وسوف نعود إلى علامة $$ الغريبة فيه بعد قليل. ولاحظ شيئين مهمين: الأول أن الأمر يطبع القيم كاملة، بما فيها مفتاح الدفع، ولذلك لا تقم بتشغيله في خط CI يحفظ سجلاته، والسبب أن كل من يقرأ السجل سوف يقرأ المفتاح. والثاني أن متغير الطرفية يغلب ملف .env في الاستبدال، فإذا كان في الطرفية APP_ENV=staging فإن Compose يستخدم ملفات staging حتى لو كان .env يقول prod، والمثال التالي يبين ذلك:

APP_ENV=staging docker compose config | grep -E 'container_name|file:'
APP_ENV= docker compose config
    container_name: dvo-env-staging
    file: D:\Active_Projects\Cloud-Event\ArabRoot\content\articles\env-config\lab\secrets\staging_db_password.txt

error while interpolating services.app.container_name: required variable APP_ENV is missing a value: set APP_ENV in .env

والسطر الأخير هو أثر الصيغة ${APP_ENV:?...}، فالمتغير الفارغ في الطرفية غطى ملف .env، فرفض Compose العمل برسالتنا نحن. وهذه الحالة تحدث فعلاً على السيرفرات عندما يصدر أحدهم export APP_ENV=... في ملف تهيئة الطرفية ثم ينساه، فيتصرف Compose بطريقة مختلفة لكل مستخدم يدخل السيرفر.

مشكلة واجهتنا: الاستبدال Interpolation قطع مفتاح الدفع دون خطأ

بعد أن رأينا الإنتاج يرفض أن يبدأ أضفنا مفتاح الدفع إلى ملف الإنتاج، وكان المفتاح التجريبي الذي اخترناه يحتوي علامة $، وهذا يحدث كثيراً مع المفاتيح والباسوردات المولدة عشوائياً:

echo 'APP_PAYMENT_API_KEY=sk_live_9f$Kq2w' >> config/prod.env
docker compose up -d
docker logs dvo-env-prod | tail -1
docker exec dvo-env-prod sh -c 'echo "$APP_PAYMENT_API_KEY"'
level=warning msg="The \"Kq2w\" variable is not set. Defaulting to a blank string."
  payment_api_key    = ****9f                             <- env:APP_PAYMENT_API_KEY
sk_live_9f

التطبيق بدأ، والتحقق نجح، والإعداد يبدو صحيحاً، ولكن المفتاح داخل ال Container هو sk_live_9f فقط. والسبب أن Compose يطبق الاستبدال Interpolation على قيم env_file أيضاً، فقرأ $Kq2w على أنه متغير اسمه Kq2w، ولم يجده، فوضع مكانه نصاً فارغاً، واكتفى بتحذير في الطرفية يختفي بين أسطر المخرج. ولاحظ أن آخر حرفين في سطر التطبيق هما 9f وليس 2w، وهذا ما كشف المشكلة، فالطباعة الجزئية للأسرار لها فائدة حقيقية. وفي الإنتاج الحقيقي كان هذا يعني أن كل طلب دفع سوف يفشل بخطأ مصادقة من بوابة الدفع، والفريق سوف يبحث في الكود وفي بوابة الدفع وفي الشبكة قبل أن يفكر في علامة الدولار.

ثم جربنا الملف نفسه مع docker run --env-file بدل Compose، فكانت النتيجة مختلفة:

docker run --rm --env-file config/prod.env python:3.13-slim sh -c 'echo "docker run --env-file: $APP_PAYMENT_API_KEY"'
docker run --env-file: sk_live_9f$Kq2w

أي أن docker run يقرأ الملف حرفياً دون استبدال، وCompose يستبدل. وبحسب توثيق الاستبدال في Compose فإن القيمة بين علامتي اقتباس مفردة Single Quotes تستخدم حرفياً، فعدلنا السطر وأعدنا التجربة بالأداتين:

sed -i "s/^APP_PAYMENT_API_KEY=.*/APP_PAYMENT_API_KEY='sk_live_9f\$Kq2w'/" config/prod.env
docker compose up -d
docker exec dvo-env-prod sh -c 'echo "compose single quotes: $APP_PAYMENT_API_KEY"'
docker run --rm --env-file config/prod.env python:3.13-slim sh -c 'echo "docker run --env-file with quotes: $APP_PAYMENT_API_KEY"'
compose single quotes: sk_live_9f$Kq2w
docker run --env-file with quotes: 'sk_live_9f$Kq2w'

Compose أصبح يقرأ المفتاح صحيحاً، ولكن docker run أصبح يضع علامات الاقتباس داخل القيمة نفسها، أي أن السطر الذي يصلح لأداة يفسد الأخرى. والصورة التالية تلخص النتائج الأربع:

السطر APP_PAYMENT_API_KEY=sk_live_9f$Kq2w بدون اقتباس: docker compose مع env_file يعطي sk_live_9f مع تحذير أن المتغير Kq2w غير موجود، وdocker run --env-file يعطي القيمة كاملة. ومع الاقتباس المفرد: docker compose يعطي القيمة كاملة لأن الاقتباس المفرد قيمة حرفية Literal، وdocker run --env-file يضع علامات الاقتباس داخل القيمة
نفس السطر وأربع نتائج: ملف env ليس صيغة واحدة

والدرس من هذه المشكلة أكبر من علامة الدولار. فملف .env ليس صيغة معيارية لها مواصفة واحدة، وإنما كل أداة تقرؤه بطريقتها: Compose، وdocker run، ومكتبة dotenv في Node.js، وpython-dotenv، وsystemd في EnvironmentFile، والطرفية إذا قرأته بالأمر source، وكل واحدة منها لها قواعدها في الاقتباس والاستبدال والتعليقات والمسافات. ولذلك عليك بثلاث قواعد: اختر أداة واحدة تقرأ ملف البيئة في كل مسار نشر ولا تخلط بينها، وتحقق من القيمة داخل ال Container نفسه وليس في الملف، وضع الأسرار في ملفات أسرار مستقلة كما فعلنا مع الباسورد، لأن الملف الذي يحتوي قيمة واحدة لا يمر على أي استبدال ولا اقتباس. وإذا كان لا بد من علامة $ في قيمة داخل ملف Compose نفسه فاكتبها $$، وهذا ما رأيته في مخرج docker compose config سابقاً، فهي الطريقة التي يكتب بها Compose الدولار الحرفي.

ماذا يحدث إذا غيرت الإعداد ثم أعدت التشغيل Restart؟

التجربة الأخيرة من نوع «ماذا يحدث لو»: الفريق احتاج أن يرفع الحد الأقصى للرفع في الإنتاج إلى 50 ميجابايت، فأضاف السطر إلى ملف الإنتاج، ثم أعاد تشغيل الخدمة بالأمر الذي يبدو منطقياً:

echo 'APP_MAX_UPLOAD_MB=50' >> config/prod.env
docker compose restart
curl -s localhost:18082/config | python -c 'import json,sys;print(json.load(sys.stdin)["max_upload_mb"])'
{'value': 20, 'source': 'file:settings.toml'}

القيمة ما زالت 20، والتطبيق لم ير المتغير الجديد أصلاً. والسبب ما ذكرناه عن البيئة في نظام التشغيل: متغيرات البيئة تكتب في إعداد ال Container لحظة إنشائه Create، والأمر docker compose restart يوقف ال Container نفسه ويشغله بنفس إعداده، ولا يقرأ ملف Compose ولا ملفات البيئة من جديد، وتوثيق الأمر ينص على ذلك صراحة. أما docker compose up -d فيقارن الإعداد الحالي بالمطلوب، فإذا وجد فرقاً حذف ال Container وأنشأ غيره:

docker compose up -d
curl -s localhost:18082/config | python -c 'import json,sys;print(json.load(sys.stdin)["max_upload_mb"])'
 Container dvo-env-prod Recreate
 Container dvo-env-prod Recreated
 Container dvo-env-prod Started
{'value': 50, 'source': 'env:APP_MAX_UPLOAD_MB'}
ثلاث خطوات: تعديل ملف config/prod.env بإضافة APP_MAX_UPLOAD_MB=50، ثم docker compose restart يبقي نفس ال Container ونفس البيئة القديمة فتبقى القيمة 20 من settings.toml، ثم docker compose up -d يكتشف التغيير فيعيد إنشاء ال Container فتصبح القيمة 50 من متغير البيئة، وتحتها أن تعديل ConfigMap في Kubernetes لا يصل إلى متغيرات البيئة في Pod يعمل
البيئة تكتب عند إنشاء ال Container وليس عند تشغيله

والقيمة الآن 50، ومصدرها متغير البيئة. والفكرة نفسها موجودة في Kubernetes بشكل أوضح، فتوثيق ConfigMap يذكر أن ال ConfigMap الذي يصل إلى ال Pod كمتغيرات بيئة لا يتحدث تلقائياً عندما تعدله، وإنما يحتاج إعادة تشغيل ال Pod، أما إذا وصل كملف داخل Volume فإنه يتحدث بعد فترة. ولذلك تعامل أغلب الفرق أي تغيير في الإعداد على أنه نشر جديد Deploy: تعديل في المستودع، ثم مراجعة، ثم إعادة إنشاء، ولا تعتمد على تحديث الإعداد أثناء العمل إلا إذا كان التطبيق مصمماً لذلك فعلاً.

الأسرار Secrets ليست إعداداً عادياً

بعد التجارب السابقة طرحنا السؤال الذي يتجاهله كثير من الفرق: إذا كانت الأسرار في متغيرات البيئة، فمن يستطيع أن يقرأها؟ فقمنا بفحص ال Container الذي يعمل في الإنتاج من ثلاث جهات:

docker inspect dvo-env-prod --format '{{range .Config.Env}}{{println .}}{{end}}' | grep APP_
docker exec dvo-env-prod sh -c 'tr "\0" "\n" < /proc/1/environ | grep PAYMENT_API'
docker exec dvo-env-prod sh -c 'ls -l /run/secrets/; id'
APP_DATABASE_URL=postgres://app@db-prod:5432/shop
APP_PAYMENT_BASE_URL=https://api.pay.example.com
APP_PAYMENT_API_KEY=sk_live_9f$Kq2w
APP_DATABASE_PASSWORD_FILE=/run/secrets/db_password
APP_ENV=prod
APP_DEBUG=false
APP_PAYMENT_API_KEY=sk_live_9f$Kq2w
total 0
-rwxrwxrwx 1 root root 12 Nov  3 09:31 db_password
uid=65534(nobody) gid=65534(nogroup) groups=65534(nogroup)

في المخرج أعلاه لاحظ التالي:

  • docker inspect يعرض مفتاح الدفع كاملاً، وكل من يستطيع أن يشغل أوامر Docker على السيرفر يستطيع أن يقرأه، وهذا يشمل أي أداة مراقبة أو إدارة لها صلاحية الوصول إلى Docker Socket.
  • الملف /proc/1/environ داخل ال Container يعرض المفتاح أيضاً، وأي Process فرعي يشغله التطبيق يرث نسخة منه.
  • باسورد قاعدة البيانات لا يظهر في أي منهما، فالمتغير الوحيد هو APP_DATABASE_PASSWORD_FILE، أي مسار الملف وليس محتواه.
  • الملف db_password يظهر بصلاحيات مفتوحة rwxrwxrwx، والسبب أن هذا المختبر يعمل على Docker Desktop في Windows، وملف السر في Compose هو Bind Mount لملف على السيرفر، فيأخذ صلاحياته من نظام الملفات الذي جاء منه. وعلى سيرفر Linux حقيقي اجعل صلاحيات ملفات الأسرار 600 أو 640 ومالكها المستخدم الذي يشغل Compose.

ثم جربنا الخطأ الأشهر على الإطلاق، وهو أن يكتب أحدهم المفتاح في Dockerfile بالتعليمة ENV ليريح نفسه من ملفات البيئة، فبنينا Image تجريبية فوق ال Image الأصلية فيها سطر واحد:

FROM dvo-env-app:1.0.0
ENV APP_PAYMENT_API_KEY=sk_live_baked_8d21
docker build -q -t dvo-env-app:bad .
docker history dvo-env-app:bad --format '{{.CreatedBy}}' | head -2
docker inspect dvo-env-app:bad --format '{{json .Config.Env}}'
ENV APP_PAYMENT_API_KEY=sk_live_baked_8d21
CMD ["python" "app.py"]
["PATH=/usr/local/bin:...","LANG=C.UTF-8","GPG_KEY=...","PYTHON_VERSION=3.13.18","PYTHON_SHA256=...","APP_PAYMENT_API_KEY=sk_live_baked_8d21"]

والمفتاح الآن جزء من ال Image نفسها، يظهر في docker history وفي docker inspect، وينتقل مع ال Image إلى ال Registry وإلى كل سيرفر يسحبها وإلى كل مطور يشغلها على جهازه، ولا يمكن حذفه منها إلا ببناء Image جديدة، والنسخ القديمة تبقى في ال Registry. والصورة التالية تجمع كل الأماكن التي ظهر فيها المفتاح في المختبر:

ستة صناديق: docker inspect يعرض القيمة في Config.Env، والملف /proc/1/environ داخل ال Container وكل عملية فرعية ترث المتغيرات، وdocker compose config يطبع الإعداد بالقيم فيصل إلى سجلات CI، وENV في Dockerfile يظهر في docker history وdocker inspect لكل من يسحب ال Image، ورسائل الأخطاء والسجلات وصفحات التشخيص قد تطبع البيئة، وبالأخضر ملف السر /run/secrets/db_password الذي لا يظهر في inspect ولا يرثه أحد
كل الأماكن التي ظهر فيها مفتاح الدفع لأنه في متغير بيئة

ملفات الأسرار Secret Files مع الاصطلاح _FILE

ويشرح توثيق الأسرار في Compose أن متغيرات البيئة متاحة لكل العمليات، ويصعب تتبع من وصل إليها، وقد تطبع في السجلات عند تصحيح الأخطاء دون أن تنتبه، ولذلك يقدم Compose الأسرار ملفاً داخل ال Container في المسار /run/secrets/<name>، عبر Bind Mount لملف واحد. ويذكر التوثيق كذلك أن المتغيرات التي تنتهي بـ _FILE اصطلاح تستخدمه Images رسمية كثيرة، ومنها Image PostgreSQL الرسمية التي تقبل POSTGRES_PASSWORD_FILE بدل POSTGRES_PASSWORD، وهذا هو الاصطلاح الذي اتبعناه في تطبيق المختبر.

وقد يتساءل البعض: إذا كان ملف السر مجرد ملف غير مشفر على السيرفر، فما الفرق الحقيقي؟ والإجابة أن الفرق في عدد الطرق التي يتسرب منها السر وليس في التشفير. فالملف لا يظهر في docker inspect، ولا يرثه أي Process فرعي، ولا يطبعه docker compose config، ولا تلتقطه أدوات الأخطاء التي تطبع البيئة كاملة، ويمكن أن تكون له صلاحيات تختلف عن بقية الإعداد. وفي Docker Swarm وKubernetes تذهب الأسرار خطوة أبعد، فتحفظ مشفرة في قاعدة بيانات المنصة وتصل إلى الذاكرة فقط على السيرفر الذي يحتاجها، ولكن الفكرة في Compose على سيرفر واحد هي تقليل الطرق، وهذا هدف واقعي ومفيد.

وإذا احتاج البناء نفسه إلى سر، مثل توكن للوصول إلى مستودع حزم خاص أثناء npm install، فلا تستخدم ARG ولا ENV، والسبب أن قيمها تبقى في تاريخ ال Image، وإنما استخدم Build Secrets التي تجعل السر متاحاً لخطوة البناء فقط دون أن يدخل أي طبقة Layer.

متى تحتاج مخزن أسرار Secrets Manager؟

ملفات الأسرار على السيرفر تكفي فريقاً صغيراً بسيرفرات قليلة، ولكن مع نمو الفريق تظهر أسئلة لا تجيب عنها الملفات: من غير هذا الباسورد ومتى؟ كيف تغيره Rotate في عشرة سيرفرات في وقت واحد؟ كيف تعطي المطور الجديد أسرار staging دون أسرار الإنتاج؟ وكيف تلغي صلاحية موظف غادر؟ وهنا تأتي مخازن الأسرار Secrets Managers مثل HashiCorp Vault وOpenBao وInfisical، ومخازن المنصات السحابية، أو أدوات تشفير الأسرار داخل المستودع نفسه مثل SOPS، فيصبح الملف المشفر في Git ولا يفكه إلا السيرفر الذي يملك المفتاح. ويلخص دليل OWASP لإدارة الأسرار ما يجب أن يوفره أي حل منها: مكان مركزي، وصلاحيات بأقل قدر ممكن، وسجل لكل وصول Audit Log، وتغيير دوري للأسرار، وطريقة سريعة لإلغاء السر عند تسربه.

والمهم هنا أن تصميم التطبيق لا يتغير عندما تنتقل من الملفات إلى مخزن أسرار، فالتطبيق ما زال يقرأ APP_DATABASE_PASSWORD_FILE، والذي يتغير هو من يكتب الملف: Compose من ملف على السيرفر، أو أداة مساعدة تجلبه من Vault وتكتبه في ذاكرة مؤقتة، أو Kubernetes من Secret. وهذه فائدة كبيرة لاصطلاح _FILE، فهو يفصل التطبيق عن طريقة توصيل الأسرار، كما فصل متغير البيئة التطبيق عن البيئة نفسها.

الإعداد في Kubernetes: ConfigMap مع Secret

إذا انتقل الفريق يوماً ما إلى Kubernetes فسوف يجد نفس الطبقات بأسماء أخرى. فال ConfigMap يحمل الإعداد العادي، ويصل إلى ال Pod إما كمتغيرات بيئة أو كملفات داخل Volume، وال Secret يحمل الأسرار بنفس الطريقتين. والتوصية نفسها التي وصلنا إليها مع Compose تنطبق هنا: الإعداد العادي متغيرات بيئة، والأسرار ملفات داخل Volume، والتطبيق يقرأ _FILE. ولاحظ أن ال Secret في Kubernetes بشكله الافتراضي مرمز بصيغة Base64 وليس مشفراً، فكل من يملك صلاحية قراءة ال Secrets في ال Namespace يقرؤها، ولذلك تحتاج إعداد التشفير في قاعدة بيانات ال Cluster وصلاحيات RBAC محدودة قبل أن تعتبرها مكاناً آمناً.

وفرق آخر يستحق الانتباه هو أن تعديل ConfigMap لا يعيد تشغيل أي شيء، فإذا كان التطبيق يقرأ الإعداد كمتغيرات بيئة فلن يرى التعديل حتى تعيد إنشاء ال Pods، وهو نفس ما رأيناه مع restart في المختبر. ولذلك تضيف كثير من الفرق بصمة Hash لمحتوى ال ConfigMap في وصف ال Deployment، فيتغير الوصف كلما تغير الإعداد، ويعيد Kubernetes إنشاء ال Pods تلقائياً، وبهذا يصبح تغيير الإعداد نشراً كاملاً بكل ما فيه من تدرج وإمكانية تراجع.

تغيير الإعداد تغيير في الإنتاج Config Changes

من أخطر الأفكار في هذا الموضوع أن تغيير الإعداد أقل خطراً من تغيير الكود، لأنه «مجرد قيمة». والواقع أن الإعداد يغير سلوك التطبيق مثل الكود تماماً، ولكنه غالباً يمر دون مراجعة ودون اختبار ودون نشر تدريجي. وفي 18 نوفمبر 2014 توقفت خدمة Azure Storage في مناطق كثيرة حول العالم، وبحسب تقرير السبب الجذري الذي نشرته Microsoft فإن السبب تغيير في الإعداد لتحسين أداء Azure Table Storage، وقد حدث فيه خطآن: لم يتبع المهندس سياسة النشر التدريجي على شرائح صغيرة لأن التغيير كان قد جرب أسابيع على جزء من الإنتاج فظنه قليل الخطر، وفعل مفتاح الإعداد بالخطأ على الواجهات الأمامية Front-Ends لخدمة Blob Storage بدل Table Storage، فدخلت هذه الواجهات في حلقة لا نهائية ولم تعد تستقبل الطلبات. وأرجع الفريق التغيير خلال 30 دقيقة، ولكن الواجهات العالقة في الحلقة لم تستطع أن تستقبل الإعداد الجديد أصلاً واحتاجت إعادة تشغيل، فطال التعافي. والدرس الذي كتبته Microsoft في التقرير أن السياسة كانت موجودة ولكن أدوات النشر كانت تعتمد على قرار الإنسان، فعدلت الأدوات لتفرض النشر التدريجي على كل تغيير، كوداً كان أو إعداداً.

وبالنسبة لفريق صغير فإن ترجمة هذا الدرس بسيطة: ملفات الإعداد غير السرية تعيش في Git بجانب الكود أو في مستودع إعداد خاص كما في GitOps، وأي تغيير فيها يمر بطلب دمج Pull Request يراجعه شخص آخر، والتحقق من الإعداد بالخيار --check يعمل في CI قبل الدمج، والتغيير يصل إلى staging قبل الإنتاج، وكل تغيير له Commit تستطيع أن ترجع إليه. أما الأسرار فلا تعيش في Git كقيم مكشوفة، ولكن قائمة أسمائها وأماكنها تعيش فيه.

توثيق الإعداد Documentation مع ملف .env.example

المطور الجديد الذي ينضم إلى الفريق يحتاج أن يعرف ما هي المتغيرات التي يحتاجها التطبيق ليعمل على جهازه، وأسوأ إجابة هي «اسأل فلان يرسل لك ملفه». والحل الشائع هو ملف .env.example في المستودع، فيه كل المتغيرات بأسمائها وقيم وهمية أو فارغة وتعليق لكل منها، ويدخل Git، أما .env الحقيقي فيدخل .gitignore. والشكل التالي مثال لملف التطبيق في المختبر:

# Copy to config/<env>.env and fill in. Required values have no default.
# true only in dev; refused in prod
APP_DEBUG=false
# required
APP_DATABASE_URL=postgres://app@db:5432/shop
# live URL only in prod
APP_PAYMENT_BASE_URL=https://sandbox.pay.example.com
# integer, megabytes
APP_MAX_UPLOAD_MB=20
# Secrets: never here. Put them in secrets/<env>_*.txt and point APP_*_FILE at them.
# APP_DATABASE_PASSWORD_FILE=/run/secrets/db_password
# APP_PAYMENT_API_KEY_FILE=/run/secrets/payment_api_key

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

ما الذي يختلف فعلاً بين البيئات؟ Environment Differences

بعد كل ما سبق قد يبدو أن كل شيء يجب أن يكون إعداداً، ولكن الهدف هو العكس: أن يكون الفرق بين البيئات أقل ما يمكن، والسبب أن كل فرق بين staging والإنتاج مكان يمكن أن تختبئ فيه مشكلة لا تظهر إلا في الإنتاج. والجدول التالي يبين ما يختلف عادة وما يجب أن يبقى متشابهاً:

الإعدادdevstagingprodملاحظة
قاعدة البياناتمحلية في Containerمنفصلة ببيانات تجريبيةالحقيقيةنفس النوع ونفس الإصدار في الثلاث
بوابة الدفعSandboxSandboxLiveالقيمة الافتراضية دائماً Sandbox
البريدأداة تلتقط الرسائل محلياًأداة التقاط أو عناوين داخليةSMTP حقيقيالسلوك إعداد وليس شرطاً في الكود
وضع التصحيح Debugيعملمغلقمغلق، والتحقق يرفضهstaging مثل الإنتاج هنا
مستوى السجلات Log Leveldebuginfoinfoيمكن رفعه مؤقتاً عند التحقيق
الأسرارقيم تجريبيةقيم خاصة بهاقيم خاصة بهالا يتشارك سر بين بيئتين أبداً
ال Imageتبنى محلياًنفس Image الإنتاجنفس Image stagingتبنى مرة واحدة وتنقل كما هي

والسطر الأخير هو الذي يجعل كل ما في المقال ممكناً، فإذا كنت تبني Image لكل بيئة فأنت تختبر في staging شيئاً غير الذي يعمل في الإنتاج. وقد شرحنا في مقال البيئات كيف تبني مرة واحدة وتنقل ال Image بين البيئات، وهذا المقال هو الجزء الذي يجعل ذلك يعمل: ال Image لا تحتوي إلا ما هو مشترك، والإعداد يأتي من الخارج.

أين تضع كل قيمة؟ Decision Table

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

جدول من خمسة أسئلة: هل يتغير حين يتغير الكود فقط فهو ثابت في الكود Constant، وهل هو مشترك بين البيئات وله قيمة معقولة فهو قيمة افتراضية أو ملف إعداد مثل port وmax_upload_mb، وهل يختلف من بيئة إلى أخرى فهو متغير بيئة مثل عنوان قاعدة البيانات وAPP_DEBUG، وهل يضر إذا قرأه شخص آخر فهو ملف سر أو مخزن أسرار مثل الباسورد ومفتاح الدفع، وهل تريد تغييره دون نشر ولنسبة من المستخدمين فهو Feature Flag
خمسة أسئلة لكل قيمة جديدة

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

أخطاء شائعة Common Mistakes

  • ملف .env داخل Git: حتى لو حذفته بعد ذلك فهو في التاريخ، وكل نسخة من المستودع تحمله. أضفه إلى .gitignore قبل أول Commit، وافحص المستودع بأداة مثل Gitleaks.
  • تحويل "false" إلى True: كما رأينا، ودالة تحويل صريحة ترفض القيم غير المعروفة تمنعه.
  • قيمة افتراضية خطيرة: مثل أن يكون عنوان بوابة الدفع الافتراضي هو الحقيقي، فيرسل أي مطور نسي الإعداد طلبات حقيقية. القيمة الافتراضية يجب أن تكون الخيار الآمن.
  • تطبيق يبدأ بإعداد ناقص: ويفشل مع أول عميل بدل أن يفشل مع أول نشر.
  • علامة $ في ملف تقرؤه Compose: تختفي بقية القيمة مع تحذير فقط، والحل ملف سر أو اقتباس مفرد أو $$ بحسب الأداة.
  • الخلط بين أدوات قراءة ملف البيئة: نفس الملف مع Compose وdocker run وdotenv يعطي قيماً مختلفة.
  • docker compose restart بعد تعديل الإعداد: لا يقرأ الملفات من جديد، والصحيح docker compose up -d.
  • الأسرار في ENV أو ARG داخل Dockerfile: تصبح جزءاً من ال Image وتنتقل معها إلى كل مكان.
  • طباعة الإعداد كاملاً في السجل: عند التشغيل أو عند الخطأ، والصحيح أن تطبع المصدر وآخر حرفين من كل سر فقط.
  • شروط if env == "prod" في الكود: مسارات لا تختبر إلا في الإنتاج، والصحيح إعداد له اسم يصف السلوك.
  • سر مشترك بين البيئات: مثل باسورد واحد لقاعدة بيانات staging والإنتاج، فيصبح اختراق staging اختراقاً للإنتاج.
  • تغيير الإعداد مباشرة على السيرفر: دون Commit ودون مراجعة، فلا يعرف أحد بعد شهر لماذا أصبحت القيمة 50.

قائمة تحقق Checklist للإعداد

البندكيف تتحقق منه
لا يوجد أي سر في المستودع ولا في تاريخهGitleaks على التاريخ كاملاً، واختبار Twelve-Factor: هل تستطيع أن تفتح المستودع الآن؟
Image واحدة لكل البيئاتنفس البصمة Digest في staging والإنتاج
كل إعداد موصوف في مكان واحد بنوعهجدول مثل SCHEMA أو مكتبة إعداد، وملف .env.example يولد منه أو يقارن به
التطبيق يرفض البدء بإعداد ناقص أو خاطئتشغيل بملف ناقص يخرج برمز غير صفر ويطبع كل المشاكل معاً
القيم المنطقية والأرقام تحول بصرامةAPP_DEBUG=flase يرفض بدل أن يصبح True أو False
القيم الافتراضية آمنةتشغيل دون أي متغير لا يتصل بأي خدمة حقيقية
الأسرار ملفات وليست متغيراتdocker inspect لا يعرض أي باسورد أو مفتاح
صلاحيات ملفات الأسرار محدودة600 أو 640 على السيرفر، وخارج مجلد المستودع
التطبيق يطبع مصدر كل قيمةسطر لكل إعداد عند التشغيل، والأسرار مخفية
تغيير الإعداد يمر بمراجعةCommit وطلب دمج وفحص --check في CI قبل النشر
تغيير الإعداد يعيد إنشاء ال Containerdocker compose up -d في سكربت النشر وليس restart

تدريب عملي Practice

  • انقل مفتاح الدفع في المختبر من متغير البيئة إلى ملف سر ثان باسم payment_api_key، مع APP_PAYMENT_API_KEY_FILE، ثم تأكد أن docker inspect لم يعد يعرضه، وأن آخر حرفين في سجل التطبيق صحيحان.
  • أضف إلى SCHEMA إعداداً جديداً اسمه log_level يقبل أربع قيم فقط: debug وinfo وwarning وerror، واجعل التحقق يرفض debug في الإنتاج.

حذف المختبر Cleanup

docker compose down
docker rm -f dvo-env-dev dvo-env-staging
docker rmi dvo-env-app:1.0.0 dvo-env-app:bad

الخلاصة Summary

وصلنا لنهاية الموضوع، وأهم ما فيه:

  • الإعداد هو ما يختلف بين أماكن تشغيل الكود نفسه، وما يتغير مع الكود فقط مكانه الكود، والأسرار فئة منفصلة لها مكانها.
  • الكود الجيد لا يعرف اسم البيئة، وإنما قيماً لها معنى، وال Image الواحدة تنتقل بين البيئات والإعداد يأتي من الخارج.
  • الطبقات الأربع، الافتراضي ثم الملف ثم البيئة ثم ملفات الأسرار، مع طباعة مصدر كل قيمة، توفر ساعات من البحث.
  • التحقق عند التشغيل يحول الإعداد الخاطئ من عطل يكتشفه العميل إلى نشر فاشل يكتشفه الفريق خلال ثوان، و"false" ليست False إلا إذا حولتها بنفسك.
  • ملف env ليس صيغة واحدة، وعلامة $ قطعت مفتاحنا في Compose وبقيت سليمة في docker run، والملف الذي يحتوي سراً واحداً يتجنب كل ذلك.
  • متغيرات البيئة تظهر في docker inspect و/proc وتورث، والأسرار مكانها ملفات أو مخزن أسرار، وتغيير الإعداد نشر كامل يمر بمراجعة ويعيد إنشاء ال Container.

وفي المقال القادم من هذه المرحلة بإذن الله نتكلم عن الإصدارات Versioning وSemVer وسجل التغييرات، أي كيف تعطي كل Image تبنيها رقماً له معنى، وكيف يعرف من يستخدمها ما الذي تغير.

دليلمن الفرع إلى الإنتاج: البيئات وGitOps للفرقكيف يختبر فريقك كل ميزة وحدها ويعرضها على العميل دون أن تصل ميزة غير جاهزة إلى الإنتاج.دليلقبل أن تنشر تطبيقك على خادمك: قائمة تحقق للمطورالأخطاء التي لا تظهر إلا بعد نشر تطبيقك في Docker خلف Reverse Proxy، وكيف تعالج كل واحد منها قبل أن يصل إلى المستخدمين.دليلSecrets Scanning: كيف تكتشف الأسرار المسربة في الكودكيف يخرج المفتاح من جهازك إلى تاريخ Git وخط CI، وكيف تكتشفه قبل غيرك، وماذا تفعل في الساعة الأولى بعد تسربه.دليلFeature Flags: انشر الكود وفعل الميزة لاحقاًكيف يفصل ال Feature Flag بين نشر الكود وإطلاق الميزة، وكيف تطلقها لجزء من المستخدمين أولاً وتوقفها فوراً إذا تعطلت.دليلGitea Actions: تشغيل CI/CD وبناء Docker Images على سيرفركاجعل سيرفرك يختبر الكود ويبني Docker Images تلقائياً مع كل push، دون أن يخرج كودك أو أسرارك إلى خدمة CI خارجية.

سجل التحديثات Changelog

  • نوفمبر 2026: كتابة الدليل وتنفيذ المختبر بإصدارات Python 3.13.18 وDocker Engine 29.8.0 وDocker Compose v5.5.1.
نشرة عرب رووت | ArabRoot

معرفة تستحق مكاناً في بريدك.

مقالات مختارة وأدوات مفيدة وأفكار لمشروعك القادم، في رسالة واحدة كل أسبوع.

يمكنك إلغاء الاشتراك متى شئت. الخصوصية

تم استلام طلبك. افتح بريدك واضغط رابط التأكيد لإتمام الاشتراك.