Generator Nginx PHP-FPM

Generator Nginx dla PHP-FPM

Nginx z PHP-FPM to najczęstsza konfiguracja aplikacji PHP na VPS-ie. Nginx serwuje pliki statyczne, a żądania do skryptów .php przekazuje przez FastCGI do procesu PHP-FPM. Generator buduje gotowy blok server dla trzech typów aplikacji: Laravel, WordPress i zwykły PHP, razem z nazwą pliku .conf i poleceniami wdrożenia dla Debiana i Ubuntu.

Najważniejsze dyrektywy

Laravel, WordPress i zwykły PHP

Laravel używa katalogu public jako root, a wszystkie adresy bez istniejącego pliku trafiają do public/index.php. WordPress działa na katalogu z wp-config.php i również potrzebuje przekazania do index.php, inaczej ładne permalinki zwracają 404. Tryb „Zwykły PHP” (root /var/www/html) nie ma front controllera: nieistniejący adres kończy się błędem 404 zamiast przekierowania do index.php.

Bezpieczeństwo

• Generator domyślnie blokuje pliki ukryte (.git, .env), z wyjątkiem .well-known potrzebnego do weryfikacji domeny.
• Opcjonalnie dodaje nagłówki X-Content-Type-Options, X-Frame-Options i Referrer-Policy, a przy HTTPS także HSTS na rok.
• Dostęp do xmlrpc.php w WordPressie i zakaz wykonywania PHP w katalogu uploadów musisz dopisać ręcznie (przykłady niżej).

Jak działa generator Nginx PHP-FPM

Generator buduje statyczny fragment konfiguracji Nginx na podstawie wybranych opcji: typu aplikacji, domen (do 10, oddzielonych spacją), katalogu głównego, adresu gniazda FPM, limitu uploadu i timeoutu. Nie łączy się z serwerem i nie uruchamia usług. Wynikiem jest blok server do skopiowania lub pobrania jako plik nazwany od pierwszej domeny, np. example.com.conf, który wklejasz do sites-available i włączasz przez symlink.

Mechanizm opiera się na podziale ról. Nginx najpierw sprawdza dopasowania dokładne (location = /favicon.ico), potem bloki z wyrażeniami regularnymi w kolejności zapisu, a gdy żaden nie pasuje, używa location /. Dla pliku statycznego zwraca go bezpośrednio z dysku z nagłówkami cache. Dla adresu, który nie wskazuje istniejącego pliku, reguła try_files kieruje żądanie do index.php. Dopiero wtedy działa blok PHP z fastcgi_pass, który przekazuje je do PHP-FPM przez gniazdo Unix lub TCP. Linia try_files $uri =404 wewnątrz bloku PHP zwraca 404 dla nieistniejących skryptów, zamiast przekazywać je do FPM.

Najczęstsze źródło problemów to niespójność dwóch wartości: root oraz SCRIPT_FILENAME. Generator składa SCRIPT_FILENAME z $document_root$fastcgi_script_name, więc wystarczy poprawny root. W Laravel root wskazuje katalog public; jeśli podasz inny, narzędzie pokaże ostrzeżenie. W WordPress root to katalog z wp-config.php, a front controller to index.php w tym samym miejscu.

Przykład konfiguracji krok po kroku

1. Wybierz tryb i root. Kliknięcie presetu ustawia root: Laravel /var/www/app/public, WordPress /var/www/wordpress, zwykły PHP /var/www/html. Domena w przykładzie to example.com z zaznaczoną opcją „Dodaj też www”, więc server_name to example.com www.example.com.
2. Ustal gniazdo PHP-FPM. Dla PHP 8.3 na Debianie i Ubuntu typowy adres to unix:/run/php/php8.3-fpm.sock, na RHEL i Fedorze unix:/run/php-fpm/www.sock. Sprawdź parametr listen w pliku puli, np. /etc/php/8.3/fpm/pool.d/www.conf. Jeśli PHP-FPM działa w osobnym kontenerze, wpisz adres TCP, np. 127.0.0.1:9000.
3. Reguła try_files. Dla Laravel i WordPress generator wstawia try_files $uri $uri/ /index.php?$query_string;. W Nginx zmienne $query_string i $args mają tę samą wartość, więc często spotykany w poradnikach WordPressa wariant z $args działa identycznie.
4. Włącz HTTPS. Opcja HTTPS dodaje osobny blok na porcie 80 z przekierowaniem 301 oraz blok na 443 ze ścieżkami /etc/letsencrypt/live/example.com/fullchain.pem i privkey.pem. W poleceniach wdrożenia pojawi się sudo certbot certonly --nginx -d example.com -d www.example.com.
5. Ustaw limity. Zwiększ client_max_body_size, jeśli aplikacja przyjmuje duże uploady (format 512k, 64m, 1g). Timeout FastCGI powyżej 300 s narzędzie oznacza ostrzeżeniem, bo długie żądania blokują procesy PHP-FPM.
6. Sprawdź i przeładuj. Zapisz plik, wykonaj sudo nginx -t i dopiero potem sudo systemctl reload nginx. Oczekiwany wynik to strona z kodem 200. Jeśli gniazdo FPM jest błędne, pojawi się 502 Bad Gateway, a szczegóły znajdziesz w /var/log/nginx/error.log.

Tabela referencyjna: Laravel, WordPress i zabezpieczenia

Praktyczne wskazówki przed wdrożeniem

• Najpierw zweryfikuj gniazdo FPM. Nazwa pliku zależy od wersji PHP i konfiguracji puli. Zamiast zgadywać, otwórz plik pool.d/www.conf i skopiuj wartość listen. Dzięki temu unikniesz 502 Bad Gateway po reloadzie.
• Certyfikat przed blokiem HTTPS. Nginx -t zgłosi błąd, jeśli plików fullchain.pem i privkey.pem jeszcze nie ma. Wdróż najpierw wersję bez HTTPS, wystaw certyfikat przez certbot, a potem podmień konfigurację.
• Nie wystawiaj portu FPM na świat. PHP-FPM nie ma uwierzytelniania. Przy adresie TCP innym niż 127.0.0.1 lub localhost generator pokazuje ostrzeżenie; taki port zamknij w firewallu.
• Zablokuj wykonywanie PHP w katalogach zapisywalnych. W WordPressie dodaj przed blokiem PHP regułę location ~* /wp-content/uploads/.*\.php$ { deny all; }. Bloki regex działają w kolejności zapisu, więc ta reguła musi stać wyżej niż location ~ \.php$. Sam zakaz nie chroni przed wszystkim, ale utrudnia uruchomienie webshella.

Czego generator nie uwzględnia

• Stanu środowiska. Narzędzie nie sprawdza, czy PHP-FPM działa, czy gniazdo istnieje i czy Nginx ma do niego uprawnienia. Te informacje musisz potwierdzić na serwerze.
• Konfiguracji PHP. Limity uploadu, memory_limit, czas wykonania i opcache ustawia się w php.ini lub w puli FPM. Sam client_max_body_size w Nginx nie wystarczy do obsługi dużych plików.
• Certyfikatów spoza Let’s Encrypt i wielu witryn. Ścieżki certyfikatu zakładają certbota. Inny dostawca wymaga ręcznej zmiany ssl_certificate, a każda kolejna aplikacja z innym root potrzebuje osobnego bloku server.
• Zaawansowanego proxy i kontenerów. Jeśli przed Nginx stoi Traefik, load balancer albo CDN, potrzebne są nagłówki X-Forwarded-For, X-Forwarded-Proto i zaufane adresy proxy. Generator nie modeluje całego łańcucha.