خطأ مفتاح التشفير أو خروج الجميع بعد نقل موقع Laravel: APP_KEY
باختصار: إذا نقل المطور موقعك المبني بـ Laravel إلى خادم جديد، فظهرت صفحة خطأ تقول إنه لم يُحدَّد مفتاح تشفير للتطبيق، أو فتح الموقع لكن كل الزبائن والموظفين خرجوا من حساباتهم، أو ظهرت أخطاء عند قراءة بيانات محفوظة، فالسبب غالباً متغير APP_KEY في ملف .env. إما أنه غير موجود على الخادم الجديد، أو أن أحدهم ولّد مفتاحاً جديداً بدل نسخ القديم. الحل: انسخ قيمة المفتاح القديم كما هي إن كانت متاحة، ولا تولّد مفتاحاً جديداً على موقع يعمل إلا وأنت تعرف العواقب، وإن اضطررت للتغيير فضع القديم في APP_PREVIOUS_KEYS.
ما هو APP_KEY ولماذا هو مهم؟
حسب توثيق التشفير في Laravel، يجب ضبط خيار key في ملف config/app.php قبل استخدام أداة التشفير في الإطار، وهذا الخيار يأخذ قيمته من متغير البيئة APP_KEY. ويقول التوثيق إن هذه القيمة تُولَّد عادة تلقائياً أثناء تثبيت Laravel، وإن الطريقة الموصى بها لتوليدها هي الأمر php artisan key:generate، لأنه يستخدم مولّد البايتات العشوائية الآمن في PHP لبناء مفتاح قوي.
الأهم من ذلك ما يذكره التوثيق عن استخدام المفتاح: Laravel يشفّر كل ملفات الكوكيز، بما فيها كوكيز الجلسات. ويُستخدم المفتاح نفسه لأي بيانات شفّرها التطبيق بأداة التشفير. إذن المفتاح ليس مجرد إعداد شكلي، بل هو ما يربط الجلسات الحالية والبيانات المشفرة بالتطبيق.
السيناريو الأول: المفتاح غير موجود على الخادم الجديد
ملف .env لا يُرفع عادة مع الكود. توثيق الإعدادات في Laravel ينص على أن ملف .env لا يجب أن يدخل نظام إدارة الكود، لأن كل خادم قد يحتاج إعدادات مختلفة، ولأن ذلك خطر أمني إن وصل أحد إلى المستودع.
النتيجة العملية: حين ينقل المطور الكود إلى خادم جديد، يجب أن ينشئ ملف .env هناك بنفسه. إذا نسي APP_KEY أو تركه فارغاً، يرفض التطبيق العمل ويعرض خطأ يشير إلى عدم وجود مفتاح تشفير. نص رسالة الخطأ الدقيق يختلف حسب الإصدار، وهو من خبرة عملية لا من صفحة التوثيق.
الحل الصحيح هنا ليس توليد مفتاح جديد فوراً، بل نسخ المفتاح من الخادم القديم إن كان ما زال متاحاً.
السيناريو الثاني: أحدهم ولّد مفتاحاً جديداً
يحدث كثيراً أن يرى المطور خطأ المفتاح المفقود، فينفّذ key:generate على الخادم الجديد. يعمل الموقع فوراً، فيظن أن المشكلة انتهت. لكن توثيق Laravel واضح بخصوص تغيير المفتاح:
- كل الجلسات المسجلة دخولها ستخرج من التطبيق، لأن كل الكوكيز، ومنها كوكيز الجلسات، مشفرة بالمفتاح القديم.
- لن يعود ممكناً فك تشفير أي بيانات شُفّرت بالمفتاح السابق.
البند الأول مزعج لكنه مؤقت: الزبائن والموظفون يسجلون دخولهم من جديد. أما البند الثاني فقد يكون خطيراً، إذا كان التطبيق يخزّن بيانات مشفرة في قاعدة البيانات، مثل ملاحظات سرية أو مفاتيح ربط مع خدمات أخرى.
مثال توضيحي: متجر ملابس في الزرقاء
متجر ملابس في الزرقاء عنده متجر إلكتروني ولوحة إدارة مبنيان بـ Laravel. انتقل المتجر إلى استضافة أسرع، ونقل مطور جديد الملفات وقاعدة البيانات. ظهر خطأ المفتاح، فولّد المطور مفتاحاً جديداً. فتح الموقع، لكن في الصباح اتصلت موظفة المبيعات تقول إنها خرجت من لوحة الإدارة، ثم ظهرت أخطاء في صفحة إعدادات الربط مع شركة التوصيل، لأن مفتاح الربط كان محفوظاً مشفراً.
الحل كان استرجاع المفتاح القديم من نسخة احتياطية لملف .env على الخادم القديم. هذا المثال توضيحي.
الخطوة الأولى: ابحث عن المفتاح القديم
قبل أي شيء:
- اسأل المطور السابق أو شركة الاستضافة القديمة عن ملف .env.
- ابحث في النسخ الاحتياطية للخادم القديم.
- إن كانت عندك أداة نشر أو لوحة استضافة تحفظ متغيرات البيئة، راجعها.
إذا وجدت القيمة، انسخها كما هي إلى APP_KEY في ملف .env على الخادم الجديد. المفتاح يبدأ عادة بالبادئة base64 كما في مثال التوثيق. إذا كان التطبيق يستخدم كاش الإعدادات، أعد بناءه بعد التعديل حتى تُقرأ القيمة.
الخطوة الثانية: إن ضاع المفتاح نهائياً
إذا لم يعد المفتاح القديم موجوداً، فلا مفر من مفتاح جديد. في هذه الحالة:
- أخبر الفريق والزبائن المهمين أن عليهم تسجيل الدخول من جديد.
- اطلب من المطور جرد البيانات التي شفّرها التطبيق، لأنها لن تُقرأ بعد الآن، ويجب إدخالها من جديد.
- كلمات المرور في تطبيقات Laravel تُحفظ عادة بطريقة التجزئة (hashing)، وهي عملية مختلفة عن التشفير الذي يشرحه توثيق التشفير. لذلك لا يُتوقع عادة أن يحتاج الزبائن إلى كلمات مرور جديدة، لكن اطلب من المطور أن يتأكد من ذلك في تطبيقك تحديداً.
الخطوة الثالثة: إن أردت تغيير المفتاح عمداً
أحياناً يجب تغيير المفتاح، مثلاً إذا تسرب ملف .env. التوثيق يقدّم طريقة لتخفيف الأثر: ضع المفاتيح السابقة في متغير APP_PREVIOUS_KEYS كقائمة مفصولة بفواصل. عندها يستخدم Laravel المفتاح الحالي للتشفير دائماً، وعند فك التشفير يجرّب المفتاح الحالي أولاً ثم المفاتيح السابقة حتى ينجح أحدها. يصف التوثيق ذلك بأنه يسمح للمستخدمين بمتابعة استخدام التطبيق دون انقطاع حتى بعد تغيير المفتاح.
بعدها يمكن للمطور إعادة تشفير البيانات المهمة بالمفتاح الجديد، ثم إزالة القديم من القائمة لاحقاً.
أين تحفظ المفتاح بأمان؟
المفتاح سر. لا يجب إرساله في محادثة عامة، ولا وضعه في المستودع. احفظ نسخة من ملف .env للإنتاج في مكان آمن تحت إدارة صاحب العمل لا المطور وحده، مثل مدير كلمات مرور للفريق. توثيق Laravel يذكر أيضاً ميزة تشفير ملف البيئة، التي تسمح بحفظه مشفراً في نظام إدارة الكود بأمان، وهي خيار للفرق التي تريد ذلك.
قائمة فحص عند نقل أي موقع Laravel
- هل APP_KEY على الخادم الجديد مطابق للقديم؟
- هل نُسخت بقية متغيرات البيئة كاملة؟
- هل أُعيد بناء كاش الإعدادات بعد التعديل؟
- هل تستطيع تسجيل الدخول بحساب كان مسجلاً قبل النقل؟
- هل صفحات الإعدادات التي فيها بيانات مشفرة تفتح دون أخطاء؟
- هل يملك صاحب العمل نسخة آمنة من ملف .env؟
أسئلة شائعة
ليش طلع خطأ مفتاح التشفير بعد ما نقلنا الموقع؟
لأن ملف .env لا يُنقل مع الكود عادة، وAPP_KEY غير موجود على الخادم الجديد. انسخ قيمته من الخادم القديم.
ولّدنا مفتاح جديد وكل الناس طلعوا من حساباتهم، طبيعي؟
نعم. توثيق Laravel يقول إن تغيير المفتاح يُخرج كل الجلسات، لأن الكوكيز مشفرة بالمفتاح القديم. وقد تتعذر قراءة البيانات المشفرة سابقاً.
هل في طريقة أغيّر المفتاح بدون ما أخرّب البيانات؟
ضع المفتاح القديم في APP_PREVIOUS_KEYS، فيجرّبه Laravel عند فك التشفير، حسب التوثيق.
مين لازم يحتفظ بالمفتاح؟
صاحب العمل، في مكان آمن، إلى جانب المطور. لا تجعله محفوظاً عند شخص واحد فقط.
إذا كنت تنقل موقعك المبني بـ Laravel أو حصل خلل بعد النقل، اتصل بنا ونراجع معك الإعدادات قبل أن يتأثر زبائنك.