دليل استكشاف أخطاء خوادم الويب في 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:
bash
# استخدم أمر الإزالة الخاص بـ Herd
herd uninstall
# إذا لم يكن الأمر متاحًا، احذف التطبيق والملفات يدويًا
rm -rf ~/Library/Application\ Support/Herd
rm -rf ~/.config/herd
1
2
3
4
5
6
2
3
4
5
6
2. حذف الملفات المتبقية في مجلد /etc/resolver
حتى بعد الإزالة الصحيحة، قد تبقى ملفات "محول DNS" في /etc/resolver/
. احذفها يدوياً:
bash
# استعرض ملفات مجلد /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
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
ملفات التحويل الشائعة التي تنشئها 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 في النظام لتطبيق التغييرات فوراً:
bash
# macOS Big Sur (11) وما بعده
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
# macOS Catalina (10.15) والإصدارات الأقدم
sudo killall -HUP mDNSResponder
1
2
3
4
5
2
3
4
5
5. التحقق من الإصلاح
بعد التنظيف، زر موقعك على ServBay:
- افتح الموقع في المتصفح
- استخدم أدوات مطور Chrome → تبويب الشبكة (Network)
- حدّث الصفحة وافحص تفاصيل الـ Timing
- يجب أن تكون مدة DNS Lookup أقل من 50ms
بهذا ستتمكن من حل مشكلة بطء التحميل الأول بعد الانتقال من MAMP أو Laravel Herd. إذا استمرت المشكلة راجع ما إذا كان لديك برامج طرف ثالث (مثل VPN أو أدوات البروكسي) تؤثر على تحليل الـ DNS.
فحص إعدادات خادم الويب
أخطاء ملفات إعداد الخادم هي سبب شائع لعدم عمل الموقع. يوفر ServBay أدوات فحص لكل خادم.
فحص ملف Caddyfile
استخدم أمر Caddy المدمج validate
للتحقق من صحة ملف Caddyfile:
bash
# 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
1
2
3
4
5
2
3
4
5
إذا كان الملف صحيحًا، تظهر رسالة Valid configuration
. أما عند وجود خطأ، سيظهر نوع الخطأ وتوضيح للسبب.
ملاحظة: قد تظهر الكثير من رسائل INFO
أو WARN
، وهي إرشادية داخلية من Caddy وليست أخطاء إذا ظهرت كلمة Valid configuration
في النهاية.
أمثلة على أخطاء Caddyfile:
خطأ عدم وجود ملف الشهادة:
bash# 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
1
2
3
4
5
6
7
8
9إذا ظهرت رسالة الخطأ
loading certificates: open xxxxx: no such file or directory
فهذا يعني أن مسار شهادة SSL في Caddyfile غير صحيح أو الملف غير موجود. تحقق من مسار ملفات الشهادة (.crt
/.cer
/.pem
) والمفتاح (.key
) وتأكد من وجودها. يدعم ServBay الاستيراد اليدوي أو الحصول التلقائي باستخدام ACME، تحقق من إعدادات SSL في ServBay.خطأ مسار مجلد الموقع (احتواء المسار فراغات):
bash# 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
1
2
3
4
5
6
7يظهر الخطأ
parsing caddyfile tokens for 'root': too many arguments
عندما يحتوي مسار مجلد الموقع على فراغات مثل:- macOS:
root * /Applications/ServBay/www/public web
حيث يرى Caddypublic 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
.- macOS:
خطأ في قواعد إعادة الكتابة Rewrite:
استخدام قواعد Rewrite غير متوافقة مع صياغة Caddy قد يؤدي للفشل عند الفحص. راجع توثيق قواعد إعادة الكتابة في Caddy أو دليل نقل مواقع NGINX إلى ServBay للتأكد من صحة الكتابة.
فحص إعدادات NGINX
استخدم الخيار -t
لفحص صحة إعدادات NGINX:
bash
# macOS
/Applications/ServBay/bin/nginx -t
# Windows
C:\ServBay\bin\nginx.exe -t
1
2
3
4
5
2
3
4
5
إذا كان كل شيء صحيحًا، تظهر الرسائل:
# 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
3
4
5
6
7
2
3
4
5
6
7
أما عند وجود أخطاء، يحدد البرنامج الملف وصف رقم السطر. من أسباب المشاكل:
- أخطاء الصياغة: مثل نسيان الفاصلة المنقوطة
;
، أو إغلاق القوس}
. - خطأ في مسار الملفات: في سطر
include
أو توجيهات أخرى. - تعارض المنافذ: محاولة استخدام منفذ مشغول بالفعل.
فحص إعدادات Apache
استخدم الأمر apachectl configtest
لفحص صحة إعداد Apache:
bash
# macOS
/Applications/ServBay/bin/apachectl configtest
# Windows
C:\ServBay\bin\httpd.exe -t
1
2
3
4
5
2
3
4
5
إذا كان كل شيء سليمًا تظهر عبارة Syntax OK
، أما في حالة الخطأ تظهر تفاصيله. الأسباب الشائعة:
- فشل تحميل الوحدة: عند تفعيل وحدة
LoadModule
بسطر خاطئ أو ملف مفقود. - أخطاء في ملف .htaccess: عند خطأ الصياغة في أحد مجلدات الموقع.
- سوء إعداد صلاحيات المجلدات: إعدادات
Directory
أوFiles
(مثلRequire
,Allow
,Deny
) قد تمنع الوصول للملفات.
معالجة خطأ 500 الداخلي للخادم
يشير خطأ 500 إلى مشكلة في الخادم أثناء تنفيذ الطلب، وغالبًا ما يتعلق بعطل في السكربتات الخلفية (PHP، Python، Node.js، إلخ).
خطوات التشخيص العامة
لدى ظهور خطأ 500، اتبع الخطوات:
مراجعة سجل أخطاء خادم الويب: غالبًا ما تكشف هذه السجلات تفاصيل هامة (مثل أخطاء السكربت أو مشاكل في الملفات أو الصلاحيات).
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
.- Caddy:
تحقق من تشغيل الخدمات الخلفية (مثل PHP-FPM): إن كان الموقع يعتمد على PHP، تأكد من أن PHP-FPM يعمل.
bashps aux | grep php-fpm
1ابحث عن سطور مثل
php-fpm: master process
أوphp-fpm: pool www
. إذا لم تجدها، قم بتشغيل الخدمة من واجهة ServBay أو عبر أمرservbayctl
.فحص سجل أخطاء السكربتات (مثلاً سجل أخطاء 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
) فقط وليس في الإنتاج.- macOS:
فحص صلاحيات الملفات والمجلدات: خادم الويب عادة ما يعمل كمستخدم نظام محدد ويحتاج صلاحيات كافية لقراءة مجلدات الموقع والكتابة في مجلدات التحميل أو السجلات.
macOS:
bashls -la /Applications/ServBay/www/your-site/
1تأكد أن المستخدم مثل
_www
لديه صلاحيات قراءة وكتابة حسب الحاجة. استخدم أوامرchmod
وchown
لتعديلها.Windows:
cmddir C:\ServBay\www\your-site
1راجع صلاحيات المستخدم الذي يشغل ServBay وتأكد أن له إمكانية الوصول عبر إعدادات الأمن في خصائص المجلد.
نقاط التشخيص الخاصة بكل خادم
Caddy:
- إعداد FastCGI: تحقق من صحة عنواين
php_fastcgi
أوreverse_proxy
في Caddyfile بحيث تشير لعنوان PHP-FPM (عادة127.0.0.1:9000
أوunix:/path/to/php-fpm.sock
). - حالة PHP-FPM: تأكد أن نسخة PHP وPHP-FPM المطلوبين يعملان في ServBay.
- إعدادات البروكسي العكسي: إذا كنت تستخدم
reverse_proxy
إلى خدمة خلفية (مثل تطبيق Node.js)، راجع العنوان والمنفذ وحالة الخدمة.
- إعداد FastCGI: تحقق من صحة عنواين
NGINX:
- توجيه
fastcgi_pass
: تحقق من صحة إعداداتfastcgi_pass
في ملفات إعداد NGINX. - إعداد
client_max_body_size
: عند رفع ملفات ضخمة، تأكد أن هذا الإعداد يسمح بالحجم المطلوب. - توجيهات
try_files
: تأكد من صحة إعدادها وعدم تعارضها مع المؤشرات للمجلدات أو الملفات الضرورية.
- توجيه
Apache:
- وحدة
mod_rewrite
: إذا كنت تستخدم ملفات.htaccess
للتحويل، تأكد أن وحدةmod_rewrite
مفعلة. - محتوى
.htaccess
: مشاكل الصياغة في.htaccess
تؤدي مباشرةً إلى خطأ 500. دقق في قواعدRewriteRule
وغيرها. - إعداد
AllowOverride
: يجب أن يسمح إعدادAllowOverride
في إعدادة Apache بتنفيذ أوامر.htaccess
(عادة يجب ضبطها علىAll
أو تضمينFileInfo
وLimit
).
- وحدة
إدارة الخدمات
بعد تعديل الإعدادات أو حل مشاكل الخدمات الخلفية، ستحتاج غالبًا لإعادة تشغيل الخادم للخدمة للتأكد من تطبيق التغييرات.
إعادة تشغيل الخدمات
استخدم أمر servbayctl restart
لإعادة تشغيل الخادم المطلوب:
bash
# إعادة تشغيل خدمة Caddy
servbayctl restart caddy -all
# إعادة تشغيل خدمة NGINX
servbayctl restart nginx -all
# إعادة تشغيل خدمة Apache
servbayctl restart apache -all
1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
الخيار -all
يعيد تشغيل الخدمات المترابطة، فمثلاً عند إعادة تشغيل Caddy/NGINX/Apache سيعاد تشغيل PHP-FPM إذا كان مستخدمًا.
عرض حالة الخدمات
استخدم أمر servbayctl status
للاطلاع على حالة الخدمة:
bash
# عرض حالة خدمة Caddy
servbayctl status caddy -all
# عرض حالة خدمة NGINX
servbayctl status nginx -all
# عرض حالة خدمة Apache
servbayctl status apache -all
1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
ستظهر حالة الخدمة كـ running
(يعمل)، أو stopped
(متوقف)، أو حالات أخرى. يساعدك ذلك على التأكد من بدء الخدمة فعليًا.
خطوات التشخيص المتقدمة
إذا لم تنجح الأساليب السابقة، جرب الطرق التالية الأكثر تفصيلًا:
- استخدام أدوات مطور المتصفح: افتحها (عادة بالضغط على F12)، وراجع تبويبي
Console
(التحكم) وNetwork
(الشبكة) لرصد أخطاء JavaScript، وحالة الطلبات، ورؤوس الاستجابة لتحديد هل المشكلة أمامية أم خلفية. - استخدام أمر curl -v: عبر الطرفية، نفذ
curl -v your-website.servbay.demo
لاستعراض تفاصيل الطلب والاستجابة، بما فيها رؤوس الـ HTTP وتفاصيل الـ SSL/TLS. عدّلyour-website.servbay.demo
ليطابق موقعك. - غلق جدار الحماية مؤقتًا: قد يمنع جدار الحماية المحلي أو البرامج الأمنية الاتصالات. أغلقه مؤقتًا وإذا اختفت المشكلة، قم بإعداد القواعد المناسبة للسماح لمنافذ ServBay (مثل 80 و443).
- الفحص عبر متصفحات/أجهزة أخرى: زر الموقع من جهاز أو متصفح آخر للتأكد أن المشكلة ليست في الكاش أو إعدادات الجهاز.
- فحص ملفات hosts أو إعدادات DNS: إذا كنت تستخدم نطاقات مخصصة (وليس
localhost
أو IP)، تأكد من تعيينها بشكل صحيح في ملف hosts المحلي:- macOS:
/etc/hosts
- Windows:
C:\Windows\System32\drivers\etc\hosts
- macOS:
الملخص
مشاكل خوادم الويب تحدٍّ شائع أثناء التطوير المحلي. بأتباع خطوات منهجية لفحص صحة الإعدادات، ومراجعة سجلات الأخطاء، والتحقق من حالة الخدمات وصلاحيات الملفات، ستتمكن غالبًا من إصلاح أغلب الأعطال بنفسك. استخدم أدوات التشخيص المدمجة في ServBay وأمر servbayctl
كأدوات قوية داعمة. وإذا واجهتك مشكلة معقدة، راجع وثائق ServBay بتوسع أو تواصل مع فريق الدعم الفني.