حل مشكلة "تعذر حفظ المستند" في برنامج ONLYOFFICE في Nextcloud

عند فتح ملف DOCX في Nextcloud، يتم تحميل ONLYOFFICE بشكل طبيعي، ثم تُجري تعديلاً، فيُظهر المحرر رسالة "تعذر حفظ المستند". قد يتبادر إلى الذهن أن المتصفح فقد الملف أو أن ONLYOFFICE نفسه لا يستطيع الكتابة على القرص. ولكن في حالة التكامل مع Nextcloud، غالباً ما يكون هذا هو السبب الخاطئ للبدء.

يكمن التفصيل المهم في آلية الحفظ. يُزوّد ​​Nextcloud برنامج ONLYOFFICE Docs برابط URL للمستند callbackUrl، ثم يقوم ONLYOFFICE بتنزيل الملف، واستضافة جلسة التحرير، ثم يستدعي Nextcloud لاحقًا ليتمكن من جلب الملف المُحدّث واستبدال النسخة المحفوظة. توضح وثائق تكامل ONLYOFFICE الرسمية آلية تبادل الاستدعاءات هذه بشكلٍ صريح. هذا يعني أن المحرر قد يُفتح بنجاح حتى لو كان مسار الإرجاع المُستخدم للحفظ معطلاً. الإجراء: تعامل مع عمليتي الفتح والحفظ كاختبارين منفصلين للشبكة.

ابدأ بالسلوك الذي تم التحقق منه، وليس بنص الخطأ.

بحسب وثائق التكامل الرسمية الحالية، يستخدم موصل Nextcloud الخاص بـ ONLYOFFICE آلية عمل بين الخوادم: يجب أن يكون خادم المستندات قابلاً للوصول من Nextcloud، ويجب أن يكون Nextcloud قابلاً للوصول من خادم المستندات أيضاً. عند انتهاء التحرير، يرسل ONLYOFFICE طلب POST إلى عنوان URL الخاص بالاستجابة؛ ثم يقوم Nextcloud بتنزيل المستند المُعدَّل واستبدال النسخة السابقة. راجع دليل تكامل ONLYOFFICE الرسمي مع Nextcloud ووصف واجهة برمجة تطبيقات ONLYOFFICE الخاصة بتكامل Nextcloud .

تم التحقق: قد يؤدي مسار رد الاتصال غير الصحيح أو غير المتاح إلى فشل عملية الحفظ حتى عند فتح المحرر. تشير وثائق استكشاف الأخطاء وإصلاحها الخاصة بـ ONLYOFFICE تحديدًا إلى ضرورة مراجعة سجلات DocService والتأكد من إمكانية الوصول إلى عنوان URL الخاص برد الاتصال عند حدوث خطأ في الحفظ. الإجراء: لا تبدأ بإعادة تثبيت المحرر أو مسح ذاكرة التخزين المؤقت للمتصفح؛ اختبر أولًا مسار الاتصال بين الخوادم.

1. قم بتشغيل فحص الاتصال المدمج في الموصل

على خادم Nextcloud، شغّل فحص موصل ONLYOFFICE بصفتك مستخدم خادم الويب. في تثبيت نموذجي لنظامي Debian أو Ubuntu:

cd /var/www/nextcloud
sudo -E -u www-data php occ onlyoffice:documentserver --check

قد يختلف مسار Nextcloud ومستخدم HTTP باختلاف التوزيعة أو بنية الحاوية. يوصي دليل إدارة Nextcloud بتشغيله occكمستخدم HTTP لضمان ثبات ملكية الملفات. تُوثّق ONLYOFFICE occ onlyoffice:documentserver --checkاختبار اتصال الموصل.

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

2. تحقق من عناوين الخوادم العامة والداخلية

في Nextcloud، افتح الإعدادات ← الإدارة ← ONLYOFFICE . يجب أن يكون عنوان ONLYOFFICE Docs الرئيسي قابلاً للاستخدام من قِبل العملاء والخدمات المعنية. إذا لم تكن عناوين URL العامة قابلة للتوجيه داخليًا بسبب شبكة Docker أو NAT أو نظام أسماء النطاقات ذي الأفق المنفصل أو سياسة جدار الحماية، فقم بتوسيع إعدادات الخادم المتقدمة.

يكشف الموصل الرسمي عن عناوين داخلية منفصلة لهذه الحالة تحديداً:

• عنوان مستندات ONLYOFFICE للطلبات الداخلية من الخادم : العنوان الذي يستخدمه Nextcloud للوصول إلى ONLYOFFICE.
• عنوان الخادم للطلبات الداخلية من ONLYOFFICE Docs : العنوان الذي تستخدمه ONLYOFFICE للوصول إلى Nextcloud لإجراء عمليات الاستدعاء وحركة المرور ذات الصلة من خادم إلى خادم.

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

سوء فهم شائع: "يفتح المحرر، لذا فإن نظام أسماء النطاقات والتوجيه يعملان بشكل جيد"

هذا الاستنتاج غير موثوق. المتصفح، وNextcloud، وONLYOFFICE Docs هي ثلاثة جهات مختلفة مشاركة في الشبكة. قد يتمكن المتصفح من الوصول إلى عنوان IP office.example.comالخاص بخادم المستندات بينما لا يستطيع الخادم الوصول إليه أو الاتصال به cloud.example.com. وبالمثل، قد يتمكن Nextcloud من الوصول إلى ONLYOFFICE عبر اسم مضيف داخلي بينما يشير رد الاتصال إلى عنوان IP عام غير قابل للوصول.

الإجراء: ادخل إلى حاوية أو مضيف ONLYOFFICE واختبر عنوان Nextcloud المتوقع استخدامه. يمكن لطلب HTTPS أساسي إلى مضيف Nextcloud تأكيد إمكانية الوصول إلى DNS/TCP/TLS، ولكن تذكر أن نجاح status.phpالطلب لا يُثبت صحة عملية تفويض رد الاتصال أو معالجة طلب POST.

3. تحقق من رمز JWT قبل تغيير قواعد الوكيل

يُعدّ JWT مصدرًا آخرًا شائعًا للالتباس. بدءًا من ONLYOFFICE Docs 7.2، يتم تفعيل JWT افتراضيًا ويتم إنشاء مفتاح سري تلقائيًا. تتطلب التعليمات الرسمية استخدام نفس المفتاح السري على خادم المستندات وفي موصل Nextcloud ONLYOFFICE. كما توضح وثائق الموصل الحالية إعداد رأس التفويض للتثبيتات التي لا تستخدم الرأس الافتراضي.

تم التحقق: يجب أن يتطابق السر المشترك. يعتمد مكان إدارته على طريقة التثبيت: يعتمد مكان إدارته على ما إذا كان ONLYOFFICE مثبتًا من حزم، أو على نظام ويندوز، أو في Docker. في عمليات نشر Docker، JWT_SECRETيُستخدم عادةً متغير بيئي؛ ويمكن أيضًا فحص تكوين الخادم الفعلي في [المسار] /etc/onlyoffice/documentserver/local.json.

الإجراء: قارن إعدادات السرّ والرأس الفعّالة على كلا الجانبين، ثم أعد تشغيل خدمات ONLYOFFICE أو الحاوية بعد إجراء التغييرات على جانب الخادم. لا تُحاول "إصلاح" المشكلة بتعطيل JWT بشكل دائم؛ فهذا يُزيل إجراءً أمنيًا بدلًا من تصحيح الإعدادات. تجد التفاصيل في دليل إعداد JWT الخاص بـ ONLYOFFICE .

4. افحص سجلات ONLYOFFICE وNextcloud وقت فشل عملية الحفظ

توصي ONLYOFFICE بمراجعة سجلات DocService بحثًا عن أخطاء الحفظ. بالنسبة لأنظمة Linux وDocker، توجد سجلات خادم المستندات في المسار التالي /var/log/onlyoffice/documentserver: [المسار]. يمكن لمستخدمي Docker أيضًا متابعة مخرجات الحاوية باستخدام [ الأمر docker logs -f <container>]. في حال الحاجة إلى مزيد من التفاصيل، توفر ONLYOFFICE وضع تصحيح مؤقتًا من خلال [الأمر] DS_LOG_LEVEL=DEBUGأو إعدادات log4js. راجع دليل تسجيل التصحيح الرسمي .

في Nextcloud، يكون سجل النظام الافتراضي المستند إلى الملفات موجودًا عادةً nextcloud.logفي دليل البيانات المُهيأ. يمكنك معرفة المسار النشط باستخدام:

sudo -E -u www-data php occ log:file

يُوثّق Nextcloud أيضًا log:tailوقت log:watchتوفّر تطبيق قارئ السجلات. الإجراء: كرّر فشل عملية الحفظ، وسجّل الطابع الزمني، ثمّ قارن بين الحالتين. يشير رفض الشبكة، أو خطأ TLS، أو استجابة 401/403، أو استجابة 5xx، أو استثناء التخزين إلى حلول مختلفة تمامًا.

5. إصلاح مشاكل TLS والخادم الوكيل العكسي دون المساس بأمان بيئة الإنتاج

قد تتسبب الشهادة الموقعة ذاتيًا أو الصادرة بشكل خاص في تعطيل بروتوكول HTTPS بين الخوادم عندما لا تكون جهة إصدار الشهادات (CA) موثوقة. يحتوي الموصل على خيار "تعطيل التحقق من الشهادة (غير آمن)" ، لكن ONLYOFFICE تُشير صراحةً إلى أنه غير آمن وتوصي باستبدال الشهادة بشهادة صادرة عن جهة إصدار شهادات موثوقة. الإجراء: استخدم تجاوز التحقق من الشهادة كخطوة تشخيصية قصيرة فقط في بيئة مُراقبة؛ أما الحل الدائم فهو سلسلة شهادات صالحة وموثوقة من كلا الخادمين.

إذا كان هناك خادم وكيل عكسي أمام ONLYOFFICE، فتأكد من أنه يحافظ على المخطط والمضيف وسلوك الترقية المتوقع. تنشر ONLYOFFICE إرشادات مخصصة للخوادم الوكيلة العكسية، بما في ذلك رؤوس التوجيه والإعدادات المتعلقة بـ WebSocket. راجع دليل تكوين الخادم الوكيل العكسي لـ Nextcloud من ONLYOFFICE .

يعتمد ذلك على بيئة النشر: لا يمكن استنتاج التكوين الدقيق لـ Nginx أو Apache أو Traefik أو HAProxy أو وحدة تحكم الدخول أو شبكة توصيل المحتوى (CDN) من خطأ الحفظ وحده. الإجراء: قارن تكوين الوكيل الخاص بك مع مثال المورّد الخاص ببنيتك، وافحص حالة HTTP المسجلة أثناء رد الاتصال قبل تغيير مهلات أو رؤوس الطلبات بشكل عشوائي.

6. إذا وصل رد الاتصال إلى Nextcloud، فتحقق من التخزين وحالات فشل الكتابة

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

المعروف: تُفرّق قيم حالة رد الاتصال في ONLYOFFICE بين المستند الجاهز للحفظ والمستند الذي به خطأ في الحفظ، ويحتوي رد الاتصال على رابط URL للمستند المُعدّل ليتمكن خادم التخزين من استرجاعه. تُعرّف وثائق معالج رد الاتصال الرسمية الحالة 2 بأنها جاهزة للحفظ، والحالة 3 بأنها خطأ في الحفظ.

ما لا يُعرف من رسالة المتصفح وحدها: ما إذا كان العطل قد حدث في ONLYOFFICE، أو على مسار الشبكة، أو في Nextcloud، أو في وحدة التخزين الأساسية. الإجراء: لا تُغيّر ملكية الملفات بشكل متكرر في مجلد بيانات Nextcloud لمجرد أن المحرر يُشير إلى عدم إمكانية الحفظ. تأكد أولاً من وجود خطأ في وحدة التخزين في سجل Nextcloud.

7. فهم زر الحفظ وسلوك الحفظ الإجباري

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

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

جدول التشخيص السريع

كيفية التحقق من الإصلاح

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

ثم أعد تشغيل فحص الموصل:

sudo -E -u www-data php occ onlyoffice:documentserver --check

النتيجة الجيدة ليست مجرد "فتح المحرر". الاختبار الكامل هو: أن يتمكن Nextcloud من الوصول إلى ONLYOFFICE، وأن يتمكن ONLYOFFICE من الوصول إلى عنوان رد الاتصال على Nextcloud، وأن تنجح عملية المصادقة، وأن يتمكن Nextcloud من جلب الملف المحدث، وأن يقبل نظام التخزين الخلفي الاستبدال.

عندما يكون السبب لا يزال غير واضح

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

عند هذه النقطة، احتفظ بالطوابع الزمنية الدقيقة، ورموز حالة HTTP، وإصدار الموصل، وإصدار Nextcloud، وإصدار ONLYOFFICE Docs، وبنية الشبكة، وسطور السجل ذات الصلة بعد تنقيحها. هذه المعلومات أكثر فائدة بكثير من رسالة المتصفح العامة "تعذر حفظ المستند".

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

• دليل تكامل Nextcloud من ONLYOFFICE
• استكشاف أخطاء واجهة برمجة تطبيقات ONLYOFFICE Docs وإصلاحها
• واجهة برمجة تطبيقات معالج ردود الاتصال ONLYOFFICE
• تكوين JWT الخاص بـ ONLYOFFICE
• إعدادات تسجيل Nextcloud