Panduan Penyelesaian Masalah Pakej ServBay MariaDB/MySQL

Pengenalan

MariaDB dan MySQL merupakan sistem pengurusan pangkalan data hubungan sumber terbuka yang terkenal dan digunakan secara meluas dalam aplikasi web serta pelbagai persekitaran perniagaan. ServBay menyepadukan pelbagai versi pakej MariaDB/MySQL pada macOS, memberikan pengalaman pembangunan pangkalan data setempat yang mudah dan efisien untuk para pembangun. Walaupun stabill, kadang-kala anda mungkin menghadapi masalah seperti pakej gagal dimulakan, kegagalan sambungan atau prestasi yang menurun semasa pembangunan dan operasi.

Panduan ini bertujuan membantu pengguna ServBay untuk mendiagnos dan menyelesaikan masalah biasa berkaitan pakej MariaDB/MySQL. Kami akan merangkumi isu lazim, langkah diagnostik, serta penyelesaian khusus, termasuk laluan dan arahan khas bagi persekitaran ServBay.

Notis Penting:

• Sebelum melakukan apa-apa perubahan yang mungkin menjejaskan data atau konfigurasi, pastikan anda backup pangkalan data anda! ServBay menyediakan fungsi sandaran terbina dan sangat disarankan untuk menggunakannya secara berkala.
• Contoh arahan dan laluan dalam dokumen ini menggunakan nombor versi spesifik (cth, 11.3 atau 11.5). Sila gantikan dengan versi MariaDB/MySQL sebenar yang anda gunakan dalam ServBay, yang boleh disemak pada antara muka aplikasi ServBay.
• Dalam contoh arahan, <username>, <database>, <your_backup.sql> dan sebagainya adalah penentu tempat – tukarkan kepada nilai sebenar anda.
• Panduan ini berasaskan sistem operasi macOS.

Langkah Diagnostik Asas Umum

Sebelum meneliti isu secara terperinci, disyorkan menjalankan semakan asas berikut:

1. Semak Status Pakej ServBay: Buka antara muka aplikasi ServBay dan pastikan versi MariaDB/MySQL yang anda ingin gunakan telah diaktifkan serta berstatus "Sedang Berjalan". Anda juga boleh menggunakan baris perintah:

   servbayctl status mariadb <version>
   # Contoh, untuk semak status MariaDB 11.3:
   servbayctl status mariadb 11.3

2. Semak Log Aplikasi ServBay: Kadang-kadang, aplikasi ServBay akan merekodkan ralat semasa memulakan atau mengurus pakej. Semak kawasan log dalam antara muka aplikasi atau fail log utama ServBay.
3. Periksa Log Ralat MariaDB/MySQL: Langkah paling penting untuk mengenal pasti punca masalah permulaan atau ralat operasi. Laluan log biasanya:

   /Applications/ServBay/logs/mariadb/<version>/<version>.err
   # Contoh, papar 50 baris terakhir log ralat MariaDB 11.3:
   tail -n 50 /Applications/ServBay/logs/mariadb/11.3/11.3.err

   Teliti mesej ralat di penghujung log - ia biasanya terang-terangan menyatakan puncanya.

Masalah Biasa & Penyelesaiannya

1. Ralat Sambungan: SQLSTATE[HY000] [2002] No such file or directory

Ralat ini kebiasaannya bermaksud klien tidak dapat berhubung ke pelayan MariaDB/MySQL melalui fail Unix socket. Di macOS, Unix socket ialah kaedah komunikasi antara proses setempat yang lebih pantas berbanding TCP/IP. Jika aplikasi atau alat baris perintah cuba guna sambungan socket tapi tidak menjumpai fail laluan socket tersebut, ralat ini akan terjadi.

Punca Mungkin & Penyelesaian:

• Pakej MariaDB/MySQL Tidak Berjalan:
  • Semak status melalui antara muka ServBay atau servbayctl status mariadb <version>.
  • Jika tidak berjalan, mula pakej: servbayctl start mariadb <version> dan semak log ralat (.err) untuk mengetahui punca kegagalan.
• Laluan Fail Socket Salah:
  • Laluan socket klien tidak sepadan dengan yang ditetapkan dalam konfigurasi pelayan (my.cnf).
  • Semak parameter socket dalam fail konfigurasi MariaDB/MySQL (/Applications/ServBay/etc/mariadb/<version>/my.cnf).
  • Pastikan aplikasi atau klien sambungan anda menggunakan laluan socket yang betul, atau guna lalai ServBay. Lalai biasanya di /Applications/ServBay/tmp/ atau /tmp/. Contoh: /Applications/ServBay/tmp/mysql.sock atau /tmp/mysql.sock.
• Masalah Tetapan Lalai ServBay:
  • Pada "Tetapan" ServBay -> "SQL Server Lalai", pastikan versi MariaDB/MySQL yang betul telah dipilih sebagai lalai. Sesetengah klien (cth, alat baris perintah mysql jika tidak guna -S atau -h) akan cuba sambung ke socket versi lalai.
• Isu Keizinan:
  • Pengguna proses MariaDB/MySQL atau pengguna klien tidak mempunyai keizinan menulis/ membaca pada direktori fail socket. ServBay lazimnya mengurus keizinan ini dengan baik, namun jika anda mengubah keizinan direktori /Applications/ServBay/tmp/ atau /tmp/ secara manual, ia boleh menimbulkan masalah.

Alternatif (Paksa Guna Sambungan Rangkaian):

• Cuba sambung menggunakan IP 127.0.0.1 (bukan localhost), yang akan memaksa penggunaan TCP/IP. Jika ini berjaya, isu hampir pasti berpunca dari fail socket.

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

2. Ralat Sambungan: berkaitan sambungan rangkaian (Connection refused, Can't connect to MySQL server)

Ralat jenis ini biasanya bermakna klien tidak dapat menyambung ke pelayan MariaDB/MySQL melalui rangkaian TCP/IP.

Punca Mungkin & Penyelesaian:

• Pakej MariaDB/MySQL Tidak Berjalan: (Rujuk di atas - semak status & log .err)
• Port Telah Digunakan:
  • Pastikan port yang didengar oleh MariaDB/MySQL (lalai 3306) tidak digunakan oleh aplikasi lain.
  • Periksa penggunaan port:

    lsof -i :3306
    # atau
    netstat -anv | grep LISTEN | grep 3306

  • Jika port digunakan, hentikan proses berkaitan, atau ubah parameter port dalam my.cnf dan mulakan semula pakej.
• Firewall Menghalang Sambungan:
  • Firewall macOS atau pihak ketiga boleh menghalang akses ke port 3306.
  • Semak Tetapan Sistem macOS -> Rangkaian -> Firewall.
  • Benarkan sementera proses mysqld melalui firewall (pastikan laluan mysqld anda benar):

    # Arahan contoh, sesuaikan dengan pelantar anda
    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

• Isu Konfigurasi (bind-address):
  • Semak bind-address dalam my.cnf. 127.0.0.1 atau localhost hanya benarkan sambungan dari mesin itu sendiri manakala 0.0.0.0 benarkan semua IP.
• Isu Konfigurasi Rangkaian (localhost):
  • Pastikan localhost dihalakan ke 127.0.0.1 dan/atau ::1.
  • Uji di Terminal: ping localhost.
  • Semak /etc/hosts mengandungi entri localhost yang betul.
  • Matikan sebarang proksi yang mungkin mengganggu trafik setempat.

3. Pakej MariaDB/MySQL Gagal Dimulakan

Punca Mungkin & Penyelesaian:

1. Periksa Log Ralat (Paling Kritikal!): Lihat /Applications/ServBay/logs/mariadb/<version>/<version>.err untuk mesej ralat permulaan tertentu. Log ialah kunci untuk mendiagnosis isu.
2. Ralat Fail Konfigurasi:
   • Fail /Applications/ServBay/etc/mariadb/<version>/my.cnf mempunyai ralat sintaks, parameter tidak sah atau laluan salah.
   • Sahkan sintaks konfigurasi (pastikan laluan mysqld betul untuk versi anda):

     # Arahan contoh
     /Applications/ServBay/bin/mariadb/<version>/bin/mysqld --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf --validate-config

3. Port Telah Digunakan: (Rujuk di atas - lsof -i :<port> atau netstat)
4. Ruang Storan Tidak Mencukupi: Direktori data (/Applications/ServBay/db/mariadb/<version>/) atau direktori log (/Applications/ServBay/logs/mariadb/<version>/) mungkin kehabisan ruang.
5. Masalah Keizinan:
   • Pengguna yang menjalankan proses MariaDB/MySQL (biasanya sistem pengguna seperti _mysql pada ServBay) tidak mempunyai keizinan baca/tulis/eksekusi yang betul.
   • Periksa keizinan:

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

     Pastikan pengguna proses mempunyai keizinan yang sesuai.
6. Fail Data Rosak: (rujuk bahagian "Pangkalan Data Tergendala/Kerosakan Data" di bawah) – fail data rosak akibat gangguan atau isu lain menghalang permulaan.

Selepas Selesai:

• Cuba hidupkan semula pakej: servbayctl restart mariadb <version>

4. Isu Keizinan Pengguna atau Pengesahan

Walaupun berjaya berhubung ke pelayan pangkalan data, anda boleh mengalami ralat akibat nama pengguna, kata laluan, atau keizinan yang tidak betul (cth, Access denied).

Punca Mungkin & Penyelesaian:

• Nama pengguna atau kata laluan salah: Pastikan maklumat akses adalah tepat. ServBay membenarkan set semula kata laluan root dengan mudah.
• Sekatan Lokasi Sambungan: Akaun pengguna mungkin terhad kepada hos tertentu seperti '<username>'@'localhost'. Cuba dari '<username>'@'127.0.0.1' boleh gagal jika dihadkan sebaliknya. '%' benarkan dari mana-mana hos.
• Keizinan Tidak Mencukupi: Pengguna tidak mempunyai keizinan untuk sambung ke pangkalan data sasaran atau menjalankan arahan (SELECT, INSERT, UPDATE, DLL).
• Semak Keizinan Pengguna:
  • Log masuk sebagai root atau pengguna lengkap hak:

    mysql -u root -p

  • Pada SQL, periksa keizinan pengguna:

    SHOW GRANTS FOR '<username>'@'<hostname>';
    -- Contoh, semak keizinan 'webapp' dari 'localhost':
    SHOW GRANTS FOR 'webapp'@'localhost';
    -- Semak 'admin' dari mana-mana hos:
    SHOW GRANTS FOR 'admin'@'%';

  • Guna GRANT dan REVOKE untuk ubah keizinan, atau cipta pengguna baru dengan akses yang diperlukan.

5. Isu Prestasi

Keberkesanan pangkalan data yang rendah memberi kesan buruk pada tindak balas aplikasi.

Punca Mungkin & Penyelesaian:

1. Kueri Perlahan: Syarat kueri yang tidak cekap, tiada indeks, atau perancangan tidak baik.
   • Aktifkan log kueri perlahan: Tetapkan slow_query_log = 1, long_query_time = 1 (log kueri lebih 1 saat), dan tentukan laluan log dalam my.cnf. Selepas mula semula, analisis log untuk kueri perlahan.
   • Guna EXPLAIN: Awali kueri mencurigakan dengan EXPLAIN untuk analisis pelan pelaksanaan.

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

   • Optimumkan arahan kueri: Berdasarkan hasil EXPLAIN, elakkan operasi tidak cekap, pastikan WHERE/ JOIN menggunakan indeks dengan efektif.
2. Indeks Tidak Sesuai/ Tiada: Kolum yang kerap digunakan untuk WHERE, ORDER BY, GROUP BY mesti diindekskan.
   • Analisis struktur jadual/kueri: Kenal pasti mana yang patut diindekskan.
   • Cipta indeks:

     CREATE INDEX idx_column_name ON your_table_name(column_name);

     Nota: Indeks meningkatkan operasi tulis dan penggunaan cakera – timbang kebaikan dan keburukannya.
3. Konfigurasi cache tidak optimum: Parameter berkaitan cache dalam my.cnf seperti innodb_buffer_pool_size, key_buffer_size (MyISAM) perlu diubah suai mengikut kapasiti sistem.
   • Sesuaikan mengikut RAM/keperluan: innodb_buffer_pool_size wajar antara 50%-70% RAM untuk pangkalan data berintensif. Perubahan perlukan mula semula.

     [mysqld]
     # Contoh, sesuaikan dengan keperluan & unit (K, M, G)
     innodb_buffer_pool_size = 2G
     # Jika banyak guna MyISAM:
     # key_buffer_size = 256M

4. Kekangan Sumber Perkakasan: CPU tinggi, RAM tidak cukup (swapping kerap), lewatan I/O cakera. Guna Activity Monitor/ top/htop untuk jejak sumber & bottleneck.

6. Pangkalan Data Tergendala/Kerosakan Data

Jika pangkalan data tidak boleh dimulakan, kerap 'crash', atau anomali data dikesan, fail data mungkin telah rosak.

Punca Mungkin & Penyelesaian:

1. Periksa Log Ralat: Periksa /Applications/ServBay/logs/mariadb/<version>/<version>.err untuk mesej tentang kerosakan seperti InnoDB error, masalah sistem fail, atau hardware.
2. Masalah Perkakasan: Isu cakera, RAM, dan sebagainya boleh menyumbang kepada korupsi data. Semak log sistem menggunakan Console.app atau alat diagnostik.
3. Konflik Perisian atau Bug: Sesetengah versi MariaDB/MySQL mengandungi bug atau berkonflik dengan aplikasi lain pada sistem.
4. Konfigurasi Salah: Parameter dalam my.cnf yang tidak tepat boleh menyebabkan ketidakstabilan atau crash.
5. Shutdown atau Gangguan Paksaan: Menutup MariaDB/MySQL secara tidak teratur (misal: tutup aplikasi ServBay secara paksa) boleh menyebabkan ketidakkonsistenan fail data.

Penyelesaian:

• Cuba Restart Selamat: Muat semula pakej menerusi ServBay atau arahan: servbayctl restart mariadb <version>. Kadangkala proses ini membolehkan pangkalan data 'memulihkan diri'.
• Periksa & Baiki jadual menggunakan mysqlcheck: Peralatan ini boleh menyemak dan baiki masalah (terutamanya jadual MyISAM).

  # Gunakan my.cnf ServBay & pengguna root untuk semua pangkalan data
  mysqlcheck --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p --check --all-databases
  # Untuk MyISAM, cuba
  # mysqlcheck --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p --auto-repair --check --all-databases

  Nota: --auto-repair untuk MyISAM sahaja. Untuk InnoDB, rujuk teknik pemulihan lanjutan (cth, InnoDB force recovery/inport dari backup).
• Force Recovery InnoDB (innodb_force_recovery): Jika InnoDB gagal dimulakan (rujuk log), cuba tetapan ini dalam my.cnf. AMARAN: Risiko kehilangan/penyimpangan data! Hanya untuk kecemasan & sandaran.
  1. SANDARKAN SEMUA fail data dahulu: Salin /Applications/ServBay/db/mariadb/<version>/ ke lokasi lain.
  2. Edit /Applications/ServBay/etc/mariadb/<version>/my.cnf.
  3. Tambah innodb_force_recovery = N pada [mysqld] (mulakan dengan 1, tambah nilai jika gagal, satu per satu).
  4. Mula semula MariaDB/MySQL: servbayctl start mariadb <version>.
  5. Jika boleh berjalan, SEGERA backup menggunakan mysqldump.

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

     Pastikan backup berhasil & ukuran munasabah.
  6. Hentikan proses MariaDB/MySQL selepas backup: servbayctl stop mariadb <version>.
  7. Edit my.cnf, buang atau komen keluar baris innodb_force_recovery = N.
  8. Pulihkan data: Inisialisasi semula direktori data baru, kemudian import semula fail backup menggunakan mysqldump.
• Pulihkan dari Sandaran: Jika tidak dapat dibaiki, pulihkan dari fail sandaran sahih. Sandaran ServBay biasanya di /Applications/ServBay/backup/mariadb/<version>/.
  • Contoh pemulihan (letakkan data ke <target_database_name>):

    # Pastikan <target_database_name> sudah wujud
    # mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p -e "CREATE DATABASE <target_database_name>;"
    
    # Jalankan import
    mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u <username> -p <target_database_name> < /Applications/ServBay/backup/mariadb/<version>/<your_backup.sql>

    Nota: <version> patut diganti dengan versi sebenar pakej MariaDB/MySQL.

7. Masalah Sandaran & Pemulihan

Isu boleh timbul semasa melakukan backup/restore melalui fungsi terbina ServBay atau mysqldump.

Punca Mungkin & Penyelesaian:

• Fail backup tidak lengkap atau rosak:
  • Semak saiz fail backup (ls -lh /path/to/your_backup.sql) untuk pastikan sesuai dengan data sebenar.
  • Guna editor teks atau less untuk semak kandungan fail backup— pastikan kelihatan seperti fail SQL yang sahih.
  • Untuk backup manual (mysqldump), semak sebarang ralat semasa proses backup. Untuk backup menggunakan ServBay, semak log aplikasi ServBay.
• Ralat Arahan Pemulihan:
  • Nama pengguna, kata laluan, atau nama pangkalan data salah.
  • Pengguna tiada hak mencukupi.
  • Ralat sintaks SQL— fail backup dari versi/jenis DB berbeza mungkin tidak serasi 100%.
• Masalah Kekangan Kunci Asing: Urutan import jadual boleh sebabkan kegagalan kekangan. Boleh matikan periksa kunci asing sebelum import:

  -- Sebelum import
  SET foreign_key_checks = 0;
  -- Jalankan arahan import, contoh:
  source /path/to/your_backup.sql; -- Dalam klien mysql
  -- Atau gunakan cara baris perintah: mysql ... < /path/to/your_backup.sql
  
  -- Setelah selesai import
  SET foreign_key_checks = 1;

  Nota: Jangan biarkan pemeriksaan kunci asing mati secara tetap, hanya semasa import.
• Isu Set Aksara/@Collation: Data atau definisi jadual dalam fail backup dan pangkalan data sasaran guna set aksara/@collation tidak serasi – boleh menimbulkan ralat atau karakter pelik. Pastikan set aksara padan (cth, utf8mb4).

Arahan Pemulihan Pangkalan Data dengan Betul (Contoh):

# Anggap fail backup untuk satu DB khas
# Pastikan <target_database_name> wujud
# mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u root -p -e "CREATE DATABASE <target_database_name>;"

# Import ke DB tepat dengan parameter betul
mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u <username> -p <target_database_name> < /Applications/ServBay/backup/mariadb/<version>/<your_backup.sql>

# Jika backup untuk semua pangkalan data (--all-databases), tiada nama DB diperlukan
# mysql --defaults-file=/Applications/ServBay/etc/mariadb/<version>/my.cnf -u <username> -p < /Applications/ServBay/backup/mariadb/<version>/<your_backup.sql>

Nota: Gantikan <version> dengan versi sebenar pakej. Fungsi sandaran ServBay biasanya hasilkan fail yang mudah dipulih & sediakan pilihan pemulihan.

8. Bug Khusus: Kegagalan InnoDB MariaDB 11.5.1 untuk Mula (ib_logfile0 was not found / Missing FILE_CHECKPOINT)

Ini ialah bug serius yang diketahui wujud pada MariaDB 11.5.1 di mana enjin InnoDB gagal inisialisasi atau memulihkan fail log, menyebabkan DB tidak boleh bermula.

Ciri Ralat Log:

Dalam /Applications/ServBay/logs/mariadb/11.5/11.5.err, anda akan lihat mesej seperti berikut:

[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

atau:

[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

Mesej sebegini menandakan InnoDB gagal menemukan atau memproses fail lognya, lalu gagal bermula.

Penyelesaian (Libatkan Pemindahan Data, Sila Backup Dahulu!):

Bug ini amat sukar untuk diperbaiki secara konvensional. Kaedah terbaik ialah memaksa inisialisasi untuk eksport data dan migrasi ke versi MariaDB yang lebih stabil.

1. Cuba Force Recovery untuk Backup Data (Berisiko!):
   • Sunting fail konfigurasi MariaDB 11.5 /Applications/ServBay/etc/mariadb/11.5/my.cnf.
   • Tambah baris innodb_force_recovery = 6 di bawah seksyen [mysqld].
   • Mula MariaDB 11.5 melalui ServBay atau arahan: servbayctl start mariadb 11.5
   • Jika boleh bermula (walaupun fungsi terhad/masih ada amaran), SEGERA lakukan backup dengan mysqldump! Ini peluang tunggal anda untuk selamatkan data.

     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

     Pastikan fail backup telah berjaya & saiz mencukupi.
2. Hentikan & Urus Data Directory Versi Bermasalah:
   • Hentikan MariaDB 11.5 pakej: servbayctl stop mariadb 11.5
   • Edit fail my.cnf, padam atau komen baris innodb_force_recovery...