دليل استكشاف أخطاء حزمة ServBay MariaDB/MySQL وإصلاحها

نظرة عامة

تُعدّ MariaDB وMySQL من أنظمة إدارة قواعد البيانات العلائقية مفتوحة المصدر الرائدة في الصناعة، وتُستخدم على نطاق واسع في تطبيقات الويب والبيئات التجارية المتنوعة. قامت ServBay بدمج عدة إصدارات من حزمة MariaDB/MySQL في نظام macOS لتقديم بيئة قاعدة بيانات محلية سهلة وفعّالة للمطورين. رغم أنها مشهورة بالاستقرار، إلا أنه من الممكن مواجهة مشاكل مثل فشل التشغيل، أو عدم القدرة على الاتصال، أو انخفاض الأداء أثناء التطوير أو التشغيل.

يهدف هذا الدليل إلى مساعدة مستخدمي ServBay في تشخيص وحل مشاكل حزمة MariaDB/MySQL الشائعة. سنغطي المشكلات الشائعة، خطوات التشخيص، والحلول المُفصّلة، مع الإشارة لمسارات وأوامر ServBay الخاصة.

ملاحظة هامة:

• قبل تنفيذ أي إجراء قد يُحدِث تغييرات على البيانات أو الإعدادات، تأكد دائمًا من عمل نسخة احتياطية لقاعدة بياناتك! تقدم ServBay ميزة النسخ الاحتياطي المدمجة ونوصي باستخدامها بانتظام.
• أمثلة المسارات والأوامر في هذا الدليل تَستخدم أرقام إصدارات محددة مثل (11.3 أو 11.5). يجب استبدالها برقم الإصدار الذي تستخدمه فعلياً في ServBay، ويمكنك الاطلاع على الإصدارات المثبتة والفعالة من داخل واجهة ServBay.
• كل مرجع لـ <username>، <database>، <your_backup.sql> هو عنصر نائب—يرجى استبداله باسم المستخدم، اسم قاعدة البيانات، أو اسم ملف النسخة الاحتياطية الخاص بك.
• تم كتابة الشرح على أساس نظام تشغيل macOS.

خطوات تشخيص أولية عامة

قبل التعمق في تحليل المشكلات المحددة، يُنصَح باتباع الخطوات الأساسية التالية:

1. تحقّق من حالة حزمة ServBay: افتح واجهة تطبيق ServBay وتأكد أن نسخة MariaDB/MySQL التي تعمل عليها "مُفعلة" و"تعمل". يمكنك أيضاً التحقق عن طريق سطر الأوامر:

   servbayctl status mariadb <version>
   # مثال: للتحقق من حالة MariaDB 11.3:
   servbayctl status mariadb 11.3

2. راجع سجلات تطبيق ServBay: أحياناً يقوم التطبيق نفسه بتسجيل الأخطاء أثناء محاولة التشغيل أو إدارة الحزم. يمكنك الاطلاع على السجلات من خلال واجهة التطبيق أو التحقق من ملف السجل الرئيسي لـ ServBay.
3. راجع سجل الأخطاء الخاص بـ MariaDB/MySQL: وهو أهم خطوة عند فشل بدء تشغيل قاعدة البيانات أو وجود أخطاء وقت التشغيل. المسار غالباً يكون:

   /Applications/ServBay/logs/mariadb/<version>/<version>.err
   # مثال: للاطلاع على آخر 50 سطر من سجل أخطاء MariaDB 11.3:
   tail -n 50 /Applications/ServBay/logs/mariadb/11.3/11.3.err

   راجع بعناية رسائل الخطأ في نهاية السجل لمعرفة سبب المشكلة بدقة.

المشاكل الشائعة والحلول

1. خطأ الاتصال: SQLSTATE[HY000] [2002] No such file or directory

يُشير هذا الخطأ عادةً إلى أن العميل (Client) غير قادر على الاتصال بخادم MariaDB/MySQL عبر ملف Unix socket. على نظام macOS، يُستخدم Unix socket كوسيلة للاتصال بين العمليات المحلية ويوفر أداء أفضل مقارنة بالاتصال عبر TCP/IP. يحدث هذا الخطأ عندما يحاول البرنامج أو أداة سطر الأوامر استخدام الـ socket ولا يعثر على المسار الصحيح للملف.

الأسباب المحتملة والحلول:

• الحزمة غير قيد التشغيل:
  • تحقق من حالة الحزمة عبر واجهة ServBay أو باستخدام الأمر أعلاه.
  • إذا لم تكن الحزمة تعمل، حاول تشغيلها: servbayctl start mariadb <version>، وراجع سجل الأخطاء (.err) لمعرفة السبب في عدم الانطلاق.
• مسار ملف الـ Socket غير صحيح:
  • المسار الذي يستخدمه العميل يختلف عن المسار المعين في إعدادات الخادم (my.cnf).
  • راجع ملف الإعدادات في /Applications/ServBay/etc/mariadb/<version>/my.cnf وابحث عن إعداد socket.
  • تأكد أن برنامجك أو أداتك مُعد للاتصال عبر المسار الصحيح للـ socket، والذي غالباً سيكون ضمن /Applications/ServBay/tmp/ أو /tmp/ مثل /Applications/ServBay/tmp/mysql.sock أو /tmp/mysql.sock حسب الإصدار والإعدادات.
• مشكلة في الإعدادات الافتراضية لـ ServBay:
  • في إعدادات ServBay، تحت "الضبط" > "خادم SQL الافتراضي"، تأكد من تحديد الإصدار الصحيح كخادم افتراضي. بعض العملاء (مثل أداة mysql بدون تعيين -S أو -h) تتصل بالافتراضي دون تحديد.
• مشكلة صلاحيات:
  • قد لا يكون للمستخدم العامِل على MariaDB/MySQL صلاحية الكتابة في مجلد ملف الـ socket، أو أن مستخدم العميل لا يمتلك إذن القراءة. على الأغلب ServBay يضبط الصلاحيات تلقائياً، ولكن إذا تم تغيير صلاحيات مجلد /Applications/ServBay/tmp/ أو /tmp/ يدوياً فقد تظهر مشاكل.

البديل (إجبار الاتصال عبر TCP/IP):

• جرب الاتصال باستخدام عنوان IP 127.0.0.1 بدلاً من localhost لإجبار الاتصال عبر TCP/IP:

  mysql -u <username> -p -h 127.0.0.1 -P 3306

2. خطأ الاتصال: يتعلق بالاتصال الشبكي (Connection refused، Can't connect to MySQL server…)

هذه الأخطاء تدل غالبًا على فشل العميل في الاتصال بحزمة MariaDB/MySQL عبر الشبكة من خلال TCP/IP.

الأسباب المحتملة والحلول:

• الحزمة ليست قيد التشغيل: (راجع أعلاه للتحقق من الحالة والسجلات)
• المنفذ مشغول:
  • تأكد أن المنفذ الذي تستمع عليه MariaDB/MySQL (افتراضياً 3306) غير مستخدم من تطبيق آخر.
  • تحقق من المنافذ:

    lsof -i :3306
    # أو
    netstat -anv | grep LISTEN | grep 3306

  • إن وجدت المنفذ مشغولاً، قم بإغلاق التطبيق المشغل أو غيّر إعداد المنفذ في my.cnf وأعد التشغيل.
• وجود جدار حماية يمنع الاتصال:
  • تحقق من إعدادات جدار الحماية في إعدادات النظام > الشبكة > جدار الحماية.
  • اسمح مؤقتاً لعملية mysqld عبر الجدار الناري. انتبه أن المسار قد يختلف مع تحديثات ServBay:

    # أمر توضيحي - عدّل المسار حسب الحاجة
    sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /Applications/ServBay/bin/mariadb/<version>/bin/mysqld
    sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblockapp /Applications/ServBay/bin/mariadb/<version>/bin/mysqld

• مشكلة إعدادات (bind-address):
  • راجع قيمة bind-address في ملف my.cnf. إذا كانت 127.0.0.1 أو localhost فالاتصال الشبكي مسموح فقط من نفس الجهاز. إن أردت السماح للأجهزة الأخرى، استخدم 0.0.0.0 أو عنوان IP محدد، وافتح المنفذ في الجدار الناري.
• مشكلة في تحليل اسم localhost:
  • تحقق أن localhost يُحلل إلى 127.0.0.1 و::1.
  • جرب الأمر ping localhost.
  • راجع ملف /etc/hosts وتأكد أنه يحوي السطر الصحيح لـ localhost.
  • أوقف أي برنامج بروكسي قد يغير توجيه الاتصالات المحلية.

3. حزمة MariaDB/MySQL لا تبدأ التشغيل

الأسباب المحتملة والحلول:

1. راجع سجل الأخطاء (الأهم!): كما سبق، اطلع على /Applications/ServBay/logs/mariadb/<version>/<version>.err لمعرفة سبب الفشل.
2. خطأ في ملف الإعدادات:
   • وجود أخطاء تركيبية أو معلمات خاطئة أو مسار غير صحيح في /Applications/ServBay/etc/mariadb/<version>/my.cnf.
   • تحقق من صحة الملف بالأمر:

     # عدّل المسار حسب ما يتطلب
     /Applications/ServBay/bin/mariadb/<version>/bin/mysqld --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf --validate-config

3. المنفذ مشغول: (راجع أعلاه)
4. عدم توفر مساحة على القرص: تحقق أن مجلد بيانات القاعدة (/Applications/ServBay/db/mariadb/<version>/) أو سجل الأخطاء فيه مساحة كافية.
5. مشكلة صلاحيات:
   • المستخدم الذي يعمل عليه MariaDB/MySQL (غالباً _mysql) لا يملك إذن القراءة أو الكتابة للإعدادات أو البيانات. تأكد من الصلاحيات:

     ls -ld /Applications/ServBay/db/mariadb/<version>
     ls -l /Applications/ServBay/etc/mariadb/<version>/my.cnf
     ls -ld /Applications/ServBay/logs/mariadb/<version>

     احرص أن المستخدم العامل يملك التصريحات المناسبة.
6. تلف ملفات البيانات: راجع قسم "التلف أو انهيار قاعدة البيانات" أدناه.

بعد حل المشكلة:

• أعد تشغيل الحزمة: servbayctl restart mariadb <version>

4. مشكلة صلاحيات المستخدم أو التوثيق

قد تظهر أخطاء (مثل Access denied) بعد الاتصال بالقاعدة بسبب اسم المستخدم أو كلمة المرور أو الصلاحيات.

الأسباب المحتملة والحلول:

• اسم المستخدم أو كلمة المرور غير صحيحين: تأكد من دقة بيانات الاعتماد. يمكنك إعادة تعيين كلمة مرور root من خلال أداة ServBay.
• تقييد الاتصال من مستضيفين محددين: المستخدم قد يكون مقيد من الاتصال إلا من localhost أو عنوان IP معين. مثلاً، '<username>'@'localhost' يختلف عن '<username>'@'127.0.0.1'. الرمز % يسمح من أي مستضيف.
• نقص الصلاحيات: قد يفتقر المستخدم لصلاحية الاتصال أو تنفيذ بعض العمليات.
• التحقق من صلاحيات المستخدم:
  • سجل دخول كمستخدم root:

    mysql -u root -p

  • في واجهة SQL:

    SHOW GRANTS FOR '<username>'@'<hostname>';
    -- مثال: لصلاحيات المستخدم 'webapp' عبر 'localhost':
    SHOW GRANTS FOR 'webapp'@'localhost';
    -- مثال لصلاحيات 'admin' من جميع المواقع:
    SHOW GRANTS FOR 'admin'@'%';

  • استخدم أوامر GRANT وREVOKE لتغيير الصلاحيات أو إضافة مستخدم جديد.

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

انخفاض أداء قاعدة البيانات يؤدي إلى بطء التطبيق.

الأسباب والحلول:

1. الاستعلامات البطيئة: الاستعلامات غير فعّالة أو بدون فهرسة، أو خطة التنفيذ غير مثالية.
   • تفعيل سجل الاستعلامات البطيئة: فعّل slow_query_log = 1 وlong_query_time = 1 (لتسجيل الاستعلامات التي تزيد عن ثانية) وحدد المسار المناسب لـ slow_query_log_file، ثم أعد تشغيل الحزمة لتحليل الاستعلامات البطيئة.
   • استخدم EXPLAIN: قبل أي استعلام كبير، استخدم:

     EXPLAIN SELECT * FROM your_table_name WHERE column_name = 'value';

   • حسّن الاستعلامات: عدّلها بناءً على نتائج EXPLAIN، وتأكد من الاستفادة من الفهارس.
2. نقص أو سوء تصميم الفهارس: التأكد من فهرسة الأعمدة المستخدمة في WHERE أو ORDER BY أو GROUP BY.
   • إنشاء فهرس:

     CREATE INDEX idx_column_name ON your_table_name(column_name);

     لاحظ أن الفهارس قد تزيد في استهلاك الموارد والمساحة، لذا استخدمها بشكل موزون.
3. إعدادات الكاش غير مناسبة: إعدادات مثل innodb_buffer_pool_size أو key_buffer_size في my.cnf قد تكون صغيرة جداً أو كبيرة جداً.
   • عدّل الإعدادات حسب ذاكرة جهازك: يوصى بأن يكون innodb_buffer_pool_size (لـ InnoDB) ما بين 50%-70% من ذاكرة النظام (إذا كان الجهاز مخصص للقاعدة)، وأعد التشغيل.

     [mysqld]
     innodb_buffer_pool_size = 2G
     # إذا كانت جداول MyISAM كثيرة:
     # key_buffer_size = 256M

4. عنق زجاجة في العتاد: راقب استهلاك المعالج والذاكرة والقرص عبر Activity Monitor أو الأوامر top/htop للعثور على المصدر.

6. انهيار القاعدة أو تلف البيانات

عند الفشل في بدء التشغيل أو التوقف المفاجئ أو وجود بيانات تالفة.

الأسباب والحلول:

1. راجع سجل الأخطاء: /Applications/ServBay/logs/mariadb/<version>/<version>.err سيظهر سبب الانهيار (مثل أخطاء InnoDB أو النظام).
2. خلل في العتاد: أعطال القرص أو الذاكرة تسبب فقدان البيانات—راجع سجلات النظام أو أداة التشخيص.
3. تعارض برمجي أو عيوب (Bug): أحياناً أخطاء في نسخ معيّنة.
4. إعدادات خاطئة في my.cnf: معلمات غير صحيحة تقود إلى عدم الاستقرار.
5. الإيقاف أو الانقطاع القسري: إنهاء العملية دون إيقاف نظامي يؤدي إلى بيانات غير متناسقة.

الحلول:

• جرب إعادة التشغيل الآمن: من نافذة التطبيق أو بالأمر servbayctl restart mariadb <version>.
• تحقق وأصلح الجداول بواسطة mysqlcheck:

  mysqlcheck --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p --check --all-databases
  # لإصلاح جداول MyISAM تلقائياً (عند الحاجة):
  # mysqlcheck --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p --auto-repair --check --all-databases

  تنبيه: --auto-repair فعال فقط مع MyISAM. مشاكل InnoDB تتطلب حلولاً متقدمة (انظر أدناه).
• استعادة InnoDB بالقوة (innodb_force_recovery): إن ظهرت أخطاء InnoDB بالملفات:
  1. خُذ نسخة احتياطية من مجلد البيانات المتضرر: انسخ /Applications/ServBay/db/mariadb/<version>/ لمكان آخر.
  2. حرر ملف الإعدادات المتعلق بـ my.cnf.
  3. أضف تحت [mysqld]: الإعداد innodb_force_recovery = N (ابدأ بـ 1 وزد تدريجياً حتى 6 حسب الحاجة).
  4. أعد تشغيل MariaDB/MySQL: servbayctl start mariadb <version>.
  5. إذا اشتغلت حتى بوضع القراءة فقط—اسحب نسخة احتياطية فورية:

     mysqldump --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p --all-databases --routines --triggers --events > /path/to/your_emergency_backup.sql

     تأكد من اكتمال نسخة الـ SQL وحجمها منطقي.
  6. أوقف القاعدة: servbayctl stop mariadb <version>
  7. أزل (أو علق) الإعداد innodb_force_recovery = N من my.cnf.
  8. ابدأ ترحيل البيانات: غالباً تحتاج تهيئة مجلد البيانات ثم الاستيراد من النسخة.
• الاستعادة من النسخ الاحتياطي: إذا استعصى الإصلاح، استرجع من أحدث نسخة متاحة (/Applications/ServBay/backup/mariadb/<version>/ عند استخدام ميزة ServBay).
  • نموذج أمر الاستعادة:

    # تأكد من إنشاء قاعدة البيانات الهدف
    # mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p -e "CREATE DATABASE <target_database_name>;"
    
    # تنفيذ الاستيراد
    mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u <username> -p <target_database_name> < /Applications/ServBay/backup/mariadb/<version>/<your_backup.sql>

    ملحوظة: استبدل <version> برقم إصدار MariaDB/MySQL المستهدف.

7. مشاكل النسخ الاحتياطي والاستعادة

خلال استخدام ميزة ServBay أو mysqldump يدوياً.

الأسباب والحلول:

• ملف النسخ الاحتياطي غير مكتمل أو تالف:
  • تحقّق من حجم الملف (ls -lh /path/to/your_backup.sql) ومراجعة محتواه بـ less أو أي محرر نصوص.
  • راجع رسائل الخطأ أثناء أمر النسخ، أو تحقق من سجل التطبيق إذا استخدمت ميزة ServBay.
• خطأ في أمر الاستعادة:
  • وضع اسم مستخدم/كلمة مرور أو اسم قاعدة خاطئ.
  • المستخدم المنفّذ عليه الأمر لا يملك الصلاحيات الكافية.
  • خطأ في بنية ملف النسخة (في حالة اختلاف نسخ أو محركات القاعدة بين المصدر والهدف).
• مشكلة قيود المفاتيح الأجنبية: تكرار أوامر الإدخال أو ترتيب الطاولات قد يسبب خللاً في العلاقات. يمكن تعطيل التحقق مؤقتاً خلال الاستيراد:

  -- قبل الاستيراد
  SET foreign_key_checks = 0;
  -- ثم نفّذ الأمر أو:
  source /path/to/your_backup.sql;
  
  -- بعد الاستيراد
  SET foreign_key_checks = 1;

  تنبيه: استخدم التعطيل فقط أثناء عملية الاستيراد لتجنب فقدان التكامل المرجعي.
• مشكلة الترميز/Collation: تأكد أن القاعدة أو الجدول المُستورد إليه يدعم نفس الترميز (يفضّل utf8mb4).

الاستعادة الصحيحة من النسخ الاحتياطي (أمر خطي نموذج):

# إذا كانت النسخة تخص قاعدة بيانات محددة، تأكد من إنشائها مسبقاً.
# mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p -e "CREATE DATABASE <target_database_name>;"

# أمر الاستيراد الصحيح إلى القاعدة الهدف:
mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u <username> -p <target_database_name> < /Applications/ServBay/backup/mariadb/<version>/<your_backup.sql>

# إذا كانت النسخة شاملة كل القواعد (--all-databases)، لا تحدد اسم القاعدة في الأمر:
# mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u <username> -p < /Applications/ServBay/backup/mariadb/<version>/<your_backup.sql>

ملاحظة: استبدل <version> برقم إصدار الحزمة المستهدفة. ServBay يُنتج نسخاً سهلة الاستعادة مع خيارات الاستعادة المناسبة.

8. خلل محدد: فشل تشغيل InnoDB في MariaDB 11.5.1 (ib_logfile0 was not found / Missing FILE_CHECKPOINT)

هذه مشكلة معروفة وخطيرة في إصدار MariaDB 11.5.1، تؤدي أحياناً إلى فشل محرك InnoDB في التهيئة أو الاستعادة من ملفات السجل، وبالتالي ينهار تشغيل قاعدة البيانات.

دلائل الخطأ في السجل:

في ملف /Applications/ServBay/logs/mariadb/11.5/11.5.err ربما تجد رسائل كالآتي:

[ERROR] InnoDB: File /Applications/ServBay/db/mariadb/11.5/ib_logfile0 was not found
[ERROR] InnoDB: Plugin initialization aborted with error Generic error
[ERROR] Plugin 'InnoDB' registration as a STORAGE ENGINE failed.
[ERROR] Unknown/unsupported storage engine: InnoDB

أو:

[ERROR] InnoDB: Missing FILE_CHECKPOINT(xxxxx) at xxxxx
[ERROR] InnoDB: Log scan aborted at LSN xxxxx
[ERROR] InnoDB: Plugin initialization aborted with error Generic error
[ERROR] Plugin 'InnoDB' registration as a STORAGE ENGINE failed.
[ERROR] Unknown/unsupported storage engine: InnoDB

هذه الرسائل توضح أن InnoDB غير قادر على العثور أو معالجة ملفات السجل، مما يؤدي لفشل التهيئة.

الحل (مهم جداً: احرص على أخذ نسخة احتياطية أولاً):

هذه مشكلة يصعب إصلاحها بالأدوات المعتادة. الأكثر أماناً هو محاولة تشغيل القاعدة بالقوة لأخذ نسخة احتياطية ثم ترحيل البيانات إلى نسخة مستقرة.

1. جرب الاستعادة الجبرية للاحتفاظ بالبيانات (خطر!):
   • حرر ملف ضبط MariaDB 11.5: /Applications/ServBay/etc/mariadb/11.5/my.cnf.
   • أضف في قسم [mysqld]: innodb_force_recovery = 6
   • جرب بدء MariaDB 11.5 عن طريق ServBay أو بالأمر: servbayctl start mariadb 11.5
   • إذا اشتغلت ولو جزئياً — أسرع بتنفيذ النسخ الاحتياطي:

     mysqldump --defaults-file=/Applications/ServBay/etc/mariadb/11.5/my.cnf -u root -p --all-databases --routines --triggers --events > /Applications/ServBay/backup/mariadb/11.5/mariadb_11.5_emergency_backup.sql

     تحقق من اكتمال النسخة وملاءمة حجمها.
2. أوقف الحزمة وتعامل مع مجلد البيانات المتضرر:
   • أوقف MariaDB 11.5: servbayctl stop mariadb 11.5
   • حرر ملف الضبط، واحذف أو علّق سطر innodb_force_recovery...