# ترحيل إصدار الإمكانات المجمع والتراجع عنه

> طبّق ترحيلات البحث والاستخدام والإضافات والتكاملات وMCP بترتيب الاعتماد، وتحقق من حالات التعطل، واعكسها بأمان.

يغطي هذا الدليل مجموعة الإمكانات المدمجة في `main` حتى التزام MCP ذي المعرّف
`9fb787ef438ecee0b65da9c785ab42dd3f2bdc1c`. لا يزال بيان الاستضافة الذاتية
المنشور يحدد v0.1.2. لا تطبق هذه التعليمات على تثبيت إنتاجي من v0.1.2 حتى يتوفر
صورة مطابقة أو بناء مصدر مراجع. الفرع المدمج ليس حاوية منشورة، ولا ينفذ تغيير
التوثيق هذا أي نشر.

## إنشاء نقطة التعافي

سجل وسم الصورة الحالي وملخصها الرقمي والتزام التطبيق ومراجعة ملف البيئة وحالة
ترحيلات قاعدة البيانات. أوقف عمليات الكتابة غير الضرورية، ثم التقط Postgres
وتخزين الكائنات من نقطة تعافٍ واحدة. إذا كان ClickHouse مفعّلًا، فالتقط إصدار
مخططه وأدلة الاحتفاظ أو التصدير المطلوبة في سياستك. اختبر الاستعادة في بيئة
معزولة قبل تغيير الإنتاج.

أبقِ MCP معطّلًا والبحث في وضع `shadow` أو `legacy` أثناء تغيير قاعدة البيانات.
لا تفعّل التكاملات أو الإضافات أو مستهلكي الاستخدام لمجرد وجود الجداول. تظل صحة
المزوّد أو تغطية الاستخدام المجهولة مجهولة؛ فهي ليست صفرًا ولا نجاحًا.

## تطبيق الترحيلات بترتيب الاعتماد

ثبّت مراجعة التطبيق الدقيقة وأنشئ عميل Prisma قبل فحص الأنواع أو تشغيل الخدمات.
يطبق أمر النشر المعتاد ترحيلات Postgres الإضافية الخمسة بترتيب أسماء الملفات:

1. `20260823180000_search_configuration_diagnostics`
2. `20260823210000_usage_metering`
3. `20260823220000_project_addons`
4. `20260823230000_add_project_integrations`
5. `20260823240000_mcp_control_plane`

يملك ترحيل التكاملات الحقل الاختياري `ApiKey.expiresAt` بوصفه متطلب مصادقة
مشتركًا. يعتمد ترحيل MCP عليه ويجب أن يبقى أخيرًا. لا تنسخ الحقل إلى ترحيل MCP
ولا تحذفه ما دام MCP أو مستهلك آخر يعتمد عليه.

```bash
pnpm install --frozen-lockfile
pnpm db:generate
pnpm db:deploy
pnpm --filter @nibleaf/database exec prisma migrate status
```

عند تفعيل التحليلات والاستخدام المدعومين بـClickHouse، طبّق ترحيلاته التقدمية
بهويّة مشغّل محدودة المدة بعد تثبيت حزم التطبيق المتوافقة:

```bash
pnpm analytics:migrate
```

يجب أن تعرض واجهة الاستخدام وAPI حالة غير متاحة أو جزئية حتى تكتمل التغطية
والتسوية. لا تستنتج اكتمال تعبئة البيانات من نجاح إنشاء الجداول.

## التشغيل بتحفظ والتحقق

شغّل عمليات API والتطبيق والعامل مع إبقاء MCP معطّلًا. تحقق من السلامة وتسجيل
الدخول وقراءة مشروع واحد وعملية نشر واحدة. ثم تحقق من كل حد قبل تفعيل التالي:

1. تحدّث إعدادات البحث إعداد المشروع الهدف فقط، وتعرض التشخيصات بيانات وصفية
   محدودة من دون محتوى أو متجهات. أبقِ الاسترجاع الهجين في الظل حتى تدعم أدلة
   المشروع واللغة والإصدار قرار التحويل.
2. تميّز مجاميع الاستخدام بين التغطية المكتملة والجزئية وغير المتاحة؛ وتبقى
   الاستحقاقات إرشادية ولا يُفعّل أي مزوّد دفع.
3. تملك المشاريع القائمة صفوف إضافات دائمة وحالة موافقة معروفة محفوظة وسجل
   تدقيق أوليًا. اختبر القبول والرفض مرة واحدة بعد تسجيل الخروج.
4. تُشفّر أسرار التكامل وتُفك بالمفتاح المخصص. تحقق من اتصال غير إنتاجي واحد
   من دون وضع بيانات الاعتماد في السجلات أو لقطات الشاشة.
5. أنشئ مفتاح MCP جديدًا مرتبطًا بالمشروع ويحمل `mcp:connect` ونطاق قراءة دقيقًا
   واحدًا. تحقق من الإمكانات، ثم ألغِ المفتاح وتأكد من توقف الوصول.

شغّل أوامر اختبار الترحيل قبل اعتبار المخطط جاهزًا:

```bash
pnpm --filter @nibleaf/database smoke:addons-migration
pnpm --filter @nibleaf/database smoke:integrations-migration
pnpm --filter @nibleaf/database smoke:mcp-migration
```

للبحث والاستخدام والإضافات والتكاملات وMCP أدلة تشغيل منفصلة. احتفظ بروابطها
الواردة في [ملاحظات إمكانات المصدر لأغسطس 2026](/releases/august-2026-capabilities)
مع سجل الترقية الدائم.

## التراجع بالترتيب العكسي

فضّل التراجع في وقت التشغيل على عكس المخطط بصورة هدامة. عطّل MCP وأوقف عملاءه
أولًا. أعد البحث إلى `SEARCH_RUNTIME=legacy`، وعطّل قراءات ClickHouse الاختيارية،
وأوقف الخطط أو الإضافات المتأثرة وعمليات تغيير التكاملات بينما تستعيد صورة
التطبيق السابقة.

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

1. جداول مستوى تحكم MCP وأعمدة مصدر مفتاح API التي يملكها MCP.
2. جداول التكاملات وبيانات الاعتماد المشفرة. لا تحذف `ApiKey.expiresAt` المشترك
   إلا بعد إزالة MCP والتأكد من عدم حاجة أي مستهلك باقٍ إليه.
3. حالة الإضافات وسجل التدقيق.
4. مستهلكو الاستخدام، ثم حالة الاستخدام في Postgres، ثم بنى ClickHouse.
5. حالة تشخيص البحث. يمكن للتطبيق عادةً إبقاء هذا الجدول الإضافي مع استخدام
   وقت التشغيل القديم.

لا ينفذ Prisma ملفات `rollback.sql` في المستودع تلقائيًا. عند نجاح ترحيل، انشر
عبارات الرجوع المراجعة بوصفها ترحيلًا تقدميًا جديدًا لاحقًا. لا تستخدم
`prisma migrate resolve --rolled-back` إلا لترحيل فاشل بعد عكس عباراته الجزئية
بأمان، ولا تستخدمه لإعادة كتابة تاريخ ترحيل إنتاجي ناجح. اتبع الحدود الهدامة
المفصلة في [قياس الاستخدام](/self-hosting/usage-metering) و
[التكاملات](/reference/integrations-engine) و[MCP](/self-hosting/mcp)
و[الإضافات](/use-nibleaf/add-ons) و[البحث](/self-hosting/search-ai).

## تسجيل القرار

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