تهيئة CORS (مشاركة الموارد بين المصادر) لموقعك في ServBay

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

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

ما هو CORS؟

مشاركة الموارد بين المصادر (CORS) هي آلية تستند إلى رؤوس HTTP تتيح للخادم تحديد النطاقات (المصدر/البروتوكول/المنفذ) المسموح لها بتحميل الموارد. عندما تحاول صفحة ويب تحميل بيانات من مصدر خارجي عن مصدرها الخاص، يعتبر ذلك "طلب HTTP عبر مصادر". وبحسب سياسة نفس الأصل، تمنع المتصفحات هذه الطلبات تلقائيًا. CORS يوفّر آلية تفاوض بين الخادم والمتصفح لتحديد ما إذا كان الطلب عبر المصادر مسموحًا وآمنًا.

لماذا يحتاج المطورون لتكوين CORS؟

عندما تبرمج تطبيقًا مقسمًا لخادم وواجهة أمامية (مثلاً: الواجهة الأمامية على app.servbay.demo و API الخلفي على api.servbay.demo) أو تحتاج الواجهة الأمامية للاتصال بخدمات أو واجهات خارجية، تمنع المتصفحات مثل هذه الطلبات المتقاطعة بسبب سياسة نفس الأصل. من خلال ضبط CORS، تسمح للخادم بمنح الإذن للمصادر الأمامية بالوصول إلى موارده، وبالتالي تتجنب فشل الطلبات المرتبط بهذه السياسة.

شرح رؤوس الاستجابة HTTP المهمة في CORS

عند استجابة الخادم لطلب عبر مصادر، سوف يتضمن بعض رؤوس الاستجابة الخاصة التي تُمكن المتصفح من تحديد ما إذا كان الطلب يجب السماح به. فيما يلي نعرض أهم خيارات CORS القابلة للتهيئة في ServBay:

1. Access-Control-Allow-Origin

   • الهدف: أهم رأس في CORS، يحدد أي المصادر (النطاقات) مسموح لها بالوصول.
   • القيم الممكنة:
     • *: يسمح لأي نطاق بالوصول. ملاحظة مهمة: استعمال * سهل لكنه يحمل مخاطر أمنية—لا يُنصح به في بيئة الإنتاج.
     • https://servbay.demo: يسمح فقط لهذا النطاق بالوصول.
     • https://servbay.demo https://api.servbay.demo: يسمح بعدة مصادر محددة (مقسومة بفراغ).
   • ملاحظة: إذا كان الطلب عبر المصادر يتضمّن ملفات كويكي أو بيانات اعتماد (أي تم ضبط Access-Control-Allow-Credentials: true)، فلا يجوز أبدًا استخدام * بل يجب تحديد النطاق صراحة.

2. Access-Control-Allow-Methods

   • الهدف: يحدد طرق HTTP المسموحة للطلبات عبر المصادر (مثل GET, POST, PUT, DELETE, OPTIONS) .
   • القيم الممكنة: مثلا: GET, POST, PUT, DELETE, OPTIONS—مقسومة بفاصلة.
   • ملاحظة: بعض الطلبات (مثل استخدام PUT أو رؤوس خاصة) تُعتبر "طلبات ليست سهلة" وتستلزم إرسال طلب تهيئة (OPTIONS)。الخادم يجب أن يستجيب لهذا الطلب ويضمن هذا الرأس كي يسمح للمتصفح بتنفيذ الطلب الفعلي. الاستخدام المتكرر لـ OPTIONS ضروري في مثل هذه الحالات.

3. Access-Control-Allow-Headers

   • الهدف: يحدد رؤوس HTTP المخصصة المسموح تمريرها عبر طلبات CORS.
   • القيم الممكنة: مثل: Content-Type, Authorization, X-Requested-With (مقسومة بفاصلة).
   • ملاحظة: إذا استخدم جانب العميل رؤوسًا مخصصة غير مدعومة افتراضيًا، سيحتاج المتصفح تنفيذ طلب تهيئة (OPTIONS) ويجب على الخادم ذكر تلك الرؤوس صراحة في هذا الرأس.

4. Access-Control-Allow-Credentials

   • الهدف: يبيّن ما إذا كان الطلب عبر المصادر مسموح له بنقل بيانات اعتماد المستخدم (كالكويكي أو شهادات SSL أو مصادقة HTTP).
   • القيم الممكنة: true أو false.
   • ملاحظة: عند التمكين (true) لا يمكن لقيمة Access-Control-Allow-Origin أن تكون *. ويجب كذلك أن يضبط العميل في كود JavaScript الخاص به الخيار الخاص بنقل بيانات الاعتماد (مثلاً: xhr.withCredentials = true أو fetch(url, { credentials: 'include' })).

كيفية تفعيل وضبط CORS في ServBay

يقدّم ServBay واجهة رسومية سهلة لضبط إعدادات CORS لكل موقع على حدة. إليك الخطوات الدقيقة:

1. فتح ServBay والذهاب لقائمة المواقع: قم بتشغيل تطبيق ServBay. وفي الشريط الجانبي، اختر "المواقع". سترى قائمة بجميع المواقع المحلية المضبوطة ضمن ServBay.

2. اختيار الموقع المطلوب لتفعيل CORS: ابحث في القائمة عن الموقع المحدد الذي ترغب في تعديل إعدادات CORS له. اضغط على اسم الموقع لدخول صفحة الإعدادات التفصيلية.

3. العثور على إعدادات CORS وتفعيلها: في واجهة إعدادات الموقع، مرّر لأسفل للعثور على قسم "CORS". في وضعه الافتراضي، يكون CORS معطلاً. حرّك زر التبديل بجانب القسم من "إيقاف" إلى "تشغيل". ستُصبح خيارات الإعداد قابلة للتعديل الآن.

4. ضبط Access-Control-Allow-Origin: في حقل الإدخال "Access-Control-Allow-Origin"، أدخل مصدرًا واحدًا أو أكثر مسموح لهم بالوصول لهذا الموقع. إذا كان هناك عدة مصادر، افصلهم بمسافة، مثال: https://frontend.servbay.demo https://anotherapp.servbay.demo. تجنب استخدام * في بيئة الإنتاج.

5. ضبط Access-Control-Allow-Methods: في حقل الإدخال "Access-Control-Allow-Methods"، أدخل طرق HTTP التي ترغب بالسماح بها، مفصولة بفاصل. مثال: GET, POST, PUT, DELETE, OPTIONS. تأكد من تضمين الطرق التي يحتاجها التطبيق، وغالباً ما يتم تضمين OPTIONS لدعم طلبات التهيئة.

6. ضبط Access-Control-Allow-Headers: في حقل الإدخال "Access-Control-Allow-Headers"، أدخل رؤوس HTTP المخصصة التي تحتاج الطلبات لحملها عبر المصادر. أكثر من رأس يتم الفصل بينهم بفاصلة، مثل: Content-Type, Authorization, X-Custom-Header. أضف فقط الرؤوس الضرورية لتطبيقك.

7. ضبط Access-Control-Allow-Credentials (اختياري): إذا رغبت بالسماح بنقل الكوكيز أو معلومات الاعتماد عبر مصدر آخر، فعّل زر التبديل بجانب "Allow-Credentials" إلى وضع التشغيل. تأكيد مهم: عند تفعيل هذا الخيار، يجب أن لا تكون قيمة Access-Control-Allow-Origin هي * كما ذُكر في الخطوة 4.

8. حفظ إعداداتك: بعد إكمال إعداد CORS حسب حاجتك، لا تنس الضغط على زر "حفظ" في الزاوية اليمنى السفلى. سيقوم ServBay تلقائياً بتحديث إعدادات الخادم (Caddy أو Nginx) ولن تحتاج لإعادة التشغيل يدويًا.

مثال على الإعداد

الصورة التالية تعرض مثالاً لإعداد CORS على موقع باسم "ServBay Demo Website" ضمن واجهة ServBay:

بحسب الإعداد الظاهر أعلاه:

• Access-Control-Allow-Origin: https://frontend.servbay.demo https://api.servbay.demo
• Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
• Access-Control-Allow-Headers: Content-Type, Authorization
• Allow-Credentials: مُفعل (true)

هذا يعني أن الطلبات المرسلة فقط من https://frontend.servbay.demo وhttps://api.servbay.demo يسمح لها بالوصول لموارد "ServBay Demo Website". ويسمح بهذه الطلبات باستخدام الطرق المذكورة، ونقل رؤوس Content-Type وAuthorization، وبيانات الاعتماد كملفات الكوكيز.

ملاحظات ونصائح هامة

• أولوية الأمان: في بيئة التطوير والاختبار قد تبدو قيمة Access-Control-Allow-Origin: * عملية ومريحة، لكن في بيئة الإنتاج ينبغي دومًا حصرها على مصادر محددة فقط لتعزيز الأمان.
• طلبات التهيئة (Preflight): فهم عمل طلبات OPTIONS أساسي في تشخيص مشاكل CORS. تأكد أن خادمك (من خلال إعدادات ServBay) يستجيب بشكل صحيح مع الرؤوس المطلوبة.
• ذاكرة التخزين المؤقت للمتصفح: قد يحتفظ المتصفح بسياسة CORS في الذاكرة. إذا واجهت مشاكل بعد تعديل الإعداد، امسح ذاكرة التخزين أو اختبر العملية في وضع التصفح الخفي.
• CORS على مستوى التطبيق: بعض أطر العمل (مثل Laravel أو Express.js أو Spring Boot) تتيح أيضاً ضبط CORS في التطبيق نفسه. إعدادات CORS ضمن ServBay تطبق على مستوى خادم الويب (Caddy/Nginx)، وتعتبر غالبًا أولوية. في الحالات المعقدة، تأكد من تناسق إعدادات CORS على مستوى الخادم والتطبيق.
• أدوات التشخيص: استخدم أدوات المطور في المتصفح (عادة بالضغط على F12) ثم التبويب "الشبكة" لفحص رؤوس الطلب والاستجابة—سيساعدك ذلك بتحديد ما إذا كانت إعدادات CORS تعمل بشكل صحيح أو تحديد سبب فشل الطلب.

الأسئلة الشائعة (FAQ)

س: طبقت تعليمات الإعداد، لكن ما زالت الطلبات عبر المصادر تفشل؟

ج: يمكنك اتباع هذه الخطوات لفحص المشكلة:

1. راجع وحدة التحكم وتبويب الشبكة في المتصفح: سترى عادة رسائل خطأ تتعلق بـ CORS في وحدة التحكم، وكما يمكنك تفحص جميع الرؤوس في تبويب الشبكة. تحقق من وجود رؤوس Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Headers صحيحين في الاستجابة، وتأكّد أن قيمهم توافق ما تصدره جهة الطلب.
2. تحقق من التوافق التام للمصدر: يجب أن تتطابق القيم (بروتوكول، اسم النطاق، المنفذ) في Access-Control-Allow-Origin مع مصدر تطبيقك الأمامي.
3. راعي الطرق والرؤوس: تأكد أن Access-Control-Allow-Methods تضم جميع طرق HTTP التي تحتاجها، وأن Access-Control-Allow-Headers تضمن جميع الرؤوس المخصصة المطلوبة.
4. مشكلات بيانات الاعتماد: إذا كان مطلوبًا تمرير الكوكيز أو بيانات الاعتماد، افعل خيار Allow-Credentials في ServBay ولا تستخدم * كقيمة لـ Access-Control-Allow-Origin، واحرص على وجود الإعداد المطلوب لتمرير بيانات الاعتماد في كود العميل.
5. طلبات التهيئة: للطلبات غير البسيطة، راقب هل المتصفح يرسل طلب OPTIONS وهل الخادم يجيب عليها مع رؤوس CORS الصحيحة.
6. حفظ في ServBay: بعد كل تعديل تأكد من الضغط على زر "حفظ".

س: هل يمكنني تطبيق سياسة CORS عامة لكافة المواقع؟

ج: إعدادات CORS في ServBay منفردة لكل موقع لتعزيز المرونة والأمان؛ لا يوجد حالياً إعداد عالمي عبر واجهة المستخدم. عليك ضبط CORS لكل موقع على حدة في حال رغبت بتوحيد السياسة.

س: كيف يضبط ServBay إعدادات CORS من الناحية التقنية؟

ج: يستخدم ServBay في الخلفية خادم Caddy أو Nginx. كل إعداد تقوم به من واجهة ServBay يتم تحويله تلقائيًا إلى تعليمات في ملفات إعدادات الخادم (Caddyfile أو Nginx)، ثم يتم تحديث الخادم بدون الحاجة لتعديل الملفات يدويًا.

الخلاصة

يتيح لك ServBay عبر واجهته الرسومية تفعيل وضبط CORS بسهولة لكل موقع في بيئة تطويرك المحلي، لتتجاوز مشاكل الوصول عبر المصادر بثقة. الفهم الصحيح لرؤوس Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Headers, وAccess-Control-Allow-Credentials وضبطها بدقة هو مفتاح نجاح طلباتك عبر المصادر بشكل آمن وسلس. الالتزام بالإرشادات وأفضل الممارسات في هذا المقال سيساعدك على تطوير مواقع الويب المحلية بكفاءة وحرفية.