المزامنة مع Dropbox

أتِح للمستخدمين مزامنة مشاريعهم مع مجلد في Dropbox الخاص بهم.

طُوّرت هذه الميزة بواسطة ayaka-notes/ayakaleaf-pro. قُدّمت في الإصدار v6.3.1 كمعاينة مبكرة، وستُطلَق رسميًا في الإصدار v6.4.0، لذا قد تتغيّر إعداداتها وسلوكها. نحتاج إلى ملاحظاتك إذا واجهت أي مشكلة.

تُبقي المزامنة مع Dropbox مشاريع المستخدم متزامنة مع Dropbox الخاص به، كما هو الحال في Overleaf Cloud: بمجرد أن يربط المستخدم حسابه على Dropbox، يظهر كل مشروع من مشاريعه كمجلد في Apps/<your Dropbox app>/، وتُرسَل التغييرات التي تُجرى في Overleaf إلى Dropbox، وتعود التغييرات التي تُجرى في Dropbox إلى Overleaf.

​

إعداد المزامنة مع Dropbox

يجب عليك تفعيل git-bridge أولًا: فبدونه تُخفي إعدادات الحساب قسم مزامنة المشاريع.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

أنشئ تطبيقًا في Dropbox App Console، بعد تسجيل الدخول بحساب Dropbox الذي سيملك التطبيق:

1. انقر على Create app، ثم املأ الصفحة:
   • 1. Choose an API: اختر Scoped access.
   • 2. Choose the type of access you need: اختر App folder، وليس Full Dropbox. لا يزامن Overleaf إلا داخل مجلد التطبيق.
   • 3. Name your app: أدخل اسمًا، مثل Overleaf. يجب أن يكون فريدًا على Dropbox. تظهر مشاريع كل مستخدم في Apps/<name of your app>/ في Dropbox الخاص به، وهذا الاسم هو DROPBOX_APP_NAME أدناه.
   • انقر على Create app. يُفتح التطبيق على علامة التبويب Settings.
2. في علامة التبويب Permissions، ضمن Files and folders، حدّد files.metadata.write و files.content.write و files.content.read. يُحدَّد account_info.read و files.metadata.read معها ولا يمكن إلغاء تحديدهما. لا تحدّد أي صلاحيات أخرى.
3. انقر على Submit في الشريط أسفل علامة التبويب Permissions. بدون Submit لا تُحفظ الصلاحيات، ويرفض Dropbox مزامنة الملفات للمستخدمين الذين يربطون حساباتهم.

Dropbox App Console: الصلاحيات التي يجب تحديدها، محفوظة عبر Submit

4. في علامة التبويب Settings، ضمن OAuth 2، أدخل ${OVERLEAF_SITE_URL}/user/dropbox/oauth/callback في Redirect URIs، ثم انقر على Add. لا تكفي كتابة العنوان: فهو لا يُحفظ إلا بعد ظهوره في القائمة فوق الحقل.

Dropbox App Console: أدخل عنوان إعادة التوجيه، ثم انقر على Add

5. في علامة التبويب Settings، ضمن Webhooks، أدخل ${OVERLEAF_SITE_URL}/dropbox/webhook في Webhook URIs، ثم انقر على Add أيضًا. يستدعيه Dropbox فورًا للتحقق منه، لذا يجب أن يكون Overleaf قيد التشغيل مسبقًا بالإعدادات أدناه وأن يكون قابلًا للوصول من الإنترنت (راجع Webhook). تظهر حالته Enabled بمجرد نجاح التحقق.

انسخ App key و App secret (انقر على Show) من علامة التبويب Settings، ثم أضف الإعدادات التالية إلى ملفات متغيرات البيئة الخاصة بـ overleaf. يمكنك إضافة الـ webhook (الخطوة 5) بعد تشغيل Overleaf بهذه الإعدادات.

config/variables.env

# used to encrypt the user's Dropbox refresh token.
# How to generate: `openssl rand -hex 32`
DROPBOX_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# Dropbox Sync Settings
DROPBOX_ENABLED=true
DROPBOX_APP_KEY=
DROPBOX_APP_SECRET=
# the name of your Dropbox app (step 1), which is the folder name in Apps/
DROPBOX_APP_NAME=Overleaf

# OAuth callback is: ${OVERLEAF_SITE_URL}/user/dropbox/oauth/callback
# Webhook is: ${OVERLEAF_SITE_URL}/dropbox/webhook
# (Optional) DROPBOX_SYNC_PROXY_URL=http://10.0.0.1:10808

• قبل تكوين عنوان إعادة التوجيه (redirect URI) والـ webhook، تأكد من ضبط OVERLEAF_SITE_URL بشكل صحيح.
• يثبّت Dropbox صلاحيات الرمز (token) عندما يربط المستخدم حسابه: ولا يؤدي إرسال الصلاحيات إلى تغيير الرموز الموجودة. يجب على المستخدمين الذين ربطوا حساباتهم قبل إرسال الصلاحيات، أو قبل أن تغيّرها، إلغاء ربط حسابهم على Dropbox وربطه مرة أخرى.
• يكون التطبيق الجديد في حالة Development. إذا كان Development users في علامة التبويب Settings يعرض Only you، فلا يمكن ربط سوى حسابك على Dropbox: انقر على Enable additional users للسماح للمستخدمين الآخرين بربط حساباتهم. بعد ذلك يعرض عدد المستخدمين الذين ربطوا حساباتهم، مثل 1 / 500: يقبل تطبيق Development حتى 500 مستخدم كحد أقصى. لعدد أكبر من المستخدمين، انقر على Apply for production، وسيراجع Dropbox التطبيق.

إذا كنت موجودًا في منطقة ذات وصول مقيّد إلى الشبكة، فقد تحتاج إلى تكوين وكيل (proxy) للوصول إلى Dropbox. اضبط متغير البيئة التالي: DROPBOX_SYNC_PROXY_URL=http://10.0.0.1:10808. يجب أن يكون وكيلًا أماميًا قياسيًا من نوع HTTP/HTTPS، ويجب ألا يستخدم 127.0.0.1.

​

إنشاء فهارس قاعدة البيانات

شغّل هذا مرة واحدة، قبل أن يربط المستخدمون حساباتهم على Dropbox. لا تُنشأ الفهارس التي تستخدمها المزامنة مع Dropbox تلقائيًا، لذا بدونها يمسح كل بحث مزامنة المجموعة (collection) بأكملها.

مستخدمو Toolkit: شغّلوا bin/mongo. مستخدمو Docker Compose: شغّلوا docker compose exec mongo mongosh sharelatex. ثم الصقوا:

db.dropboxEntities.createIndex(
  { 'overleaf.userId': 1, 'dropbox.id': 1 },
  { name: 'overleaf.userId_1_dropbox.id_1', unique: true,
    partialFilterExpression: { 'dropbox.id': { $exists: true } } })
db.dropboxEntities.createIndex(
  { 'overleaf.userId': 1, 'overleaf.id': 1 },
  { name: 'overleaf.userId_1_overleaf.id_1', unique: true,
    partialFilterExpression: { 'overleaf.id': { $exists: true } } })
db.dropboxEntities.createIndex({ 'overleaf.userId': 1, 'dropbox.pathLower': 'hashed' })
db.dropboxProjects.createIndex({ userId: 1, projectId: 1 }, { name: 'projectId_userId_1', unique: true })
db.dropboxProjects.createIndex({ userId: 1, dropboxId: 1 }, { name: 'userId_dropboxId_1', unique: true })

لا ضرر من تشغيله مرة أخرى: يتخطى MongoDB الفهارس الموجودة بالفعل.

لا تشغّل بدلًا من ذلك عمليات ترحيل dropboxEntities الموجودة في tools/migrations: إذ يحذف 20220825160708_recreate_dropboxEntities المجموعة، مما يمحو حالة المزامنة لكل مستخدم.

​

Webhook

يُبلغ Dropbox نظام Overleaf بالتغييرات التي تُجرى في Dropbox عبر webhook، لذا تظهر في Overleaf خلال ثوانٍ. يُرسَل الـ webhook إلى عنوان موقعك، ${OVERLEAF_SITE_URL}/dropbox/webhook، ولا حاجة إلى منفذ إضافي، لكن يجب أن يتمكن Dropbox من الوصول إليه من الإنترنت. عند إضافته في App Console، يتحقق منه Dropbox فورًا.

بدون webhook، على سبيل المثال على خادم لا يستطيع Dropbox الوصول إليه، تظل التغييرات التي تُجرى في Overleaf تُرسَل إلى Dropbox، لكن التغييرات التي تُجرى في Dropbox لا تعود إلا عندما ينقر المستخدم على sync this project now في نافذة Dropbox في المحرر.

​

كيف تعمل المزامنة

• الربط: عندما يربط المستخدم حسابه على Dropbox، تُرسَل المشاريع التي يملكها إلى Dropbox. أما المشاريع المشتركة معه فتظهر في Dropbox مع تغييرها التالي.
• من Overleaf إلى Dropbox: تُرسَل الملفات الجديدة وعمليات إعادة التسمية والنقل والحذف وإعادة تسمية المشاريع فورًا. أما التعديلات في المحرر فتُرسَل بمجرد أن يحفظها Overleaf في مساحة التخزين الخاصة به، بعد بضع دقائق من مغادرة الجميع للمشروع. لإرسالها في وقت أبكر، انقر على sync this project now في نافذة Dropbox في المحرر (مرة واحدة كل دقيقة).
• من Dropbox إلى Overleaf: تُطبَّق الملفات الجديدة والمعدّلة والمجلدات الجديدة وعمليات الحذف في مجلد المشروع على المشروع. ويصبح المجلد الجديد في المستوى الأعلى من مجلد التطبيق مشروعًا جديدًا. ويؤدي حذف مجلد مشروع في Dropbox إلى وضع علامة “محذوف” على المشروع في Overleaf.
• التعارضات: عندما يتغيّر ملف في كلا المكانين في الوقت نفسه، يفوز التغيير الأخير. وقد يحتفظ Dropbox بالنسخة الأخرى كـ conflicted copy.
• المتعاونون: يحصل المتعاونون الذين يربطون حساباتهم على Dropbox على المشاريع المشتركة معهم. ويحصل المشاهدون ذوو صلاحية القراءة فقط والمراجعون على المشروع، لكن تغييراتهم في Dropbox لا تُزامَن عائدةً إلى Overleaf.
• الملفات المتجاهلة: تبقى الملفات التي لا يزامنها Overleaf، مثل مخرجات البناء (.aux و .log و …) أو .DS_Store أو بيئات Python الافتراضية، في Dropbox فقط.

​

أسئلة وأجوبة (Q&A)

لماذا لا يستطيع مستخدم ربط حسابه على Dropbox؟

• يُطابَق مجلد Dropbox الذي لا يعرفه Overleaf بعد مع مشروع حسب اسمه، لذا يُطلب من المستخدم الذي تشترك مشاريعه في اسم واحد إعادة تسميتها أولًا. تُقارَن الأسماء دون تمييز بين الأحرف الكبيرة والصغيرة، وتُحتسب المشاريع المؤرشفة والمنقولة إلى سلة المهملات أيضًا.
• لا يمكن ربط حساب Dropbox إلا بحساب Overleaf واحد.

لماذا أُلغي ربط حساب Dropbox؟

الإجابة: يُلغي Overleaf ربط حساب Dropbox عندما يرفض Dropbox الرمز الخاص به (على سبيل المثال بعد أن يزيل المستخدم التطبيق في Dropbox)، أو عندما تمتلئ مساحة Dropbox، أو عندما يعلّق Dropbox الحساب. ويُعلم إشعارٌ في قائمة المشاريع المستخدمَ بأيٍّ من هذه الحالات حدث، إلى أن يربط الحساب مرة أخرى. ويمكن للمستخدم ربطه مرة أخرى بمجرد حل المشكلة.

هل يمكنني إعادة تسمية مجلد مشروع في Dropbox؟

الإجابة: يُرجى إعادة تسمية المشروع في Overleaf بدلًا من ذلك: إذ يُعاد تسمية مجلده في Dropbox أيضًا. فبالنسبة إلى Overleaf، تؤدي إعادة تسمية المجلد في Dropbox إلى حذف مجلد المشروع وإنشاء مجلد جديد، لذا يوضع على المشروع القديم علامة “محذوف” ويُنشأ مشروع جديد من الملفات.

لماذا تحمل بعض مجلدات المشاريع أرقامًا، مثل «Thesis (1)»؟

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

ويُسمّى المشروع المرفوع الذي يكون اسمه مستخدمًا بالفعل برقم في Overleaf أيضًا، على سبيل المثال «Thesis (1)».

ماذا يحدث عندما أحذف مجلد مشروع في Dropbox؟

• إذا لم يكن هناك مشروع آخر يحمل اسم المجلد، يوضع على المشروع علامة “محذوف” في Overleaf. وتُحفَظ ملفاته وسجله.
• إذا كانت عدة مشاريع تحمل ذلك الاسم، فلا يستطيع Overleaf معرفة المشروع الذي كان المجلد يخصه. فيُلغي ربط حساب Dropbox ويعرض إشعارًا يطلب إعادة تسمية المشاريع. امنح المشاريع أسماء مختلفة قبل حذف مجلداتها في Dropbox.
• المجلد المرقّم، مثل «Thesis (1)»، لا يطابق أي اسم مشروع، لذا لا يؤدي حذفه إلى تغيير المشروع في Overleaf. انقر على sync this project now في نافذة Dropbox في المحرر لإرسال المشروع إلى Dropbox مرة أخرى.

ماذا يحدث في Dropbox عندما أحذف مشروعًا في Overleaf؟

الإجابة: لا شيء، يبقى مجلده في Dropbox. احذف المجلد في Dropbox إذا لم تعد بحاجة إليه.

ماذا يحدث للتغييرات في Dropbox بينما يكون المشروع مؤرشفًا أو في سلة المهملات؟

الإجابة: لا تُطبَّق على المشروع، ولا تؤدي استعادة المشروع إلى جلبها أيضًا. وبعد الاستعادة، يتوقف Overleaf عن إرسال تغييراته على الملفات التي تغيّرت في Dropbox خلال تلك الفترة، فيختلف الجانبان.

لإعادة مثل هذا الملف إلى المزامنة، احفظه مرة أخرى في Dropbox. عندها يعتمد Overleaf نسخة Dropbox: وتُستبدَل التغييرات التي أُجريت على الملف في Overleaf منذ الاستعادة، وتبقى في سجل المشروع. استعد المشروع قبل أن تغيّره في Dropbox.

لماذا يفتح رابط Dropbox في المحرر الصفحة الرئيسية لـ Dropbox؟

الإجابة: يشير الرابط إلى Apps/<app folder>/<project> على dropbox.com، كما في Overleaf Cloud. وعندما يعرض Dropbox مجلد Apps باسم مترجم، على سبيل المثال 应用 بالصينية، لا يعثر الرابط على المجلد ويفتح Dropbox صفحته الرئيسية بدلًا من ذلك. افتح مجلد المشروع من مجلد Apps المترجم في Dropbox.

لماذا تنقص بعض ملفات المشروع في Dropbox؟

الإجابة: التغييرات التي أُجريت أثناء توقف خدمة المزامنة عن العمل، على سبيل المثال أثناء إعادة تشغيلها، لا تُرسَل إلى Dropbox لاحقًا. انقر على sync this project now في نافذة Dropbox في المحرر: فهو يرسل المشروع بأكمله مرة أخرى.