الأسئلة الشائعة حول التعاون بين ServBay وDocker (FAQ)

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

س1: لماذا يقوم ServBay بتعديل ملف hosts الخاص بالنظام؟ وهل يمكنني منعه من ذلك؟

يقوم ServBay بإضافة مدخلات في ملف hosts بالنظام (مثل: mysite.servbay.demo 127.0.0.1) لتتمكن من الوصول لموقعك المحلي عبر اسم نطاق مخصص (مثل mysite.servbay.demo). هذا الموقع يعمل فعليًا على عنوان 127.0.0.1 في جهازك.

لكن نظرًا لآلية Docker، يتم نسخ ملف hosts من الجهاز المضيف (macOS أو Windows)، ما يجعل mysite.servbay.demo يُترجم إلى 127.0.0.1 داخل الحاوية، وبالتالي يحاول Docker الوصول إلى خدمته الخاصة بدلاً من خدمة ServBay.

شرح الآلية الأساسية:

• عند إنشاء موقع جديد في ServBay وتعيين نطاق (مثل example.servbay.demo)، يقوم ServBay تلقائيًا بتوجيه هذا النطاق إلى 127.0.0.1.
• هذا الإجراء هو الطريقة القياسية لتسهيل الوصول المحلي بأسماء نطاقات ودية. إذا لم يتم تعديل ملف hosts، فستحتاج للوصول عبر http://127.0.0.1:PORT ولا يمكن استخدام اسم النطاق المخصص.

هل يمكن منعه؟

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

في معظم سيناريوهات التطوير المحلي، الإدارة التلقائية لـ hosts عبر ServBay هي السلوك الأمثل الذي يوفر الكثير من الوقت والجهد للمطورين.

س2: كيف يمكن لحاوية Docker الوصول بشكل صحيح إلى مواقع ServBay على الجهاز المضيف باسم النطاق (مثل mysite.servbay.demo)؟

هذه المشكلة شائعة وتحتاج لحل مدروس. عندما يشغل ServBay موقعًا باسم نطاق (مثل mysite.servbay.demo على الجهاز المضيف ويشير إلى 127.0.0.1)، فإن أي استخدام لهذا العنوان داخل الحاوية يوجه الطلب إلى الحاوية نفسها وليس للجهاز المضيف.

الحل الخاطئ: استخدام host.docker.internal كاسم المضيف في عنوان URL عند محاولة الوصول:

على الرغم من أن Docker Desktop يوفر اسم DNS خاص host.docker.internal للوصول إلى الجهاز المضيف من الداخل، إلا أنه لا ينصح أبدًا باستخدامه مباشرة كاسم مضيف في عنوان الموقع (أي الوصول إلى http://host.docker.internal/ متوقعًا منه التوجيه إلى mysite.servbay.demo).

المشكلة تكمن في أن رأس HTTP Host سيكون host.docker.internal وليس اسم موقعك الحقيقي، ما يمنع خادم الويب في ServBay من توجيه الطلب بشكل صحيح أو يؤدي إلى أخطاء SNI عند استخدام HTTPS، حيث الشهادة صادرة لـmysite.servbay.demo وليس لـhost.docker.internal.

الحل الصحيح: إضافة تعيين نطاقات عبر extra_hosts عند إنشاء الحاوية

ولتجنب هذه المشاكل، يجب أن تضيف اسم النطاق الخاص بموقعك (مثل mysite.servbay.demo) إلى ملف hosts داخل الحاوية وتوجهه إلى عنوان الجهاز المضيف باستخدام extra_hosts في ملف docker-compose.yml أو باستخدام الخيار --add-host مع docker run، ويفضل استخدام القيمة host-gateway.

• أمر docker run:

  docker run --add-host=mysite.servbay.demo:host-gateway ... your_image

  (host-gateway هو قيمة خاصة تستبدل تلقائيًا بعنوان IP الداخلي للجهاز المضيف، وعادة يدعمها Docker بداية من الإصدار 20.10+.)

• ملف docker-compose.yml:

  version: '3.8' # أو أعلى
  services:
    myapp:
      image: your_image
      extra_hosts:
        - "mysite.servbay.demo:host-gateway" # أو "mysite.servbay.demo:host.docker.internal"
      # ... باقي الإعدادات

بعد الإعداد، سيحدث ما يلي داخل الحاوية:

1. عندما يحاول التطبيق الوصول إلى http://mysite.servbay.demo أو https://mysite.servbay.demo، سيُترجم اسم النطاق إلى عنوان الجهاز المضيف.
2. سيرسل الطلب فعليًا إلى خادم الويب في ServBay العامل على الجهاز المضيف.
3. رأس HTTP Host سيحمل اسم الموقع الحقيقي، ما يسمح لـServBay بتوجيه الطلب بشكل صحيح وتقديم شهادة SSL المناسبة إذا كنت تستخدم HTTPS.

س3: كيف تربط حاوية Docker بقواعد البيانات التي يديرها ServBay (مثل MySQL أو PostgreSQL) أو أي خدمات أخرى غير HTTP؟

في هذه الحالة، استخدام host.docker.internal كاسم مضيف للخادم هو الخطوة الصحيحة والموصى بها حيث لا تعتمد الخدمات هنا على أسماء النطاقات أو آلية SNI مثل المواقع.

الخطوات:

1. تأكد من تشغيل حزمة قاعدة البيانات في ServBay وأنها تسمح باتصالات من الجهاز المضيف (عادةً تكون الإعدادات الافتراضية مناسبة للتطوير المحلي).

2. داخل الحاوية، عند ضبط إعدادات الاتصال بقاعدة البيانات:

   • اسم السيرفر (Hostname/Server): استخدم host.docker.internal.
   • المنفذ (Port): المنفذ المناسب كما هو محدد في ServBay (مثلا: MySQL على 3306، PostgreSQL على 5432).
   • اسم المستخدم/كلمة مرور: كما أعددتها في ServBay.

   مثال للاتصال بـMySQL المدارة عبر ServBay:

   • المضيف: host.docker.internal
   • المنفذ: 3306
   • اسم المستخدم: your_db_user
   • كلمة المرور: your_db_password

س4: كيف يمكن جعل الحاوية تثق بشهادة CA التي يصدرها ServBay (عند زيارة موقع HTTPS عبر النطاق في الحاوية)؟

في حالة تتبعك نصيحة الإجابة السابقة وأضفت تعيين النطاق باستخدام extra_hosts أو --add-host، وكنت تستخدم شهادة SSL صادرة من ServBay User CA، فإن الحاوية لن تعتبر هذه CA موثوقة بشكل افتراضي ويحدث فشل في الاتصال عبر SSL.

موقع ملف CA الخاص بـServBay:

• شهادة الجذر (Root CA) الخاصة بServBay User:
  • macOS: /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt
  • Windows: C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt
• ملف PEM يحتوي على جميع شهادات CA:
  • macOS (ARM): /Applications/ServBay/package/common/openssl/3.2/cacert.pem
  • macOS (Intel): /Applications/ServBay/package/common/openssl/1.1.1u/cacert.pem
  • Windows: C:\ServBay\package\common\openssl\3.3\cacert.pem

طرق الحل:

هناك ثلاث طرق لجعل الحاوية تثق بشهادة CA التي يصدرها ServBay:

1. الطريقة 1: دمج الثقة بالنظام أثناء البناء (داخل Dockerfile) - مثالية إذا كنت تبني صورة Docker مخصصة.
2. الطريقة 2: الثقة على مستوى التطبيق أثناء التشغيل (حجم مثبت وخصائص بيئة) - مناسبة إذا كنت تريد تطبيقًا بعينه يثق بـCA.
3. الطريقة 3: دمج الثقة بالنظام أثناء التشغيل عبر أمر مخصص وmount - مناسبة إذا كنت ترغب بنظام الحاوية كاملاً أن يثق بـCA دون بناء صورة جديدة.

الطريقة 1: الدمج أثناء البناء (Dockerfile)

تقوم هذه الطريقة أثناء بناء صورة Docker بدمج شهادة CA في نظام الثقة داخل الحاوية.

• جهز ملف شهادة CA: انسخ ملف الجذر إلى مجلد البناء الخاص بك (بجانب Dockerfile).
  • macOS: /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt
  • Windows: C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt
• مثال Dockerfile (توزيعة Debian/Ubuntu):

  # Dockerfile
  FROM ubuntu:latest
  COPY ServBay-Private-CA-ECC-Root.crt /usr/local/share/ca-certificates/ServBay-User-CA.crt
  RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates && \
      update-ca-certificates && \
      rm -rf /var/lib/apt/lists/*

• مثال Dockerfile (Alpine):

  # Dockerfile
  FROM alpine:latest
  COPY ServBay-Private-CA-ECC-Root.crt /usr/local/share/ca-certificates/ServBay-User-CA.crt
  RUN apk add --no-cache ca-certificates && update-ca-certificates

• تبني عبر Docker Compose:

  # docker-compose.yml
  version: '3.8'
  services:
    myapp:
      build:
        context: ./app_service # مجلد يحتوي Dockerfile وServBay-Private-CA-ECC-Root.crt
        dockerfile: Dockerfile
      extra_hosts: ["secure.servbay.demo:host-gateway"]

الطريقة 2: الثقة التطبيقية أثناء التشغيل (mount وبيئة)

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

• مثال docker-compose.yml:

  version: '3.8'
  services:
    myapp:
      image: some-base-image
      volumes:
        # لمستخدمي macOS
        - /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt:/etc/ssl/certs/MyCustomCA.crt:ro
        # Windows (عدل المسار حسب نظامك)
        # - C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt:/etc/ssl/certs/MyCustomCA.crt:ro
      environment:
        # أمثلة لبيئة Node.js:
        - NODE_EXTRA_CA_CERTS=/etc/ssl/certs/MyCustomCA.crt
        # أمثلة لبيئة Python (requests):
        # - REQUESTS_CA_BUNDLE=/etc/ssl/certs/MyCustomCA.crt
        # أمثلة عامة:
        # - SSL_CERT_FILE=/etc/ssl/certs/MyCustomCA.crt
      extra_hosts: ["secure.servbay.demo:host-gateway"]

  راجع توثيق تطبيقك لمعرفة متغيرات البيئة المناسبة.

الطريقة 3: دمج أثناء التشغيل النظامي (mount وأمر مخصص)

تعتمد هذه الطريقة على تركيب شهادة الـ CA عند تشغيل الحاوية، وتنفيذ أمر لتحديث ثقة النظام قبل إطلاق التطبيق.

• مثال docker-compose.yml (مبني على Debian/Ubuntu):

  version: '3.8'
  services:
    myapp:
      image: ubuntu:latest
      volumes:
        # macOS
        - /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt:/usr/local/share/ca-certificates/ServBay-User-CA.crt:ro
        # Windows
        # - C:\ServBay\ssl\private\ServBay-Private-CA-ECC-Root.crt:/usr/local/share/ca-certificates/ServBay-User-CA.crt:ro
      command: >
        sh -c "
          echo 'Attempting to update CA certificates...' &&
          if command -v update-ca-certificates > /dev/null; then
            if [ ! -f /usr/bin/update-ca-certificates ]; then apt-get update && apt-get install -y --no-install-recommends ca-certificates; fi &&
            update-ca-certificates &&
            echo 'CA certificates updated.'
          else
            echo 'update-ca-certificates command not found, skipping CA update.'
          fi &&
          echo 'Starting application...' &&
          exec your_original_application_command_here
        "
      extra_hosts: ["secure.servbay.demo:host-gateway"]
      # قد تحتاج لتعديل صلاحيات المستخدم إذا كان التطبيق يعمل بغير مستخدم root

  ملاحظات:
  • التعقيد: تعديل أمر بدء الحاوية قد يكون صعبًا مع الصور الرسمية المعقدة، لذا تحقق من تدفق بدء التطبيق لديك.
  • الصلاحيات: يحتاج الأمر لتشغيل update-ca-certificates غالبًا لصلاحيات root.
  • التبعيات: يجب أن تتوفر الحزم المطلوبة داخل الحاوية، والكود أعلاه يحاول تثبيتها عند الحاجة.
  • وقت البدء: تزداد مدة تشغيل الحاوية بسبب تنفيذ الأمر في كل مرة.
  • Alpine Linux: استخدم الأمر apk add --no-cache ca-certificates && update-ca-certificates بدلًا من أوامر apt.

كيف تختار الطريقة الأنسب؟

• إذا كنت تبني صورة Docker مخصصة وتريد ثقة شاملة لكل الأدوات، استخدم الطريقة 1.
• إذا أردت فقط تطبيق واحد يثق بـ CA دون تعديل الصورة، استخدم الطريقة 2.
• إذا أردت أقل تعديل ولا ترغب ببناء صورة جديدة مع ثقة نظامية، استخدم الطريقة 3.

بالنسبة للشهادات العامة الصادرة من جهات مثل Let's Encrypt: إذا كان موقعك على ServBay يستخدم شهادة مصدرها جهة عامة عبر بروتوكول ACME، فإن معظم الصور الأساسية في Docker تعترف بها تلقائيًا ولا تحتاج لخطوات إضافية.

س5: كيف يمكن إعداد نطاقات وproxies عكسية عبر ServBay لتطبيقات داخل حاويات Docker؟

قد تشغّل داخل الحاوية تطبيقًا مثل Node.js ويستمع على منفذ معين (مثلا: 3000)، وتريد الوصول إليه من متصفح الجهاز عبر نطاق ودّي مثل myapp.servbay.demo وأيضًا الاستفادة من إدارة شهادات SSL بواسطة ServBay.

خطوات التنفيذ:

1. تشغيل الحاوية مع ربط المنفذ على الجهاز المضيف إلى 127.0.0.1 فقط: يجب تعيين منفذ تطبيقك في الحاوية ليكون متاحًا للجهاز المضيف فقط، أي عبر 127.0.0.1 كي لا يتاح عبر الشبكة الخارجية:

   # مثال: التطبيق بالحاوية يستمع على 3000 ويرتبط بالمنفذ 3001 على المضيف
   docker run -d -p 127.0.0.1:3001:3000 your-docker-app-image

   بهذا يمكن الوصول للتطبيق عبر http://127.0.0.1:3001 على المضيف.

2. إضافة موقع عبر ServBay وضبط إعدادات البروكسي العكسي:

   • افتح واجهة إدارة ServBay.
   • اختر "إضافة موقع جديد".
   • اسم النطاق: أدخل نطاقك المطلوب مثل: myapp.servbay.demo.
   • نوع الموقع: اختر "بروكسي عكسي" من الخيارات.
   • عنوان IP: أدخل 127.0.0.1.
   • المنفذ: أدخل رقم المنفذ المعين في الخطوة السابقة (مثلا: 3001).
   • اضغط "حفظ" أو "إضافة".

3. (اختياري) تفعيل SSL: بعد إضافة الموقع، يمكنك ضبط إعدادات SSL، حيث يدعم ServBay الحصول تلقائيًا على شهادات عامة عبر بروتوكول ACME مثل شهادات Let's Encrypt، أو استخدام شهادة ServBay User CA أو ServBay Public CA. ServBay يتولى عملية إنهاء SSL، ويظل الاتصال بينه وبين الحاوية HTTP عادي.

4. اختبار الوصول: بعد الحفظ، جرب زيارة http://myapp.servbay.demo أو https://myapp.servbay.demo (إن فعلت SSL). ServBay سيعيد توجيه الطلب تلقائيًا إلى التطبيق داخل الحاوية عبر البروكسي العكسي.

مسار العمل: المستخدم ← المتصفح ← https://myapp.servbay.demo ← ServBay (SSL وproxy) ← http://127.0.0.1:3001 ← التطبيق بالحاوية.

ملخص

يقدم ServBay تجربة تطوير ويب محلية سلسة للغاية على macOS وWindows. ومع دمجه مع Docker:

• للوصول إلى المواقع المدارة عبر ServBay من داخل الحاوية، استخدم تعيينات اسم النطاق (extra_hosts أو --add-host) بحيث يشير اسم النطاق إلى host-gateway لضمان مرور رأس Host بشكل صحيح وتجنب مشاكل SNI.
• للوصول لقواعد البيانات والخدمات غير HTTP، استخدم host.docker.internal كاسم مضيف للخادم مباشرةً.
• لجعل الحاوية تثق في شهادة SSL التي يصدرها ServBay User CA، ركّب ملف الشهادة في صورة الحاوية أو ثبته في نظام الحاوية عند التشغيل حسب الحاجة.
• لإنشاء نطاق وproxy عكسي عبر ServBay لتطبيقات Docker، اختر نوع الموقع "بروكسي عكسي" ووجهه للمنفذ المعين على 127.0.0.1.

احرص دائمًا على ضبط إعدادات ServBay (وخوادمه وقواعد بياناته) بالإضافة لتجهيز حاويات Docker بشكل صحيح ومناسب قبل بدء العمل.