متغيرات البيئة في رصيف: لماذا لا يكفي الحفظ أو إعادة التشغيل؟

افهم متى تُطبّق متغيرات البيئة في رصيف، وكيف تعمل مراجع الخدمات، وشخّص القيم القديمة وأخطاء الاتصال دون كشف الأسرار.

عدّلت DATABASE_URL أو مفتاح خدمة خارجية في لوحة التحكم، لكن التطبيق ما زال يتصرف كأن شيئًا لم يتغير. قبل تعديل الشفرة أو إعادة تشغيل قاعدة البيانات، افصل بين ثلاثة أشياء: الإعداد المحفوظ، والقيمة التي حُلّت عند النشر، والإصدار الذي يعمل الآن.

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

القاعدة الأساسية: الحفظ ليس نشرًا

وفق وثائق المتغيرات، تُطبَّق المتغيرات عند النشر التالي. حفظ قيمة جديدة لا يعيد تشغيل الإصدار الجاري، وإعادة التشغيل تحتفظ بالقيم الحالية لذلك الإصدار.

الإجراءالنتيجة
حفظ متغير جديديحفظ الإعداد للنشر التالي؛ لا يغيّر التطبيق الجاري
نشر الإعداد المحفوظيبدأ إصدارًا بالقيم التي تُحَلّ وقت النشر
إعادة تشغيل الإصدار الجاريتحتفظ بالقيم الحالية؛ ليست وسيلة لتطبيق التعديلات المحفوظة
التراجع إلى إصدار سابقيستخدم القيم المحفوظة مع ذلك النشر

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

اربط الخدمات بمرجع بدل نسخ بيانات الاتصال

لنفترض أن لديك تطبيقًا وقاعدة PostgreSQL باسم db في البيئة نفسها. أضف في Variables الخاصة بالتطبيق:

DATABASE_URL=${{ db.DATABASE_URL }}

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

انتبه إلى شروط المراجع:

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

يُحفظ المرجع بهوية الخدمة؛ لذلك لا يؤدي تغيير اسم الخدمة إلى كسره. أما عنوانها الخاص، فالأفضل استخدام المرجع بدل نسخه يدويًا.

ماذا يحدث عندما تتغير القيمة في الخدمة المصدر؟

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

التسلسل المقترح:

  1. نفّذ التغيير المطلوب في الخدمة المصدر وانشره.
  2. راجع الخدمات التي تعتمد على القيمة.
  3. انشر كل خدمة مستهلكة تحتاج التحديث.
  4. اختبر عملية فعلية تعتمد على الاتصال، مثل قراءة سجل تجريبي.
  5. راقب الأخطاء دون طباعة سلسلة الاتصال أو المفتاح.

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

هذه خطوات تشغيلية مقترحة، وليست وعدًا بأن تدوير أي سر يتم بلا انقطاع.

مثال Node.js: تحقق من وجود الإعداد دون كشفه

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

const required = ['DATABASE_URL'];
const missing = required.filter(
  (name) => !process.env[name]?.trim()
);

if (missing.length > 0) {
  console.error('Missing required configuration:', missing.join(', '));
  process.exit(1);
}

console.info('Required configuration is present');

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

ولا تطبع process.env كاملًا للتشخيص. توضح الوثائق أن إخفاء الأسرار في السجلات له شروط وحدود؛ هو طبقة مساعدة لا مبرر لطباعة القيم الحساسة.

جدول تشخيص سريع

العَرَضما الذي تتحقق منه؟الخطوة التالية
القيمة القديمة ما زالت مستخدمةهل حفظت فقط أو اخترت Restart؟انشر الإعداد المحفوظ ثم اختبر السلوك
فشل حل المرجع عند النشراسم المرجع، البيئة، ونشر الخدمة المصدرصحح المرجع وانشر المصدر قبل المستهلك
المتغير موجود لكن الاتصال يفشلحالة قاعدة البيانات، المنفذ الخاص، وصلاحية بيانات الدخولافصل تشخيص الشبكة عن تشخيص المصادقة
الاتصال يعمل من التطبيق ولا يعمل من جهازكهل تستخدم العنوان الخاص؟اختبر من خدمة داخل البيئة نفسها
عاد خطأ المصادقة بعد Rollbackهل يستخدم الإصدار السابق سرًا أُلغي؟راجع توافق بيانات الدخول قبل اعتماد التراجع

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

قبل استخدام المحرر الخام أو التراجع

في Raw editor، تُطبَّق القائمة كما تحفظها: حذف سطر يحذف المتغير المقابل، وإذا تكرر الاسم تُستخدم القيمة الأخيرة. راجع الفروق قبل الحفظ، خصوصًا عند لصق ملف .env كامل.

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

قائمة تحقق للتغيير القادم

  • وثّق أسماء المتغيرات المطلوبة في .env.example دون قيم حساسة.
  • راجع الخدمة والبيئة المستهدفتين قبل الحفظ.
  • انشر التغيير؛ لا تكتفِ بالحفظ أو إعادة التشغيل.
  • اختبر وظيفة تعتمد على القيمة، وليس مجرد ظهور حالة تشغيل ناجحة.
  • تأكد أن خطة التراجع صالحة مع بيانات الدخول ومخطط البيانات الحاليين.

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

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