لماذا ملف Adminer.php فارغ؟ مع العلم أن إعادة تسميته تُحل المشكلة. إليكم تحليل السبب وحل من ثلاث خطوات.

بعد ظهر أمس، كنتُ أقوم بإعداد أداة إدارة قواعد البيانات Adminer على الخادم. Adminer أداة خفيفة وسهلة الاستخدام؛ ملف PHP واحد يكفي، على عكس phpMyAdmin الذي يتطلب العديد من التبعيات. قمتُ بتنزيل أحدث إصدار من الموقع الرسمي، ورفعته إلى الخادم، وضبطتُ الصلاحيات، ثم فتحتُ المتصفح، مستعدًا لتجربته.

ثم، أصبح كل شيء فارغاً.

قمت بتحديث الصفحة ثلاث مرات، وأصابعي تؤلمني من كثرة الضغط على زر F5. لا شيء. فتحت أدوات مطوري المتصفح؛ ظهرت رسالة خطأ 200 OK، لكن محتوى الاستجابة كان فارغًا. كنتُ في حيرة تامة. ما الذي يحدث؟

فكرتُ في الأمر للحظة. هل يُحتمل أن تكون المشكلة في صلاحيات الملف؟ تحققتُ، وكانت 755. هل يُحتمل أن يكون السبب عدم توافق إصدار PHP؟ تحققتُ، وهو PHP 8.2، وهذا مناسب. هل يُحتمل أن يكون الملف نفسه تالفًا؟ نزّلتُ نسخة جديدة، واستبدلتُ النسخة القديمة، ولا يزال الملف فارغًا.

لسبب غير مفهوم، فكرت، لماذا لا أحاول تغيير اسمي؟

قمت بتغيير اسم الملف adminer.php إلى adminer1.php وقمت بتحديث الصفحة.

تم الوصول بنجاح.

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

ملف adminer.php فارغ.

علمت لاحقاً أن هذا لم يكن نوعاً من الخرافات؛ بل كان التخزين المؤقت لـ PHP هو الذي يسبب المشكلة.

OPcache، اختصارًا لـ Opcode Cache، هو إضافة لتحسين أداء لغة PHP. مبدأ عمله بسيط: PHP لغة مُفسَّرة، ويتطلب كل طلب ترجمة كود PHP إلى رمز تشغيل (opcode) قبل تنفيذه. يقوم OPcache بتخزين النتيجة المُترجمة في الذاكرة، مما يسمح للطلبات اللاحقة باستخدام النسخة المُخزَّنة مباشرةً دون إعادة الترجمة، ما يُحسِّن الأداء بشكل ملحوظ.

لكن المشكلة تكمن هنا.

في السابق، كان ملف adminer.php يعرض رسالة "الملف غير موجود" (كنت قد حمّلت الملف الخاطئ)، وكان OPcache قد خزّن نتيجة تجميع ذلك المحتوى غير الصحيح. لاحقًا، استبدلت ملف adminer.php بالرمز الصحيح، لكن OPcache تجاهله واستمر في قراءة ذاكرة التخزين المؤقت القديمة، مما أدى إلى ظهور صفحة فارغة أو رسالة الخطأ القديمة.

عندما تقوم بإعادة تسميته إلى adminer1.php، يصبح مسار ملف جديد تمامًا لـ OPcache، وسيعيد تحميله وحله بشكل صحيح.

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

السبب الأول: ذاكرة التخزين المؤقت OPcache تتسبب في ظهور مساحات فارغة

كيفية التعامل معها؟

أعد تشغيل خدمة PHP-FPM وقم بمسح ذاكرة التخزين المؤقت OPcache.

# 查看正在运行的PHP版本
php -v

# 重启对应的PHP-FPM（例如PHP 8.5）
sudo systemctl restart php8.5-fpm

# 或者重启所有PHP-FPM服务
sudo systemctl restart php*-fpm

بعد إعادة التشغيل، أعد تسمية الملف إلى adminer.php، ثم قم بتحديث صفحة الويب (يوصى بالضغط على Ctrl+F5 لإجبار المتصفح على التحديث)، ويجب أن يتم حل المشكلة.

لكن القصة لم تنته بعد.

بعد إعادة تشغيل PHP-FPM، قمتُ بتغيير ملف adminer.php إلى وضعه الأصلي، ثم قمتُ بتحديث الصفحة، لكنها ظلت فارغة. لقد كنتُ في حيرةٍ تامة.

السبب الثاني: قيود قواعد تكوين Nginx

وهذا يقودنا إلى السبب الثاني المحتمل.

قد يحتوي ملف تكوين Nginx على قواعد خاصة تقيد ملف adminer.php.

قمتُ سابقًا بضبط Fail2Ban في لوحة تحكم HestiaCP، وكتبتُ قاعدة مطابقة تامة لملف adminer.php لمنع هجمات التخمين العشوائي. كانت القاعدة تُثبّت اسم الملف adminer.php، لذا بمجرد إعادة تسميته إلى adminer1.php، يُمكن تجاوز قاعدة Nginx هذه والوصول إليه بشكل طبيعي.

طريقة استكشاف الأخطاء وإصلاحها بسيطة: ابحث عن إدخالات ثابتة في تكوين Nginx.

sudo grep -rn "adminer.php" /etc/nginx/

إذا وجدت قواعد مثل `location = /adminer.php { … }`، فهذا يعني أن Nginx يتعامل مع هذا الملف تحديدًا بطريقة خاصة. ما عليك سوى حذفه أو تعديله.

السبب الثالث: إعدادات عرض أخطاء PHP

السبب الثالث أكثر دقة.

يتم اعتراض سكربت PHP أو يُصدر خطأً، لكن الصفحة تُعطّل عرض الأخطاء (display_errors = Off). في بيئة الإنتاج، يُخفي PHP الأخطاء افتراضيًا، ويعرض صفحة فارغة. إذا تعطل ملف الإدخال (مثل index.php) لسبب ما أثناء محاولة تضمين "./adminer.php"، فستصبح الصفحة فارغة.

في هذه الحالة، يعد فحص سجل الأخطاء الطريقة الأكثر موثوقية:

# 查看Nginx错误日志
sudo tail -n 20 /var/log/nginx/error.log

# 或者查看HestiaCP对应域名的error日志
sudo tail -n 20 /var/log/nginx/domains/adminer.domain.com.error.log

سيخبرك سجل النظام بالسبب الحقيقي لظهور الشاشة البيضاء.

بصراحة، اكتشفت المشكلة أخيرًا بفحص ملف سجل الأخطاء (error.log). اتضح أن ملف adminer.php كان يستدعي إضافة PHP غير موجودة، وأن خاصية عرض الأخطاء (display_errors) كانت معطلة، لذا كانت الصفحة فارغة، لكن سجل الأخطاء سجل ذلك بوضوح.

الحلول وخطوات استكشاف الأخطاء وإصلاحها

لقد تركت هذه الحادثة أثراً عميقاً في نفسي.

غالباً ما تكون المشاكل التقنية أكثر تعقيداً مما تبدو عليه ظاهرياً. قد يبدو ملف adminer.php الفارغ مشكلة في الملف للوهلة الأولى، لكن التعمق في البحث قد يكشف عن مشكلة في التخزين المؤقت، وفي مرحلة لاحقة قد تكون مشكلة في الإعدادات، وفي مرحلة أبعد قد تكون مشكلة في الكود نفسه.

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

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

لا يمكننا وصف الدواء المناسب إلا من خلال إيجاد السبب الجذري الحقيقي.

وأخيرًا، إذا واجهت أيضًا مشكلة ملف adminer.php الفارغ، فتحقق منه بهذا الترتيب:

أولاً، أعد تشغيل PHP-FPM وقم بمسح ذاكرة التخزين المؤقت، ثم تحقق من إعدادات Nginx، وأخيراً تحقق من ملف error.log.

في معظم الحالات، تكفي الخطوتان الأوليان لحل المشكلة.

بالطبع، إذا لم ينجح ذلك، فتحقق من ملف سجل الأخطاء (error.log).

سيخبرك بالإجابة.

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

شكراً لكم على قراءة مقالتي. أراكم في المرة القادمة.