> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# تكامل Zotero

> اسمح للمستخدمين باستيراد ملف .bib من مكتبتهم في Zotero في نشر قائم على Kubernetes.

يعمل الاستيراد من Zotero داخل خدمة **web** (الوحدة `tpr-webmodule`) في كل pod من Ayakaleaf Pro. سجّل عميل OAuth الخاص بـ Zotero كما هو موضّح في [تكامل Zotero](https://ayakaleaf-pro.mintlify.site/ar/on-premises/configuration/overleaf-toolkit/integrations/zotero-integration.md)، مع عنوان الاستدعاء الراجع `${OVERLEAF_SITE_URL}/user/zotero/oauth/callback`، ثم اضبط Kubernetes كما يلي.

| | |
| - | - |
| الخدمة | web، في كل pod من Ayakaleaf Pro؛ تُقرأ عند بدء تشغيل web |
| Pod → Zotero | `https://www.zotero.org/oauth/*` و`https://api.zotero.org`، عندما يربط مستخدم حساب Zotero أو يستورد ملفًا أو يحدّثه |
| المتصفح ← Zotero | `https://www.zotero.org/oauth/authorize`، ثم العودة إلى عنوان الاستدعاء الراجع |
| Zotero → Overleaf | لا شيء: لا يلزم أن يكون المثيل قابلًا للوصول من الإنترنت |
| البيانات المخزّنة | مفتاح Zotero الخاص بالمستخدم، مشفّرًا، في MongoDB |
| المهام الدورية | لا شيء: لا يُحدَّث الملف إلا عندما يطلب المستخدم ذلك |

### الإعداد

**1. ConfigMap**

```yaml title="30-config.yaml (changes)" theme={null}
  ENABLED_LINKED_FILE_TYPES: project_file,project_output_file,url,zotero
  ZOTERO_CLIENT_ID: <client key>
  # optional: send the module's requests to Zotero through an HTTP proxy
  # ZOTERO_PROXY_URL: http://proxy.example.com:3128
```

يستبدل `ENABLED_LINKED_FILE_TYPES` القيمة الواردة من التثبيت؛ لذا احتفظ بالأنواع الموجودة لديك وأضف `zotero` (و`mendeley`، إذا كنت تستخدم كليهما).

**2. Secret**

```bash theme={null}
kubectl -n overleaf patch secret overleaf-secrets --type merge -p '{"stringData":{
  "ZOTERO_CLIENT_SECRET":"<client secret>",
  "ZOTERO_CIPHER_PASSWORD":"'"$(openssl rand -hex 32)"'"}}'
```

يشفّر `ZOTERO_CIPHER_PASSWORD` مفاتيح Zotero الخاصة بالمستخدمين في MongoDB. ومن دونه، يُنشئ كل pod ملف مفتاح في مجلد `/var/lib/overleaf/data` الخاص به. ومع [عدة نسخ متماثلة](https://ayakaleaf-pro.mintlify.site/ar/on-premises/configuration/kubernetes/horizontal-scaling.md) يصبح لكل عقدة مفتاح مختلف، ولا يستطيع المستخدم الذي تخدمه نسخة متماثلة أخرى استخدام حساب Zotero المرتبط به. اضبطه قبل أن يربط أول مستخدم حساب Zotero: فتغييره لاحقًا يُلزم كل مستخدم بربط Zotero من جديد.

**3. التطبيق وإعادة التشغيل**

```bash theme={null}
kubectl apply -f 30-config.yaml
kubectl -n overleaf rollout restart deployment/overleaf     # or statefulset/overleaf
```

### عدة نسخ متماثلة

اضبط `ZOTERO_CIPHER_PASSWORD` في الـ Secret، كما هو موضّح أعلاه. فمن دونه، لا يمكن تحديث ملف مستورد على نسخة متماثلة من نسخة متماثلة أخرى: إذ يفشل التحديث مع الرسالة "The remote service produced an error"، لأن ملف المفتاح الخاص بتلك النسخة المتماثلة لا يستطيع فك تشفير مفتاح Zotero الخاص بالمستخدم. أما مع وجود كلمة المرور في الـ Secret فيعمل على كل نسخة متماثلة؛ وقد اختبرنا الحالتين بالاستيراد على `overleaf-0` والتحديث على `overleaf-1`. تحفظ مصافحة OAuth حالتها في الجلسة داخل Redis، لذا يمكن أن يصل الاستدعاء الراجع (callback) إلى أي نسخة متماثلة.

### الاختبار على Kubernetes

في مقابل محاكاة لـ [www.zotero.org](http://www.zotero.org) وapi.zotero.org (موثوق بها عبر `NODE_EXTRA_CA_CERTS` من `overleaf-certs`)، وعلى Kubernetes 1.37 مع ثلاث نسخ متماثلة خلف HAProxy، تنجح اختباراتنا الشاملة (end-to-end) لـ Zotero (18 حالة): الربط عبر OAuth 1.0a وإلغاء الربط، واستيراد المكتبة والمجموعات إلى ملف `.bib`، وتحديثه، وإلغاء المفتاح على Zotero، وطلب الربط من جديد، وإمكانية البحث في المراجع من قِبل المتعاونين، واقتصار التحديث على من قام بالاستيراد، وأخطاء واجهة API، والاتصالات البطيئة بـ Zotero.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.