كيفية إعداد Collabora CODE على Kubernetes باستخدام Helm

قد تبقى صفحة Collabora Online فارغة أو تُشير إلى أن خادم المكتب غير متاح حتى بعد تشغيل وحدة CODE. إن تشغيل وحدة CODE بشكل سليم ليس سوى جزء واحد من الإعداد: يجب أن يتمكن المتصفح وتطبيق WOPI الخاص بك من الوصول إلى Collabora عبر اسم المضيف العام، ويجب أن تتفق إعدادات TLS والوكيل، ويجب أن يثق Collabora بمضيف WOPI. يقوم مخطط Helm الرسمي لـ Collabora بنشر الخادم في Kubernetes؛ ولا يقوم بتثبيت أو تهيئة Nextcloud أو ownCloud أو أي مضيف WOPI آخر نيابةً عنك.

يستخدم هذا الدليل مخطط Helm الذي تُشرف عليه Collabora مع مثال NGINX Ingress. استبدل نطاقات المثال بنطاقاتك الخاصة. CODE هو إصدار التطوير من Collabora Online، وهو مُخصّص للتقييم والاستخدام المنزلي والفرق الصغيرة؛ وتُشير Collabora إلى أنه لا يُنصح باستخدامه في بيئات الإنتاج التي تتطلب إصدارًا مستقرًا مدعومًا. بالنسبة لأحمال العمل الإنتاجية، يُرجى تقييم عرض Collabora Online المدعوم وشروط الترخيص والدعم الخاصة به.

ما تحتاجه قبل التثبيت

• مجموعة Kubernetes عاملة، kubectlو Helm 3 مع إمكانية الوصول إلى المجموعة.
• تم تثبيت وحدة تحكم Ingress في المجموعة. يستخدم المثال أدناه ingress-nginx؛ كما يوثق مخطط Collabora أيضًا HAProxy ويدعم تكوينات توجيه أخرى.
• اسم DNS مثل office.example.comالذي يشير إلى عنوان الدخول العام، بالإضافة إلى شهادة TLS مخزنة كسر Kubernetes في مساحة اسم Collabora.
• يجب أن يكون تطبيق WOPI مثل Nextcloud، الذي يحمل عنوان URL مثل cloud.example.com. Collabora، قادراً على الوصول إلى تطبيق WOPI، كما يجب أن يكون التطبيق ومتصفحات المستخدمين قادرين على الوصول إلى Collabora.
• خطة TLS واضحة. ينهي هذا المثال بروتوكول HTTPS عند نقطة الدخول ويرسل HTTP إلى خدمة Collabora داخل المجموعة.

لضمان سرعة النشر المنزلي أو التجريبي، يُبقي استخدام وحدة CODE واحدة عملية التوجيه بسيطة. يمكن لنسخ متعددة تحسين السعة، لكن دليل Kubernetes الخاص بـ Collabora يُشير إلى ضرورة موازنة الأحمال باستخدام WOPISrc لضمان وصول جلسات التحرير لنفس المستند إلى نفس الوحدة. لا تُوسّع نطاق النسخ قبل التأكد من قدرة وحدة تحكم الدخول على توفير التقارب المطلوب.

الخطوة 1: أضف المخطط الرسمي وحدد الإصدار

تنشر Collabora مخططها البياني من مشروع CollaboraOnline. تعرض صفحة الإصدار حاليًا الإصدار 1.3.5 (تم التحقق منه في 6 أكتوبر 2026). تحقق من الإصدارات المتوفرة في بيئتك، وثبّت إصدار المخطط البياني حتى لا يؤدي تحديث المستودع لاحقًا إلى تغيير المخطط الذي تنشره دون علمك.

helm repo add collabora https://collaboraonline.github.io/online/
helm repo update
helm search repo collabora/collabora-online --versions

يُعد مستودع المخططات الرسمي مفيدًا للتحقق من الإعدادات الافتراضية الحالية قبل كتابة التعديلات:

helm show values collabora/collabora-online --version 1.3.5

إذا كان مستودعك يُدرج مخططًا متوافقًا أحدث عند اتباع هذا الدليل، فراجع ملاحظات الإصدار وقيمه قبل استبداله. يُعدّ كلٌّ من إصدار المخطط وإصدار صورة تطبيق CODE من مُدخلات الإصدار ذات الصلة، لكنهما ليسا الإعداد نفسه.

الخطوة الثانية: إنشاء مساحة اسم وحماية كلمة مرور المسؤول

أنشئ مساحة اسم وكلمة مرور سرية في Kubernetes لبيانات اعتماد مسؤول Collabora الاختيارية للمخطط. استبدل كلمة المرور الافتراضية بكلمة مرور سرية قوية، أو أنشئ كلمة المرور السرية من خلال مدير كلمات المرور السرية في مؤسستك أو من خلال سير عمل كلمات المرور السرية في GitOps. لا تُضِف كلمة مرور حقيقية في ملف values.yaml.

kubectl create namespace collabora

kubectl -n collabora create secret generic collabora-admin \
  --from-literal=username=admin \
  --from-literal=password='REPLACE_WITH_A_LONG_RANDOM_PASSWORD'

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

الخطوة 3: تكوين اسم المضيف، ومضيف WOPI، ونقطة الدخول

أنشئ ملفًا باسم collabora-values.yaml. يفترض هذا المثال وجود ingress-nginx، وسر TLS باسم office-example-com-tls، وNextcloud على https://cloud.example.com. يجب أن تُسمّي مجموعة الأسماء المستعارة مضيف تطبيق WOPI الذي يُسمح لـ Collabora بالاتصال به؛ وهو ليس اسم مضيف Collabora العام.

replicaCount: 1

autoscaling:
  enabled: false

ingress:
  enabled: true
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "0"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "600"
  hosts:
    - host: office.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific
  tls:
    - secretName: office-example-com-tls
      hosts:
        - office.example.com

collabora:
  aliasgroups:
    - host: "https://cloud.example.com:443"
  extra_params: "--o:ssl.enable=false --o:ssl.termination=true"
  existingSecret:
    enabled: true
    secretName: collabora-admin

يستخدم المثال الموثق في المخطط aliasgroupsالسماح لمضيف WOPI ومعلمات SSL هذه عند إنهاء وكيل عكسي لبروتوكول TLS. في هذا الترتيب، office.example.comيستخدم المرور الخارجي بروتوكول HTTPS، بينما يقوم المدخل بتوجيه المرور إلى Collabora عبر بروتوكول HTTP داخل المجموعة. إذا كان مدخلك يستخدم تمرير TLS أو بروتوكولًا داخليًا مختلفًا، فلا تنسخ علامات SSL هذه بشكل أعمى؛ بل عدّلها لتتوافق مع مسار TLS الفعلي والقيم الحالية في المخطط.

تأكد من وجود سر TLS في collaboraمساحة الاسم. إذا كنت تستخدم وحدة تحكم دخول مختلفة، فاستبدل الفئة والتعليقات التوضيحية بما يعادلها من الوثائق الخاصة بتلك الوحدة. أبقِ حركة مرور WebSocket مُفعّلة، واسمح بالاتصالات طويلة الأمد؛ تختلف الإعدادات الافتراضية لوحدات التحكم.

الخطوة الرابعة: عرض المخطط وتثبيته

قم أولاً بعرض ملفات البيان لاكتشاف أخطاء YAML ومراجعة إعدادات Ingress وService وworkload المُنشأة. ثم قم بتثبيت إصدار المخطط المُثبّت.

helm template collabora-online collabora/collabora-online \
  --namespace collabora \
  --version 1.3.5 \
  --values collabora-values.yaml

helm upgrade --install collabora-online collabora/collabora-online \
  --namespace collabora \
  --version 1.3.5 \
  --values collabora-values.yaml

تابعوا المصادر عند بدء تشغيلها:

kubectl get pods,services,ingress -n collabora
kubectl get events -n collabora --sort-by=.lastTimestamp

انتظر حتى يصبح البود جاهزًا قبل توصيل تطبيق WOPI. إذا بقي معلقًا، فتحقق مما إذا كانت المجموعة تحتوي على ما يكفي من وحدة المعالجة المركزية والذاكرة القابلة للجدولة، وما إذا كانت هناك أي محددات للعقد أو علامات أو حصص موارد تمنع التوزيع. يترك المخطط طلبات الموارد وحدودها للمشغل ليختارها؛ يوفر ملف README الخاص بـ Collabora قيم موارد أكبر كمثال لبيئات الإنتاج، ولكن الحجم الفعلي يعتمد على التحرير المتزامن وحجم العمل على المستندات.

الخطوة 5: قم بتوصيل Nextcloud أو مضيف WOPI آخر

افتح إعدادات Office أو Collabora لتطبيق WOPI الخاص بك، وأدخل عنوان URL للخدمة الخارجية https://office.example.com. في Nextcloud، يشرح دليل الإدارة كيفية تعيين عنوان URL لخادم Collabora Online في إعدادات إدارة Office. تحقق أيضًا من قائمة السماح لطلبات WOPI في Nextcloud إذا كان إعدادك يقيد الأجهزة المضيفة المسموح لها بالاتصال. يجب أن يكون العنوان متاحًا لكل من متصفحات المستخدمين النهائيين وخادم التطبيق الذي يُرسل طلبات WOPI.

إذا فشل الاتصال وظهرت رسالة "مضيف WOPI غير مصرح به" أو رسالة مشابهة، قارن عنوان URL الفعلي لمضيف WOPI مع عنوان URL المذكور collabora.aliasgroups. تحقق من البروتوكول واسم المضيف والمنفذ، وأضف أي أسماء مضيف بديلة مشروعة عن قصد. تجنب استخدام أنماط المضيف العامة إلا إذا كنت تفهم تأثيرها. إذا كنت تستخدم أكثر من تطبيق WOPI واحد، فاتبع بنية مجموعة الأسماء المستعارة الموثقة في المخطط لكل مضيف بدلاً من السماح بكل نطاق.

متى يجب عليك التوسع إلى أكثر من وحدة واحدة؟

في تجربة صغيرة، يُنصح باستخدام نسخة واحدة مع تعطيل خاصية التوسع التلقائي لتجنب تعقيد التوجيه. أما في حالة استخدام نسخ متعددة، فيوضح ملف README الخاص بمخطط Collabora تقارب NGINX بناءً على WOPISrcوسيطة الاستعلام. أضف التعليق التوضيحي الموثق إلى بوابة الدخول عند استخدام ingress-nginx.

nginx.ingress.kubernetes.io/upstream-hash-by: "$arg_WOPISrc"

يُوجّه هذا الإجراء طلبات الوصول إلى نفس المستند إلى نفس وحدة الخادم الخلفية، وهو أمرٌ بالغ الأهمية للتحرير التعاوني وطلبات الحافظة. راجع وثائق إصدار وحدة التحكم بالوصول لديك؛ فالتعليقات التوضيحية التي يدعمها ingress-nginx لا تُعتبر صالحة تلقائيًا لـ HAProxy أو Traefik أو تطبيقات Gateway API. بعد تفعيل المزيد من النسخ المتماثلة أو التوسع التلقائي، اختبر التحرير المتزامن لنفس المستند وراقب سجلات Collabora وسجلات الوصول إلى وحدة التحكم بالوصول. يتطلب تحديد حجم الموارد وسلوك الجلسة والتوافر العالي التحقق من صحة البيانات بما يتناسب مع حجم العمل.

تحقق من عملية النشر من الخارج

1. تأكد من أن Kubernetes يُبلغ عن أن pod جاهز وأن الخدمة و Ingress موجودان: kubectl get pods,svc,ingress -n collabora.
2. تحقق من نقطة نهاية الاكتشاف العامة. يجب أن تُرجع ملف XML بدلاً من خطأ في المتصفح أو الخادم الوكيل.

   curl -fsS https://office.example.com/hosting/discovery | head -c 300

3. افتح تطبيق WOPI وقم بتحرير مستند تجريبي. تأكد من تحميل المحرر وحفظ التغييرات، وأن إعادة فتح المستند تُظهر المحتوى المحفوظ.
4. في حال استخدام نسخ متعددة، افتح المستند نفسه في جلستين وتأكد من إمكانية التعاون بينهما دون الحاجة إلى إعادة الاتصال بشكل متكرر. يساعد هذا في تحديد أي خلل في ترابط الجلسات.
5. راجع سجلات الأخطاء المتعلقة ببروتوكول TLS أو تفويض WOPI أو أخطاء المصدر:

   kubectl logs -n collabora deploy/collabora-online --tail=100

   إذا أنشأ المخطط عبء عمل باسم مختلف، فاستخدم kubectl get deployments -n collaboraالاسم الفعلي واستبدله.

يؤكد نجاح عملية اكتشاف البيانات أن نقطة النهاية العامة تُقدّم بيانات تعريف Collabora، لكنها لا تُثبت نجاح مصادقة WOPI أو حفظ المستندات. ويُعدّ اختبار المستندات الشامل هو الفحص النهائي.

نقاط الفشل الشائعة

• يُعيد Ingress رمز الخطأ 404 أو 502: تحقق من نظام أسماء النطاقات (DNS)، وفئة Ingress، وسر TLS، ونقاط نهاية الخدمة. تأكد من قدرة Ingress على الوصول إلى خدمة Collabora على منفذ خدمة المخطط.
• يعمل الاكتشاف، لكن المحرر يبقى فارغًا: افحص أخطاء وحدة تحكم المتصفح وسجلات الوكيل. تحقق من إعدادات إنهاء HTTPS، ومعالجة WebSocket، ومهلات الطلبات الطويلة.
• مضيف WOPI غير المصرح به: اسمح بأصل تطبيق WOPI في aliasgroups؛ لا تستبدل اسم مضيف خادم المكتب.
• إعادة تشغيل Pod أو إخراجه: فحص kubectl describe podسجلات الحاويات، ثم تحديد طلبات وحدود واقعية للموارد المتاحة للمجموعة.
• يصبح التحرير غير مستقر بعد إضافة النسخ المتماثلة: تحقق من التقارب المستند إلى WOPISrc وتأكد من أن وحدة التحكم تحتفظ بوسيط الاستعلام عند توجيه الطلبات.

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

المراجع الرسمية

• مخطط Helm الخاص بـ Kubernetes ودليل النشر الذي تديره Collabora
• قيم مخطط هيلم كولابورا
• إصدارات مخططات كولابورا
• إرشادات إصدار تطوير Collabora Online (CODE)
• دليل تكوين Nextcloud Office
• توثيق التعليقات التوضيحية لـ ingress-nginx
• مرجع أوامر تثبيت Helm