ServBay Web 伺服器故障排除指南

ServBay 支援使用 Caddy、NGINX、Apache 做為預設的 Web 伺服器，為您提供靈活的本地開發環境。在使用過程中，您可能會遇到網站無法訪問、載入緩慢或回傳錯誤（如 500 內部伺服器錯誤）等問題。本指南旨在協助您診斷與解決 ServBay 環境中常見的 Web 伺服器相關故障。

使用 ServBay 內建的故障診斷工具

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

打開 ServBay 應用，在左側導覽列點擊 故障診斷，即可進入 ServBay 內建的故障診斷介面。

該工具會檢查 ServBay 的核心元件狀態、連接埠占用、設定檔語法等，並給出提示與建議，協助您快速定位問題所在。

檢查 Web 伺服器設定檔

Web 伺服器設定檔錯誤，是造成網站無法正常訪問的主要原因之一。ServBay 為每款伺服器提供專屬的語法檢查工具。

Caddyfile 檢查

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

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

若設定檔語法正確，指令會回傳 Valid configuration。有錯誤時，則根據錯誤類型提供相關提示資訊。

注意: caddy validate 指令可能會輸出大量 INFO 或 WARN 訊息，這些通常為 Caddy 內部載入過程的資訊，不一定代表設定錯誤，只要最終顯示 Valid configuration，即表示語法正確。

常見 Caddyfile 錯誤範例：

• 憑證檔案不存在錯誤：

  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

  出現類似 loading certificates: open xxxxx: no such file or directory 的錯誤，代表您的 Caddyfile 所指定的 SSL 憑證檔路徑不正確或檔案不存在。請檢查網站設定中憑證（.crt/.cer/.pem）與私鑰（.key）檔案地址是否正確，並確認該檔案實際存在。ServBay 支援手動匯入或透過 ACME 自動申請 SSL 憑證，請檢查 ServBay SSL 設定。

• 網站根目錄路徑錯誤（含空格）：

  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

  此錯誤 parsing caddyfile tokens for 'root': too many arguments 通常是網站根目錄含有空格造成。例如 root * /Applications/ServBay/www/public web 裡的 public web 會被 Caddy 視為兩個獨立參數。正確做法是用雙引號 " 將路徑包裹，如 root * "/Applications/ServBay/www/public web"。

  建議： 為避免此類問題，強烈建議檔名與目錄名避免使用空格及特殊符號。建議使用連字符 - 或底線 _ 分隔單字，例如 public-folder 或 public_dir。

• Rewrite 規則錯誤：

  在 Caddyfile 中使用了不符 Caddy 語法規則的重寫（Rewrite）規則（例：直接複製 NGINX 規則），會導致設定驗證失敗。請參考 Caddy Rewrite 模組官方文件 或 ServBay 提供的 NGINX 網站遷移至 ServBay 指南，確保規則語法正確。

NGINX 設定檔檢查

請用 NGINX 內建的 -t 參數檢測設定檔語法與有效性。

/Applications/ServBay/bin/nginx -t

設定檔正確時，會顯示：

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

若有錯誤，NGINX 會標明問題所在檔案及行號。常見錯誤包含：

1. 語法錯誤： 如漏掉分號 ;、大括號 } 未封閉等。
2. 檔案路徑錯誤： include 指令或其他指定的檔案、目錄路徑不存在。
3. 連接埠衝突： 設定中使用的埠已被其他程式佔用。

Apache 設定檔檢查

使用 Apache 的 apachectl configtest 指令檢查 Apache 設定檔語法。

/Applications/ServBay/bin/apachectl configtest

設定檔正確時，會顯示 Syntax OK。否則會有詳細錯誤資訊。常見錯誤包括：

1. 模組載入失敗： 設定檔啟用的模組（LoadModule）不存在或路徑錯誤。
2. .htaccess 檔案語法錯誤： 網站目錄的 .htaccess 有語法錯，可能讓整份設定檔檢查失敗或特定目錄存取異常。
3. 目錄權限設定不當： Directory 或 Files 等指令的權限（Require, Allow, Deny）導致無法存取網站檔案。

500 內部伺服器錯誤處理

500 Internal Server Error 屬於通用 HTTP 狀態碼，代表伺服器在處理請求時遇到意外狀況，導致無法完成請求。對 Web 應用而言，通常代表後端腳本（如 PHP、Python、Node.js 等）執行失敗。

通用排查步驟

遇到 500 錯誤時，可依下列步驟排查：

1. 查看 Web 伺服器錯誤日誌： 這是找出 500 錯誤主因的首要步驟。錯誤日誌通常包含詳細資訊，如腳本錯誤、檔案不存在、權限問題等。

   • Caddy: /Applications/ServBay/var/logs/caddy/error.log
   • NGINX: /Applications/ServBay/var/logs/nginx/error.log
   • Apache: /Applications/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 介面或 servbayctl 指令啟動。

3. 查看後端腳本（如 PHP）錯誤日誌： 若 Web 伺服器日誌顯示 FastCGI 或後端腳本執行錯誤，需要檢查語言錯誤日誌。

   • PHP: /Applications/ServBay/var/logs/php/php_error.log 請查看 PHP 日誌，搜尋 Fatal error、Parse error、Warning、Notice 等訊息，關注與目前訪問腳本有關的錯誤。建議生產環境關閉 display_errors，開發階段可臨時開啟（於 php.ini 設定），方便除錯。

4. 檢查檔案與目錄權限： Web 伺服器程序通常以特定用戶（例：_www）執行，須有足夠權限存取網站檔案與目錄，且需能寫入上傳資料與日誌。

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

   請確認 Web 伺服器用戶對網站根目錄及子目錄、檔案擁有讀取權限。如有檔案上傳或日誌需求，須具寫入權限。可用 chmod、chown 調整權限及所有人，操作前請謹慎。

各 Web 伺服器 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），請檢查代理目標與埠號，以及後端服務本身狀態。

• NGINX:

  1. fastcgi_pass 設定： 檢查設定檔中 fastcgi_pass 是否對應正確 PHP-FPM 地址。
  2. client_max_body_size: 若上傳大型檔案產生 500 錯誤，有可能此參數設定過小，請適當調整。
  3. try_files 指令： 確認其內容是否正確，能正確尋找索引檔或轉交請求至 FastCGI。

• Apache:

  1. mod_rewrite 模組： 若使用 .htaccess 做 URL 重寫，需確保 Apache 已啟用 mod_rewrite。
  2. .htaccess 檔內容： 錯誤的 .htaccess 指令會直接導致 500 錯誤。請檢查語法及 Rewrite 相關規則。
  3. AllowOverride 設定： 把握對應目錄的 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 參數會嘗試重啟與該伺服器有關的其他服務。如設有 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 替換成您的實際 ServBay 網站域名。
3. 暫時關閉防火牆測試： 本機防火牆（如 macOS 內建防火牆）或第三方安全軟體有時會阻擋連線。可暫時關閉測試，若問題排除，請調整規則，允許 ServBay 所用的連接埠（例：80, 443）。
4. 換不同瀏覽器/設備測試： 用其他瀏覽器或設備訪問網站，確認問題是否普遍，排除瀏覽器快取或裝置設定異常。
5. 檢查本地 DNS 解析或 hosts 設定： 若使用自訂網域（非 localhost 或 IP），請檢查 /etc/hosts 或本地 DNS 設定，確保網域解析至 127.0.0.1 或 ::1。

總結

Web 伺服器故障是本地開發常見挑戰。透過系統化檢查設定檔語法、分析錯誤日誌、確認服務運作狀態與檔案權限，大部分問題都能迎刃而解。ServBay 內建的故障診斷工具與 servbayctl 指令行工具是您強大的助手。如遇複雜問題，建議查閱更完整的 ServBay 文件，或聯絡技術支援團隊協助處理。