ServBay Web 伺服器疑難排解指南

ServBay 支援以 Caddy、NGINX、Apache 作為預設的網頁伺服器，為您打造彈性的本地開發環境。使用過程中，可能會遇到網站無法存取、載入緩慢或出現錯誤（如 500 內部伺服器錯誤）等問題。本指南旨在協助您診斷並解決 ServBay 環境下常見的網頁伺服器故障。

使用 ServBay 內建故障診斷工具

ServBay 提供功能強大的故障診斷工具，可自動偵測並提示常見的設定和服務問題。強烈建議遇到問題時，先行使用此工具自助排查。

開啟 ServBay 應用程式，於左側導覽列點選 故障診斷，即可進入 ServBay 內建的診斷介面。

此工具會檢查 ServBay 核心元件狀態、連接埠占用、設定檔語法等，並依情況給予提示及建議，助您迅速找出問題根源。

自 MAMP 或 Laravel Herd 移轉後網站首次存取緩慢

若您自 MAMP 或 Laravel Herd 轉換至 ServBay，發現網站在閒置一段時間後首次存取需等待 5 秒以上，但接下來一段時間速度正常，若再次閒置，首次存取又會變得非常慢。

問題症狀

於 Chrome 瀏覽器開啟開發者工具（按 F12 或 Cmd+Option+I），切換至 網路 (Network) 標籤，重新整理頁面後點選請求查看詳細 Timing 資訊，可見 DNS Lookup 一欄等待時間約 5 秒。

(說明：在 Chrome 開發者工具 Network 標籤中檢查 DNS Lookup 時間)

問題原因

MAMP 與 Laravel Herd 安裝時會強制修改 macOS 的 DNS 設定，並創建特殊 DNS 解析器設定檔，攔截指定網域（例如 *.test、*.local）。這些檔案通常放在 /etc/resolver/ 目錄下。

即使已解除安裝 MAMP 或 Laravel Herd，這類 DNS 設定很可能依然殘留於系統。當您存取使用相同後綴（如 .test）的網站時，macOS 會優先透過這些舊有解析器查詢 DNS，但因 MAMP/Herd DNS 服務早已不存在，導致 DNS 查詢逾時（通常 5 秒），最後才回退至系統預設 DNS 進行解析。

解決方案

請依下列步驟徹底清除 MAMP 或 Laravel Herd 遺留的 DNS 設定：

1. 正確解除安裝 MAMP 或 Laravel Herd

若尚未完整解除安裝 MAMP 或 Laravel Herd，請使用其官方解除安裝程式或腳本進一步清理：

MAMP 解除安裝：

• 使用 MAMP 應用程式的解除安裝功能
• 或手動移除 /Applications/MAMP 目錄及相關設定檔

Laravel Herd 解除安裝：

# 使用 Herd 提供的解除安裝指令
herd uninstall

# 若上列指令無法使用，手動刪除 Herd 程式與設定
rm -rf ~/Library/Application\ Support/Herd
rm -rf ~/.config/herd

2. 移除 /etc/resolver 目錄殘留檔案

即使正確解除安裝 MAMP 或 Herd，/etc/resolver/ 目錄下的 DNS 設定檔可能仍在，需手動清理：

# 檢查 /etc/resolver 目錄檔案
ls -la /etc/resolver

# 移除特定解析器設定檔（例如 test 與 local）
sudo rm /etc/resolver/test
sudo rm /etc/resolver/local

# 若還有其他 MAMP/Herd 創建的設定檔一併移除
# 例如：sudo rm /etc/resolver/herd

MAMP/Herd 常見解析器設定檔包括：

• test — 用於解析 *.test 網域
• local — 用於解析 *.local 網域
• herd — Laravel Herd 專用

注意： 執行刪除需有管理員權限（sudo）。

3. 避免使用 *.local 網域後綴

macOS 將 *.local 保留作為**區域網路（LAN）**的 mDNS（Multicast DNS, Bonjour）用途。將 .local 當作本地開發網域可能導致：

• DNS 解析衝突
• 存取緩慢
• 不預期的網路行為

建議： 使用其他網域後綴作為本地開發網址，例如：

• .test — 專為測試預留的頂級網域
• .localhost — 保證指向本地回圈位址
• .dev — 雖為正式 TLD，亦常用於本地開發
• 或採用 ServBay 推薦的自定義後綴

4. 清除 DNS 快取（可選）

完成以上清理後，建議清除系統 DNS 快取以立即生效：

# macOS Big Sur (11) 以上版本
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

# macOS Catalina (10.15) 與更舊版本
sudo killall -HUP mDNSResponder

5. 驗證修復

清理完畢後，重新存取您的 ServBay 網站：

1. 於瀏覽器存取您的本地網站
2. 開啟 Chrome 開發者工具 → 網路 (Network) 標籤
3. 重新整理頁面並檢查請求的 Timing 資訊
4. 確認 DNS Lookup 時間已回復正常（通常小於 50ms）

依上述步驟，應可徹底解決自 MAMP 或 Laravel Herd 移轉後首次存取緩慢的情況。若問題仍在，請確認是否有其它第三方軟體（如 VPN、代理等）干擾 DNS 解析。

檢查 Web 伺服器設定檔

Web 伺服器設定檔錯誤是網站無法正常運作的常見主因。ServBay 為每種 Web 伺服器提供專用語法檢查工具。

Caddyfile 檢查

使用 Caddy 內建的 validate 指令檢驗您的 Caddyfile 設定是否正確。

# 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

若語法正確，會顯示 Valid configuration。設定有誤則依錯誤型態回報提示訊息。

注意: caddy validate 指令可能輸出大量 INFO 或 WARN 訊息，為 Caddy 內部載入過程資訊，不一定代表設定錯誤，只要結果為 Valid configuration 即屬語法正確。

常見 Caddyfile 錯誤範例：

• 憑證檔案不存在錯誤:

  # macOS 範例
  2024/12/09 17:24:16.970 INFO using config from file {"file": "/Applications/ServBay/etc/caddy/Caddyfile"}
  ... (其他 INFO/WARN 訊息) ...
  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
  
  # Windows 範例
  2024/12/09 17:24:16.970 INFO using config from file {"file": "C:\\ServBay\\etc\\caddy\\Caddyfile"}
  ... (其他 INFO/WARN 訊息) ...
  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

  類似 loading certificates: open xxxxx: no such file or directory 表示 Caddyfile 設定中 SSL 憑證檔路徑錯誤或檔案不存在。請檢查網站設定憑證（.crt/.cer/.pem）及私鑰（.key）位置是否正確，並確認檔案確實存在。ServBay 支援憑手動匯入及 ACME 自動申請 SSL 憑證，請參考 ServBay SSL 設定。

• 網站根目錄路徑錯誤（含空白）:

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

  此錯誤訊息 parsing caddyfile tokens for 'root': too many arguments 通常因網站根目錄路徑中出現空白。例如：

  • macOS: root * /Applications/ServBay/www/public web 中的 public web 被視為兩個參數
  • Windows: root * C:\ServBay\www\public web 中的 public web 被視為兩個參數

  正確寫法須以雙引號 " 包覆含空白路徑：

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

  建議: 避免使用空白及特殊符號於檔案/目錄命名，建議採用中線 - 或底線 _ 取代，例如 public-folder 或 public_dir。

• Rewrite 規則錯誤:

  於 Caddyfile 使用不符合 Caddy 語法之 rewrite 規則（如複製 NGINX 規則），亦會致驗證失敗。請參考 Caddy Rewrite 模組文件 或 ServBay 的 NGINX 網站移轉指南，確保語法正確。

NGINX 設定檢查

使用 NGINX 內建的 -t 參數檢查設定語法及有效性。

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

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

若設定無誤，會顯示：

# 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

若有錯誤，NGINX 會標明錯誤設定檔及行號。常見 NGINX 錯誤包括：

1. 語法錯誤： 如分號 ; 遺漏、括號 } 不配對等。
2. 檔案路徑錯誤： include 或指令指定路徑不正確或不存在。
3. 連接埠衝突： 設定監聽的 port 已被其他程式占用。

Apache 設定檢查

可用 Apache 的 apachectl configtest 檢查設定語法。

# macOS
/Applications/ServBay/bin/apachectl configtest

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

無誤時會顯示 Syntax OK，否則回報錯誤訊息。Apache 常見錯誤包括：

1. 模組載入失敗： 設定檔指定開啟的模組 (LoadModule) 不存在或路徑出錯。
2. .htaccess 語法錯誤： 目錄內的 .htaccess 若語法有誤，可能致 Apache 檢查失敗或目標目錄無法存取。
3. 目錄權限設置不當： Directory、Files 等指定的權限設置 (Require, Allow, Deny) 阻止網站檔案存取。

500 內部伺服器錯誤處理

500 Internal Server Error 為通用 HTTP 狀態碼，表示伺服器處理請求時遇預期外的情況而無法完成。Web 應用程式出現此錯誤通常是後端腳本（如 PHP、Python、Node.js）執行失敗。

通用排查步驟

遇到 500 錯誤時，可依以下步驟檢查：

1. 檢查 Web 伺服器錯誤日誌： 這是排查 500 錯誤首要步驟。錯誤日誌通常包含詳細錯誤細節，如腳本錯誤、檔案不存在、權限問題等。

   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

   檢查最新日誌條目，尋找含 error 或 critical 關鍵字。

2. 檢查後端服務（如 PHP-FPM）是否運作： 若網站依賴 PHP，須確認 PHP-FPM 服務已啟動。

   ps aux | grep php-fpm

   搜尋 php-fpm: master process 或 php-fpm: pool www 相關行。若無相關進程，代表 PHP-FPM 未啟動或異常終止。可透過 ServBay UI 或 servbayctl 指令啟動 PHP 服務。

3. 檢查後端腳本（如 PHP）錯誤日誌： 若 Web 伺服器日誌顯示 FastCGI 或後端腳本錯誤，應查閱後端語言的錯誤日誌。

   PHP 錯誤日誌位置：

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

   查閱 PHP 錯誤日誌，尋找 Fatal error, Parse error, Warning, Notice 等資訊，尤其是與目前存取腳本相關錯誤。請確保 display_errors 於生產環境關閉，開發階段可暫時開啟以查看詳細錯誤（通常於 php.ini 設定）。

4. 檢查檔案及目錄權限： Web 伺服器進程通常以特定使用者執行，需有足夠權限讀取網站檔案目錄、寫入上傳目錄或日誌檔。

   macOS:

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

   確認 Web 伺服器（如 _www）擁有網站根目錄及其下所有檔案讀取權限。若涉及檔案上傳或日誌寫入需有寫入權限。可用 chmod、chown 修改權限和所有者。

   Windows:

   dir C:\ServBay\www\your-site

   Windows 下應確保執行 ServBay 之使用者帳號擁有網站目錄的適當存取權。可於檔案屬性中的安全標籤檢查和修改權限。

各伺服器 500 錯誤排查重點

• Caddy:

  1. FastCGI 設定： 檢查 Caddyfile 的 php_fastcgi 或 reverse_proxy 是否正確指向 PHP-FPM 聆聽位址（如 127.0.0.1:9000 或 unix:/path/to/php-fpm.sock）。
  2. PHP-FPM 狀態： 確認 ServBay 中對應 PHP 版本及 PHP-FPM 服務運作正常。
  3. 反向代理設定： 如使用 reverse_proxy 代理至其他後端（如 Node.js），需檢查代理位址、port 是否正確及後端服務有正常運作。

• NGINX:

  1. fastcgi_pass 設定： 檢查 nginx.conf 或網站專屬設定中的 fastcgi_pass 是否正確指向 PHP-FPM。
  2. client_max_body_size： 如大檔上傳造成 500，可能此值過小限制請求大小。
  3. try_files 指令： 檢查指令配置，確保正確尋找索引檔或傳遞請求給 FastCGI。

• Apache:

  1. mod_rewrite 模組： 使用 .htaccess 做 URL 重寫時需確保已啟用 mod_rewrite。
  2. .htaccess 檔案內容： .htaccess 筆誤會直接導致 500 錯誤。檢查 RewriteRule 等規則語法。
  3. AllowOverride 設定： 檢查 Apache 設定檔中該目錄的 AllowOverride，確認允許 .htaccess 規則生效（通常設為 All 或至少含 FileInfo 與 Limit）。

服務管理

修改設定檔或解決後端問題後，通常需要重啟 Web 伺服器或相關服務使變更生效。

重啟服務

使用 servbayctl restart 指令重啟指定 Web 伺服器服務。

# 重啟 Caddy 服務
servbayctl restart caddy -all

# 重啟 NGINX 服務
servbayctl restart nginx -all

# 重啟 Apache 服務
servbayctl restart apache -all

-all 參數會同步重啟 Web 伺服器所需附屬服務，例如設定含 FastCGI 時一併重啟 PHP-FPM。

查看服務狀態

用 servbayctl status 指令查詢指定服務目前執行情形。

# 查詢 Caddy 服務狀態
servbayctl status caddy -all

# 查詢 NGINX 服務狀態
servbayctl status nginx -all

# 查詢 Apache 服務狀態
servbayctl status apache -all

輸出會顯示服務 running（執行中）、stopped（已停止）或其他狀態，有助於快速確認服務啟動是否成功。

進階排障步驟

若以上方法仍未排除故障，可嘗試更深入的檢查：

1. 查閱瀏覽器開發者工具： 開啟瀏覽器開發者工具（通常按 F12），切換 控制台 (Console) 與 網路 (Network) 標籤，檢查前端 JavaScript 錯誤、網路請求詳細狀態碼、回應標頭與內容，有助判斷是前端或後端問題。
2. 使用 curl -v 測試： 於終端用 curl -v your-website.servbay.demo 存取網站。-v 顯示完整請求/回應，包括標頭、SSL/TLS 資訊，有利於診斷連線或協議問題。請將 your-website.servbay.demo 替換為您的實際網站網域。
3. 暫時關閉防火牆測試： macOS 內建防火牆或第三方安全軟體可能阻擋進站連線。可暫時關閉測試，若故障消失，需檢查防火牆規則，允許 ServBay 使用的 port（如 80、443）通過。
4. 更換瀏覽器/設備測試： 於不同瀏覽器或裝置存取，判斷問題是否普遍，排除瀏覽器快取或本機設定問題。
5. 檢查本地 DNS 解析或 hosts 設定： 若採用自定義網域（非 localhost 或 IP），請檢查 hosts 或 DNS 設定，確保網域解析至 127.0.0.1 或 ::1。
   • macOS: /etc/hosts
   • Windows: C:\Windows\System32\drivers\etc\hosts

結論

Web 伺服器疑難雖為本地開發常見挑戰，但只要有系統地檢查設定檔語法、分析錯誤日誌、確認服務狀態與檔案權限，大多數問題都能獲得解決。ServBay 內建的故障診斷工具與 servbayctl 命令既快速又強大。若遇到棘手問題，歡迎深入瀏覽 ServBay 詳細文件或聯繫技術支援團隊取得協助。