دليل استكشاف أخطاء خوادم الويب في ServBay وإصلاحها

يدعم ServBay استخدام Caddy وNGINX وApache كـخوادم ويب افتراضية، ليمنحك بيئة تطوير محلية مرنة. قد تواجه أثناء الاستخدام مشاكل في الوصول للموقع أو بطء التحميل أو ظهور أخطاء (مثل خطأ 500 الداخلي). يهدف هذا الدليل إلى مساعدتك في تشخيص وحل مشاكل خوادم الويب الشائعة ضمن بيئة ServBay.

استخدام أداة التشخيص المدمجة في ServBay

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

افتح تطبيق ServBay ومن القائمة الجانبية اختر تشخيص الأعطال للدخول إلى لوحة التشخيص.

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

بطء تحميل الموقع لأول مرة بعد الانتقال من MAMP أو Laravel Herd

قد تلاحظ بعد الانتقال من MAMP أو Laravel Herd إلى ServBay، أن الموقع يحتاج لأكثر من 5 ثواني ليعمل عند أول زيارة بعد فترة خمول، بينما يكون التحميل سريع في الزيارات التالية. إذا توقفت عن العمل لمدة، يتكرر البطء في أول تحميل جديد مرة أخرى.

أعراض المشكلة

عند فتح أدوات مطوري Chrome (بالضغط على F12 أو Cmd+Option+I) والذهاب إلى تبويب الشبكة (Network)، ثم تحديث الصفحة وإلقاء نظرة على تفاصيل الـ Timing ستجد أن مدة DNS Lookup تصل إلى حوالي 5 ثواني.

(توضيح: عرض مدة DNS Lookup ضمن تبويب الشبكة في أدوات مطور Chrome)

سبب المشكلة

يقوم MAMP و Laravel Herd عند تثبيتهما بتعديل إعدادات DNS في macOS عبر إنشاء ملفات إعداد خاصة لتحويل أسماء نطاقات معينة (*.test, *.local وغيرها) من خلال ملفات في مجلد /etc/resolver/.

حتى بعد إزالة MAMP أو Laravel Herd، قد تبقى هذه الملفات ويتسبب ذلك بأن macOS يحاول أولاً استخدام تلك "المحولّات" القديمة للاستعلام عن DNS، ومع غياب خدمة DNS الخاصة بـ MAMP/Herd يحدث تأخير (عادة 5 ثواني) قبل أن يرجع النظام إلى DNS الافتراضي.

الحل

اتبع الخطوات التالية لإزالة إعدادات DNS المتبقية من MAMP أو Laravel Herd:

1. إزالة MAMP أو Laravel Herd بالكامل

إذا لم تقم بإزالة البرامج تماماً، استخدم أدوات الإزالة الرسمية أو أسطر الأوامر المخصصة.

إزالة MAMP:

• استخدم وظيفة الإزالة داخل تطبيق MAMP.
• أو احذف مجلد /Applications/MAMP يدوياً ونظف الملفات المتعلقة.

إزالة Laravel Herd:

# استخدم أمر الإزالة الخاص بـ Herd
herd uninstall

# إذا لم يكن الأمر متاحًا، احذف التطبيق والملفات يدويًا
rm -rf ~/Library/Application\ Support/Herd
rm -rf ~/.config/herd

2. حذف الملفات المتبقية في مجلد /etc/resolver

حتى بعد الإزالة الصحيحة، قد تبقى ملفات "محول DNS" في /etc/resolver/. احذفها يدوياً:

# استعرض ملفات مجلد /etc/resolver
ls -la /etc/resolver

# احذف ملفات التحويل المستهدفة (مثلاً test و local)
sudo rm /etc/resolver/test
sudo rm /etc/resolver/local

# احذف أي ملفات محوّلات أخرى أنشأتها MAMP/Herd
# مثال: sudo rm /etc/resolver/herd

ملفات التحويل الشائعة التي تنشئها MAMP/Herd:

• test - لأسماء النطاقات على صيغة *.test
• local - لأسماء على شكل *.local
• herd - خاص بـ Laravel Herd

ملاحظة: تحتاج صلاحية المدير (sudo) للحذف.

3. تجنب استخدام لاحقة *.local للنطاقات

تحجز macOS لاحقة .local للـ mDNS (خدمة Bonjour للشبكات المحلية)، واستخدامها في التطوير يسبب:

• تعارضات في تحليل DNS
• بطء في الوصول
• تصرفات غير متوقعة في الشبكة

النصيحة: استخدم لاحقات أخرى أثناء التطوير مثل:

• .test - TLD مخصص للاختبار
• .localhost - دائمًا يشير إلى محلي loopback
• .dev - TLD حقيقي لكن شائع محليًا
• أو استخدم لاحقة مخصصة حسب توصية ServBay

4. تفريغ ذاكرة DNS (اختياري)

بعد الخطوات السابقة، أفرغ ذاكرة DNS في النظام لتطبيق التغييرات فوراً:

# macOS Big Sur (11) وما بعده
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

# macOS Catalina (10.15) والإصدارات الأقدم
sudo killall -HUP mDNSResponder

5. التحقق من الإصلاح

بعد التنظيف، زر موقعك على ServBay:

1. افتح الموقع في المتصفح
2. استخدم أدوات مطور Chrome → تبويب الشبكة (Network)
3. حدّث الصفحة وافحص تفاصيل الـ Timing
4. يجب أن تكون مدة DNS Lookup أقل من 50ms

بهذا ستتمكن من حل مشكلة بطء التحميل الأول بعد الانتقال من MAMP أو Laravel Herd. إذا استمرت المشكلة راجع ما إذا كان لديك برامج طرف ثالث (مثل VPN أو أدوات البروكسي) تؤثر على تحليل الـ DNS.

فحص إعدادات خادم الويب

أخطاء ملفات إعداد الخادم هي سبب شائع لعدم عمل الموقع. يوفر ServBay أدوات فحص لكل خادم.

فحص ملف Caddyfile

استخدم أمر Caddy المدمج validate للتحقق من صحة ملف Caddyfile:

# macOS
/Applications/ServBay/bin/caddy validate -c /Applications/ServBay/etc/caddy/Caddyfile

# Windows
C:\ServBay\bin\caddy.exe validate -c C:\ServBay\etc\caddy\Caddyfile

إذا كان الملف صحيحًا، تظهر رسالة Valid configuration. أما عند وجود خطأ، سيظهر نوع الخطأ وتوضيح للسبب.

ملاحظة: قد تظهر الكثير من رسائل INFO أو WARN، وهي إرشادية داخلية من Caddy وليست أخطاء إذا ظهرت كلمة Valid configuration في النهاية.

أمثلة على أخطاء Caddyfile:

• خطأ عدم وجود ملف الشهادة:

  # macOS
  2024/12/09 17:24:16.970 INFO using config from file {"file": "/Applications/ServBay/etc/caddy/Caddyfile"}
  ... (INFO/WARN أخرى) ...
  Error: loading http app module: provision http: getting tls app: loading tls app module: provision tls: loading certificates: open /Applications/ServBay/ssl/private/tls-certs/mail.servbay.host/mail.servbay.host.1crt: no such file or directory
  
  # Windows
  2024/12/09 17:24:16.970 INFO using config from file {"file": "C:\\ServBay\\etc\\caddy\\Caddyfile"}
  ... (INFO/WARN أخرى) ...
  Error: loading http app module: provision http: getting tls app: loading tls app module: provision tls: loading certificates: open C:\\ServBay\\ssl\\private\\tls-certs\\mail.servbay.host\\mail.servbay.host.1crt: no such file or directory

  إذا ظهرت رسالة الخطأ loading certificates: open xxxxx: no such file or directory فهذا يعني أن مسار شهادة SSL في Caddyfile غير صحيح أو الملف غير موجود. تحقق من مسار ملفات الشهادة (.crt/.cer/.pem) والمفتاح (.key) وتأكد من وجودها. يدعم ServBay الاستيراد اليدوي أو الحصول التلقائي باستخدام ACME، تحقق من إعدادات SSL في ServBay.

• خطأ مسار مجلد الموقع (احتواء المسار فراغات):

  # macOS
  2024/12/09 17:26:37.371 INFO using config from file {"file": "/Applications/ServBay/etc/caddy/Caddyfile"}
  Error: adapting config using caddyfile: parsing caddyfile tokens for 'root': too many arguments; should only be a matcher and a path, at /Applications/ServBay/etc/caddy/Caddyfile:1388
  
  # Windows
  2024/12/09 17:26:37.371 INFO using config from file {"file": "C:\\ServBay\\etc\\caddy\\Caddyfile"}
  Error: adapting config using caddyfile: parsing caddyfile tokens for 'root': too many arguments; should only be a matcher and a path, at C:\\ServBay\\etc\\caddy\\Caddyfile:1388

  يظهر الخطأ parsing caddyfile tokens for 'root': too many arguments عندما يحتوي مسار مجلد الموقع على فراغات مثل:

  • macOS: root * /Applications/ServBay/www/public web حيث يرى Caddy public web كمُعاملين.
  • Windows: root * C:\ServBay\www\public web يرى public web كمُعاملين.

  الحل الصحيح: استخدم علامات الاقتباس " حول المسار:

  • macOS: root * "/Applications/ServBay/www/public web"
  • Windows: root * "C:\ServBay\www\public web"

  نصيحة: تجنب الفراغات والرموز الخاصة عند تسمية الملفات والمجلدات. استخدم الشرط أو underscore مثل public-folder أو public_dir.

• خطأ في قواعد إعادة الكتابة Rewrite:

  استخدام قواعد Rewrite غير متوافقة مع صياغة Caddy قد يؤدي للفشل عند الفحص. راجع توثيق قواعد إعادة الكتابة في Caddy أو دليل نقل مواقع NGINX إلى ServBay للتأكد من صحة الكتابة.

فحص إعدادات NGINX

استخدم الخيار -t لفحص صحة إعدادات NGINX:

# macOS
/Applications/ServBay/bin/nginx -t

# Windows
C:\ServBay\bin\nginx.exe -t

إذا كان كل شيء صحيحًا، تظهر الرسائل:

# macOS
nginx: the configuration file /Applications/ServBay/etc/nginx/nginx.conf syntax is ok
nginx: configuration file /Applications/ServBay/etc/nginx/nginx.conf test is successful

# Windows
nginx: the configuration file C:\ServBay\etc\nginx\nginx.conf syntax is ok
nginx: configuration file C:\ServBay\etc\nginx\nginx.conf test is successful

أما عند وجود أخطاء، يحدد البرنامج الملف وصف رقم السطر. من أسباب المشاكل:

1. أخطاء الصياغة: مثل نسيان الفاصلة المنقوطة ;، أو إغلاق القوس }.
2. خطأ في مسار الملفات: في سطر include أو توجيهات أخرى.
3. تعارض المنافذ: محاولة استخدام منفذ مشغول بالفعل.

فحص إعدادات Apache

استخدم الأمر apachectl configtest لفحص صحة إعداد Apache:

# macOS
/Applications/ServBay/bin/apachectl configtest

# Windows
C:\ServBay\bin\httpd.exe -t

إذا كان كل شيء سليمًا تظهر عبارة Syntax OK، أما في حالة الخطأ تظهر تفاصيله. الأسباب الشائعة:

1. فشل تحميل الوحدة: عند تفعيل وحدة LoadModule بسطر خاطئ أو ملف مفقود.
2. أخطاء في ملف .htaccess: عند خطأ الصياغة في أحد مجلدات الموقع.
3. سوء إعداد صلاحيات المجلدات: إعدادات Directory أو Files (مثل Require, Allow, Deny) قد تمنع الوصول للملفات.

معالجة خطأ 500 الداخلي للخادم

يشير خطأ 500 إلى مشكلة في الخادم أثناء تنفيذ الطلب، وغالبًا ما يتعلق بعطل في السكربتات الخلفية (PHP، Python، Node.js، إلخ).

خطوات التشخيص العامة

لدى ظهور خطأ 500، اتبع الخطوات:

1. مراجعة سجل أخطاء خادم الويب: غالبًا ما تكشف هذه السجلات تفاصيل هامة (مثل أخطاء السكربت أو مشاكل في الملفات أو الصلاحيات).

   macOS:

   • Caddy: /Applications/ServBay/var/logs/caddy/error.log
   • NGINX: /Applications/ServBay/var/logs/nginx/error.log
   • Apache: /Applications/ServBay/var/logs/apache/error.log

   Windows:

   • Caddy: C:\ServBay\var\logs\caddy\error.log
   • NGINX: C:\ServBay\var\logs\nginx\error.log
   • Apache: C:\ServBay\var\logs\apache\error.log

   ابحث عن أحدث السطور التي تحتوي على كلمة error أو critical.

2. تحقق من تشغيل الخدمات الخلفية (مثل PHP-FPM): إن كان الموقع يعتمد على PHP، تأكد من أن PHP-FPM يعمل.

   ps aux | grep php-fpm

   ابحث عن سطور مثل php-fpm: master process أو php-fpm: pool www. إذا لم تجدها، قم بتشغيل الخدمة من واجهة ServBay أو عبر أمر servbayctl.

3. فحص سجل أخطاء السكربتات (مثلاً سجل أخطاء PHP): إذا احتوى سجل خادم الويب على خطأ خاص بـ FastCGI أو السكربت الخلفي، راجع سجل أخطاء PHP.

   أماكن سجل أخطاء PHP:

   • macOS: /Applications/ServBay/var/logs/php/php_error.log
   • Windows: C:\ServBay\var\logs\php\php_error.log

   ابحث عن رسائل مثل Fatal error, Parse error, Warning, Notice، خاصة المتعلقة بالسكريبت الذي تزوره. تأكد أن خاصية display_errors مفعلة مؤقتًا أثناء التطوير (عبر إعداد php.ini) فقط وليس في الإنتاج.

4. فحص صلاحيات الملفات والمجلدات: خادم الويب عادة ما يعمل كمستخدم نظام محدد ويحتاج صلاحيات كافية لقراءة مجلدات الموقع والكتابة في مجلدات التحميل أو السجلات.

   macOS:

   ls -la /Applications/ServBay/www/your-site/

   تأكد أن المستخدم مثل _www لديه صلاحيات قراءة وكتابة حسب الحاجة. استخدم أوامر chmod و chown لتعديلها.

   Windows:

   dir C:\ServBay\www\your-site

   راجع صلاحيات المستخدم الذي يشغل ServBay وتأكد أن له إمكانية الوصول عبر إعدادات الأمن في خصائص المجلد.

نقاط التشخيص الخاصة بكل خادم

• Caddy:

  1. إعداد FastCGI: تحقق من صحة عنواين php_fastcgi أو reverse_proxy في Caddyfile بحيث تشير لعنوان PHP-FPM (عادة 127.0.0.1:9000 أو unix:/path/to/php-fpm.sock).
  2. حالة PHP-FPM: تأكد أن نسخة PHP وPHP-FPM المطلوبين يعملان في ServBay.
  3. إعدادات البروكسي العكسي: إذا كنت تستخدم reverse_proxy إلى خدمة خلفية (مثل تطبيق Node.js)، راجع العنوان والمنفذ وحالة الخدمة.

• NGINX:

  1. توجيه fastcgi_pass: تحقق من صحة إعدادات fastcgi_pass في ملفات إعداد NGINX.
  2. إعداد client_max_body_size: عند رفع ملفات ضخمة، تأكد أن هذا الإعداد يسمح بالحجم المطلوب.
  3. توجيهات try_files: تأكد من صحة إعدادها وعدم تعارضها مع المؤشرات للمجلدات أو الملفات الضرورية.

• Apache:

  1. وحدة mod_rewrite: إذا كنت تستخدم ملفات .htaccess للتحويل، تأكد أن وحدة mod_rewrite مفعلة.
  2. محتوى .htaccess: مشاكل الصياغة في .htaccess تؤدي مباشرةً إلى خطأ 500. دقق في قواعد RewriteRule وغيرها.
  3. إعداد AllowOverride: يجب أن يسمح إعداد AllowOverride في إعدادة Apache بتنفيذ أوامر .htaccess (عادة يجب ضبطها على All أو تضمين FileInfo و Limit).

إدارة الخدمات

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

إعادة تشغيل الخدمات

استخدم أمر servbayctl restart لإعادة تشغيل الخادم المطلوب:

# إعادة تشغيل خدمة Caddy
servbayctl restart caddy -all

# إعادة تشغيل خدمة NGINX
servbayctl restart nginx -all

# إعادة تشغيل خدمة Apache
servbayctl restart apache -all

الخيار -all يعيد تشغيل الخدمات المترابطة، فمثلاً عند إعادة تشغيل Caddy/NGINX/Apache سيعاد تشغيل PHP-FPM إذا كان مستخدمًا.

عرض حالة الخدمات

استخدم أمر servbayctl status للاطلاع على حالة الخدمة:

# عرض حالة خدمة Caddy
servbayctl status caddy -all

# عرض حالة خدمة NGINX
servbayctl status nginx -all

# عرض حالة خدمة Apache
servbayctl status apache -all

ستظهر حالة الخدمة كـ running (يعمل)، أو stopped (متوقف)، أو حالات أخرى. يساعدك ذلك على التأكد من بدء الخدمة فعليًا.

خطوات التشخيص المتقدمة

إذا لم تنجح الأساليب السابقة، جرب الطرق التالية الأكثر تفصيلًا:

1. استخدام أدوات مطور المتصفح: افتحها (عادة بالضغط على F12)، وراجع تبويبي Console (التحكم) وNetwork (الشبكة) لرصد أخطاء JavaScript، وحالة الطلبات، ورؤوس الاستجابة لتحديد هل المشكلة أمامية أم خلفية.
2. استخدام أمر curl -v: عبر الطرفية، نفذ curl -v your-website.servbay.demo لاستعراض تفاصيل الطلب والاستجابة، بما فيها رؤوس الـ HTTP وتفاصيل الـ SSL/TLS. عدّل your-website.servbay.demo ليطابق موقعك.
3. غلق جدار الحماية مؤقتًا: قد يمنع جدار الحماية المحلي أو البرامج الأمنية الاتصالات. أغلقه مؤقتًا وإذا اختفت المشكلة، قم بإعداد القواعد المناسبة للسماح لمنافذ ServBay (مثل 80 و443).
4. الفحص عبر متصفحات/أجهزة أخرى: زر الموقع من جهاز أو متصفح آخر للتأكد أن المشكلة ليست في الكاش أو إعدادات الجهاز.
5. فحص ملفات hosts أو إعدادات DNS: إذا كنت تستخدم نطاقات مخصصة (وليس localhost أو IP)، تأكد من تعيينها بشكل صحيح في ملف hosts المحلي:
   • macOS: /etc/hosts
   • Windows: C:\Windows\System32\drivers\etc\hosts

الملخص

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