Przewodnik rozwiązywania problemów z serwerem WWW ServBay

ServBay umożliwia korzystanie z Caddy, NGINX lub Apache jako domyślnego serwera WWW, oferując elastyczne środowisko lokalne dla programistów. W trakcie pracy możesz napotkać problemy z dostępem do stron, powolnym ładowaniem lub błędami (np. 500 Internal Server Error). Ten przewodnik pomoże Ci zdiagnozować oraz rozwiązać typowe awarie serwerów WWW w ekosystemie ServBay.

Korzystanie z wbudowanego narzędzia diagnostycznego ServBay

ServBay posiada zaawansowane, wbudowane narzędzie diagnostyczne, które automatycznie wykrywa i podpowiada najczęstsze problemy związane z konfiguracją i usługami. Jeśli pojawią się problemy, zalecamy rozpoczęcie od samodzielnego przeszukania błędów za pomocą tego narzędzia.

Otwórz aplikację ServBay, a następnie wybierz Diagnostyka w menu po lewej stronie, aby przejść do dedykowanego panelu diagnostyki.

Narzędzie sprawdza stan kluczowych komponentów ServBay, zajętość portów, składnię plików konfiguracyjnych i podaje przydatne wskazówki oraz sugestie, umożliwiając szybkie namierzenie źródła problemów.

Powolny dostęp do strony po migracji z MAMP lub Laravel Herd

Jeśli przechodzisz z MAMP lub Laravel Herd na ServBay i zauważysz, że po okresach bezczynności pierwsze wejście na stronę lokalną trwa ponad 5 sekund, podczas gdy kolejne próby są już szybkie, to występuje typowy problem z DNS. Po kolejnym okresie bezczynności znów pojawiają się opóźnienia przy pierwszym wejściu.

Objawy problemu

Otwórz Narzędzia deweloperskie Chrome (F12 lub Cmd+Option+I), przejdź do zakładki Sieć (Network), odśwież stronę i sprawdź szczegóły Timing. Zwróć uwagę, ile trwa DNS Lookup – często będzie to około 5 sekund.

(Wskazówka: patrz kolumna DNS Lookup w Narzędziach deweloperskich Chrome, zakładka Network)

Przyczyna problemu

MAMP i Laravel Herd podczas instalacji modyfikują ustawienia DNS macOS, tworząc specjalne pliki konfiguracyjne DNS w celu przechwytywania wybranych domen (np. *.test, *.local itd.). Pliki te zlokalizowane są zazwyczaj w /etc/resolver/.

Nawet po odinstalowaniu MAMP lub Herd pliki DNS mogą pozostać w systemie. W efekcie, podczas próby odwiedzenia strony o takim samym sufiksie (.test itd.), macOS najpierw próbuje wykonać zapytanie DNS przez stary resolver, który już nie działa – to skutkuje timeoutem (zwykle 5 sekund). Dopiero potem system korzysta z domyślnego DNS.

Rozwiązanie

Wykonaj te kroki, aby całkowicie usunąć pozostałości konfiguracji DNS po MAMP/Herd:

1. Prawidłowe odinstalowanie MAMP lub Laravel Herd

Jeśli jeszcze nie odinstalowałeś MAMP lub Herd, skorzystaj z oficjalnych deinstalatorów lub skryptów usuwających:

Deinstalacja MAMP:

• Z aplikacji MAMP użyj funkcji odinstalowania
• Lub ręcznie usuń katalog /Applications/MAMP i skasuj odpowiednie pliki konfiguracyjne

Deinstalacja Laravel Herd:

# Oficjalne polecenie deinstalujące Herd
herd uninstall

# Jeśli polecenie nie działa, usuń aplikację i katalogi konfiguracyjne ręcznie
rm -rf ~/Library/Application\ Support/Herd
rm -rf ~/.config/herd

2. Usuń pozostałe pliki z katalogu /etc/resolver

Po nawet poprawnej deinstalacji MAMP lub Herd, w /etc/resolver/ mogą pozostać stare pliki DNS. Musisz je usunąć samodzielnie:

# Wyświetlenie listy plików w /etc/resolver
ls -la /etc/resolver

# Usuwanie plików konfiguracyjnych, np. test i local
sudo rm /etc/resolver/test
sudo rm /etc/resolver/local

# Jeśli znajdziesz inne pliki utworzone przez MAMP/Herd, usuń je też, np.
# sudo rm /etc/resolver/herd

Najczęstsze pliki utworzone przez MAMP/Herd:

• test – obsługa domen *.test
• local – obsługa domen *.local
• herd – dedykowany dla Laravel Herd

Uwaga: Usuwanie wymaga uprawnień administratora (sudo).

3. Unikaj używania sufiksu *.local dla domen deweloperskich

macOS rezerwuje końcówkę domeny *.local dla mDNS (Multicast DNS, czyli Bonjour) w lokalnej sieci LAN. Użycie .local dla testowych stron może powodować:

• Konflikty DNS
• Spowolniony dostęp
• Nieprzewidywalne zachowanie sieci

Rekomendacja: Wykorzystuj inne sufiksy domen dla środowiska deweloperskiego, np.:

• .test – dedykowana domena dla testów
• .localhost – przemapowuje na adres zwrotny
• .dev – choć to realna TLD, jest często wykorzystywana lokalnie
• Albo własny, rekomendowany przez ServBay sufiks

4. Wyczyść cache DNS (opcjonalnie)

Po powyższej procedurze warto wyczyścić cache DNS, by zmiany były natychmiastowe:

# macOS Big Sur (11) i nowszy
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

# macOS Catalina (10.15) i starsze
sudo killall -HUP mDNSResponder

5. Weryfikacja działania

Po oczyszczeniu, sprawdź jeszcze raz dostęp do strony ServBay:

1. Otwórz adres strony w przeglądarce
2. Użyj Narzędzi deweloperskich Chrome → zakładka Network
3. Odśwież stronę i sprawdź dane w sekcji Timing
4. Upewnij się, że DNS Lookup trwa już krótko (zwykle poniżej 50ms)

W ten sposób rozwiążesz problem powolnego pierwszego wejścia po migracji z MAMP/Herd. Jeśli problem pozostaje, sprawdź czy inne programy (VPN, proxy) nie zakłócają zapytań DNS.

Sprawdzanie plików konfiguracyjnych serwera WWW

Błędy w plikach konfiguracyjnych to najczęstsza przyczyna niedziałających stron. ServBay oferuje narzędzia do sprawdzania składni dla każdego serwera WWW.

Sprawdzanie Caddyfile

Użyj wbudowanego polecenia Caddy validate, aby sprawdzić czy Caddyfile jest poprawny.

# 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

Przy poprawnej konfiguracji pojawi się Valid configuration. W razie błędów komenda wskaże, co jest źle.

Uwaga: Polecenie caddy validate może generować wiele komunikatów INFO/WARN (informacje o działaniu Caddy), które nie muszą oznaczać błędu. Liczy się końcowy komunikat Valid configuration.

Typowe błędy Caddyfile:

• Błąd związany z brakiem pliku certyfikatu SSL:

  # macOS – przykład
  2024/12/09 17:24:16.970 INFO using config from file {"file": "/Applications/ServBay/etc/caddy/Caddyfile"}
  ... (inne 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 – przykład
  2024/12/09 17:24:16.970 INFO using config from file {"file": "C:\\ServBay\\etc\\caddy\\Caddyfile"}
  ... (inne 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

  Jeśli pojawia się komunikat loading certificates: open xxxxx: no such file or directory, oznacza to niepoprawną ścieżkę do plików certyfikatów SSL w Caddyfile lub ich brak. Zweryfikuj poprawność ścieżek do certyfikatów (.crt/.cer/.pem) oraz kluczy prywatnych (.key). ServBay umożliwia ręczny import oraz automatyczne generowanie certyfikatów za pomocą ACME – sprawdź ustawienia SSL w ServBay.

• Błąd ścieżki katalogu root (zawiera spację):

  # macOS – przykład
  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 – przykład
  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

  Ten błąd parsing caddyfile tokens for 'root': too many arguments często wynika ze spacji w ścieżce katalogu. Przykłady:

  • macOS: root * /Applications/ServBay/www/public web – public web zostanie potraktowany jako dwa argumenty.
  • Windows: root * C:\ServBay\www\public web – również dwa argumenty.

  Aby poprawić błąd, otocz ścieżkę zawierającą spację cudzysłowami ":

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

  Rekomendacja: Unikaj spacji i znaków specjalnych w nazwach plików/katalogów. Używaj myślnika - lub podkreślenia _, np. public-folder lub public_dir.

• Błąd reguł rewrite:

  Skopiowanie reguł z NGINX do Caddyfile bez dostosowania składni spowoduje błędy walidacji. Odnoś się do dokumentacji Rewrite dla Caddy i poradników ServBay (Migracja stron z NGINX do ServBay).

Sprawdzanie konfiguracji NGINX

Do sprawdzania składni i poprawności konfiguracji NGINX służy parametr -t.

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

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

Przy poprawnej konfiguracji zobaczysz:

# 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

W przypadku błędów, komunikat wskaże plik oraz numer linii. Popularne błędy:

1. Błędy składni: Brak średnika ;, niedopasowane nawiasy {} itd.
2. Błędna ścieżka pliku: Niepoprawny path w include lub innych lekturach plików.
3. Konflikt portów: Podany port jest już zajęty przez inny program.

Sprawdzanie konfiguracji Apache

Apache sprawdza konfigurację poleceniem apachectl configtest.

# macOS
/Applications/ServBay/bin/apachectl configtest

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

Poprawność skryptu oznacza komunikat Syntax OK. W razie błędów wyświetlane są szczegóły z powodem awarii. Typowe błędy:

1. Błędne ładowanie modułów: Nieprawidłowa ścieżka lub brak modułu (LoadModule).
2. Błąd składni w .htaccess: Jeśli plik .htaccess w katalogu strony zawiera błędy, strona nie będzie dostępna.
3. Niepoprawne uprawnienia katalogów: Instrukcje Directory, Files (Require, Allow, Deny) blokują dostęp do plików.

Diagnozowanie błędu 500 Internal Server Error

500 Internal Server Error (błąd serwera) wskazuje, że serwer napotkał nieoczekiwany problem obsługując żądanie. W przypadku stron WWW oznacza to zwykle awarię backendu – np. skryptu PHP/Python/Node.js.

Uniwersalne kroki diagnostyczne

Widząc błąd 500 wykonaj:

1. Sprawdź logi błędów serwera WWW: To najważniejsze miejsce do wskazania przyczyn 500. Logi podpowiadają, czy problemem jest skrypt, brak pliku, złe uprawnienia itd.

   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

   Sprawdź ostatnie wpisy z frazą error lub critical.

2. Sprawdź, czy backendowa usługa (PHP-FPM) działa: Dla stron korzystających z PHP, upewnij się, że usługa PHP-FPM jest uruchomiona.

   ps aux | grep php-fpm

   Powinieneś zobaczyć linię z php-fpm: master process albo php-fpm: pool www. Jeśli brak, to PHP-FPM nie działa. Uruchom PHP przez panel ServBay lub servbayctl.

3. Sprawdź logi błędów backendu (PHP):

   Lokalizacja logów PHP:

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

   Szukaj wpisów typu Fatal error, Parse error, Warning, Notice związanych ze skryptem, który wywołujesz. W środowisku produkcyjnym opcja display_errors powinna być wyłączona, lecz na lokalnym możesz ją czasowo włączyć (php.ini).

4. Sprawdź uprawnienia plików i katalogów:

   Proces serwera pracuje pod określonym użytkownikiem, musi mieć prawo czytać pliki strony oraz zapisywać w katalogach (np. upload/logi).

   macOS:

   ls -la /Applications/ServBay/www/twoja-strona/

   Upewnij się, że użytkownik serwera (np. _www) ma dostęp do katalogów i plików. Dla uploadu/logów – prawo zapisu (chmod, chown).

   Windows:

   dir C:\ServBay\www\twoja-strona

   Potwierdź, że użytkownik ServBay ma dostęp do katalogu. Zmień ustawienia w zakładce Bezpieczeństwo pliku/katalogu.

Jak sprawdzać błąd 500 w zależności od serwera WWW

• Caddy:

  1. Konfiguracja FastCGI: Upewnij się, że w Caddyfile dyrektywy php_fastcgi lub reverse_proxy wskazują na poprawny adres nasłuchu PHP-FPM (najczęściej 127.0.0.1:9000 lub unix:/path/to/php-fpm.sock).
  2. Stan PHP-FPM: Sprawdź, czy wybrana wersja PHP oraz PHP-FPM jest uruchomiona w ServBay.
  3. Reverse proxy: Jeśli korzystasz z proxy do innych backendów (np. Node.js), sprawdź, czy port/usługa działa poprawnie.

• NGINX:

  1. fastcgi_pass: W pliku konfiguracyjnym NGINX (nginx.conf lub wybrany vhost) upewnij się, że dyrektywa kieruje żądania do właściwego PHP-FPM.
  2. client_max_body_size: Zbyt niska wartość uniemożliwia upload większych plików – pojawia się błąd 500.
  3. Dyrektywa try_files: Składnia musi pozwalać znaleźć plik indeksowy lub przekierować żądanie do fastcgi.

• Apache:

  1. mod_rewrite: Jeśli stosujesz .htaccess do rewritów, sprawdź, czy Apache ma aktywowany moduł mod_rewrite.
  2. Poprawność .htaccess: Nawet mały błąd w składni .htaccess wywoła 500.
  3. AllowOverride: W konfiguracji Apache, katalog strony musi mieć zezwolenie (AllowOverride All albo choćby FileInfo, Limit) na wywoływanie instrukcji z .htaccess.

Zarządzanie usługami serwera WWW

Po zmianie konfiguracji lub naprawie backendu wymagany jest restart serwera WWW lub wybranych usług, by zmiany zadziałały.

Restart usług

Użyj polecenia servbayctl restart, by zresetować wybrany serwer WWW.

# Restart Caddy
servbayctl restart caddy -all

# Restart NGINX
servbayctl restart nginx -all

# Restart Apache
servbayctl restart apache -all

Opcja -all restartuje także powiązane usługi, np. PHP-FPM dla serwerów obsługujących FastCGI.

Sprawdzanie statusu usług

Polecenie servbayctl status pozwala sprawdzić aktualny status wybranego serwera.

# Status Caddy
servbayctl status caddy -all

# Status NGINX
servbayctl status nginx -all

# Status Apache
servbayctl status apache -all

Wynik pokazuje czy usługa jest running (uruchomiona), stopped (zatrzymana) itd. Ułatwia to monitorowanie uruchomienia/zatrzymania.

Zaawansowane kroki diagnostyczne

Gdy standardowa diagnoza nie wystarczy, możesz podjąć poniższe działania:

1. Analiza narzędzi deweloperskich przeglądarki: Przejdź do Konsoli (Console) oraz Sieci (Network) w przeglądarce (F12), sprawdź błędy JS, statusy żądań, nagłówki i ciało odpowiedzi. To pozwala ustalić czy awaria wynika z frontendu czy backendu.
2. Test poleceniem curl -v: W terminalu wpisz curl -v twoja-strona.servbay.demo. Parametr -v pokaże pełen przebieg żądania: nagłówki, SSL/TLS, itp. Zamień twoja-strona.servbay.demo na faktyczną domenę z ServBay.
3. Tymczasowe wyłączenie zapory sieciowej: Lokalny firewall (np. macOS) albo programy bezpieczeństwa mogą blokować porty (np. 80, 443). Wyłącz tymczasowo zaporę, testuj dostępność. Jeśli działa, ustaw odpowiednie reguły firewall.
4. Test na innych przeglądarkach/urządzeniach: Sprawdź, czy problem występuje także w innych przeglądarkach lub na innych komputerach, by wykluczyć błąd cache lub lokalnej konfiguracji.
5. Sprawdzenie lokalnych wpisów DNS/hosts: Przy domenach niestandardowych, sprawdź plik hosts lub ustawienia lokalnego DNS, czy domena wskazuje na 127.0.0.1 lub ::1.
   • macOS: /etc/hosts
   • Windows: C:\Windows\System32\drivers\etc\hosts

Podsumowanie

Usterki serwera WWW to codzienność w lokalnym środowisku deweloperskim. Przeprowadzając systematyczną kontrolę składni, analizę logów błędów, sprawdzając status usług oraz uprawnienia do plików, większość awarii można wyeliminować. Wbudowane narzędzia diagnostyczne ServBay oraz polecenia servbayctl są niezastąpionymi pomocnikami. W razie złożonych problemów, korzystaj z dokumentacji ServBay lub skontaktuj się z zespołem wsparcia technicznego.