Panduan Penyelesaian Masalah Pelayan Web ServBay

ServBay menyokong penggunaan Caddy, NGINX, dan Apache sebagai pelayan web utama, menawarkan persekitaran pembangunan tempatan yang fleksibel kepada anda. Dalam proses penggunaan, anda mungkin akan menghadapi isu seperti tapak web tidak boleh dicapai, lambat dimuat, atau menerima ralat seperti 500 Internal Server Error. Panduan ini bertujuan membantu anda mendiagnos dan menyelesaikan kerosakan lazim berkaitan pelayan web dalam persekitaran ServBay.

Menggunakan Alat Diagnosa Masalah Terbina Dalam ServBay

ServBay menyediakan alat diagnosa masalah yang berkuasa dan terbina dalam, mampu mengesan secara automatik serta memberi cadangan berkaitan isu konfigurasi dan perkhidmatan biasa. Sebaiknya, gunakan alat ini sebagai langkah pertama penyelesaian isu.

Buka aplikasi ServBay, klik Diagnosa Masalah pada bar navigasi sebelah kiri untuk mengakses panel diagnostik terbina dalam ServBay.

Alat ini akan memeriksa status komponen teras ServBay, penggunaan port, sintaks fail konfigurasi, dan memberikan nasihat berserta cadangan untuk membantu mengenal pasti punca masalah dengan cepat.

Semak Fail Konfigurasi Pelayan Web

Kesilapan dalam fail konfigurasi pelayan web merupakan penyebab utama laman gagal dicapai. ServBay menyediakan alat semakan sintaks khusus untuk setiap pelayan web.

Semakan Caddyfile

Gunakan arahan terbina dalam Caddy validate untuk menyemak sama ada fail Caddyfile anda betul.

/Applications/ServBay/bin/caddy validate -c /Applications/ServBay/etc/caddy/Caddyfile

Jika sintaks konfigurasi betul, arahan akan kembali Valid configuration. Jika terdapat kesilapan, maklumat ralat yang berkaitan akan dipaparkan.

Nota: Arahan caddy validate mungkin mengeluarkan banyak maklumat INFO atau WARN. Ini adalah maklumat pemuatan dalaman Caddy dan tidak semestinya menandakan kesilapan konfigurasi. Selagi anda menerima Valid configuration pada akhirnya, sintaks telah disahkan betul.

Contoh Ralat Caddyfile Biasa:

• Ralat Fail Sijil Tidak Wujud:

  2024/12/09 17:24:16.970 INFO using config from file {"file": "/Applications/ServBay/etc/caddy/Caddyfile"}
  ... (maklumat INFO/WARN lain) ...
  Error: loading http app module: provision http: getting tls app: loading tls app module: provision tls: loading certificates: open /Applications/ServBay/ssl/private/tls-certs/mail.servbay.host/mail.servbay.host.1crt: no such file or directory

  Jika ralat seumpama loading certificates: open xxxxx: no such file or directory dipaparkan, ini bermakna laluan fail sijil SSL yang ditetapkan dalam Caddyfile anda adalah salah atau fail tidak wujud. Sila semak alamat fail sijil (.crt/.cer/.pem) dan fail private key (.key) dalam konfigurasi tapak anda dan pastikan fail tersebut memang ada di lokasi berkenaan. ServBay menyokong import manual atau permohonan sijil SSL secara automatik melalui ACME—semak tetapan SSL ServBay anda.

• Ralat Laluan Root Direktori Tapak (Terdapat ruang kosong):

  2024/12/09 17:26:37.371 INFO using config from file {"file": "/Applications/ServBay/etc/caddy/Caddyfile"}
  Error: adapting config using caddyfile: parsing caddyfile tokens for 'root': too many arguments; should only be a matcher and a path, at /Applications/ServBay/etc/caddy/Caddyfile:1388

  Ralat parsing caddyfile tokens for 'root': too many arguments lazimnya berlaku kerana laluan direktori root tapak mengandungi ruang kosong. Sebagai contoh, root * /Applications/ServBay/www/public web akan dianggap parameter berasingan oleh Caddy. Penyelesaian yang betul ialah bungkus laluan yang ada ruang menggunakan tanda petik dua ", contohnya root * "/Applications/ServBay/www/public web".

  Cadangan: Untuk elak isu ini, sangatlah disarankan untuk tidak menggunakan ruang atau simbol khas pada nama fail dan direktori. Guna tanda hubung (-) atau garis bawah (_) untuk memisahkan perkataan, seperti public-folder atau public_dir.

• Ralat Peraturan Rewrite:

  Sekiranya anda menggunakan peraturan penulisan semula (rewrite) dalam Caddyfile yang tidak mematuhi sintaks Caddy, seperti terus menyalin konfigurasi NGINX, pemeriksaan konfigurasi akan gagal. Rujuk dokumentasi modul rewrite Caddy atau panduan migrasi NGINX ke ServBay untuk memastikan peraturan anda betul.

Semakan Konfigurasi NGINX

Gunakan parameter terbina dalam NGINX -t untuk menguji sintaks dan kesahan fail konfigurasi NGINX.

/Applications/ServBay/bin/nginx -t

Jika konfigurasi betul, hasilnya ialah:

nginx: the configuration file /Applications/ServBay/etc/nginx/nginx.conf syntax is ok
nginx: configuration file /Applications/ServBay/etc/nginx/nginx.conf test is successful

Jika terdapat ralat, NGINX akan nyatakan fail serta baris yang bermasalah. Ralat konfigurasi NGINX lazim meliputi:

1. Kesalahan Sintaks: Seperti tertinggal tanda semikolon ;, padanan kurungan } yang tidak kena, dsb.
2. Laluan Fail Salah: Laluan fail yang ditetapkan pada include atau arahan lain tidak tepat atau fail tidak wujud.
3. Konflik Port: Port yang didengari telah digunakan proses lain.

Semakan Konfigurasi Apache

Gunakan arahan Apache apachectl configtest untuk menyemak sintaks fail konfigurasi Apache.

/Applications/ServBay/bin/apachectl configtest

Jika betul, arahan ini akan memaparkan Syntax OK. Jika terdapat ralat, maklumat ralat terperinci akan dipaparkan. Kesalahan konfigurasi Apache yang kerap:

1. Gagal Memuat Modul: Modul yang dipanggil dalam konfigurasi (LoadModule) tidak wujud atau laluan salah.
2. Sintaks Fail .htaccess Salah: Sekiranya terdapat fail .htaccess dalam direktori laman dan terdapat ralat sintaks di dalamnya, ini mungkin menjejaskan ujian konfigurasi atau akses ke direktori tertentu.
3. Tetapan Akses Direktori Tidak Tepat: Arahan akses dalam Directory atau Files seperti Require, Allow, Deny menghalang pelayan web mengakses fail tapak.

Menangani Ralat 500 Internal Server Error

500 Internal Server Error ialah kod status HTTP umum yang menunjukkan pelayan web menghadapi situasi tak dijangka lalu gagal memproses permintaan. Bagi aplikasi web, ini sering berpunca daripada skrip back-end (seperti PHP, Python, Node.js) yang gagal dijalankan.

Langkah Penyelesaian Umum

Apabila anda menemui ralat 500, ikut langkah pemeriksaan berikut:

1. Periksa Log Ralat Pelayan Web: Ini adalah langkah terpenting. Log ralat biasanya mengandungi maklumat terperinci seperti kesalahan skrip, fail tiada, atau isu kebenaran.

   • Caddy: /Applications/ServBay/var/logs/caddy/error.log
   • NGINX: /Applications/ServBay/var/logs/nginx/error.log
   • Apache: /Applications/ServBay/var/logs/apache/error.log Semak entri terbaharu, cari perkataan error atau critical.

2. Pastikan Perkhidmatan Back-End (Contohnya PHP-FPM) Berjalan: Jika laman anda menggunakan PHP, pastikan servis PHP-FPM dimulakan dengan betul.

   ps aux | grep php-fpm

   Cari baris mengandungi php-fpm: master process atau php-fpm: pool www. Jika proses tiada, PHP-FPM belum bermula atau telah terhenti. Anda boleh mulakan semula melalui UI ServBay atau arahan servbayctl.

3. Semak Log Ralat Skrip Back-End (seperti PHP): Jika log pelayan web mengisyaratkan ralat FastCGI atau kegagalan skrip back-end, periksa log bahasa back-end.

   • PHP: /Applications/ServBay/var/logs/php/php_error.log Dalam log ralat PHP, cari Fatal error, Parse error, Warning, Notice khususnya berkaitan skrip yang sedang diakses. Pastikan display_errors dimatikan dalam produksi tetapi anda boleh mengaktifkannya buat sementara dalam pembangunan untuk melihat ralat perincian (set dalam php.ini).

4. Pastikan Fail & Direktori Mempunyai Kebenaran Tepat: Proses pelayan web selalunya dijalankan sebagai pengguna tertentu (cth. _www), dan memerlukan kebenaran membaca fail tapak serta menulis ke direktori muat naik atau log.

   ls -la /Applications/ServBay/www/your-site/

   Pastikan pengguna pelayan web mempunyai kebenaran membaca ke atas root dan subdirektori laman. Untuk upload/logging, kebenaran menulis juga diperlukan. Sesuaikan dengan chmod dan chown jika perlu, tetapi lakukan dengan berhati-hati.

Tumpuan Semakan Mengikut Pelayan Web untuk Ralat 500

• Caddy:

  1. Konfigurasi FastCGI: Pastikan arahan php_fastcgi atau reverse_proxy dalam Caddyfile betul menunjuk ke alamat pendengaran PHP-FPM (kebiasaannya 127.0.0.1:9000 atau unix:/laluan/php-fpm.sock).
  2. Status PHP-FPM: Pastikan versi PHP serta servis PHP-FPM yang sepadan aktif dalam ServBay.
  3. Tetapan Reverse Proxy: Jika menggunakan reverse_proxy ke servis lain (contohnya aplikasi Node.js), semak alamat/port proksi dan status servis back-end.

• NGINX:

  1. Tetapan fastcgi_pass: Sahkan arahan fastcgi_pass dalam nginx.conf atau konfigurasi laman menunjuk tepat ke alamat pendengaran PHP-FPM.
  2. client_max_body_size: Jika muat naik fail besar menyebabkan ralat 500, kemungkinan nilai ini terlalu kecil dan mengehadkan saiz permintaan.
  3. Arahan try_files: Pastikan try_files dikonfigurasi dengan betul, supaya index file ditemui atau permintaan diteruskan ke FastCGI.

• Apache:

  1. Modul mod_rewrite: Jika .htaccess digunakan untuk rewrite, pastikan modul mod_rewrite telah diaktifkan.
  2. Kandungan .htaccess: Arahan yang salah dalam .htaccess boleh serta-merta menyebabkan ralat 500. Periksa sintaks dan logik peraturan seperti RewriteRule.
  3. Tetapan AllowOverride: Pastikan konfigurasi direktor telah mengaktifkan AllowOverride yang membolehkan .htaccess berfungsi (kebiasaannya All atau sekurang-kurangnya FileInfo dan Limit).

Pengurusan Perkhidmatan

Selepas mengubah konfigurasi atau membetulkan isu back-end, biasanya anda perlu memulakan semula pelayan web atau perkhidmatan berkaitan supaya perubahan berkuat kuasa.

Memulakan Semula Perkhidmatan

Gunakan arahan servbayctl restart untuk memulakan semula perkhidmatan pelayan web tertentu.

# Mulakan semula perkhidmatan Caddy
servbayctl restart caddy -all

# Mulakan semula perkhidmatan NGINX
servbayctl restart nginx -all

# Mulakan semula perkhidmatan Apache
servbayctl restart apache -all

Parameter -all akan turut cuba memulakan semula perkhidmatan berkaitan seperti PHP-FPM apabila anda memulakan semula Caddy/NGINX/Apache.

Semak Status Perkhidmatan

Gunakan servbayctl status untuk menyemak status semasa perkhidmatan tertentu.

# Semak status perkhidmatan Caddy
servbayctl status caddy -all

# Semak status perkhidmatan NGINX
servbayctl status nginx -all

# Semak status perkhidmatan Apache
servbayctl status apache -all

Output arahan akan menunjukkan sama ada perkhidmatan dalam keadaan running (sedang berjalan), stopped (terhenti), atau status lain. Ini memudahkan anda mengesahkan keberjayaan pelancaran perkhidmatan.

Langkah Penyelesaian Masalah Lanjutan

Jika masalah masih berlarutan selepas mencuba langkah di atas, anda boleh teruskan dengan langkah berikut:

1. Semak Alat Pembangun Pelayar: Buka alat pembangunan (kebiasaannya tekan F12), lihat tab Console dan Network untuk mengesan ralat JavaScript di bahagian klien, status HTTP, header dan isi respons—membezakan isu klien atau server.
2. Guna curl -v: Dalam terminal, jalankan curl -v your-website.servbay.demo. Flag -v akan memaparkan maklumat penuh permintaan/respons, termasuk header & SSL/TLS, berguna untuk diagnosis rangkaian atau protokol. Tukar your-website.servbay.demo dengan domain sebenar laman anda dalam ServBay.
3. Uji Dengan Mematikan Firewall Sementara: Firewall macOS atau aplikasi keselamatan lain berkemungkinan menahan sambungan. Cuba matikan firewall seketika—jika isu selesai, semak peraturan firewall dan pastikan port yang digunakan ServBay (contohnya 80, 443) dibenarkan.
4. Uji Pada Browser/Peranti Berbeza: Capa laman menggunakan browser atau peranti berlainan untuk memastikan masalah bukan berpunca dari cache browser atau tetapan khusus peranti.
5. Periksa Konfigurasi DNS Tempatan atau fail hosts: Jika menggunakan domain khas (bukan localhost atau IP), pastikan /etc/hosts atau tetapan DNS tempatan menghala domain ke 127.0.0.1 atau ::1 dengan betul.

Rumusan

Kerosakan pada pelayan web adalah cabaran umum dalam pembangunan tempatan. Dengan memeriksa sintaks konfigurasi, meneliti log ralat, mengesahkan status perkhidmatan, serta memastikan kebenaran fail betul, kebanyakan isu boleh diselesaikan sendiri. Alat diagnosa dan baris arahan servbayctl ServBay ialah pembantu terbaik anda. Untuk masalah lebih rumit, rujuk dokumentasi ServBay atau hubungi sokongan teknikal untuk bantuan lanjut.