> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# كيفية التعافي من لقطة Keeper تالفة

> مقالة تشرح كيفية التعافي من لقطة Keeper تالفة: كيف تتجلى المشكلة، وما هي اللقطة وأين يمكن العثور عليها، وما هي استراتيجيات التعافي الممكنة.

يمكن أن تتسبب لقطات ClickHouse Keeper التالفة أو غير الصالحة في حدوث قدر كبير من عدم استقرار النظام، مثل عدم اتساق البيانات الوصفية، أو تحول الجداول إلى حالة read-only، أو استنزاف الموارد، أو فشل النسخ الاحتياطية. تتناول هذه المقالة ما يلي:

* [ما هي اللقطات وأين يمكن العثور عليها](#overview)
* [كيف تتجلى المشكلة](#symptoms)
* [استراتيجيات التعافي الممكنة](#recovery-strategies) وما الذي تعنيه كل منها

<div id="overview">
  ## لمحة عامة عن لقطات Keeper
</div>

<div id="what-is-snapshot">
  ### ما هي اللقطة؟
</div>

اللقطة هي حالة مُسلسلة لبيانات Keeper الداخلية (مثل البيانات الوصفية الخاصة بالمجموعات العنقودية، ومسارات تنسيق الجداول، والتهيئات) في نقطة زمنية محددة. وتُعد اللقطات بالغة الأهمية لإعادة مزامنة عُقد Keeper داخل المجموعة العنقودية، واستعادة البيانات الوصفية أثناء حالات الفشل، ولدعم عمليات بدء التشغيل أو إعادة التشغيل التي تعتمد على حالة سليمة ومعروفة لـ Keeper.

<div id="where-to-find-snapshots">
  ### أين يمكنني العثور على اللقطات؟
</div>

تُخزَّن اللقطات كملفات على نظام الملفات المحلي لعُقد Keeper. افتراضيًا، تُحفَظ في `/var/lib/clickhouse/coordination/snapshots/`، أو في المسار المخصّص الذي تحدّده `snapshot_storage_path` في ملف `keeper_server.xml`. وتُسمّى اللقطات بأرقام متزايدة (على سبيل المثال: snapshot.23)، بحيث تحمل اللقطات الأحدث أرقامًا أكبر.

في المجموعات متعددة العُقد، تكون لكل عقدة Keeper دليل لقطات خاص بها.

<Note>
  يُعدّ اتساق اللقطات بين العُقد أمرًا بالغ الأهمية للتعافي.
</Note>

<div id="symptoms">
  ## الأعراض والمظاهر الرئيسية لتلف لقطات Keeper
</div>

يوضح الجدول أدناه بعض الأعراض والمظاهر الشائعة لتلف لقطات Keeper:

| **الفئة**                      | **نوع المشكلة**      | **ما الذي يجب البحث عنه**                                                                         |
| ------------------------------ | -------------------- | ------------------------------------------------------------------------------------------------- |
| **مشكلات تشغيلية**             | وضع القراءة فقط      | تتحول الجداول بشكل غير متوقع إلى وضع القراءة فقط                                                  |
|                                | فشل الاستعلامات      | فشل متكرر في الاستعلامات مع أخطاء `Coordination::Exception`                                       |
| **تلف البيانات الوصفية**       | بيانات وصفية قديمة   | لا تنعكس الجداول المحذوفة؛ وفشل في العمليات بسبب بيانات وصفية قديمة                               |
| **زيادة الحمل على الموارد**    | استنفاد موارد النظام | تستهلك عُقد Keeper قدرًا مفرطًا من CPU أو الذاكرة أو مساحة القرص؛ مع احتمال حدوث انقطاع في الخدمة |
|                                | امتلاء القرص         | امتلاء القرص أثناء إنشاء اللقطة                                                                   |
| **النسخ الاحتياطي والاستعادة** | فشل النسخ الاحتياطي  | تفشل النسخ الاحتياطية بسبب بيانات وصفية مفقودة أو غير متسقة في Keeper                             |
| **إنشاء اللقطات/نقلها**        | تعطل Keeper          | يتعطل Keeper أثناء إنشاء اللقطة (ابحث عن أخطاء "SEGFAULT")                                        |
|                                | تلف نقل اللقطة       | حدوث تلف أثناء نقل اللقطة بين النسخ المتماثلة                                                     |
|                                | حالة سباق            | حالة سباق أثناء ضغط السجل - وصول خيط commit في الخلفية إلى سجلات محذوفة                           |
|                                | مزامنة الشبكة        | مشكلات في الشبكة تمنع مزامنة اللقطة من العقدة القائدة إلى العقد التابعة                           |

**مؤشرات السجل:**

قبل تشخيص تلف اللقطة، تحقق من **سجلات Keeper** بحثًا عن أنماط أخطاء محددة:

| **نوع السجل**            | **ما الذي يجب البحث عنه**                                                                                                                                                                                                                                                                                                                  |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **أخطاء تلف اللقطة**     | • `Aborting because of failure to load from latest snapshot with index`<br />• `Failure to load from latest snapshot with index {}: {}. Manual intervention is necessary for recovery`<br />• `Failed to preprocess stored log at index {}, aborting to avoid inconsistent state`<br />• فشل في تسلسل اللقطات أو تحميلها أثناء بدء التشغيل |
| **مشكلات Keeper الأخرى** | • `Coordination::Exception`<br />• `Zookeeper::Session Timeout`<br />• مشكلات في المزامنة أو الانتخاب<br />• حالات سباق أثناء ضغط السجل                                                                                                                                                                                                    |

<div id="recovery-strategies">
  ## التعافي من لقطات Keeper التالفة
</div>

قبل التعامل مع أي ملفات، احرص دائمًا على ما يلي:

1. أوقف جميع عُقد Keeper لمنع تفاقم التلف
2. أنشئ نسخة احتياطية من كل شيء عبر نسخ دليل التنسيق بالكامل إلى موقع آمن
3. تحقّق من نصاب العنقود للتأكد من أن عقدة واحدة على الأقل تحتوي على بيانات سليمة

***

<div id="restore-from-existing-backup">
  ### 1. الاستعادة من نسخة احتياطية موجودة
</div>

ينبغي اتباع هذه العملية إذا:

* كان تلف البيانات الوصفية أو اللقطات في Keeper يجعل البيانات الحالية غير قابلة للاستعادة.
* كانت هناك نسخة احتياطية تتضمن حالة سليمة ومعروفة لـ Keeper.

اتبع الخطوات التالية لاستعادة نسخة احتياطية موجودة:

1. حدِّد أحدث نسخة احتياطية وتحقّق من اتساق البيانات الوصفية فيها.
2. أوقف خدمتي ClickHouse وKeeper.
3. استبدل اللقطات والسجلات التالفة بتلك الموجودة في دليل النسخة الاحتياطية.
4. أعد تشغيل عنقود Keeper وتحقّق من مزامنة البيانات الوصفية.

<Tip>
  **أنشئ نسخًا احتياطية بانتظام**

  إذا كانت النسخ الاحتياطية قديمة، فقد تفقد بعض التغييرات الأخيرة في البيانات الوصفية. لذلك، نوصي بإنشاء نسخ احتياطية بانتظام.
</Tip>

***

<div id="rollback-to-older-snapshot">
  ### 2. التراجع إلى لقطة أقدم
</div>

يجب اتباع هذه العملية في الحالات التالية:

* تكون اللقطات الحديثة تالفة، بينما تظل اللقطات الأقدم قابلة للاستخدام.
* تكون السجلات التزايدية سليمة، بما يتيح استردادًا متسقًا.

اتبع الخطوات التالية للتراجع إلى لقطة أقدم:

1. حدِّد واختر لقطة أقدم صالحة (مثلًا، snapshot.19) من دليل Keeper.
2. أزل اللقطات والسجلات الأحدث.
3. أعد تشغيل Keeper لكي يعيد تطبيق السجلات ويُعيد بناء حالة البيانات الوصفية.

<Warning>
  **خطر عدم تزامن البيانات الوصفية**

  هناك خطر بحدوث عدم تزامن في البيانات الوصفية إذا كانت اللقطات والسجلات مفقودة أو غير مكتملة.
</Warning>

***

<div id="restore-metadata-with-system-restore-replica">
  ### 3. استعادة البيانات الوصفية باستخدام `SYSTEM RESTORE REPLICA`
</div>

يُوصى باتباع هذه العملية في الحالات التالية:

* عند فقدان البيانات الوصفية في Keeper أو تلفها، مع بقاء بيانات الجدول موجودة على القرص
* عند انتقال الجداول إلى وضع القراءة فقط بسبب فقدان البيانات الوصفية في ZooKeeper/Keeper
* عندما تحتاج إلى إعادة إنشاء البيانات الوصفية في Keeper استنادًا إلى أجزاء البيانات المتوفرة محليًا

اتبع الخطوات التالية لاستعادة البيانات الوصفية:

1. تحقّق من وجود بيانات الجدول محليًا في مسار بيانات clickHouse-server، والمحدَّد بواسطة `<path>` في config. (المسار الافتراضي هو `/var/lib/clickhouse/data/`)

2. لكل جدول متأثر، نفّذ:

```sql theme={null}
SYSTEM RESTART REPLICA [db.]table_name;
SYSTEM RESTORE REPLICA [db.]table_name;
```

3. للاسترداد على مستوى قاعدة البيانات (إذا كنت تستخدم محرك قاعدة البيانات Replicated):

```sql theme={null}
SYSTEM RESTORE DATABASE REPLICA db_name;
```

4. انتظر حتى يكتمل التزامن:

```sql theme={null}
SYSTEM SYNC REPLICA [db.]table_name;
```

5. تحقّق من نجاح الاستعادة عبر فحص `system.replicas` للتأكد من أن `is_readonly = 0`، ومراقبة `system.detached_parts`

<Info>
  **كيف يعمل**

  يقوم `SYSTEM RESTORE REPLICA` بفصل جميع الأجزاء الحالية، وإعادة إنشاء البيانات الوصفية في Keeper (كما لو كان جدولًا فارغًا جديدًا)، ثم يعيد إرفاق جميع الأجزاء. وهذا يجنّب إعادة تنزيل البيانات عبر الشبكة.
</Info>

<Warning>
  **المتطلبات الأساسية**

  لا ينجح هذا إلا إذا كانت أجزاء البيانات المحلية سليمة. وإذا كانت البيانات تالفة أيضًا، فاستخدم الاستراتيجية رقم 5 (إعادة بناء العنقود) بدلًا من ذلك.
</Warning>

***

<div id="drop-and-recreate-replica-metadata">
  ### 4. حذف بيانات تعريف النسخة المتماثلة في Keeper وإعادة إنشائها
</div>

يجب اتباع هذه العملية في الحالات التالية:

* إذا كان الخطأ يحدث في نسخة متماثلة واحدة من العنقود وكانت بيانات التعريف الخاصة بها في Keeper تالفة أو غير متسقة
* إذا واجهت أخطاء مثل "Part XXXXX intersects previous part YYYYY"
* إذا كنت بحاجة إلى إعادة تعيين بيانات تعريف النسخة المتماثلة في Keeper بالكامل مع الحفاظ على البيانات المحلية

اتبع الخطوات التالية لحذف بيانات التعريف وإعادة إنشائها:

1. على النسخة المتماثلة المتأثرة، افصل الجدول:

```sql theme={null}
DETACH TABLE [db.]table_name;
```

2. أزل البيانات الوصفية للنسخة المتماثلة من Keeper (نفّذ ذلك على أي نسخة متماثلة):

```sql theme={null}
SYSTEM DROP REPLICA 'replica_name' FROM ZKPATH '/clickhouse/tables/{shard}/table_name';
```

للعثور على مسار ZooKeeper الصحيح:

```sql theme={null}
SELECT zookeeper_path, replica_name FROM system.replicas WHERE table = 'table_name';
```

3. أعِد إرفاق الجدول (سيكون في وضع القراءة فقط):

```sql theme={null}
ATTACH TABLE [db.]table_name;
```

4. استعِد البيانات الوصفية للنسخة المتماثلة:

```sql theme={null}
SYSTEM RESTORE REPLICA [db.]table_name;
```

5. زامِن مع النسخ المتماثلة الأخرى:

```sql theme={null}
SYSTEM SYNC REPLICA [db.]table_name;
```

6. تحقّق من `system.detached_parts` على جميع النسخ المتماثلة بعد الاستعادة

<Warning>
  **نفّذ ذلك على جميع النسخ المتماثلة المتأثرة**

  إذا كان التلف يؤثر في عدة نسخ متماثلة، فكرّر هذه الخطوات على كل واحدة منها بالتتابع.
</Warning>

<Tip>
  **لقاعدة البيانات بالكامل**

  إذا كنت تستخدم قاعدة بيانات Replicated، فيمكنك استخدام `SYSTEM DROP REPLICA ... FROM DATABASE db_name` بدلًا من ذلك.
</Tip>

**بديل: استخدام علامة force\_restore\_data**

للاستعادة التلقائية لجميع الجداول المتماثلة عند بدء تشغيل الخادم:

1. أوقِف خادم ClickHouse
2. أنشئ علامة الاستعادة:

```bash theme={null}
sudo -u clickhouse touch /var/lib/clickhouse/flags/force_restore_data
```

3. شغّل خادم ClickHouse
4. سيحذف الخادم العلامة تلقائيًا ويستعيد جميع الجداول المُكرَّرة
5. راقب السجلات لمتابعة تقدّم التعافي

يفيد هذا النهج عندما تحتاج عدة جداول إلى الاستعادة في الوقت نفسه.

***

<div id="rebuild-keeper-cluster">
  ### 5. إعادة بناء مجموعة Keeper
</div>

يجب اتباع هذه العملية في الحالات التالية:

* عدم توفر أي لقطات أو سجلات أو نسخ احتياطية صالحة للاسترداد.
* الحاجة إلى إعادة إنشاء مجموعة Keeper بالكامل وبياناتها الوصفية.

اتبع الخطوات التالية لإعادة بناء مجموعة Keeper:

1. أوقف مجموعتَي ClickHouse وKeeper بالكامل.
2. أعد ضبط كل عقدة في Keeper بتنظيف أدلة اللقطات والسجلات.
3. هيّئ عقدة واحدة في Keeper لتكون leader، ثم أضف العقد الأخرى بالتدريج.
4. أعد استيراد البيانات الوصفية إذا كانت متاحة من سجلات خارجية.

<Warning>
  **عملية تستغرق وقتًا طويلًا**

  هذه العملية تستغرق وقتًا طويلًا وتنطوي على خطر انقطاع ممتد. يلزم إعادة بناء البيانات بالكامل.
</Warning>