Panduan Penyelesaian Masalah Pelayan Web ServBay

ServBay menyokong penggunaan Caddy, NGINX, dan Apache sebagai pelayan web lalai, menawarkan persekitaran pembangunan tempatan yang fleksibel. Semasa penggunaan, anda mungkin menghadapi isu seperti laman web tidak boleh diakses, lambat dimuat, atau mengembalikan ralat (seperti ralat 500 Dalaman Pelayan). Panduan ini bertujuan membantu anda mendiagnosis dan menyelesaikan masalah pelayan web yang lazim dalam persekitaran ServBay.

Menggunakan Alat Diagnostik ServBay yang Disertakan

ServBay menyediakan alat diagnostik masalah terbina yang berkuasa, mampu mengesan dan memberi amaran mengenai isu konfigurasi dan perkhidmatan yang biasa. Sangat disarankan untuk menggunakan alat ini terlebih dahulu sekiranya anda menghadapi masalah.

Buka aplikasi ServBay, dan klik Diagnostik Masalah di bar navigasi kiri untuk masuk ke antara muka alat diagnostik ServBay.

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

Kunjungan Laman Perlahan Selepas Migrasi Dari MAMP atau Laravel Herd

Jika anda beralih dari MAMP atau Laravel Herd ke ServBay dan mendapati kunjungan pertama ke laman web selepas tempoh tidak aktif mengambil lebih 5 saat sebelum boleh diakses, tetapi kelajuan bertambah baik selepas itu, dan masalah perlahan berulang selepas tempoh tidak aktif.

Gejala Masalah

Buka alat pembangun Chrome (tekan F12 atau Cmd+Option+I), pergi ke tab Network, kemudian segarkan laman dan klik pada permintaan untuk melihat maklumat Timing. Anda akan nampak masa DNS Lookup berada sekitar 5 saat.

(Rajah: Menyemak masa DNS Lookup dalam tab Network alat pembangun Chrome)

Punca Masalah

MAMP dan Laravel Herd mengubah tetapan DNS macOS secara paksa semasa pemasangan, dan mencipta fail konfigurasi resolver DNS khas untuk menangkap domain tertentu (seperti *.test, *.local dan lain-lain). Fail-fail ini biasanya terletak dalam direktori /etc/resolver/.

Walaupun anda telah menyahpasang MAMP atau Laravel Herd, fail konfigurasi DNS resolver ini mungkin masih wujud. Apabila anda mengakses laman dengan akhiran domain yang sama (cth .test), macOS akan cuba menggunakan konfigurasi resolver lama itu terlebih dahulu, tetapi kerana perkhidmatan DNS MAMP/Herd sudah tiada, pencarian DNS akan tamat masa (kebiasaannya 5 saat) sebelum sistem menggunakan DNS lalai.

Cara Penyelesaian

Ikuti langkah berikut untuk membersihkan sepenuhnya konfigurasi DNS yang ditinggalkan oleh MAMP atau Laravel Herd:

1. Nyahpasang MAMP atau Laravel Herd Sepenuhnya

Jika anda belum nyahpasang MAMP atau Laravel Herd secara menyeluruh, gunakan penghapus rasmi atau skrip uninstaller:

Nyahpasang MAMP:

• Gunakan fungsi nyahpasang dalam aplikasi MAMP
• Atau padam manual direktori /Applications/MAMP, serta fail konfigurasi berkaitan

Nyahpasang Laravel Herd:

# Gunakan perintah uninstall Herd
herd uninstall

# Jika perintah tidak tersedia, padam secara manual aplikasi dan konfigurasi Herd
rm -rf ~/Library/Application\ Support/Herd
rm -rf ~/.config/herd

2. Padam Fail Tinggal Dalam Direktori /etc/resolver

Walaupun sudah dinyahpasang, fail resolver DNS dalam /etc/resolver/ mungkin masih tinggal dan perlu dipadam secara manual:

# Lihat fail dalam direktori /etc/resolver
ls -la /etc/resolver

# Padam fail konfigurasi tertentu (misalnya test dan local)
sudo rm /etc/resolver/test
sudo rm /etc/resolver/local

# Padam fail lain yang dicipta oleh MAMP/Herd jika ada
# Contoh: sudo rm /etc/resolver/herd

Fail resolver biasa hasil ciptaan MAMP/Herd:

• test - untuk domain *.test
• local - untuk domain *.local
• herd - khas untuk Laravel Herd

Nota: Anda perlu hak pentadbir (sudo) untuk padam fail-fail ini.

3. Elakkan Guna Akhiran Domain *.local

macOS memperuntukkan domain *.local untuk rangkaian setempat (LAN) melalui mDNS (Multicast DNS/Bonjour). Menggunakan .local sebagai domain pembangunan boleh menyebabkan:

• Konflik DNS
• Akses perlahan
• Tingkah laku jaringan yang tidak dijangka

Cadangan: Pilih akhiran domain lain untuk pembangunan tempatan seperti:

• .test — disimpan khusus untuk tujuan ujian
• .localhost — pasti beresolusi ke alamat loopback tempatan
• .dev — akhiran TLD sebenar tetapi sering digunakan untuk pembangunan
• Atau gunakan akhiran tersuai yang disarankan ServBay

4. Kosongkan Cache DNS (Pilihan)

Selepas langkah di atas, kosongkan cache DNS supaya perubahan berkuat kuasa segera:

# Untuk macOS Big Sur (11) ke atas
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

# Untuk macOS Catalina (10.15) dan sebelumnya
sudo killall -HUP mDNSResponder

5. Sahkan Penyelesaian

Selepas selesai, cuba akses laman web ServBay anda semula:

1. Layari laman tempatan anda di pelayar
2. Buka alat pembangun Chrome → tab Network
3. Segarkan laman dan periksa maklumat Timing permintaan
4. Pastikan masa DNS Lookup sudah turun ke paras normal (biasanya kurang 50ms)

Langkah-langkah ini sepatutnya menyelesaikan masalah akses pertama terlambat selepas migrasi dari MAMP/Laravel Herd. Jika masalah berterusan, semak sama ada perisian pihak ketiga (VPN, proksi dsb) mengganggu pencarian DNS.

Semak Fail Konfigurasi Pelayan Web

Kesalahan dalam fail konfigurasi pelayan web adalah punca utama laman tidak boleh diakses. ServBay menyediakan alat semak sintaks khusus untuk setiap pelayan web.

Pemeriksaan Caddyfile

Guna arahan validate Caddy untuk pastikan fail Caddyfile anda sah.

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

# Windows
C:\ServBay\bin\caddy.exe validate -c C:\ServBay\etc\caddy\Caddyfile

Jika sintaks betul, akan terpapar Valid configuration. Jika ada kesilapan, maklumat akan diberikan berdasarkan jenis ralat.

Nota: Arahan caddy validate mungkin memaparkan banyak mesej INFO atau WARN yang biasanya adalah proses dalaman Caddy. Selagi ada Valid configuration di akhir, sintaks dianggap betul.

Contoh Kesilapan Umum Caddyfile:

• Ralat fail sijil tiada:

  # Contoh macOS
  2024/12/09 17:24:16.970 INFO using config from file {"file": "/Applications/ServBay/etc/caddy/Caddyfile"}
  ... (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
  
  # Contoh Windows
  2024/12/09 17:24:16.970 INFO using config from file {"file": "C:\\ServBay\\etc\\caddy\\Caddyfile"}
  ... (INFO/WARN lain) ...
  Error: loading http app module: provision http: getting tls app: loading tls app module: provision tls: loading certificates: open C:\\ServBay\\ssl\\private\\tls-certs\\mail.servbay.host\\mail.servbay.host.1crt: no such file or directory

  Jika anda lihat ralat seperti loading certificates: open xxxxx: no such file or directory, maksudnya laluan fail sijil SSL dalam Caddyfile anda salah atau fail tersebut tiada. Semak konfigurasi laman anda dan pastikan fail sijil (.crt/.cer/.pem) dan kunci peribadi (.key) wujud di laluan yang ditetapkan. ServBay menyokong import manual atau permohonan SSL secara automatik dengan ACME. Semak tetapan SSL ServBay anda.

• Ralat laluan root laman web (mengandungi ruang):

  # Contoh macOS
  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
  
  # Contoh Windows
  2024/12/09 17:26:37.371 INFO using config from file {"file": "C:\\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 C:\\ServBay\\etc\\caddy\\Caddyfile:1388

  Ralat parsing caddyfile tokens for 'root': too many arguments biasanya kerana laluan root laman mengandungi ruang. Contoh:

  • macOS: root * /Applications/ServBay/www/public web — public web dianggap dua argumen
  • Windows: root * C:\ServBay\www\public web — public web dianggap dua argumen

  Penyelesaian: balut laluan dengan tanda petikan dua ":

  • macOS: root * "/Applications/ServBay/www/public web"
  • Windows: root * "C:\ServBay\www\public web"

  Cadangan: Elak penggunaan ruang dan simbol khas pada nama fail/direktori. Gunakan tanda - atau _ sebagai pemisah, seperti public-folder atau public_dir.

• Ralat peraturan Rewrite:

  Menggunakan peraturan Rewrite yang tidak ikut sintaks Caddy, seperti salin terus dari NGINX, juga akan gagal. Ikuti dokumentasi modul Rewrite Caddy atau panduan migrasi NGINX ke ServBay untuk gaya penulisan yang betul.

Pemeriksaan Konfigurasi NGINX

Guna parameter -t untuk uji sintaks dan kesahihan konfigurasi NGINX:

# macOS
/Applications/ServBay/bin/nginx -t

# Windows
C:\ServBay\bin\nginx.exe -t

Jika tiada ralat, paparan adalah:

# macOS
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

# Windows
nginx: the configuration file C:\ServBay\etc\nginx\nginx.conf syntax is ok
nginx: configuration file C:\ServBay\etc\nginx\nginx.conf test is successful

Jika ada masalah, NGINX akan nyatakan fail konfigurasi dan nombor baris bermasalah. Kesilapan lazim:

1. Kesilapan sintaks: Contoh kurang tanda ;, kurungan } tidak sepadan.
2. Ralat laluan fail: Laluan fail/direktori tiada atau salah pada arahan include atau seumpamanya.
3. Pertindihan port: Port didengar dalam konfigurasi sudah digunakan aplikasi lain.

Pemeriksaan Konfigurasi Apache

Guna arahan apachectl configtest untuk menyemak sintaks fail konfigurasi Apache:

# macOS
/Applications/ServBay/bin/apachectl configtest

# Windows
C:\ServBay\bin\httpd.exe -t

Jika betul, paparan adalah Syntax OK. Jika ada masalah, akan diberikan maklumat terperinci. Senarai kesilapan biasa:

1. Modul gagal dimuat: Modul yang dijadikan aktif (LoadModule) tiada atau laluan salah.
2. Kesilapan sintaks .htaccess: Jika fail .htaccess ada dan sintaks salah, seluruh konfigurasi atau akses direktori spesifik boleh gagal.
3. Tetapan izin direktori tidak tepat: Arahan seperti Directory atau Files (izin Require, Allow, Deny) menghalang akses fail laman.

Penyelesaian Ralat 500 Dalaman Pelayan

500 Internal Server Error ialah kod HTTP umum yang bermaksud pelayan tidak dapat memenuhi permintaan akibat isu yang tidak dijangka. Biasanya berlaku kerana skrip belakang (PHP, Python, Node.js dsb) gagal dilaksanakan.

Langkah Penyelesaian Umum

Jika anda terlihat ralat 500, lakukan langkah berikut:

1. Periksa log ralat pelayan web: Langkah utama, log ralat mengandungi maklumat terperinci seperti isu skrip, fail tiada, masalah izin dsb.

   macOS:

   • Caddy: /Applications/ServBay/var/logs/caddy/error.log
   • NGINX: /Applications/ServBay/var/logs/nginx/error.log
   • Apache: /Applications/ServBay/var/logs/apache/error.log

   Windows:

   • Caddy: C:\ServBay\var\logs\caddy\error.log
   • NGINX: C:\ServBay\var\logs\nginx\error.log
   • Apache: C:\ServBay\var\logs\apache\error.log

   Semak log terbaru, cari maklumat mengandungi error atau critical.

2. Pastikan perkhidmatan belakang seperti PHP-FPM berjalan: Jika laman anda guna PHP, pastikan PHP-FPM aktif.

   ps aux | grep php-fpm

   Cari baris php-fpm: master process atau php-fpm: pool www. Pastikan proses wujud; jika tiada, PHP-FPM mungkin belum bermula atau telah tamat. Mulakan melalui ServBay UI atau arahan servbayctl.

3. Periksa log kesilapan skrip belakang (PHP): Jika log pelayan web paparkan masalah FastCGI atau skrip, semak log PHP:

   Lokasi log PHP:

   • macOS: /Applications/ServBay/var/logs/php/php_error.log
   • Windows: C:\ServBay\var\logs\php\php_error.log

   Cari maklumat Fatal error, Parse error, Warning, Notice terutamanya berkaitan skrip yang diakses. Pastikan display_errors ditutup dalam produksi tetapi boleh dibuka buat sementara waktu untuk pembangunan (tetapan melalui php.ini).

4. Semak izin fail/direktori: Proses pelayan web biasanya berjalan dalam akaun pengguna tertentu dan perlukan izin secukupnya untuk membaca fail/direktori laman serta menulis ke direktori upload/log.

   macOS:

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

   Pastikan pengguna pelayan web (contoh _www) boleh baca fail dan direktori tapak. Untuk upload/log, perlu izin menulis. Boleh guna arahan chmod dan chown.

   Windows:

   dir C:\ServBay\www\your-site

   Pastikan akaun pengguna yang menjalankan ServBay boleh akses direktori laman web. Semak dan ubah melalui tab keselamatan pada sifat fail.

Titik Penyelesaian Spesifik Mengikut Pelayan Web

• Caddy:

  1. Konfigurasi FastCGI: Semak arahan php_fastcgi atau reverse_proxy dalam Caddyfile, pastikan menunjuk alamat PHP-FPM yang betul (127.0.0.1:9000 atau unix:/path/to/php-fpm.sock).
  2. Status PHP-FPM: Pastikan versi PHP berkaitan serta perkhidmatan PHP-FPM dalam ServBay berjalan.
  3. Konfigurasi reverse proxy: Jika reverse_proxy ke perkhidmatan lain (Node.js dsb), semak alamat/port dan pastikan servis belakang aktif.

• NGINX:

  1. Tetapan fastcgi_pass: Semak arahan fastcgi_pass dalam nginx.conf atau fail tapak, pastikan alamat PHP-FPM betul.
  2. client_max_body_size: Jika upload fail besar berikan ralat 500, tingkatkan nilai tetapan ini.
  3. Arahan try_files: Semak konfigurasi try_files, pastikan boleh jumpa fail indeks atau lalukan ke FastCGI.

• Apache:

  1. Modul mod_rewrite: Jika guna .htaccess untuk penulisan semula URL, pastikan modul mod_rewrite diaktifkan.
  2. Kandungan .htaccess: Kesilapan atau ralat dalam .htaccess beri kesan kepada pelayan. Semak khusus arahan seperti RewriteRule.
  3. Tetapan AllowOverride: Dalam fail konfigurasi Apache untuk direktori berkenaan, pastikan AllowOverride dibenarkan (All atau sekurangnya FileInfo dan Limit).

Pengurusan Perkhidmatan

Setelah mengubah konfigurasi atau menyelesaikan isu belakang, biasanya pelayan web perlu dimulakan semula agar perubahan berkuat kuasa.

Mulakan Semula Perkhidmatan

Guna arahan servbayctl restart untuk mula semula pelayan web yang terpilih.

# Mulakan semula Caddy
servbayctl restart caddy -all

# Mulakan semula NGINX
servbayctl restart nginx -all

# Mulakan semula Apache
servbayctl restart apache -all

Parameter -all turut restart servis berkait (contoh, jika pelayan web guna FastCGI, PHP-FPM juga dimulakan semula).

Semak Status Perkhidmatan

Guna arahan servbayctl status untuk semak status semasa perkhidmatan:

# Status Caddy
servbayctl status caddy -all

# Status NGINX
servbayctl status nginx -all

# Status Apache
servbayctl status apache -all

Maklumat akan tunjuk sama ada servis sedang running (berjalan), stopped (berhenti) atau status lain. Ini membantu pengesahan servis bermula dengan jayanya.

Langkah Penyelesaian Masalah Lanjutan

Jika kaedah asas tidak berjaya, cuba kaedah lanjutan berikut:

1. Semak alat pembangun pelayar: Tekan F12 dan ke tab Console dan Network untuk detect ralat JavaScript, status kod permintaan, header dan badan respons; ini mengenal pasti sama ada masalah depan atau belakang.
2. Guna perintah curl -v: Dalam terminal, jalankan curl -v your-website.servbay.demo untuk paparkan maklumat permintaan dan respons terperinci (header permintaan/respons, info SSL/TLS dsb), membantu diagnosis isu sambungan/protokol. Gantikan your-website.servbay.demo dengan domain sebenar laman ServBay anda.
3. Matikan firewall sementara untuk ujian: Firewall tempatan (seperti firewall macOS atau perisian keselamatan pihak ketiga) boleh menghalang sambungan; matikan sekejap untuk ujian. Jika masalah selesai, semak peraturan firewall untuk membenarkan port ServBay (cth 80, 443).
4. Uji di pelayar/peranti lain: Cuba akses laman dengan pelayar lain atau peranti lain untuk sahkan masalah bukan berpunca dari cache pelayar atau tetapan peranti.
5. Semak tetapan DNS tempatan atau fail hosts: Jika guna domain tersuai (bukan localhost/IP langsung), semak fail hosts dan tetapan DNS untuk pastikan domain betul-betul menunjuk ke 127.0.0.1 atau ::1.
   • macOS: /etc/hosts
   • Windows: C:\Windows\System32\drivers\etc\hosts

Kesimpulan

Masalah pelayan web adalah cabaran biasa dalam pembangunan tempatan. Dengan pemeriksaan fail konfigurasi, analisis log ralat, pengesahan status servis serta semakan izin fail, kebanyakan masalah boleh diselesaikan. Alat diagnostik ServBay dan perintah servbayctl adalah pembantu utama. Untuk isu kompleks, jangan ragu untuk rujuk dokumentasi terperinci ServBay atau hubungi pasukan sokongan teknikal untuk bantuan lanjut.