Przewodnik po rozwiązywaniu problemów z serwerem WWW ServBay

ServBay obsługuje Caddy, NGINX i Apache jako domyślne serwery WWW, oferując elastyczne środowisko do rozwoju lokalnego. Podczas korzystania możesz napotkać problemy, takie jak brak dostępu do strony, powolne ładowanie lub pojawianie się błędów (np. 500 Internal Server Error). Ten przewodnik pomoże Ci zdiagnozować i rozwiązać najczęstsze problemy z serwerami WWW w środowisku ServBay.

Korzystanie z wbudowanego narzędzia diagnostyki błędów ServBay

ServBay udostępnia potężne narzędzie diagnostyczne, które automatycznie wykrywa i sygnalizuje typowe problemy z konfiguracją oraz usługami. Zdecydowanie zalecamy użycie tego narzędzia jako pierwszego kroku przy napotkaniu problemów.

Otwórz aplikację ServBay i kliknij Diagnostyka w lewym panelu nawigacyjnym, aby przejść do wbudowanego panelu diagnostycznego ServBay.

Narzędzie sprawdza status podstawowych komponentów ServBay, zajętość portów, składnię plików konfiguracyjnych oraz udziela odpowiednich wskazówek i zaleceń, pomagając szybko zlokalizować źródło problemu.

Sprawdzanie plików konfiguracyjnych serwera WWW

Błędy w konfiguracji serwera WWW są jedną z najczęstszych przyczyn niedostępności strony. ServBay zapewnia dedykowane narzędzia do sprawdzania poprawności składni dla każdego z serwerów.

Sprawdzanie Caddyfile

Aby zweryfikować poprawność pliku Caddyfile, użyj wbudowanej komendy validate w Caddy.

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

Jeśli składnia jest poprawna, komenda zwróci Valid configuration. W przypadku błędów pojawią się odpowiednie komunikaty zależne od ich rodzaju.

Uwaga: Komenda caddy validate może wypisać wiele komunikatów typu INFO lub WARN. Są to zazwyczaj informacje z procesu ładowania Caddy i nie zawsze oznaczają błąd w konfiguracji. Dopóki finalne hasło to Valid configuration, składnia jest poprawna.

Przykładowe błędy w Caddyfile:

• Brak pliku certyfikatu:

  2024/12/09 17:24:16.970 INFO using config from file {"file": "/Applications/ServBay/etc/caddy/Caddyfile"}
  ... (inne komunikaty 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

  Błąd typu loading certificates: open xxxxx: no such file or directory oznacza, że w Twoim pliku Caddyfile wskazano nieprawidłową ścieżkę do pliku certyfikatu SSL lub plik nie istnieje. Sprawdź, czy adresy do certyfikatu (.crt/.cer/.pem) oraz klucza prywatnego (.key) są poprawne i pliki rzeczywiście znajdują się pod podanymi ścieżkami. ServBay pozwala zarówno na ręczny import, jak i na automatyczne uzyskiwanie certyfikatów SSL przez ACME – zweryfikuj odpowiednie ustawienia SSL w ServBay.

• Błąd ścieżki katalogu głównego strony (zawiera spację):

  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

  Komunikat parsing caddyfile tokens for 'root': too many arguments zwykle pojawia się, gdy w ścieżce katalogu głównego strony występuje spacja. Przykładowo, root * /Applications/ServBay/www/public web traktuje public web jako dwa osobne parametry. Rozwiązanie: otocz ścieżkę ze spacjami cudzysłowami, np. root * "/Applications/ServBay/www/public web".

  Zalecenie: Aby uniknąć tego rodzaju problemów, nie używaj spacji ani znaków specjalnych w nazwach plików i katalogów. Możesz stosować myślniki - lub podkreślenia _ do oddzielania słów, np. public-folder lub public_dir.

• Błąd reguł Rewrite:

  Stosowanie reguł przepisywania (Rewrite), które nie są zgodne ze składnią Caddy, np. bezpośrednie kopiowanie konfiguracji z NGINX, prowadzi do błędów walidacji. Sprawdź dokumentację modułu Rewrite Caddy lub przejrzyj przewodnik ServBay o migracji witryn z NGINX, aby upewnić się, że reguły zostały poprawnie przepisane.

Sprawdzanie konfiguracji NGINX

Użyj parametru -t, aby sprawdzić poprawność składni i ważność konfiguracji NGINX.

/Applications/ServBay/bin/nginx -t

Jeżeli wszystko jest prawidłowe, pojawi się:

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

W przypadku błędów NGINX wskaże nieprawidłowy plik i numer linii. Najczęstsze błędy NGINX to:

1. Błąd składni: np. brak średnika ;, niezamknięty nawias } itp.
2. Błąd w ścieżce do pliku: np. niepoprawny adres pliku lub katalogu w include bądź innej dyrektywie.
3. Konflikt portów: port ustawiony do nasłuchu jest już używany przez inny program.

Sprawdzanie konfiguracji Apache

Skorzystaj z komendy apachectl configtest, aby zweryfikować poprawność pliku konfiguracyjnego Apache.

/Applications/ServBay/bin/apachectl configtest

Poprawna konfiguracja zostanie potwierdzona komunikatem Syntax OK. W przypadku błędów pojawi się ich szczegółowy opis. Najczęstsze błędy Apache to:

1. Nieudane ładowanie modułów: np. żądany przez LoadModule moduł nie istnieje lub jest zła ścieżka.
2. Błędy składni w pliku .htaccess: obecność błędów składniowych w .htaccess może wywołać błąd całkowity lub ograniczony do określonego katalogu.
3. Nieprawidłowe ustawienia uprawnień katalogów: dyrektywy Directory i Files, szczególnie Require, Allow, Deny mogą zablokować dostęp do plików strony.

Radzenie sobie z błędem 500 Internal Server Error

500 Internal Server Error to uniwersalny kod HTTP, który oznacza, że serwer nie był w stanie poprawnie zrealizować żądania z powodu nieoczekiwanego problemu. Najczęściej dotyczy to niepowodzenia skryptu backendowego (np. PHP, Python, Node.js).

Ogólna procedura diagnozowania błędu 500

Gdy zobaczysz błąd 500, przeprowadź następujące kroki:

1. Sprawdź dzienniki błędów serwera WWW: To podstawowy krok. Logi zawierają szczegółowe informacje o przyczynie problemu, np. błędy skryptów, brakujące pliki, brak uprawnień.

   • Caddy: /Applications/ServBay/var/logs/caddy/error.log
   • NGINX: /Applications/ServBay/var/logs/nginx/error.log
   • Apache: /Applications/ServBay/var/logs/apache/error.log Przejrzyj najnowsze wpisy, szukając informacji z frazami error lub critical.

2. Upewnij się, że usługa backendowa (np. PHP-FPM) działa: Jeśli Twoja strona korzysta z PHP, sprawdź czy PHP-FPM jest uruchomiony.

   ps aux | grep php-fpm

   Odnajdź linie zawierające php-fpm: master process lub php-fpm: pool www. Brak procesów oznacza, że PHP-FPM nie działa lub się zawiesił. Możesz go uruchomić z poziomu interfejsu ServBay lub poleceniem servbayctl.

3. Przejrzyj dzienniki błędów backendu (np. PHP): Jeśli logi WWW wskazują na błąd FastCGI lub backendu, sprawdź dziennik błędów backendowego języka.

   • PHP: /Applications/ServBay/var/logs/php/php_error.log Przeszukaj log pod kątem informacji typu Fatal error, Parse error, Warning, Notice, zwłaszcza tych związanych z odwiedzaną stroną. Pamiętaj, że w środowisku produkcyjnym display_errors powinien być wyłączony, ale w deweloperskim można go tymczasowo włączyć w php.ini dla lepszej diagnostyki.

4. Sprawdź uprawnienia plików i katalogów: Proces serwera WWW działa zwykle pod konkretnym użytkownikiem (np. _www) i potrzebuje mieć wystarczające uprawnienia do odczytu plików strony oraz zapisu w katalogach do uploadu bądź logów.

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

   Upewnij się, że użytkownik serwera WWW ma prawa odczytu do katalogu głównego i wszystkich podkatalogów/pliki strony. Katalogi do uploadu lub logów wymagają także praw zapisu. Uprawnienia i właściciela zmienisz poleceniami chmod i chown – zachowaj jednak ostrożność.

Charakterystyczne źródła błędów 500 w poszczególnych serwerach WWW

• Caddy:

  1. Konfiguracja FastCGI: Sprawdź, czy w Caddyfile dyrektywa php_fastcgi lub reverse_proxy wskazuje poprawnie na adres nasłuchu PHP-FPM (typowo 127.0.0.1:9000 lub unix:/ścieżka/do/php-fpm.sock).
  2. Stan PHP-FPM: Upewnij się, że odpowiednia wersja PHP i PHP-FPM jest aktywna w ServBay.
  3. Reverse proxy: Jeżeli używasz reverse_proxy do aplikacji backendowej (np. Node.js), potwierdź poprawność adresu, portu i działanie backendu.

• NGINX:

  1. Dyrektywa fastcgi_pass: Zweryfikuj, czy w nginx.conf lub odpowiednim pliku konfiguracyjnym witryny adres fastcgi_pass prawidłowo wskazuje na PHP-FPM.
  2. client_max_body_size: W razie błędów 500 przy uploadzie dużych plików sprawdź, czy limit ten nie jest zbyt niski.
  3. Dyrektywa try_files: Sprawdź poprawność konfiguracji, by zapewnić odszukanie właściwego pliku indeksowego lub przekazanie żądania do FastCGI.

• Apache:

  1. Moduł mod_rewrite: Jeśli używasz przepisywania URL w .htaccess, upewnij się, że moduł jest aktywny.
  2. Zawartość pliku .htaccess: Błędy składni (np. w RewriteRule) w pliku .htaccess często prowadzą do błędu 500. Zweryfikuj strukturę pliku.
  3. Dyrektywa AllowOverride: Upewnij się w konfiguracji Apache, że dla katalogu zezwolono na działanie poleceń z plików .htaccess (najczęściej All lub przynajmniej FileInfo, Limit).

Zarządzanie usługami

Po wprowadzeniu zmian w konfiguracji lub naprawieniu błędów backendu zwykle konieczny jest restart serwera WWW lub powiązanych usług, by zmiany zaczęły obowiązywać.

Restart usług

Użyj polecenia servbayctl restart, by ponownie uruchomić wybraną usługę serwera WWW.

# Restart usługi Caddy
servbayctl restart caddy -all

# Restart usługi NGINX
servbayctl restart nginx -all

# Restart usługi Apache
servbayctl restart apache -all

Opcja -all spróbuje również ponownie uruchomić powiązane usługi, np. jeśli korzystasz z FastCGI, to podczas restartu Caddy/NGINX/Apache również PHP-FPM zostanie zrestartowany.

Sprawdzenie statusu usług

Polecenie servbayctl status pozwala zweryfikować aktualny stan wybranej usługi.

# Sprawdzenie statusu usługi Caddy
servbayctl status caddy -all

# Sprawdzenie statusu usługi NGINX
servbayctl status nginx -all

# Sprawdzenie statusu usługi Apache
servbayctl status apache -all

Wyjście komendy pokaże, czy usługa jest w stanie running (działa), stopped (zatrzymana) lub innym. Dzięki temu potwierdzisz, czy uruchomienie przebiegło pomyślnie.

Zaawansowane kroki diagnostyczne

Jeśli powyższe metody nie przyniosą efektu, spróbuj poniższych, bardziej szczegółowych kroków:

1. Sprawdź narzędzia deweloperskie przeglądarki: Otwórz narzędzia deweloperskie (zwykle F12), przejdź do zakładek Konsola (Console) i Sieć (Network). Zwróć uwagę na błędy JavaScript, kody odpowiedzi żądań, nagłówki i treści odpowiedzi – pomoże to określić, czy problem leży po stronie backendu, czy frontendu.
2. Użyj polecenia curl -v: W terminalu wykonaj curl -v your-website.servbay.demo. Opcja -v wyświetli szczegóły żądania i odpowiedzi, łącznie z nagłówkami oraz informacjami o połączeniu SSL/TLS. Zastąp your-website.servbay.demo faktyczną domeną Twojej strony w ServBay.
3. Tymczasowo wyłącz zaporę ogniową: Lokalny firewall (np. wbudowany w macOS lub aplikacja zewnętrzna) może blokować połączenia. Na czas testów wyłącz firewall, a jeśli problem zniknie – dodaj odpowiednie reguły przepuszczające ruch na portach ServBay (np. 80, 443).
4. Przetestuj na innych przeglądarkach/urządzeniach: Sprawdź stronę w innej przeglądarce lub na innym sprzęcie, by wykluczyć błędy cache lub indywidualnych ustawień.
5. Zweryfikuj lokalne ustawienia DNS lub plik hosts: Przy niestandardowych domenach (nie localhost czy IP) sprawdź plik /etc/hosts lub ustawienia DNS, by domena kierowała na 127.0.0.1 lub ::1.

Podsumowanie

Problemy z serwerami WWW są częstym wyzwaniem podczas lokalnego developmentu. Systematyczne sprawdzanie składni plików konfiguracyjnych, analiza dzienników błędów, weryfikacja stanu usług oraz uprawnień plików pozwalają rozwiązać większość problemów. Wbudowane narzędzia diagnostyczne oraz polecenia servbayctl stanowią ogromną pomoc. W przypadku trudniejszych przypadków sięgnij po szczegółowe dokumentacje ServBay lub skontaktuj się z zespołem wsparcia technicznego.