كيفية إعداد بروتوكول HTTPS وشهادة SSL لبرنامج ONLYOFFICE Docker

لوضع ONLYOFFICE Docs خلف بروتوكول HTTPS في Docker، استخدم شهادة مطابقة لاسم المضيف العام، واجعلها متاحة داخل الحاوية، وانشر منفذ HTTPS الخاص بالحاوية. HTTPS هو اتصال ويب مشفر؛ وتساعد شهادة TLS المتصفحات على التحقق من وصولها إلى الخادم المطلوب. يستخدم هذا الدليل شهادة ومفتاحًا خاصًا حصلت عليهما مسبقًا من جهة إصدار شهادات موثوقة. إذا كنت تستخدم خادم وكيل عكسي، فاتبع الخيار المنفصل أدناه لأن الخادم الوكيل قد يتعامل مع HTTPS بدلاً من ذلك.

ما هو إعداد HTTPS الأنسب لعملية النشر الخاصة بك؟

يمكن لـ ONLYOFFICE Docs تقديم خدمة HTTPS مباشرةً من حاوية Docker الخاصة بها، أو يمكن لخادم وكيل عكسي مثل NGINX أو Traefik قبول طلبات HTTPS وإعادة توجيهها إلى Docs. يُعدّ استخدام TLS المباشر خيارًا مناسبًا للخادم المستقل الذي تتوفر لديه المنافذ العامة 80 و443. غالبًا ما يكون استخدام خادم وكيل عكسي أسهل عندما تمتلك خدمة ويب أخرى هذه المنافذ بالفعل أو عندما تشترك عدة مواقع في خادم واحد. تجنّب تكوين كلا الطبقتين بشكل عشوائي: حدّد المكوّن الذي يُنهي اتصال TLS، ووثّق ما إذا كان اتصال الوكيل بالحاوية HTTP أم HTTPS.

يشرح هذا الدليل كيفية إعداد بروتوكول HTTPS المباشر باستخدام شهادة صادرة عن جهة مصدقة. كما يوثق ONLYOFFICE خيار Let's Encrypt التلقائي باستخدام LETS_ENCRYPT_DOMAIN` LETS_ENCRYPT_MAIL. يتطلب هذا الخيار أن يكون المنفذان 80 و443 متاحين وغير مشغولين بواسطة خادم وكيل. تُعد الشهادة الموقعة ذاتيًا مفيدة لشبكة اختبار خاصة، ولكن المتصفحات العامة وخدمات التخزين المتصلة لن تثق بها تلقائيًا.

ما الذي يجب عليك تحضيره أولاً؟

• مضيف لينكس مثبت عليه محرك Docker ومكون Docker Compose الإضافي.
• سجل DNS من النوع A لاسم المضيف، مثلاً docs.example.com، يشير إلى عنوان IPv4 العام للمضيف. أضف سجل AAAA فقط إذا كان IPv6 مُهيأً ومتاحاً.
• قواعد جدار الحماية الوارد وجدار الحماية السحابي التي تسمح بـ TCP 443. إذا طلبت أو جدد شهادات مع التحقق من صحة HTTP، فقد يكون TCP 80 مطلوبًا أيضًا.
• سلسلة شهادات لاسم المضيف المحدد ومفتاحه الخاص المطابق. عادةً ما توفر جهات إصدار الشهادات ملف سلسلة الشهادات الكاملة وملف المفتاح الخاص.
• دليل مضيف دائم لوحدة تخزين بيانات ONLYOFFICE ورمز JWT سري قوي. رمز JWT (رمز الويب JSON) هو سر مشترك يُستخدم لمصادقة الطلبات بين Docs والتطبيق المتكامل.

الخطوة 1: ضع الشهادة والمفتاح الخاص على المضيف

في هذا المثال، يحتفظ المضيف بالبيانات الدائمة في المسار المحدد /srv/onlyoffice/data. استبدل اسم المضيف والمسارات المذكورة في المثال ببياناتك الخاصة. خزّن سلسلة الشهادات الكاملة في المسار المحدد، tls.crtوالمفتاح الخاص المطابق في المسار المحدد، tls.keyفي certsمجلد فرعي.

sudo mkdir -p /srv/onlyoffice/data/certs
sudo install -m 0644 /path/to/fullchain.pem /srv/onlyoffice/data/certs/tls.crt
sudo install -m 0600 /path/to/privkey.pem /srv/onlyoffice/data/certs/tls.key
sudo chown root:root /srv/onlyoffice/data/certs/tls.key

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

تحقق من تواريخ الشهادة وأسماء المضيفين قبل بدء الخدمة:

openssl x509 -in /srv/onlyoffice/data/certs/tls.crt -noout -subject -issuer -dates -ext subjectAltName

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

openssl x509 -in /srv/onlyoffice/data/certs/tls.crt -pubkey -noout | openssl sha256
openssl pkey -in /srv/onlyoffice/data/certs/tls.key -pubout | openssl sha256

الخطوة الثانية: تهيئة خدمة Docker Compose

تُدرج وثائق Docker الخاصة بـ ONLYOFFICE الشهادات ضمن مجلد /var/www/onlyoffice/Data/certs. تُحدد قائمة متغيرات البيئة الحالية أسماء ملفات الشهادات الافتراضية كـ tls.crtو tls.key، بينما تستخدم تعليمات التثبيت النموذجية أيضًا onlyoffice.crtو onlyoffice.key. يُجنّب تحديد المسارات بشكل صريح الاعتماد على اصطلاح تسمية الملفات. يتم ربط دليل المضيف بدليل بيانات الحاوية المطابق، ويتم نشر المنفذ 443 كمنفذ المضيف 443.

أنشئ compose.yamlملفًا كهذا، واستبدل قيمة JWT النموذجية برمز سري مُولّد خصيصًا لتثبيتك. الصورة الموضحة أدناه هي مثال توضيحي؛ راجع قائمة الصور الرسمية واستخدم النسخة التي تنوي الاحتفاظ بها.

services:
  documentserver:
    image: onlyoffice/documentserver:9.4.0
    container_name: onlyoffice-documentserver
    restart: unless-stopped
    ports:
      - "443:443"
    volumes:
      - /srv/onlyoffice/data:/var/www/onlyoffice/Data
    environment:
      SSL_CERTIFICATE_PATH: /var/www/onlyoffice/Data/certs/tls.crt
      SSL_KEY_PATH: /var/www/onlyoffice/Data/certs/tls.key
      JWT_SECRET: replace_with_a_long_random_secret

أنشئ رمزًا سريًا قويًا openssl rand -hex 32وضعه في ملف البيئة أو في إعدادات Compose مع منح صلاحيات الملف المناسبة. إذا كان هناك تطبيق آخر مُدمج مع Docs، فقم بتكوين ذلك التطبيق باستخدام نفس الرمز السري JWT وعنوان HTTPS العام. إذا كان هذا تثبيتًا موجودًا، فاحتفظ بوحدات التخزين والشبكات ومتغيرات البيئة الأخرى وإعدادات التكامل عند تعديل ملف Compose الحالي؛ ولا تستبدل تعريف خدمة عاملة بهذا المثال البسيط.

ابدأ الخدمة أو أعد إنشائها من الدليل الذي يحتوي على ملف Compose:

docker compose up -d
docker compose ps
docker compose logs --tail=100 documentserver

الخطوة 3: اختبار HTTPS والشهادة

افتح https://docs.example.comالمتصفح، مع استبدال اسم المضيف الخاص بك. تأكد من أن المتصفح يُظهر اتصالاً آمناً ولا يُبلغ عن عدم تطابق الاسم، أو شهادة منتهية الصلاحية، أو جهة إصدار غير موثوقة. تأكد من تحميل صفحة الترحيب الخاصة بـ ONLYOFFICE Docs. عند ربط Docs بـ Nextcloud أو ownCloud أو أي منصة أخرى، اختبر فتح مستند وحفظه أيضاً؛ فقفل المتصفح وحده لا يُثبت عمل طلبات رد الاتصال الخاصة بالتكامل أو إعدادات JWT.

من خلال سطر الأوامر، اطلب من الخادم شهادة TLS الخاصة به واختبر استجابة HTTPS:

openssl s_client -connect docs.example.com:443 -servername docs.example.com </dev/null
curl -I https://docs.example.com/

يُرسل هذا -servernameالخيار اسم المضيف باستخدام مؤشر اسم الخادم (SNI)، مما يسمح للخادم باختيار الشهادة الصحيحة عند مشاركة عدة أسماء مضيفين لنفس العنوان. يجب أن تتطابق تواريخ الشهادة والجهة المُصدرة وSAN مع الشهادة التي قمت بتثبيتها. راجع docker compose logsما إذا كان المتصفح لا يستطيع الاتصال أو إذا كانت الحاوية تُعاد تشغيلها بشكل متكرر.

ماذا لو كان الخادم الوكيل العكسي يدعم بروتوكول HTTPS بالفعل؟

إذا كان NGINX أو Traefik أو Caddy أو بوابة الاستضافة يمتلكان بالفعل المنفذين العامين 80 و443، فقد يكون من الأفضل تثبيت الشهادة العامة على هذا الخادم الوكيل. في هذه الحالة، انشر حاوية Docs فقط على شبكة Docker خاصة أو اربط منفذ HTTP الخاص بها بشبكة الاسترجاع، ثم قم بتهيئة الخادم الوكيل لإعادة توجيه الطلبات المطلوبة وحركة مرور WebSocket. عيّن عنوان ONLYOFFICE الخاص بالتطبيق المُدمج إلى عنوان https://URL العام. اتبع تعليمات الخادم الوكيل وONLYOFFICE الحالية بشأن إعادة توجيه الرؤوس وTLS؛ لا تنشر منفذ الحاوية 443 على نفس منفذ المضيف الذي يستخدمه الخادم الوكيل بالفعل.

اختر هذا النمط عندما يقوم خادم وكيل واحد بتوجيه حركة المرور لعدة خدمات. استخدم إعداد الحاوية المباشر المذكور أعلاه عندما يكون لدى Docs نقطة نهاية HTTPS عامة والمنافذ المطلوبة متاحة. إذا اتصل الخادم الوكيل بالحاوية عبر HTTP، فلن تكون هذه القفزة الداخلية مشفرة؛ احتفظ بها على شبكة خاصة موثوقة أو قم بتكوين TLS للمصدر إذا كانت متطلبات الأمان لديك تتطلب ذلك.

المشاكل الشائعة وكيفية حلها

• يُشير المتصفح إلى أن الشهادة غير صالحة. تحقق من اسم مضيف SAN، وتاريخ انتهاء صلاحية الشهادة، وسلسلة الشهادات الكاملة، وأن نظام أسماء النطاقات (DNS) يُشير إلى المضيف المقصود. لا تُغطي الشهادة الخاصة بالنطاق الرئيسي النطاق الفرعي تلقائيًا.
• يُشير الحاوية إلى وجود شهادة أو مفتاح مفقود. تحقق من مسار المصدر على المضيف، ووجهة الربط، وأسماء الملفات بدقة، والقيمتين SSL_..._PATH. يتطلب بناء جملة Docker --mountوجود مسار المصدر؛ كما يجب أن تُشير عمليات الربط في Compose إلى الدليل الموجود المقصود.
• المنفذ 443 مُخصّص بالفعل. أوقف الخدمة المُتعارضة، أو استخدم خادم وكيل عكسي، أو اختر منفذًا عامًا مختلفًا للمضيف وتأكد من أن عنوان URL وجدار الحماية يعكسان ذلك. إذا كان هناك خادم وكيل، فمن المفترض أن يكون لديه المنفذ العام 443.
• يعمل بروتوكول HTTPS، لكن تحرير المستندات يفشل. تحقق من عنوان URL الخاص بالتكامل، ورمز JWT السري على كلا الخدمتين، وقواعد إعادة توجيه الوكيل، وما إذا كان بإمكان Docs الوصول إلى منصة التخزين. اختبر عملية فتح وحفظ فعلية.
• يتم تجديد الشهادة، لكن الموقع لا يزال يستخدم الشهادة القديمة. تأكد من أن التجديد قد حدّث الملف المُثبّت على المضيف، وأن برنامج ONLYOFFICE قد أعاد تحميله. إذا لزم الأمر، أعد تشغيل الخدمة بعد التجديد، على سبيل المثال باستخدام خطاف نشر Certbot الذي يتم تشغيله docker compose restart documentserverمن دليل مشروع Compose. اختبر التجديد باستخدام خيار التشغيل التجريبي في Certbot قبل الاعتماد على التشغيل الآلي.

حافظ على صلاحية الشهادة

لا يكتمل إعداد HTTPS إلا عند التخطيط للتجديد. سجّل الجهة التي تُصدر الشهادة وتُجددها، ومكان تخزين المفتاح الخاص، والعملية التي تنسخ الملفات المُجددة إلى الدليل المُثبّت، وكيفية إعادة تحميلها بواسطة الخدمة. شغّل اختبارًا تجريبيًا لعميل التجديد، وراقب تاريخ انتهاء صلاحية الشهادة، وتحقق من نقطة النهاية العامة بعد كل تجديد. إذا كنت تستخدم متغيرات Let's Encrypt المُدمجة في ONLYOFFICE بدلًا من شهادة مُدارة من قِبل المضيف، فاتبع تعليمات Docker الحالية لهذه الطريقة، وتحقق من سلوك التجديد الخاص بها للصورة والنشر اللذين تستخدمهما.

للمزيد من المعلومات، يُرجى مراجعة دليل تثبيت Docker وHTTPS الخاص بـ ONLYOFFICE ، ووثائق ربط Docker ، ووثائق Docker Compose ، ووسوم صور Docker الرسمية الخاصة بـ ONLYOFFICE ، والتعليمات الرسمية لـ Certbot . قد تتغير الوسوم المتاحة وتفاصيل الواجهة؛ لذا يُرجى مراجعتها عند إعداد عملية نشر جديدة.