كيفية إعداد مصادقة مفتاح JWT السري في ONLYOFFICE

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

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

مرجع سريع

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

1. تحديد حاوية ONLYOFFICE وطريقة النشر

بالنسبة لمضيف Docker، ابدأ بما يلي:

docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'
docker images | grep onlyoffice

حدد ما إذا تم تشغيل المثيل باستخدام docker runDocker Compose أو لوحة تحكم أو طبقة تنسيق أخرى. ستحتاج إلى تغيير إعدادات المصدر التي تُنشئ الحاوية. تعديل ملف مُنشأ داخل الحاوية ليس حلاً دائمًا.

بالنسبة لـ Docker تحديدًا، يُوجّه برنامج ONLYOFFICE المسؤولين إلى استخدام متغيرات البيئة بدلًا من التعديل اليدوي /etc/onlyoffice/documentserver/local.json. إذا قمتَ بتعديل قيم JWT مباشرةً في هذا الملف، فبإمكان عملية بدء تشغيل Docker استعادتها أو إعادة إنشائها عند إعادة تشغيل الحاوية.

2. ابتكر سرًا قويًا واحفظه في مكان آمن

أحد أوامر سطر الأوامر المفيدة هو:

openssl rand -hex 32

ينتج عن ذلك 32 بايتًا عشوائيًا ممثلة بـ 64 حرفًا سداسيًا عشريًا. لا يشترط برنامج ONLYOFFICE هذا التنسيق تحديدًا؛ فالشرط الأساسي هو أن يتشارك الطرفان نفس السر وأن يكون من الصعب تخمينه.

تعامل معها JWT_SECRETكما لو كانت كلمة مرور أو بيانات اعتماد واجهة برمجة التطبيقات (API):

• لا تقم بإيداعه في مستودع Git عام.
• لا تضعه في جافا سكريبت الواجهة الأمامية التي يتم شحنها إلى المتصفحات.
• قم بتقييد الوصول إلى ملف بيئة Compose أو مخزن الأسرار الذي يحتوي عليه.
• استخدم كلمة مرور مختلفة لبيئات منفصلة مثل بيئة الإنتاج وبيئة الاختبار.

تُحذّر وثائق التوقيع الخاصة بـ ONLYOFFICE صراحةً من ضرورة توقيع الرمز المميز على الخادم، لأن أي كود برمجي في المتصفح يحتوي على السرّ يُعرّضه للمستخدمين. تستخدم الأمثلة الرسمية خوارزمية HMAC-SHA256 HS256. راجع وثائق توقيع JWT الخاصة بـ ONLYOFFICE .

3. قم بتهيئة JWT في Docker Compose

يمكن أن تتضمن خدمة Compose الأساسية ما يلي:

services:
  documentserver:
    image: onlyoffice/documentserver:latest
    restart: unless-stopped
    environment:
      JWT_ENABLED: "true"
      JWT_SECRET: "${ONLYOFFICE_JWT_SECRET}"
      JWT_HEADER: "Authorization"
      JWT_IN_BODY: "false"
    ports:
      - "8080:80"

احتفظ بالسر الفعلي خارج ملف Compose كلما أمكن ذلك. على سبيل المثال، ضعه في .envملف مقيد الصلاحيات:

ONLYOFFICE_JWT_SECRET=replace_with_your_random_secret

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

يوثق مستودع ONLYOFFICE Docker-DocumentServer الرسمي الملفات التالية JWT_ENABLED: JWT_SECRET[ المستندات المطلوبة ]. ويقوم كود بدء تشغيل Docker الحالي بتفعيل التحقق من صحة JWT افتراضيًا، ويستخدم [العنوان الافتراضي] كعنوان افتراضي، ويُنشئ سرًا عشوائيًا في حال عدم توفير سر صريح.JWT_HEADERJWT_IN_BODYAuthorization

4. أعد إنشاء الحاوية لتطبيق البيئة الجديدة

للتأليف الموسيقي:

docker compose up -d --force-recreate
docker compose ps

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

يمكنك أيضًا فحص بيئة الحاوية قيد التشغيل دون طباعة السر نفسه:

docker inspect onlyoffice-documentserver \
  --format '{{range .Config.Env}}{{println .}}{{end}}' \
  | grep '^JWT_' \
  | sed 's/^JWT_SECRET=.*/JWT_SECRET=[REDACTED]/'

إذا اختلف اسم الحاوية، فاستبدله onlyoffice-documentserverوفقًا لذلك.

5. قم بتكوين نفس السر في التكامل

هذا هو الجزء الذي يُغفل عنه غالبًا. تفعيل JWT على ONLYOFFICE Docs دون تهيئة جانب إدارة المستندات يؤدي إلى رفض طلبات المحرر. يجب على الموصل أو التطبيق المخصص توقيع الطلبات باستخدام نفس السر تمامًا.

مثال على Nextcloud

في إعدادات ONLYOFFICE الخاصة بـ Nextcloud، أدخل نفس المفتاح السري المستخدم من قِبل خادم المستندات. يجب أن يتطابق اسم العنوان أيضًا. تُدرج وثائق تكامل Nextcloud الحالية الخاصة بـ ONLYOFFICE jwt_secretإعدادات jwt_headerالموصل، مع Authorizationاستخدام العنوان الافتراضي. راجع وثائق موصل Nextcloud الرسمية .

إذا كان الموصل الخاص بك يحتوي على حقل بعنوان "المفتاح السري" أو "سر JWT" أو ما شابه، فلا تقم بإنشاء سر مستقل ثانٍ هناك. انسخ نفس قيمة السر.

6. لإجراء تكامل مخصص، قم بتوقيع إعدادات المحرر بالكامل على الخادم

بالنسبة للتطبيق المخصص، قم أولاً بإنشاء تكوين المحرر، ثم قم بتوقيع هذا التكوين على الواجهة الخلفية، ثم قم بتعيين JWT الناتج إلى tokenالخاصية ذات المستوى الأعلى.

مثال على استخدام Node.js:

import jwt from "jsonwebtoken";

const config = {
  documentType: "word",
  document: {
    fileType: "docx",
    key: "document-2026-001",
    title: "Project Plan.docx",
    url: "https://files.example.com/project-plan.docx"
  },
  editorConfig: {
    callbackUrl: "https://app.example.com/onlyoffice/callback"
  }
};

config.token = jwt.sign(config, process.env.ONLYOFFICE_JWT_SECRET, {
  algorithm: "HS256"
});

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

يحتوي التكوين الناتج الذي تم تمريره إلى DocsAPI.DocEditorالرمز المميز على ما يلي:

new DocsAPI.DocEditor("placeholder", config);

يُعرّف مرجع واجهة برمجة التطبيقات الرسمي config.tokenالتوقيع المشفر الذي تستخدمه ONLYOFFICE Docs للتحقق من صحة تكوين المحرر.

7. فهم الفرق بين رموز الترويسة ورموز الجسم

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

يدعم ONLYOFFICE رموز الطلب في كلٍ من نص الطلب ورأسه. تشير الأسئلة الشائعة الأمنية إلى أن الرؤوس قد تصل إلى حدود طول معينة خاصة بالخادم، ولذلك يُوصى باستخدام رموز نص الطلب للطلبات الواردة التي تنطبق عليها هذه القيود. بدءًا من الإصدار 7.1 من الوثائق، يُعطى رمز نص الطلب الوارد الأولوية عند وجوده؛ وإلا يُستخدم رمز الرأس. يمكن للطرف المُرسِل إرسال كليهما. راجع وثائق ONLYOFFICE الخاصة برموز الطلب .

يتم ضبط متغير Docker JWT_IN_BODYافتراضيًا على قيمة فارغة false، لذا لا تقم بتفعيله لمجرد وجوده. قم بتغييره فقط عندما يكون التكامل الخاص بك مصممًا لإرسال رموز التحقق من صحة البيانات بشكل متسق.

8. اختبر باستخدام طلب محرر حقيقي

يُعد تسلسل التحقق المفيد ما يلي:

1. افتح مستندًا من خلال التكامل الحقيقي الخاص بك.
2. تأكد من تحميل المحرر بدون أخطاء في الرموز المميزة.
3. قم بإجراء تعديل بسيط.
4. أغلق المحرر أو قم بتشغيل مسار الحفظ العادي.
5. تحقق من أن تطبيق التخزين يستقبل ويقبل رد الاتصال.

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

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

9. تحقق من حالة JWT وسجلاتها عند فشل المصادقة

يُشير رمز بدء تشغيل Docker الحالي إلى أداة مساعدة حالة JWT. قم بتشغيل الأمر التالي باستخدام اسم الحاوية الصحيح:

docker exec onlyoffice-documentserver \
  sudo documentserver-jwt-status.sh

يمكنك أيضًا فحص السجلات:

docker logs --tail 200 onlyoffice-documentserver
docker exec onlyoffice-documentserver \
  find /var/log/onlyoffice/documentserver -type f -maxdepth 3 -print

إذا فشلت عملية التكامل مباشرة بعد تغيير السر، فقارن هذه العناصر بالترتيب التالي:

• هل JWT_ENABLEDتم تفعيلها بالفعل في الحاوية المعاد إنشاؤها؟
• هل يستخدم التكامل نفس السر بالضبط، بما في ذلك الأحرف الكبيرة وعلامات الترقيم؟
• هل يستخدم الموصل نفس اسم رأس JWT؟
• بالنسبة للمحرر المخصص، هل تقوم بتوقيع نفس كائن التكوين الذي ترسله إلى المتصفح؟
• هل يتم أيضاً توقيع طلبات الاستدعاء وطلبات الأوامر والتحقق من صحتها حسب الحاجة؟
• هل تم اقتطاع أو تفسير أو استبدال سر مخزن في ملف shell أو Compose عن طريق توسيع متغير البيئة؟

أنماط الفشل الشائعة

"رمز غير صالح" أو "توقيع غير صالح"

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

يعمل البرنامج حتى إعادة تشغيل Docker

هذا يعني عادةً أن عملية النشر كانت تعتمد على رمز JWT السري المُنشأ تلقائيًا. يُحذر ONLYOFFICE صراحةً من إمكانية إعادة إنشاء رمز سري عشوائي بعد إعادة التشغيل أو إعادة إنشاء الحاوية. لذا، قم بتعيينه JWT_SECRETبنفسك وضع القيمة نفسها في التكامل.

يعرض Nextcloud خطأ في الاتصال أو الرمز المميز

تحقق أولاً من السر والعنوان على كلا الجانبين. تتطلب وثائق Nextcloud الخاصة بـ ONLYOFFICE jwt_headerأن يتطابق عنوان الموصل مع العنوان المُكوّن في خادم المستندات. القيمة الافتراضية الحالية هي Authorization.

يؤدي طلب كبير موقّع إلى إرجاع خطأ HTTP

تحقق مما إذا كان رمز JWT يُرسل في ترويسة تتجاوز الحد الأقصى لحجم الترويسة المسموح به من قِبل الخادم الوكيل أو خادم الويب. توضح الأسئلة الشائعة الأمنية في ONLYOFFICE أن هذا أحد أسباب تفضيل استخدام رموز الجسم في طلبات POST المناسبة.

تدوير سر JWT بأمان

يجب تنسيق عملية تغيير رمز JWT السري. لا فائدة من تغيير خادم المستندات فقط بينما يستمر الموصل في التوقيع باستخدام الرمز السري القديم.

لعملية نشر بسيطة لنسخة واحدة:

1. قم بإنشاء السر الجديد واحفظه بشكل آمن.
2. حدد فترة صيانة قصيرة إذا كان من الممكن أن تتأثر عمليات التحرير النشطة.
3. قم بتحديث سر التكامل وسر خادم المستندات JWT_SECRETكتغيير منسق واحد.
4. أعد إنشاء حاوية خادم المستندات.
5. افتح مستندًا تجريبيًا، وقم بتحريره، ثم احفظه.
6. تأكد من عمل ردود الاتصال قبل إعادة الخدمة إلى الاستخدام العادي.

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

قائمة التحقق من الإنتاج

• السر الدائم: يتم تعيينه JWT_SECRETبشكل صريح؛ لا تعتمد على القيمة العشوائية المولدة.
• السر نفسه في كل مكان: يجب أن يتشارك خادم المستندات والتكامل نفس القيمة.
• التوقيع من جانب الخادم: لا تكشف السر أبدًا في كود الواجهة الأمامية/المتصفح.
• HS256: استخدم أسلوب HMAC-SHA256 الموضح في نماذج التعليمات البرمجية الرسمية لـ ONLYOFFICE.
• اتفاقية الترويسة: إذا أرسل الموصل JWT عبر ترويسة مسماة، فيجب أن يتطابق هذا الاسم مع خادم المستندات.
• إعادة إنشاء الحاوية: تتطلب تغييرات بيئة Docker إعادة إنشاء الحاوية.
• اختبار تكامل حقيقي: فتح، تحرير، حفظ، والتحقق من سلوك الاستدعاء.
• التخزين السري: حافظ على السر بعيدًا عن المستودعات والسجلات العامة.
• التدوير المتحكم به: قم بتحديث كلا الجانبين معًا وتحقق قبل إنهاء الصيانة.

خلاصة القول

بالنسبة لتثبيت ONLYOFFICE باستخدام Docker، فإنّ عملية التهيئة الدائمة بسيطة: يتم إنشاء سرّ قوي، وتعيينه JWT_ENABLED=trueمن JWT_SECRETخلال متغيرات بيئة الحاوية، ثم إعادة إنشاء الحاوية، وتكوين السرّ نفسه تمامًا في الموصل أو الواجهة الخلفية. يجب على عمليات التكامل المخصصة توقيع إعدادات المحرر وطلبات الخدمة على الخادم باستخدام HS256، وليس في كود المتصفح.

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