المشكلات الشائعة واستكشاف الأخطاء وإصلاحها

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

كيفية استخدام هذا الدليل

1. حدد مشكلتك من الفئات أدناه
2. اتبع خطوات استكشاف الأخطاء وإصلاحها بالترتيب
3. جرب الحلول حتى يتم حل المشكلة
4. إذا لم تحل المشكلة، استخدم قسم "الاتصال بالدعم"

مرجع سريع: المشكلات الشائعة

| المشكلة | السبب المحتمل | الحل السريع | | --------------------------- | ------------------------------------- | ----------------------------------------- | | لا يمكن الاتصال بـ PostgreSQL | الخادم لا يعمل، جدار الحماية يمنع الاتصال | شغل PostgreSQL، تحقق من إعدادات جدار الحماية | | أداء استعلام بطيء | فهارس مفقودة، مجموعات بيانات كبيرة | أضف فهارس، استخدم LIMIT، حسّن الاستعلامات | | استخدام ذاكرة عالي | علامات تبويب مفتوحة كثيرة، مجموعات نتائج كبيرة | أغلق علامات التبويب غير المستخدمة، فعّل وضع البث | | فشل التصدير | مشكلات أذونات، قرص ممتلئ | تحقق من أذونات الملفات، حرر مساحة القرص | | واجهة المستخدم تبدو بطيئة | قيود موارد النظام | أغلق التطبيقات الأخرى، أعد تشغيل HarborDB |

مشكلات الاتصال

"لا يمكن الاتصال بخادم PostgreSQL"

الأعراض:

• أخطاء مهلة الاتصال
• رسائل "تم رفض الاتصال"
• تحميل لا نهائي عند اختبار الاتصال

استكشاف الأخطاء وإصلاحها خطوة بخطوة:

1. تحقق من حالة خادم PostgreSQL:

   # في Terminal، تحقق مما إذا كان PostgreSQL يعمل
   pg_isready -h localhost -p 5432
   

   • إذا لم يكن يعمل: brew services start postgresql (Homebrew) أو ابدأ عبر تفضيلات النظام

2. تحقق من تفاصيل الاتصال:

   • اسم المضيف: localhost للمحلي، عنوان IP/اسم مضيف صحيح للبعيد
   • المنفذ: الافتراضي هو 5432، أكد منفذ PostgreSQL الخاص بك
   • اسم قاعدة البيانات: يجب أن تكون موجودة قبل الاتصال
   • اسم المستخدم/كلمة المرور: حساسة لحالة الأحرف، تحقق من بيانات الاعتماد

3. تحقق من إعدادات جدار الحماية:

   • تفضيلات النظام → الأمان والخصوصية → جدار الحماية
   • تأكد من السماح بمنفذ PostgreSQL (5432)
   • جرب تعطيل جدار الحماية مؤقتًا للاختبار

4. اختبر اتصال الشبكة:

   # للخوادم البعيدة
   ping your-server-address
   telnet your-server-address 5432
   

الحلول الشائعة:

• ✅ شغل خدمة PostgreSQL
• ✅ صحح اسم المضيف/عنوان IP
• ✅ افتح منفذ جدار الحماية 5432
• ✅ استخدم بيانات اعتماد صحيحة

"فشلت مصادقة كلمة المرور"

الأسباب:

• اسم مستخدم أو كلمة مرور غير صحيحة
• عدم تطابق طريقة مصادقة PostgreSQL
• المستخدم يفتقر إلى أذونات قاعدة البيانات

الحلول:

1. أعد تعيين كلمة مرور PostgreSQL:

   -- اتصل كمستخدم فائق (عبر سطر الأوامر)
   ALTER USER username WITH PASSWORD 'new_password';
   

2. تحقق من طريقة المصادقة:

   • اعرض ملف pg_hba.conf
   • الطرق الشائعة: md5, scram-sha-256, trust
   • حدّث الطريقة إذا لزم الأمر، أعد تشغيل PostgreSQL

3. تحقق من أذونات المستخدم:

   -- اذكر المستخدمين والأذونات
   \du
   
   -- اذكر قواعد البيانات والوصول
   \l
   

أخطاء اتصال SSL/TLS

عند الاتصال بالخوادم البعيدة:

1. تحقق من متطلبات SSL:

   • قد يتطلب الخادم وضع SSL محددًا
   • قد يحتاج إلى استيراد شهادة

2. جرب أوضاع SSL مختلفة في HarborDB:

   • ابدأ بـ prefer
   • ثم جرب require
   • أخيرًا verify-full (يتطلب شهادة)

3. استورد الشهادات إذا كنت تستخدم verify-full:

   • احصل على الشهادة من مسؤول الخادم
   • استورد إلى Keychain Access في macOS
   • امنح HarborDB الوصول إلى الشهادة

مشكلات الأداء

تنفيذ استعلام بطيء

خطوات التشخيص:

1. استخدم EXPLAIN للتحليل:

   • انقر على زر "Explain" (⚡) في HarborDB
   • ابحث عن "Seq Scan" (فحص جدولي كامل) - غالبًا ما يكون بطيئًا
   • ابحث عن "Index Scan" - عادة أسرع

2. تحقق من الفهارس المفقودة:

   -- ابحث عن الأعمدة التي يتم تصفيتها بشكل متكرر بدون فهارس
   SELECT schemaname, tablename, attname
   FROM pg_stats
   WHERE schemaname NOT LIKE 'pg_%'
     AND n_distinct > 100
     AND attname NOT IN (
       SELECT column_name
       FROM information_schema.columns
       WHERE table_schema = schemaname
         AND table_name = tablename
     );
   

3. أضف فهارس مناسبة:

   -- فهرس عمود واحد
   CREATE INDEX idx_table_column ON table_name(column_name);
   
   -- فهرس متعدد الأعمدة لأنماط الاستعلام الشائعة
   CREATE INDEX idx_table_col1_col2 ON table_name(col1, col2);
   

إصلاحات الأداء السريعة:

• أضف بند LIMIT للاستعلامات الاستكشافية
• اختر الأعمدة المطلوبة فقط (ليس SELECT *)
• استخدم بنود WHERE مع الأعمدة المفهرسة
• تجنب الدوال في بنود WHERE التي تمنع استخدام الفهرس

استخدام ذاكرة عالي

الأعراض:

• يستخدم HarborDB ذاكرة وصول عشوائي (RAM) مفرطة (تحقق من مراقب النشاط)
• يصبح النظام بطيئًا
• أخطاء "نفاد الذاكرة"

الحلول:

1. قلل حجم ذاكرة التخزين المؤقت للاستعلامات:

   • التفضيلات → الأداء → ذاكرة التخزين المؤقت للاستعلامات
   • قلل من 256 ميجابايت الافتراضية إلى 128 ميجابايت إذا كانت الذاكرة محدودة

2. فعّل وضع البث:

   • التفضيلات → الأداء → نتائج البث
   • فعّل للنتائج > 10,000 صف
   • يقلل استخدام الذاكرة لمجموعات البيانات الكبيرة

3. إدارة علامات التبويب المفتوحة:

   • أغلق علامات تبويب الاستعلام غير المستخدمة
   • يحتفظ HarborDB بمجموعات النتائج في الذاكرة لكل علامة تبويب
   • العمل العادي: 5-10 علامات تبويب كحد أقصى

4. أعد تشغيل HarborDB:

   • أغلق وأعد التشغيل يوميًا أثناء الاستخدام المكثف
   • يزيل استخدام الذاكرة المتراكم

التطبيق يشعر بالبطء

إصلاحات سريعة:

1. أغلق التطبيقات الأخرى:

   • خاصة التطبيقات كثيفة الاستخدام للموارد (Chrome مع علامات تبويب كثيرة، Docker، إلخ.)
   • تحقق من مراقب النشاط لضغط الذاكرة

2. قلل الرسوم المتحركة لواجهة المستخدم:

   • التفضيلات → المظهر → عطّل الرسوم المتحركة
   • تجربة أكثر سلاسة على الأجهزة القديمة

3. بسّط الواجهة:

   • طيّ أقسام الشريط الجانبي غير المستخدمة
   • استخدم سمة لون أبسط
   • عطّل تمييز الصيغة للاستعلامات الكبيرة جدًا

مشكلات التصدير والملفات

فشل التصدير أو إنشاء ملفات فارغة

الأسباب والحلول الشائعة:

1. مشكلات الأذونات:

   # تحقق من أذونات المجلد
   ls -la ~/Desktop/
   
   # جرب موقع حفظ مختلف
   # استخدم مجلد المستندات بدلاً من سطح المكتب
   

2. مشكلات مساحة القرص:

   # تحقق من مساحة القرص المتاحة
   df -h
   
   # تحتاج إلى مساحة حرة على الأقل ضعف حجم التصدير
   

3. مشكلات تنسيق الملف:

   • CSV: جرب محددًا مختلفًا (فاصلة، فاصلة منقوطة، تبويب)
   • CSV: أضف مؤهلات نصية (علامات اقتباس حول الحقول)
   • JSON: جرب كلا التنسيقين "Pretty" و "Compact"

4. تحسين التصدير الكبير:

   • صدر على دفعات أصغر
   • استخدم CSV بدلاً من JSON لمجموعات البيانات الكبيرة
   • فعّل الضغط في إعدادات التصدير

"ملف غير موجود" أو تصديرات مفقودة

1. تحقق من موقع الحفظ الافتراضي:

   • التفضيلات → التصدير → موقع الحفظ الافتراضي
   • غيّر إلى مجلد يتم الوصول إليه بشكل متكرر

2. ابحث عن الملفات:

   # ابحث عن ملفات CSV/JSON حديثة
   find ~ -name "*.csv" -mtime -1
   find ~ -name "*.json" -mtime -1
   

3. تحقق من سلة المهملات:

   • ربما تم حذف التصديرات عن طريق الخطأ
   • استرجع من سلة المهملات إذا وجدت

مشكلات الواجهة والعرض

عدم تطبيق السمة بشكل صحيح

مشكلات الوضع الداكن/الفاتح في macOS:

1. تحقق من إعدادات النظام:

   • تفضيلات النظام → المظهر
   • تأكد من اختيار "تلقائي" أو السمة المطلوبة

2. أعد تشغيل HarborDB:

   • أغلق تمامًا (⌘ + Q)
   • أعد الفتح لتطبيق سمة النظام

3. فرض السمة في HarborDB:

   • التفضيلات → المظهر → السمة
   • اختر "فاتح"، "داكن"، أو "النظام"

ميزات أو قوائم مفقودة

1. حدّث HarborDB:

   • تحقق من وجود تحديثات (HarborDB → تحقق من وجود تحديثات)
   • متجر التطبيقات → علامة تبويب التحديثات

2. أعد تعيين تخطيط الواجهة:

   • نافذة → إعادة تعيين التخطيط
   • يعيد ترتيب الألواح الافتراضي

3. تحقق من توفر الميزة:

   • تتطلب بعض الميزات إصدارات محددة من PostgreSQL
   • تحقق من التوافق في وثائق الميزة

مشكلات عرض النص

مشكلات حجم الخط/إمكانية القراءة:

1. اضبط حجم خط المحرر:

   • التفضيلات → المحرر → حجم الخط
   • زِد لتحسين إمكانية القراءة

2. استخدم تكبير macOS:

   • تفضيلات النظام → إمكانية الوصول → التكبير
   • فعّل للتكبير المؤقت

3. وضع التباين العالي:

   • تفضيلات النظام → إمكانية الوصول → العرض
   • زِد التباين لتحسين الرؤية

مشكلات خاصة بنظام macOS

خطأ "التطبيق تالف"

عند فتح HarborDB:

# أزل سمة الحجر الصحي
sudo xattr -cr /Applications/HarborDB.app

# أعد فتح HarborDB
open /Applications/HarborDB.app

تحذيرات Gatekeeper

للتنزيلات المباشرة (ليس متجر التطبيقات):

1. تفضيلات النظام → الخصوصية والأمان
2. انتقل إلى قسم "الأمان"
3. انقر على "فتح على أي حال" بجانب تحذير HarborDB
4. أكد الفتح

مشكلات Touch ID/الوصول إلى سلسلة المفاتيح

أخطاء "يريد HarborDB استخدام كلمة المرور الخاصة بك":

1. أعد تعيين أذونات سلسلة المفاتيح:

   • افتح تطبيق Keychain Access
   • ابحث عن "HarborDB"
   • احذف الإدخالات الموجودة
   • أعد إضافة الاتصال في HarborDB

2. أصلح سلسلة المفاتيح:

   • Keychain Access → ملف → Keychain First Aid
   • شغّل الإصلاح على سلسلة المفاتيح "Login"

التوافق مع إصدارات macOS

الحد الأدنى: macOS 12.0 (Monterey) الموصى به: macOS 13.0 (Ventura) أو أحدث

تحقق من التوافق:

# تحقق من إصدار macOS
sw_vers

# تحقق من البنية (Apple Silicon مقابل Intel)
uname -m

مشكلات خاصة بقاعدة البيانات

"العلاقة غير موجودة"

عند الاستعلام عن الجداول:

1. تحقق من المخطط:

   -- اذكر جميع الجداول في المخطط الحالي
   \dt
   
   -- اذكر الجداول في جميع المخططات
   SELECT schemaname, tablename
   FROM pg_tables
   WHERE tablename LIKE '%your_table%';
   

2. استخدم أسماء مؤهلة:

   -- بدلاً من: SELECT * FROM users;
   -- استخدم تأهيل المخطط:
   SELECT * FROM public.users;
   SELECT * FROM auth.users;
   

3. عيّن المخطط الافتراضي:

   • حرر الاتصال في HarborDB
   • عيّن "المخطط الافتراضي" إلى المخطط المستخدم بشكل شائع

أخطاء الأذونات على كائنات قاعدة البيانات

رفض الإذن للعلاقة

1. تحقق من أذوناتك:

   -- اتصل كمستخدم فائق أو مالك الجدول
   SELECT grantee, privilege_type
   FROM information_schema.role_table_grants
   WHERE table_name = 'your_table';
   

2. اطلب الأذونات:

   -- مثال: منح إذن SELECT
   GRANT SELECT ON table_name TO your_username;
   

التعامل مع مجموعات البيانات الكبيرة

"نفاد الذاكرة" أو بطيء جدًا:

1. استخدم ترقيم الصفحات من جانب الخادم:

   -- بدلاً من: SELECT * FROM huge_table;
   -- استخدم:
   SELECT * FROM huge_table LIMIT 1000 OFFSET 0;
   -- ثم زِد OFFSET للصفحات التالية
   

2. فعّل البث في HarborDB:

   • التفضيلات → الأداء → وضع البث
   • عيّن العتبة (مثلاً، 10,000 صف)

3. استخدم مناظير مادية للاستعلامات المعقدة المتكررة

مشكلات الشبكة والاتصال البعيد

اتصالات بعيدة بطيئة

نصائح التحسين:

1. فعّل الضغط:

   • إعدادات الاتصال → متقدم → الضغط
   • يقلل حجم نقل البيانات

2. استخدم نفق SSH:

   • أكثر أمانًا من الاتصال المباشر
   • يمكن أن يحسن الأداء على الشبكات المقيدة

3. جدول الاستعلامات الثقيلة:

   • شغّل خلال ساعات غير الذروة
   • استخدم ميزة مجدول الاستعلامات في HarborDB

انقطاع الاتصال المتقطع

1. زِد إعدادات المهلة:

   • إعدادات الاتصال → المهلة
   • زِد من 30 إلى 60 ثانية

2. فعّل Keep-Alive:

   • إعدادات الاتصال → Keep-Alive
   • يحافظ على الاتصالات الخاملة

3. تحقق من استقرار الشبكة:

   # اختبر استقرار الشبكة
   ping -c 100 your-server-address
   # ابحث عن فقدان الحزم
   

قبل الاتصال بالدعم

المعلومات التي يجب جمعها

إذا استمرت المشكلات بعد استكشاف الأخطاء وإصلاحها، اجمع هذه المعلومات:

1. معلومات النظام:

   • إصدار macOS (قائمة Apple → حول هذا Mac)
   • إصدار HarborDB (HarborDB → حول HarborDB)
   • إصدار PostgreSQL (SELECT version();)

2. تفاصيل الخطأ:

   • رسالة الخطأ الدقيقة (لقطة شاشة إذا أمكن)
   • خطوات إعادة إنتاج المشكلة
   • متى بدأت المشكلة

3. تفاصيل التكوين:

   • إعدادات الاتصال (بدون كلمات المرور)
   • الاستعلام الذي يسبب المشكلات (إذا كان مناسبًا)
   • إعدادات التصدير (إذا كانت متعلقة بالتصدير)

أدوات التشخيص في HarborDB

1. أنشئ تقرير تشخيص:

   • مساعدة → إنشاء تقرير تشخيص
   • يتضمن السجلات، التكوين، معلومات النظام

2. اعرض سجلات التطبيق:

   • مساعدة → اعرض السجلات
   • صفّ حسب رسائل الخطأ والتحذير

3. Console.app لسجلات النظام:

   • افتح Console.app
   • ابحث عن "HarborDB"
   • ابحث عن تقارير التعطل

فحص ذاتي سريع

قبل الاتصال بالدعم، تحقق من:

• [ ] macOS محدث
• [ ] HarborDB هو أحدث إصدار
• [ ] خادم PostgreSQL يعمل
• [ ] اتصال الشبكة مستقر
• [ ] مساحة قرص كافية متاحة
• [ ] المستخدم لديه الأذونات اللازمة

الاتصال بالدعم

إذا جربت جميع خطوات استكشاف الأخطاء وإصلاحها واستمرت المشكلة:

1. دعم البريد الإلكتروني: support@harbordb.com

2. تضمّن في بريدك الإلكتروني:

   • تقرير تشخيص (من قائمة المساعدة)
   • لقطات شاشة لرسائل الخطأ
   • خطوات إعادة إنتاج المشكلة
   • خطوات استكشاف الأخطاء وإصلاحها التي جربتها

3. وقت الاستجابة المتوقع:

   • رد أولي: خلال 24-48 ساعة
   • ساعات العمل: الاثنين-الجمعة، 9 صباحًا-5 مساءً بالتوقيت الشرقي
   • مشكلات طارئة: علّم البريد الإلكتروني بـ "عاجل"

إجراءات وقائية

الصيانة المنتظمة

أسبوعيًا:

• أعد تشغيل HarborDB لمسح الذاكرة
• امسح ملفات التصدير المؤقتة
• احفظ نسخة احتياطية لإعدادات الاتصال المهمة

شهريًا:

• حدّث HarborDB وPostgreSQL
• راجع وحسّن الاستعلامات البطيئة
• نظّف الاتصالات غير المستخدمة

أفضل الممارسات لتجنب المشكلات

1. إدارة الاتصال:

   • استخدم أسماء اتصالات ذات معنى
   • اختبر الاتصالات بانتظام
   • أزل الاتصالات غير المستخدمة

2. تطوير الاستعلامات:

   • استخدم LIMIT دائمًا أثناء الاستكشاف
   • اختبر بـ EXPLAIN قبل تشغيل الاستعلامات الكبيرة
   • احفظ الاستعلامات المعقدة لإعادة الاستخدام

3. صيانة النظام:

   • حافظ على تحديث macOS
   • نسخ احتياطي منتظم لـ Time Machine
   • راقب مساحة القرص

موارد إضافية

• أسئلة وأجوبة HarborDB - إجابات للأسئلة الشائعة
• دليل البدء - التثبيت والإعداد
• تحسين الأداء - ضبط متقدم
• دليل أمان macOS - أفضل ممارسات الأمان