الأسئلة الشائعة حول تكامل ServBay وDocker على macOS

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

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

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

ولكن بسبب آلية Docker، يتم جلب ملف hosts مباشرة من جهاز macOS، ما يؤدي إلى解析 نطاق mysite.servbay.demo إلى 127.0.0.1 داخل الحاوية، وهذا يوجه الطلب بالخطأ لخدمة تعمل داخل الحاوية بدلاً من استهداف خدمة ServBay على المضيف.

الآلية الأساسية:

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

هل يمكن منعه؟

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

لأغلب حالات تطوير الويب محليًا، يُفضل ترك ServBay يدير ملف hosts تلقائيًا حيث يُبسط هذا من مراحل التطوير.

س2: كيف يمكن لحاوية Docker الوصول بشكل صحيح إلى المواقع المُدارة عبر ServBay على مضيف macOS (مثل mysite.servbay.demo)؟

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

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

مع أن Docker Desktop لنظامي Mac وWindows يوفر الاسم host.docker.internal ليترجم داخل الحاوية إلى عنوان المضيف، إلا أنه لا يُنصح باستخدامه مباشرة في الـ URL عند الوصول إلى مواقع ServBay (مثلاً، لا تستخدم http://host.docker.internal/ وتتوقع أن تصل إلى mysite.servbay.demo).

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

الحل الصحيح: إضافة خاصية extra_hosts عند تشغيل الحاوية

لجعل التطبيق داخل الحاوية يستخدم النطاق الأصلي لموقعك (مثلاً، mysite.servbay.demo) ويرسل رأس Host الصحيح، عليك إضافة سطر للربط بين اسم النطاق وعنوان المضيف داخل /etc/hosts للحاوية، باستخدام إما extra_hosts مع Docker Compose أو --add-host مع أمر docker run، وربطه إما بـ host.docker.internal أو، المفضل، بـ host-gateway.

• عند استخدام docker run:

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

  (host-gateway هو قيمة خاصة تقوم Docker باستبدالها بعنوان IP الداخلي للمضيف. في إصدارات Docker بعد 20.10 يعتبر خيارًا أفضل حتى من host.docker.internal.)

• عند استخدام 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، سيتم حل النطاق إلى عنوان IP الخاص بالمضيف من خلال /etc/hosts.
2. ستُرسل الطلبات إلى خادم ServBay على المضيف.
3. سيبقى رأس HTTP Host صحيحًا بحيث يستطيع ServBay توجيه الطلب وتقديم الشهادة الصحيحة (في حال استخدام HTTPS).

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

على عكس خدمات الويب، عند الاتصال بقواعد بيانات أو خدمات TCP عامة لا تعتمد على SNI، يُوصى وباختصار باستخدام host.docker.internal كاسم مضيف للخادوم.

الخطوات:

1. تأكد أن خدمة قاعدة البيانات في ServBay تعمل ومهيئة لاستقبال الاتصالات من الجهاز (غالبًا الإعدادات الافتراضية مناسبة).
2. داخل الحاوية، قم بتكوين بيانات الاتصال كالتالي:
   • اسم المضيف: host.docker.internal
   • المنفذ: المنفذ المُستخدم داخل ServBay (مثلاً، MySQL عادةً 3306، PostgreSQL غالبًا 5432)
   • اسم المستخدم/كلمة المرور: كما هو مُعين في قواعد بيانات ServBay

مثال (للاتصال بـ MySQL المدار بواسطة ServBay): إذا كانت MySQL تعمل افتراضيًا على المنفذ 3306:

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

س4: عند وصول الحاوية عبر النطاق (مع ضبط extra_hosts) إلى موقع ServBay يعمل بـ HTTPS (بشهادة من ServBay User CA)، كيف أجعل الحاوية تثق بذاك المرجع (CA)؟

عندما يُستخدم النطاق مثل secure.servbay.demo مع شهادة SSL صادرة عن ServBay User CA، لن تثق بها الحاويات افتراضيًا، ما يؤدي لفشل الاتصال الآمن.

مسار ملف CA الخاص بـ ServBay (على المضيف macOS):

• شهادة الجذر لـ ServBay User CA: /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt
• ملف PEM يحتوي على جميع الشهادات:
  • أجهزة Mac بمعالج ARM: /Applications/ServBay/package/common/openssl/3.2/cacert.pem
  • أجهزة Intel: /Applications/ServBay/package/common/openssl/1.1.1u/cacert.pem

طرق الحل:

يمكن جعل الحاوية تثق في CA الخاص بـ ServBay عبر عدة طرق:

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

الطريقة 1: إضافة الشهادة أثناء بناء الصورة (Dockerfile)

هذه المقاربة تُدرج شهادة CA إلى نظام الثقة داخل صورة Docker.

• جهز ملف الشهادة: انسخ /Applications/ServBay/ssl/private/ServBay-Private-CA-ECC-Root.crt إلى نفس مسار Dockerfile.
• مثال 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 + متغير بيئة)

في هذه الطريقة يتم ربط الشهادة كملف بالحاوية ثم تحديد متغير بيئة مناسب ليستخدمها التطبيق.

• مثال docker-compose.yml:

  version: '3.8'
  services:
    myapp:
      image: some-base-image
      volumes:
        - /Applications/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:
        # - SSL_CERT_FILE=/etc/ssl/certs/MyCustomCA.crt
      extra_hosts: ["secure.servbay.demo:host-gateway"]

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

الطريقة 3: الثقة على مستوى النظام عند التشغيل (mount + تحديث مكتبة الشهادات تلقائيًا)

تمزج هذه الطريقة بين ربط ملف الشهادة وتنفيذ تحديث بالقائمة الموثوقة عند بدء الحاوية؛ بذلك لا تحتاج لبناء صورة مخصصة.

• مثال docker-compose.yml (لصور Debian/Ubuntu):

  version: '3.8'
  services:
    myapp:
      image: ubuntu:latest # أو صورة تدعم update-ca-certificates
      volumes:
        # ربط الشهادة مباشرة لدليل شهادات النظام
        - /Applications/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: أضف السطر أسفل هذا التعليق
      # user: root

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

أي طريقة تختار؟

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

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

س5: كيف أخصص نطاقًا لتطبيق يعمل داخل Docker وأُعدّ وكيلًا عكسيًا باستخدام ServBay؟

قد يكون لديك تطبيق (مثل 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 حلول تلقائية للحصول على شهادات Let's Encrypt أو شهاداته الداخلية. SSL سيتم إنهاؤه عند ServBay بينما الاتصال بالحاوية يبقى HTTP عاديًا (http://127.0.0.1:3001).

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

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

الخلاصة

يُسهّل ServBay تطوير مواقع الويب على نظام macOS بشكل كبير. وعند دمجه مع Docker:

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

تأكد دومًا أن حزم ServBay (سيرفر الويب، قاعدة البيانات... إلخ) وحاويات Docker مفعّلة ومهيأة بشكل صحيح.