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:
bash
# 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
1
2
3
4
5
6
2
3
4
5
6
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:
bash
# 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
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
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:
bash
# macOS Big Sur (11) i nowszy
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
# macOS Catalina (10.15) i starsze
sudo killall -HUP mDNSResponder
1
2
3
4
5
2
3
4
5
5. Weryfikacja działania
Po oczyszczeniu, sprawdź jeszcze raz dostęp do strony ServBay:
- Otwórz adres strony w przeglądarce
- Użyj Narzędzi deweloperskich Chrome → zakładka Network
- Odśwież stronę i sprawdź dane w sekcji Timing
- 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.
bash
# 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
1
2
3
4
5
2
3
4
5
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:
bash# 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
1
2
3
4
5
6
7
8
9Jeś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ę):
bash# 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
1
2
3
4
5
6
7Ten 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
lubpublic_dir
.- macOS:
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
.
bash
# macOS
/Applications/ServBay/bin/nginx -t
# Windows
C:\ServBay\bin\nginx.exe -t
1
2
3
4
5
2
3
4
5
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
1
2
3
4
5
6
7
2
3
4
5
6
7
W przypadku błędów, komunikat wskaże plik oraz numer linii. Popularne błędy:
- Błędy składni: Brak średnika
;
, niedopasowane nawiasy{}
itd. - Błędna ścieżka pliku: Niepoprawny path w
include
lub innych lekturach plików. - Konflikt portów: Podany port jest już zajęty przez inny program.
Sprawdzanie konfiguracji Apache
Apache sprawdza konfigurację poleceniem apachectl configtest
.
bash
# macOS
/Applications/ServBay/bin/apachectl configtest
# Windows
C:\ServBay\bin\httpd.exe -t
1
2
3
4
5
2
3
4
5
Poprawność skryptu oznacza komunikat Syntax OK
. W razie błędów wyświetlane są szczegóły z powodem awarii. Typowe błędy:
- Błędne ładowanie modułów: Nieprawidłowa ścieżka lub brak modułu (
LoadModule
). - Błąd składni w .htaccess: Jeśli plik
.htaccess
w katalogu strony zawiera błędy, strona nie będzie dostępna. - 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:
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
lubcritical
.- Caddy:
Sprawdź, czy backendowa usługa (PHP-FPM) działa: Dla stron korzystających z PHP, upewnij się, że usługa PHP-FPM jest uruchomiona.
bashps aux | grep php-fpm
1Powinieneś zobaczyć linię z
php-fpm: master process
albophp-fpm: pool www
. Jeśli brak, to PHP-FPM nie działa. Uruchom PHP przez panel ServBay lubservbayctl
.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 opcjadisplay_errors
powinna być wyłączona, lecz na lokalnym możesz ją czasowo włączyć (php.ini
).- macOS:
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:
bashls -la /Applications/ServBay/www/twoja-strona/
1Upewnij 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:
cmddir C:\ServBay\www\twoja-strona
1Potwierdź, ż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:
- Konfiguracja FastCGI: Upewnij się, że w Caddyfile dyrektywy
php_fastcgi
lubreverse_proxy
wskazują na poprawny adres nasłuchu PHP-FPM (najczęściej127.0.0.1:9000
lubunix:/path/to/php-fpm.sock
). - Stan PHP-FPM: Sprawdź, czy wybrana wersja PHP oraz PHP-FPM jest uruchomiona w ServBay.
- Reverse proxy: Jeśli korzystasz z proxy do innych backendów (np. Node.js), sprawdź, czy port/usługa działa poprawnie.
- Konfiguracja FastCGI: Upewnij się, że w Caddyfile dyrektywy
NGINX:
fastcgi_pass
: W pliku konfiguracyjnym NGINX (nginx.conf
lub wybrany vhost) upewnij się, że dyrektywa kieruje żądania do właściwego PHP-FPM.client_max_body_size
: Zbyt niska wartość uniemożliwia upload większych plików – pojawia się błąd 500.- Dyrektywa
try_files
: Składnia musi pozwalać znaleźć plik indeksowy lub przekierować żądanie do fastcgi.
Apache:
mod_rewrite
: Jeśli stosujesz.htaccess
do rewritów, sprawdź, czy Apache ma aktywowany modułmod_rewrite
.- Poprawność
.htaccess
: Nawet mały błąd w składni.htaccess
wywoła 500. AllowOverride
: W konfiguracji Apache, katalog strony musi mieć zezwolenie (AllowOverride All
albo choćbyFileInfo
,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.
bash
# Restart Caddy
servbayctl restart caddy -all
# Restart NGINX
servbayctl restart nginx -all
# Restart Apache
servbayctl restart apache -all
1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
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.
bash
# Status Caddy
servbayctl status caddy -all
# Status NGINX
servbayctl status nginx -all
# Status Apache
servbayctl status apache -all
1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
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:
- Analiza narzędzi deweloperskich przeglądarki: Przejdź do
Konsoli (Console)
orazSieci (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. - Test poleceniem
curl -v
: W terminalu wpiszcurl -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. - 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.
- 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.
- 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
- macOS:
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.