Pterodactyl Panel: kompletna instalacja na własnym VPS

Zainstalujemy na Twoim VPS Pterodactyl Panel, interfejs WWW do zarządzania serwerami gier. Po zakończeniu będzie działać pod https://panel.example.cz z certyfikatem Let's Encrypt, kolejką zadań, cronem i Twoim kontem admina.

Jak to działa#

Pterodactyl ma dwie części. Panel to aplikacja WWW (PHP, framework Laravel), w której tworzysz użytkowników i serwery i w której gracze sterują konsolą. Wings to usługa, która faktycznie uruchamia serwery gier w kontenerach Dockera. Panel i Wings mogą działać na tym samym VPS. Ten poradnik instaluje Panel; Wings dodasz w kolejnym poradniku Pterodactyl Wings.

Panel potrzebuje kilku innych programów:

Sam Panel jest lekki. Jeśli na tym samym VPS będą działać serwery gier, RAM planuj głównie pod nie i dodaj rezerwę na system, bazę danych i Panel (mniej więcej 1–⁠2 GB).

Plan instalacji#

Domena i DNS#

Panel potrzebuje własnej domeny lub subdomeny. Certyfikaty HTTPS są wystawiane dla domen, nie dla adresów IP.

1. W strefie klienta otwórz Moje usługi, kliknij swój VPS i w zakładce Sieć skopiuj adres IPv4 (i opcjonalnie adres IPv6).

2. U dostawcy DNS utwórz rekord A dla panel.example.cz z adresem IPv4 VPS (na przykład 203.0.113.10).

3. Opcjonalnie utwórz też rekord AAAA z adresem IPv6 VPS (na przykład 2001:db8::10). Poniższa konfiguracja Nginx nasłuchuje także na IPv6.

4. Na VPS sprawdź, czy domena już wskazuje we właściwe miejsce:

   getent hosts panel.example.cz

   • getent hosts – pyta systemowy DNS o adres domeny i go wypisuje.

   Zobaczysz linię z adresem IP swojego VPS. Jeśli nic się nie wypisuje, poczekaj kilka minut (zależnie od TTL rekordu) i spróbuj ponownie.

Firewall#

Przeglądarka łączy się z Panelem na porcie 443 (HTTPS). Port 80 (HTTP) jest potrzebny do walidacji domeny przy wystawianiu certyfikatu i do przekierowania na HTTPS.

• Firewall w strefie klienta: jeśli ruch przychodzący jest ustawiony na Blokuj wszystko poza dozwolonym, dodaj reguły Przychodzący · Zezwól · TCP · port 80,443. Reguła SSH (port 22) musi zostać. Poradnik: Firewall w strefie klienta.

• UFW na VPS: jeśli go używasz, zezwól na porty także tam:

  ufw allow 80/tcp
  ufw allow 443/tcp

  • ufw allow 80/tcp – zezwala na przychodzące połączenia TCP na port 80.
  • ufw allow 443/tcp – to samo dla portu 443.

Porty dla Wings (8080 i 2022) i serwerów gier otworzysz w poradniku Pterodactyl Wings.

Instalacja zależności#

Najpierw zaktualizuj system, aby instalować na aktualnej bazie:

apt update && apt -y upgrade

• apt update – pobiera aktualną listę pakietów.
• apt -y upgrade – instaluje dostępne aktualizacje; -y odpowiada „tak” na potwierdzenie.

Następnie zainstaluj zależności. Kroki zależą od systemu: Ubuntu 24.04 ma PHP 8.3 bezpośrednio w repozytorium, natomiast domyślne repozytorium Debiana 13 ma PHP 8.4, którego Panel nie obsługuje (aktualny Panel wymaga PHP 8.2 lub 8.3). Na Debianie dodasz więc repozytorium packages.sury.org, które zaleca także oficjalna dokumentacja Pterodactyla.

Co zawiera polecenie instalacji:

Sprawdź, czy masz właściwą wersję PHP:

php -v

PHP 8.3.x (cli) …

Pierwsza linia musi mówić PHP 8.3. Jeśli widzisz PHP 8.4, zobacz Rozwiązywanie problemów.

Sprawdź, czy usługi działają:

systemctl is-active mariadb redis-server nginx php8.3-fpm

• systemctl is-active – wypisuje stan każdej wymienionej usługi.

Zobaczysz cztery razy active. Jeśli któraś jest inactive, uruchom ją i włącz przy starcie przez systemctl enable --now <NAZWA_USLUGI>, na przykład systemctl enable --now redis-server.

Composer#

Composer pobiera biblioteki PHP Panelu. Zainstaluj go oficjalnym instalatorem:

curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer

• curl -sS https://getcomposer.org/installer – pobiera skrypt instalacyjny Composera.
• | php -- – przekazuje skrypt do wykonania przez PHP; -- oddziela parametry PHP od parametrów instalatora.
• --install-dir=/usr/local/bin – gdzie Composer się instaluje (katalog, w którym system szuka programów).
• --filename=composer – nazwa programu, więc uruchamiasz go potem poleceniem composer.

Kontrola: composer --version wypisuje Composer version 2.…. Jako root zobaczysz też ostrzeżenie Do not run Composer as root/super user! i ewentualnie pytanie Continue as root/super user [yes]?. Potwierdź je klawiszem Enter. Podczas instalacji Panelu niżej zmienna COMPOSER_ALLOW_SUPERUSER=1 wycisza ostrzeżenie.

Pobieranie Panelu#

1. Utwórz katalog dla Panelu i przejdź do niego:

   mkdir -p /var/www/pterodactyl
   cd /var/www/pterodactyl

   • mkdir -p – tworzy katalog (łącznie z nadrzędnymi); jeśli już istnieje, nie wypisuje błędu.
   • cd – przechodzi do katalogu. Wszystkie dalsze polecenia php artisan uruchamiaj w nim.

2. Pobierz i rozpakuj najnowsze wydanie Panelu:

   curl -Lo panel.tar.gz https://github.com/pterodactyl/panel/releases/latest/download/panel.tar.gz
   tar -xzvf panel.tar.gz

   • curl -Lo panel.tar.gz … – pobiera archiwum najnowszego wydania z GitHuba i zapisuje je jako panel.tar.gz.
   • tar -xzvf – rozpakowuje archiwum (x rozpakuj, z format gzip, v wypisuj pliki, f z pliku).

3. Ustaw uprawnienia katalogów, do których Panel pisze:

   chmod -R 755 storage/* bootstrap/cache/

   • chmod -R 755 – właściciel może czytać, pisać i wchodzić do katalogów; wszyscy pozostali tylko czytać i wchodzić. -R dotyczy całej zawartości.
   • storage/ – logi, cache i przesłane pliki; bootstrap/cache/ – skompilowana konfiguracja.

Baza danych dla Panelu#

Panel potrzebuje własnej bazy danych i własnego użytkownika. Autorzy Pterodactyla wprost zabraniają używania dla Panelu użytkownika bazy root: gdyby ktoś przejął Panel, dostałby dostęp do wszystkich baz na VPS.

1. Wygeneruj silne hasło dla użytkownika bazy, na przykład generatorem haseł. Używaj tylko liter i cyfr (co najmniej 24 znaki), aby nie borykać się ze znakami specjalnymi w SQL i w .env. Zapisz hasło; za chwilę będzie znów potrzebne.

2. Zaloguj się do MariaDB jako administrator:

   mariadb

   • mariadb – klient bazy danych. Zarówno na Ubuntu, jak i na Debianie systemowy użytkownik root loguje się do MariaDB bez hasła (przez uwierzytelnianie unix socket). Zobaczysz znak zachęty MariaDB [(none)]>.

3. Utwórz użytkownika i bazę danych. Zamiast <HASLO_DB_PANELU> wstaw hasło z kroku 1 (zachowaj pojedyncze cudzysłowy wokół niego):

   CREATE USER 'pterodactyl'@'127.0.0.1' IDENTIFIED BY '<HASLO_DB_PANELU>';
   CREATE DATABASE panel;
   GRANT ALL PRIVILEGES ON panel.* TO 'pterodactyl'@'127.0.0.1';
   exit

Konfiguracja środowiska (.env)#

Ustawienia Panelu są w /var/www/pterodactyl/.env. Utworzysz go z szablonu, zainstalujesz biblioteki i wygenerujesz klucz szyfrowania.

1. Skopiuj szablon:

   cp .env.example .env

2. Zainstaluj biblioteki PHP Panelu:

   COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader

   • COMPOSER_ALLOW_SUPERUSER=1 – pozwala Composerowi działać jako root bez pytania.
   • composer install – pobiera biblioteki dokładnie w wersjach określonych przez Panel (plik composer.lock).
   • --no-dev – pomija narzędzia deweloperskie niepotrzebne na serwerze produkcyjnym.
   • --optimize-autoloader – przygotowuje szybsze wczytywanie klas PHP.

   Instalacja trwa kilka minut i kończy się bez komunikatów o błędach (żółte ostrzeżenie o przestarzałych pakietach jest w porządku).

3. Wygeneruj klucz szyfrowania:

   php artisan key:generate --force

   • php artisan – narzędzie Panelu do zarządzania z wiersza poleceń.
   • key:generate – tworzy losowy APP_KEY i zapisuje go w .env.
   • --force – wykonuje polecenie bez potwierdzenia (Panel działa w trybie produkcyjnym, gdzie inaczej by zapytał).

4. Wyświetl klucz i zapisz całą linię gdzieś poza serwerem (w menedżerze haseł lub zaszyfrowanym pliku na komputerze):

   grep APP_KEY /var/www/pterodactyl/.env

   APP_KEY=base64:…

Kreator p:environment:setup#

Podstawową konfigurację załatwia kreator. Uruchom go:

php artisan p:environment:setup

Zadaje po kolei następujące pytania (wartość domyślna jest w nawiasach kwadratowych; potwierdzasz ją klawiszem Enter):

Gdy wpiszesz adres zaczynający się od https://, kreator sam włącza bezpieczne ciasteczka (SESSION_SECURE_COOKIE=true).

Kreator p:environment:database#

php artisan p:environment:database

Kreator od razu próbuje się połączyć. Jeśli dane są błędne, wypisuje Unable to connect to the MySQL server…, niczego nie zapisuje i pyta, czy chcesz spróbować ponownie.

Kreator p:environment:mail#

Panel wysyła e-maile (zaproszenia dla nowych użytkowników, resety haseł). Bez ustawień poczty Panel działa, ale te e-maile nie wyjdą. Możesz skonfigurować to także później tym samym poleceniem:

php artisan p:environment:mail

Ważne klucze w .env#

Kreatory zapisują te wartości w .env. Plik możesz też edytować ręcznie (nano /var/www/pterodactyl/.env); po ręcznej edycji uruchom php artisan config:clear.

Tabele w bazie danych i pierwszy administrator#

1. Utwórz tabele i wczytaj dane domyślne:

   php artisan migrate --seed --force

   • migrate – tworzy wszystkie tabele w bazie panel.
   • --seed – wypełnia je danymi domyślnymi, łącznie z szablonami gier (Minecraft, Rust i inne).
   • --force – wykonuje polecenie bez potwierdzenia w trybie produkcyjnym.

   Polecenie może trwać kilka minut. Nie przerywaj go, inaczej baza zostanie utworzona w połowie.

2. Utwórz konto admina:

   php artisan p:user:make

Na końcu zobaczysz tabelę z danymi konta i wierszem Admin | Yes.

Uprawnienia plików#

Pliki Panelu należą teraz do roota. Serwer WWW działa jako użytkownik www-data i musi pisać do katalogów storage i bootstrap/cache:

chown -R www-data:www-data /var/www/pterodactyl/*

• chown -R – zmienia właściciela plików i całej zawartości katalogów.
• www-data:www-data – użytkownik i grupa, jako które na Ubuntu i Debianie działają Nginx i PHP-FPM.

Cron i kolejka zadań#

Cron#

Cron co minutę uruchamia harmonogram Panelu (czyszczenie starych logowań, zaplanowane zadania serwerów).

1. Otwórz crontab roota:

   crontab -e

   Przy pierwszym uruchomieniu pyta, którego edytora użyć. Wybierz nano (wpisz jego numer i naciśnij Enter). Jeśli system mówi crontab: command not found, brakuje crona. Zainstaluj go przez apt -y install cron i powtórz ten krok.

2. Dodaj tę linię na końcu pliku:

   * * * * * php /var/www/pterodactyl/artisan schedule:run >> /dev/null 2>&1

3. Zapisz (Ctrl+O, Enter) i zamknij edytor (Ctrl+X). Zobaczysz crontab: installing new crontab.

Usługa kolejki pteroq#

Kolejka obsługuje pracę w tle: wysyłanie e-maili i zadania, które użytkownicy planują dla swoich serwerów (sekcja Schedules, na przykład nocny restart lub kopia zapasowa). Bez niej e-maile nie wychodzą, a zaplanowane zadania się nie uruchamiają.

1. Utwórz plik usługi:

   nano /etc/systemd/system/pteroq.service

2. Wklej zawartość:

   # Pterodactyl Queue Worker File
   [Unit]
   Description=Pterodactyl Queue Worker
   After=redis-server.service
   
   [Service]
   User=www-data
   Group=www-data
   Restart=always
   ExecStart=/usr/bin/php /var/www/pterodactyl/artisan queue:work --queue=high,standard,low --sleep=3 --tries=3
   StartLimitInterval=180
   StartLimitBurst=30
   RestartSec=5s
   
   [Install]
   WantedBy=multi-user.target

3. Zapisz i zamknij edytor.

4. Włącz Redisa i kolejkę przy starcie i uruchom je od razu:

   systemctl enable --now redis-server
   systemctl enable --now pteroq.service

   • enable – włącza automatyczny start po restarcie VPS.
   • --now – uruchamia też usługę natychmiast.

5. Sprawdź status:

   systemctl status pteroq

   Zobaczysz Active: active (running). Wyjście zamknij klawiszem q.

Certyfikat Let's Encrypt#

Poniższa konfiguracja Nginx odwołuje się do plików certyfikatu. Nginx nie wystartuje z nią, dopóki certyfikat nie istnieje, więc najpierw go uzyskasz.

1. Zainstaluj Certbota i jego wtyczkę Nginx:

   apt -y install certbot python3-certbot-nginx

   • certbot – program uzyskujący i odnawiający certyfikaty Let's Encrypt.
   • python3-certbot-nginx – wtyczka, która weryfikuje domenę przez działający Nginx bez jego zatrzymywania.

2. Uzyskaj certyfikat. Zamień panel.example.cz na swoją domenę:

   certbot certonly --nginx -d panel.example.cz

   • certonly – tylko uzyskuje certyfikat i go zapisuje, bez edycji konfiguracji Nginx (tę napiszesz sam).
   • --nginx – walidacja domeny przechodzi przez Nginx na porcie 80.
   • -d panel.example.cz – domena, dla której chcesz certyfikat.

3. Przy pierwszym uruchomieniu odpowiedz na pytania:

   • E-mail (Enter email address…) – wpisz swój e-mail. Let's Encrypt wysyła tam ważne powiadomienia o koncie. Od 2025 nie wysyła już przypomnień o wygaśnięciu certyfikatu, więc odnawianie jest automatyczne (zobacz krok 5).
   • Warunki usługi (Please read the Terms of Service… Do you agree?) – odpowiedz Y; bez zgody nie dostaniesz certyfikatu.
   • Udostępnienie e-maila EFF (Would you be willing… to share your email address with the Electronic Frontier Foundation…) – Twoja decyzja; nie wpływa na certyfikat.

   Na końcu zobaczysz Successfully received certificate. i ścieżki plików:

   Certificate is saved at: /etc/letsencrypt/live/panel.example.cz/fullchain.pem
   Key is saved at:         /etc/letsencrypt/live/panel.example.cz/privkey.pem

4. Spraw, aby Nginx wczytywał nowy certyfikat po każdym odnowieniu. Utwórz deploy hook (skrypt uruchamiany przez Certbota po udanym odnowieniu):

   cat > /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh <<'EOF'
   #!/bin/sh
   systemctl reload nginx
   EOF
   chmod 755 /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh

   • cat > … <<'EOF' … EOF – zapisuje linie między <<'EOF' a EOF do pliku.
   • systemctl reload nginx – wczytuje nową konfigurację i certyfikaty bez zrywania połączeń.
   • chmod 755 – czyni skrypt wykonywalnym; Certbot uruchamia w katalogu renewal-hooks/deploy tylko pliki wykonywalne.

5. Sprawdź, czy automatyczne odnawianie działa. Zarówno na Ubuntu, jak i na Debianie pakiet Certbota zawiera timer, który dwa razy dziennie próbuje odnowienia:

   systemctl list-timers | grep certbot
   certbot renew --dry-run

   • systemctl list-timers – wypisuje zaplanowane timery; powinien być wśród nich certbot.timer.
   • certbot renew --dry-run – próbuje odnowienia na serwerze testowym Let's Encrypt bez dotykania prawdziwego certyfikatu.

   Test kończy się Congratulations, all simulated renewals succeeded.

Certyfikat jest ważny 90 dni (stan na październik 2026; Let's Encrypt stopniowo skraca ważność). Certbot odnawia go sam, gdy zostaje mniej więcej jedna trzecia ważności.

Nginx#

1. Wyłącz domyślną stronę Nginx:

   rm /etc/nginx/sites-enabled/default

   • Usuwa tylko dowiązanie w sites-enabled; sam plik zostaje w sites-available. Inaczej port 80 obsługiwałaby domyślna strona zamiast Panelu.

2. Utwórz konfigurację Panelu:

   nano /etc/nginx/sites-available/pterodactyl.conf

3. Wklej zawartość i zamień wszystkie cztery wystąpienia panel.example.cz na swoją domenę:

   server {
       listen 80;
       listen [::]:80;
       server_name panel.example.cz;
       return 301 https://$server_name$request_uri;
   }
   
   server {
       listen 443 ssl http2;
       listen [::]:443 ssl http2;
       server_name panel.example.cz;
       server_tokens off;
   
       root /var/www/pterodactyl/public;
       index index.php;
   
       access_log /var/log/nginx/pterodactyl.app-access.log;
       error_log  /var/log/nginx/pterodactyl.app-error.log error;
   
       # wieksze przesylki i dluzszy czas dzialania skryptow
       client_max_body_size 100m;
       client_body_timeout 120s;
   
       sendfile off;
   
       ssl_certificate /etc/letsencrypt/live/panel.example.cz/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/panel.example.cz/privkey.pem;
       ssl_session_cache shared:SSL:10m;
       ssl_protocols TLSv1.2 TLSv1.3;
       ssl_ciphers "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384";
       ssl_prefer_server_ciphers on;
   
       add_header X-Content-Type-Options nosniff;
       add_header X-XSS-Protection "1; mode=block";
       add_header X-Robots-Tag none;
       add_header Content-Security-Policy "frame-ancestors 'self'";
       add_header X-Frame-Options DENY;
       add_header Referrer-Policy same-origin;
   
       location / {
           try_files $uri $uri/ /index.php?$query_string;
       }
   
       location ~ \.php$ {
           fastcgi_split_path_info ^(.+\.php)(/.+)$;
           fastcgi_pass unix:/run/php/php8.3-fpm.sock;
           fastcgi_index index.php;
           include fastcgi_params;
           fastcgi_param PHP_VALUE "upload_max_filesize = 100M \n post_max_size=100M";
           fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
           fastcgi_param HTTP_PROXY "";
           fastcgi_intercept_errors off;
           fastcgi_buffer_size 16k;
           fastcgi_buffers 4 16k;
           fastcgi_connect_timeout 300;
           fastcgi_send_timeout 300;
           fastcgi_read_timeout 300;
       }
   
       location ~ /\.ht {
           deny all;
       }
   }

Konfiguracja opiera się na oficjalnej dokumentacji Pterodactyla. Dodaliśmy nasłuchiwanie na IPv6 (listen [::]:…) i ukryliśmy wersję Nginx. Co robi każda część:

4. Włącz konfigurację, przetestuj ją i zrestartuj Nginx:

   ln -s /etc/nginx/sites-available/pterodactyl.conf /etc/nginx/sites-enabled/pterodactyl.conf
   nginx -t
   systemctl restart nginx

   • ln -s – tworzy dowiązanie do pliku w sites-enabled; Nginx wczytuje tylko konfiguracje z sites-enabled.
   • nginx -t – sprawdza składnię. Musi zakończyć się linią test is successful. Jeśli nie, nie restartuj Nginx; popraw linię wskazaną w błędzie.
   • systemctl restart nginx – wczytuje nową konfigurację.

Pierwsze logowanie#

1. Otwórz w przeglądarce https://panel.example.cz. Zobaczysz stronę logowania Panelu z kłódką (ważny certyfikat) w pasku adresu.
2. Zaloguj się nazwą użytkownika lub e-mailem admina i hasłem.
3. Kliknij ikonę koła zębatego (część administracyjna) w prawym górnym rogu. W sekcji Settings ustaw nazwę Panelu (Company Name).
4. Włącz uwierzytelnianie dwuskładnikowe: kliknij swoje konto w prawym górnym rogu, otwórz Account i w sekcji dwuskładnikowej zeskanuj kod QR aplikacją (na przykład Google Authenticator lub Aegis). Konto admina steruje wszystkimi serwerami, więc chroń je czymś więcej niż hasłem.

Weryfikacja#

Sprawdź całą instalację:

systemctl is-active nginx php8.3-fpm mariadb redis-server pteroq
curl -sI https://panel.example.cz | head -n 1

• Pierwsze polecenie musi wypisać pięć razy active.
• curl -sI pobiera tylko nagłówki odpowiedzi; pierwsza linia to HTTP/2 302 (przekierowanie do logowania) lub HTTP/2 200.

Panel jest gotowy. Następny krok to dodanie węzła z usługą Wings, na którym będą działać serwery gier: Pterodactyl Wings.

Panel za Cloudflare#

Panel możesz postawić za proxy Cloudflare (pomarańczowa chmurka). Dotyczy to tylko Panelu, nie Wings (zobacz Pterodactyl Wings).

1. W Cloudflare ustaw tryb SSL/TLS na Full (strict). Cloudflare łączy się wtedy z VPS przez HTTPS i weryfikuje Twój certyfikat Let's Encrypt.

2. Przełącz rekord panel.example.cz na Proxied.

3. Dodaj zakresy IP Cloudflare do .env w jednej linii. Za proxy wszystkie żądania docierają do Panelu z adresów Cloudflare. Panel bierze wtedy prawdziwy adres IP odwiedzającego z nagłówka X-Forwarded-For, ale tylko od adresów, którym ufa. Bez tej linii Panel widziałby dla wszystkich użytkowników tylko adresy Cloudflare, zarówno w logach aktywności, jak i w ochronie przed brute force, która liczy próby na adres IP. Poniższa lista jest aktualna na 1 października 2026; najnowszą znajdziesz na cloudflare.com/ips (otwiera się w nowym oknie):

   TRUSTED_PROXIES=173.245.48.0/20,103.21.244.0/22,103.22.200.0/22,103.31.4.0/22,141.101.64.0/18,108.162.192.0/18,190.93.240.0/20,188.114.96.0/20,197.234.240.0/22,198.41.128.0/17,162.158.0.0/15,104.16.0.0/13,104.24.0.0/14,172.64.0.0/13,131.0.72.0/22,2400:cb00::/32,2606:4700::/32,2803:f800::/32,2405:b500::/32,2405:8100::/32,2a06:98c0::/29,2c0f:f248::/32

   • TRUSTED_PROXIES – lista adresów i zakresów (oddzielonych przecinkami, bez spacji), od których Panel przyjmuje nagłówki X-Forwarded-* z prawdziwym adresem IP i protokołem odwiedzającego. Od każdego innego adresu te nagłówki ignoruje, więc nikt nie może ich podrobić.

4. Wczytaj nową konfigurację: cd /var/www/pterodactyl && php artisan config:clear.

Aktualizacja Panelu#

Nowe wersje Panelu naprawiają błędy i luki bezpieczeństwa, więc aktualizuj regularnie. Przed aktualizacją przeczytaj informacje o wydaniu na GitHubie i sprawdź, jakiej wersji PHP wymaga nowe wydanie (php -v).

• mariadb-dump --single-transaction panel – eksportuje bazę panel do pliku SQL bez blokowania tabel.
• $(date +%F) – wstawia do nazwy pliku dzisiejszą datę (na przykład 2026-10-01).

Następnie uruchom aktualizację:

cd /var/www/pterodactyl
php artisan down
curl -L https://github.com/pterodactyl/panel/releases/latest/download/panel.tar.gz | tar -xzv
chmod -R 755 storage/* bootstrap/cache
COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader
php artisan view:clear
php artisan config:clear
php artisan migrate --seed --force
chown -R www-data:www-data /var/www/pterodactyl/*
php artisan queue:restart
php artisan up

Po aktualizacji Panelu zaktualizuj też Wings; kroki są w poradniku Pterodactyl Wings. Wersje Panelu i Wings powinny iść w parze, więc używaj najnowszego wydania obu.

Kopie zapasowe Panelu#

Do przywrócenia Panelu potrzebujesz dwóch rzeczy: bazy panel i pliku .env (przede wszystkim APP_KEY). Dane serwerów gier leżą na węźle Wings, nie w Panelu, więc archiwizuj je osobno. Jak zautomatyzować kopie i wynieść je poza serwer, opisuje artykuł Kopie zapasowe na VPS.

Rozwiązywanie problemów#

502 Bad Gateway#

Nginx nie mógł dotrzeć do PHP-FPM. Sprawdź, czy PHP-FPM działa i czy ścieżka socketu się zgadza:

systemctl status php8.3-fpm
ls /run/php/

Wyjście ls musi zawierać php8.3-fpm.sock, a ta sama ścieżka musi być w dyrektywie fastcgi_pass. Jeśli usługa nie działa, uruchom ją: systemctl enable --now php8.3-fpm.

Błąd 500 lub pusta strona#

Zajrzyj do logu Panelu:

tail -n 100 /var/www/pterodactyl/storage/logs/laravel-$(date +%F).log

• tail -n 100 – wypisuje ostatnie 100 linii dzisiejszego logu.

Szukaj linii z datą i słowem ERROR. Najczęstsze przyczyny:

• Permission denied – zły właściciel plików. Uruchom ponownie chown -R www-data:www-data /var/www/pterodactyl/*.
• No application encryption key has been specified. – brakuje APP_KEY. Przy pierwszej instalacji uruchom php artisan key:generate --force. Jeśli Panel ma już dane, przywróć pierwotny klucz z kopii zapasowej.
• SQLSTATE[HY000] [1045] Access denied – hasło lub użytkownik bazy w .env są błędne.

The MAC is invalid#

Baza została zaszyfrowana innym APP_KEY niż ten, który jest teraz w .env. Zwykle dzieje się to po przywróceniu bazy na nową instalację. Jedyną naprawą jest przywrócenie pierwotnego APP_KEY w .env. Bez niego zaszyfrowanych danych nie da się odzyskać.

E-maile nie są wysyłane#

Najczęściej nie działa kolejka. Sprawdź usługę i jej log:

systemctl status pteroq
journalctl -u pteroq -n 50

• journalctl -u pteroq -n 50 – ostatnie 50 linii logu usługi.

Sprawdź też, czy działa Redis (systemctl status redis-server). Po naprawie uruchom systemctl restart pteroq. Jeśli kolejka działa, sprawdź ustawienia poczty (php artisan p:environment:mail) i błędy w logu Panelu (zobacz Błąd 500).

Serwer wisi na instalacji#

Instalację serwera wykonuje Wings, nie Panel. Zobacz sekcję „Rozwiązywanie problemów” poradnika Pterodactyl Wings (najczęściej zepsuty DNS w kontenerach albo nieosiągalny węzeł).

Zaplanowane zadania serwerów się nie uruchamiają#

Sprawdź, czy działa kolejka (systemctl status pteroq), linię crona (crontab -l) i strefy czasowe: systemu (timedatectl) i Panelu (APP_TIMEZONE w .env). Pomóc może też wyczyszczenie cache harmonogramu:

php /var/www/pterodactyl/artisan schedule:clear-cache
systemctl restart pteroq

Nginx nie startuje: cannot load certificate#

Certyfikat dla domeny z konfiguracji nie istnieje: nie uzyskano go albo domena w server_name i w ścieżce /etc/letsencrypt/live/… różni się od tej, dla której go wystawiono. certbot certificates wypisuje Twoje certyfikaty.

Certbot: Timeout during connect (likely firewall problem)#

Let's Encrypt nie mógł dotrzeć do portu 80 Twojego VPS. Sprawdź, czy rekord A domeny wskazuje na adres IPv4 VPS, czy port 80 jest dozwolony zarówno w firewallu strefy klienta, jak i w UFW, i czy Nginx działa. Jeśli domena ma rekord AAAA, musi wskazywać na adres IPv6 tego VPS, bo Let's Encrypt próbuje też IPv6.

Composer lub artisan zgłasza złą wersję PHP#

Komunikat brzmi mniej więcej requires php ^8.2 || ^8.3 but your php version (8.4…) does not satisfy that requirement. Polecenie php uruchamia inną wersję niż 8.3, zwykle na Debianie 13 po zainstalowaniu domyślnego pakietu php. Ustaw domyślne PHP na 8.3:

update-alternatives --set php /usr/bin/php8.3
php -v

• update-alternatives --set php … – ustawia, którą wersję uruchamia polecenie php.

Jeśli /usr/bin/php8.3 nie istnieje, PHP 8.3 nie jest zainstalowane. Wróć do sekcji Instalacja zależności.

Strona za Cloudflare kręci się w przekierowaniach (ERR_TOO_MANY_REDIRECTS)#

Cloudflare jest w trybie Flexible. Przełącz go na Full (strict) i sprawdź też TRUSTED_PROXIES zgodnie z sekcją Panel za Cloudflare.

Za Cloudflare nie działa konsola serwera#

Domena węzła przechodzi przez proxy Cloudflare (pomarańczowa chmurka). Zwykle dzieje się to, gdy węzeł używa tej samej domeny co Panel. Przełącz domenę węzła na DNS only albo daj węzłowi własną subdomenę.

Dalsza lektura#

• Pterodactyl: Getting Started (otwiera się w nowym oknie)
• Pterodactyl: Webserver Configuration (otwiera się w nowym oknie)
• Pterodactyl: Updating the Panel (otwiera się w nowym oknie)
• Pterodactyl: Additional Configuration (otwiera się w nowym oknie)
• Pterodactyl: Troubleshooting (otwiera się w nowym oknie)
• Certbot: User Guide (otwiera się w nowym oknie)