حل مشكلة "الرمز المميز غير صالح" في برنامج ONLYOFFICE على منصة Nextcloud

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

أبقِ JWT مُفعّلاً. حدّد أولاً السر النشط ونوع النشر، ثمّ حدّث الإعدادات الصحيحة، ثمّ شغّل فحص اتصال الموصل. يجب أن يُشير الفحص إلى نجاح الاتصال؛ فمجرّد فتح مُحرّر المتصفح لا يُثبت عمل تنزيلات المستندات وعمليات الاستدعاء.

ماذا يخبرك هذا الخطأ؟

رمز JWT (رمز الويب JSON) هو رمز موقّع يُستخدم للتحقق من موثوقية الطلب المُرسل بين Nextcloud و ONLYOFFICE Docs. يقوم الموصل بتوقيع الطلبات باستخدام سرّه المُكوّن، بينما يقوم خادم المستندات بالتحقق منها باستخدام سرّه المُكوّن أيضًا. في حال اختلاف أسرار التوقيع، يتعذر التحقق من صحة توقيع الرمز، وبالتالي يُرفض الطلب.

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

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

1. ابحث عن سر خادم المستندات النشط

استخدم الإعدادات الخاصة بخادم المستندات قيد التشغيل. لا تفترض أن أي سرّ محفوظ من حاوية أو خادم سابق لا يزال نشطًا.

• لينكس: فحص /etc/onlyoffice/documentserver/local.json.
• ويندوز: فحص %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json.
• دوكر: اقرأ السر من الحاوية قيد التشغيل. تدعم الصورة الرسمية أيضًا قراءة سر الجلسة باستخدام هذا الأمر:

sudo docker exec <containerID> /var/www/onlyoffice/documentserver/npm/json -f /etc/onlyoffice/documentserver/local.json 'services.CoAuthoring.secret.session.string'

استبدل <containerID>هذا باسم الحاوية أو معرّفها الفعلي. تعامل مع القيمة المُعادة كبيانات اعتماد: لا تقم بلصقها في منتديات الدعم أو لقطات الشاشة أو السجلات العامة.

في ملف local.jsonالإعدادات، قارن القيم في كل من services.CoAuthoring.secret.inbox.stringو services.CoAuthoring.secret.outbox.stringو services.CoAuthoring.secret.session.string. يجب أن تكون جميعها متطابقة في هذا الإعداد القياسي. تأكد أيضًا من تفعيل التحقق من صحة الرمز المميز للمتصفح، وصندوق الوارد، وصندوق الصادر. تتطلب إصدارات المستندات السابقة للإصدار 7.2 تفعيل التحقق من صحة الرمز المميز بشكل صريح؛ بينما تُفعّله الإصدارات الأحدث افتراضيًا.

2. تحديث موصل ONLYOFFICE الخاص بـ Nextcloud

1. قم بتسجيل الدخول كمسؤول Nextcloud وافتح الإعدادات > الإدارة > ONLYOFFICE .
2. في إعدادات الخادم، أدخل المفتاح السري الموجود على خادم المستندات قيد التشغيل في حقل "المفتاح السري" . تجنب المسافات البادئة أو اللاحقة، ولا تُضِف علامات اقتباس إلا إذا كانت جزءًا من المفتاح السري نفسه.
3. تحقق من إعدادات رأس JWT إذا كان النشر الخاص بك يستخدم رأسًا مخصصًا. يجب أن تتطابق إعدادات الموصل jwt_headerمع رأس الرمز المميز المُكوّن في خادم المستندات. إذا لم تقم بتخصيص الرأس عمدًا، فلا تُغيره كجزء من عملية الإصلاح هذه.
4. احفظ الإعدادات. أبقِ رمز JWT مُفعّلاً على كلا الجانبين.

يمكن أيضًا تغيير إعدادات الموصل الموثقة باستخدام أمر Nextcloud occمن دليل تثبيت Nextcloud:

sudo -u www-data php occ config:app:set onlyoffice jwt_secret --value='YOUR_SECRET'

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

3. قم بتطبيق التغيير بالطريقة الصحيحة لتثبيتك

Docker أو Docker Compose

بالنسبة لعمليات النشر باستخدام Docker، قم بتكوين JWT من خلال بيئة الحاوية بدلاً من تعديل الملف الذي تم إنشاؤه تلقائيًا يدويًا local.json. قم بتعيين نفس السر في تعريف خدمة خادم المستندات.

environment:
  - JWT_ENABLED=true
  - JWT_SECRET=YOUR_SECRET

بعد تعديل ملف Compose، أعد إنشاء حاوية خادم المستندات لتطبيق التغييرات. على سبيل المثال، من الدليل الذي يحتوي على ملف Compose:

docker compose up -d --force-recreate <documentserver-service>

استبدل اسم الخدمة من ملف Compose الخاص بك. إعادة التشغيل العادية لا تُطبّق قيمة البيئة المُعدّلة على حاوية موجودة. إذا كنت تستخدم docker run، فأعد إنشاء الحاوية بالقيم المُحدّثة JWT_ENABLED، JWT_SECRETمع الحفاظ على منافذها ووحدات التخزين والخيارات الأخرى المطلوبة. لا تحذف حاوية الإنتاج حتى تتأكد من هذه الإعدادات ونقاط ربط البيانات الدائمة.

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

حزمة لينكس أو تثبيت ويندوز

إذا قمتَ بتعيين سرّ مخصص عمدًا local.json، فتأكد من تطابق حقول السرّ الثلاثة وتفعيل قيم التحقق من صحة الرمز المميز المطلوبة. طبّق التغيير بإعادة تشغيل خدمات خادم المستندات ذات الصلة. تتضمن تعليمات ONLYOFFICE الحالية قائمة بـ ds-converterو ds-docserviceو ds-metricsعلى نظام Linux؛ قد تتطلب عمليات التثبيت المُدارة بواسطة مُشرف خدمة مختلف طريقة إعادة التشغيل المناسبة لذلك الإعداد. على نظام Windows، أعد تشغيل خدمات ONLYOFFICE بعد حفظ التكوين.

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

تحقق من الإصلاح

1. في دليل تثبيت Nextcloud، قم بتشغيل فحص الموصل الرسمي:

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

استخدم حساب خادم الويب المناسب لتثبيتك إن لم يكن كذلك www-data. يجب أن يُشير الأمر إلى نجاح الاتصال. إذا استمر في الإبلاغ عن رمز غير صالح، فتأكد مجددًا من تطابق السر النشط لخادم المستندات المُشغّل مع Nextcloud تمامًا، وأن أي رأس JWT مخصص متطابق أيضًا.

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

تُثبت هذه الفحوصات صحة الاتصال المُهيأ ومسار الحفظ الأساسي. لكنها لا تُثبت صحة كل مسار للخادم الوكيل العكسي، أو إعدادات التخزين الخارجي، أو بنية الخوادم المتعددة؛ لذا اختبر هذه المسارات بشكل منفصل إذا كان نظامك يستخدمها.

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

• أونلي أوفيس: تكامل نيكست كلاود وإعداد JWT
• ONLYOFFICE: تهيئة JWT لخادم المستندات
• موصل ONLYOFFICE Nextcloud: خيارات التكوين وأوامر occ

تم التحقق من تفاصيل التكوين مقابل وثائق ONLYOFFICE الرسمية ومستودع الموصل في 9 أكتوبر 2026. يمكن أن تختلف تسميات واجهة المستخدم وإدارة الخدمة حسب الموصل ونظام التشغيل وطريقة النشر.