Instalacja panelu Pterodactyl dla serwerów gier

Pterodactyl to najczęściej używany darmowy panel do serwerów gier. Opinia, że jest skomplikowany, prawie nigdy nie bierze się z samej instalacji, tylko z jednego nieporozumienia: Pterodactyl to nie jeden program, tylko dwa. Ten poradnik czysto rozdziela oba, pokazuje różnice między Debianem a Ubuntu, a potem przechodzi przez komunikaty błędów, które dosłownie kopiujesz do wyszukiwarki.

Panel i Wings: dwa programy, dwie role

Panel to aplikacja PHP oparta na Laravelu. Dostarcza interfejs webowy, zarządza użytkownikami, uprawnieniami, bazami danych i harmonogramami, a wszystko zapisuje we własnej bazie MySQL albo MariaDB. Panel nigdy sam nie uruchamia serwera gry. Nie zna nawet Dockera.

Wings to pojedynczy program napisany w Go. Działa na każdej maszynie, na której faktycznie mają chodzić serwery gier, rozmawia z demonem Dockera, uruchamia kontenery, streamuje konsolę i udostępnia dostęp SFTP. Wings nie ma ani interfejsu webowego, ani bazy danych. Nasłuchuje na porcie HTTP i czeka na polecenia z panelu.

Oba komunikują się ze sobą wyłącznie po HTTP, w obie strony, przy użyciu podpisanych tokenów. Wynikają z tego trzy rzeczy, które warto zaakceptować od samego początku:

• Panel musi osiągać węzeł po nazwie domeny, a nie po adresie IP. Certyfikat jest przypisany do nazwy.
• Panel i Wings muszą mówić tym samym protokołem. Panel na HTTPS plus Wings na HTTP nie zadziała, przeglądarka zablokuje połączenie z konsolą.
• Oba zegary muszą się zgadzać. Tokeny żyją tylko kilka minut.

Jeśli zapamiętasz te trzy zdania, unikniesz z góry połowy typowych problemów z Pterodactylem.

Wymagania i wybór systemu

Pterodactyl 1.11 i nowszy wymaga PHP 8.2 albo 8.3. To moment, w którym większość poradników robi się nieprecyzyjna, bo dystrybucje dostarczają bardzo różne wersje. Stan na lipiec 2026 w standardowych repozytoriach wygląda tak:

Ten poradnik dotyczy wyłącznie Debiana i Ubuntu. Na systemach AlmaLinux, Rocky Linux i Oracle Linux nie ma apt, więc żadne z poniższych poleceń pakietowych nie ma tam zastosowania.

Praktyczny wniosek: Debian 12 i Ubuntu 24.04 to dwa systemy, na których panel działa bez zewnętrznych repozytoriów. Na Ubuntu 22.04 potrzebujesz PPA Ondřeja Surego, na Debianie 13 jego debianowego odpowiednika, ponieważ metapakiet dostarcza tam PHP 8.4, a composer.json panelu wyraźnie wymaga ^8.2 || ^8.3. W praktyce Composer pod PHP 8.4 co prawda przechodzi, ale to teren niesprawdzony i nie jest to stan, w jakim chcesz prowadzić serwer produkcyjny. Jeśli chcesz sobie oszczędzić dodatkowego repozytorium, weź Debiana 12 albo Ubuntu 24.04.

Oba zbyt stare systemy nie wywracają się zresztą na poleceniu instalacji pakietów, tylko dopiero dwa kroki później, i to czyni je tak podstępnymi. apt install php kończy się na Ubuntu 22.04 (PHP 8.1.2) oraz na Debianie 11 (PHP 7.4.33) kodem wyjścia 0, dopiero Composer przerywa pracę: na Ubuntu 22.04 komunikatem brick/math requires php (^8.2) failed, na Debianie 11 komunikatem aws/aws-sdk-php requires php (>=8.1) failed. Jeśli musisz zostać przy jednym z tych systemów, zainstaluj z zewnętrznego repozytorium jawnie wersjonowane pakiety (php8.3, php8.3-cli, php8.3-fpm i tak dalej) zamiast metapakietu php, bo inaczej znowu zadziała wersja z dystrybucji.

Druga różnica, która regularnie zaskakuje: Debian w ogóle nie dostarcza pakietu mysql-server. Tam standardem jest MariaDB i jest to całkowicie w porządku, Pterodactyl wymaga MariaDB 10.2 albo nowszej. Jeśli na Debianie wpiszesz apt install mysql-server, dostaniesz E: Unable to locate package mysql-server i zaczniesz potem szukać w złym miejscu.

Dla węzła z Wings te reguły dotyczące PHP w ogóle nie obowiązują. Wings to statycznie zlinkowany program w Go, któremu wystarczy Docker i w miarę aktualna wersja jądra. Węzeł może spokojnie działać na Debianie 13, podczas gdy panel stoi na Debianie 12.

Instalacja panelu

Wszystkie poniższe polecenia wykonujesz jako root. Najpierw pakiety podstawowe. Zwróć uwagę, żeby wziąć komplet rozszerzeń PHP, brakujący php-bcmath ujawnia się dopiero przy uruchomieniu Composera.

apt update
apt -y install curl ca-certificates gnupg lsb-release tar unzip git
apt -y install mariadb-server nginx redis-server
apt -y install php php-cli php-common php-gd php-mysql php-mbstring php-bcmath php-xml php-fpm php-curl php-zip

Od razu sprawdź, czy wersja się zgadza, zanim pójdziesz dalej:

php -v
php -m | grep -E "bcmath|mbstring|curl|zip|gd|xml"

Następnie Composer i pliki panelu:

curl -sS https://getcomposer.org/installer -o /tmp/composer-setup.php
php /tmp/composer-setup.php --install-dir=/usr/local/bin --filename=composer
mkdir -p /var/www/pterodactyl
curl -Lo /var/www/pterodactyl/panel.tar.gz https://github.com/pterodactyl/panel/releases/latest/download/panel.tar.gz
tar -xzf /var/www/pterodactyl/panel.tar.gz -C /var/www/pterodactyl

Teraz baza danych. Załóż użytkownika na 127.0.0.1, a nie na localhost, bo inaczej zadziała dostęp przez socket i Laravel dostanie później odmowę dostępu, mimo że hasło jest poprawne. Jak rozłożyć ten przypadek na czynniki pierwsze, opisujemy we wpisie o Access denied for user.

mariadb -u root -e "CREATE DATABASE panel;"
mariadb -u root -e "CREATE USER 'pterodactyl'@'127.0.0.1' IDENTIFIED BY 'TutajDlugieHaslo';"
mariadb -u root -e "GRANT ALL PRIVILEGES ON panel.* TO 'pterodactyl'@'127.0.0.1' WITH GRANT OPTION;"
mariadb -u root -e "FLUSH PRIVILEGES;"

Bazę danych warto następnie zabezpieczyć, mamy o tym osobny wpis o zabezpieczaniu MariaDB i MySQL.

Teraz właściwa konfiguracja. Polecenia p:environment są interaktywne i pytają o adres panelu, strefę czasową, sterownik cache oraz dostęp do bazy danych:

cd /var/www/pterodactyl
cp .env.example .env
COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader
php artisan key:generate --force
php artisan p:environment:setup
php artisan p:environment:database
php artisan migrate --seed --force
php artisan p:user:make
chown -R www-data:www-data /var/www/pterodactyl/*

Przy p:environment:setup wybierz Redis jako sterownik sesji i cache, wtedy opisana niżej kolejka zadziała czysto. Adres panelu wpisz z https://. Wpisane w tym miejscu http:// powoduje później mieszaną zawartość i konsolę, która w nieskończoność czeka na połączenie.

nginx i pułapka wersji

Podstawy konfiguracji serwera WWW opisaliśmy we wpisie o instalacji nginx. Dla Pterodactyla ważne są dwa szczegóły, na których gotowe szablony z internetu regularnie się wykładają.

Po pierwsze socket PHP-FPM. Nazwa pliku zawiera wersję PHP i różni się w zależności od systemu. Sprawdź ją, zamiast zgadywać:

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

Na Debianie 12 socket nazywa się php8.2-fpm.sock, na Ubuntu 24.04 php8.3-fpm.sock. Błędna ścieżka daje dokładnie tę stronę 502 Bad Gateway, której szuka tylu ludzi. Zapytanie o status stoi tu celowo przed listowaniem: plik socketu powstaje dopiero wtedy, gdy usługa FPM działa. Jeśli nie jest uruchomiona, /run/php/ jest pusty, a ty niesłusznie uznasz ścieżkę za błędną. Gdy usługa jeszcze nie chodzi, pomoże systemctl enable --now php8.2-fpm z numerem wersji pasującym do twojej instalacji.

Po drugie zapis HTTP/2. Nowa dyrektywa http2 on; istnieje dopiero od nginx 1.25.1. Na Debianie 12 (1.22), Ubuntu 22.04 (1.18) oraz na Ubuntu 24.04 (1.24) musisz użyć starej formy listen 443 ssl http2;, inaczej start przerwie się komunikatem nginx: [emerg] unknown directive "http2". Tylko Debian 13 z nginx 1.26 rozumie obie formy.

server {
    listen 443 ssl http2;
    server_name panel.example.com;
    root /var/www/pterodactyl/public;
    index index.php;
    client_max_body_size 100m;

    ssl_certificate /etc/letsencrypt/live/panel.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/panel.example.com/privkey.pem;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param HTTP_PROXY "";
    }
}

Kolejka i harmonogram

Bez tych dwóch elementów panel wygląda na sprawny, ale nie wysyła maili i nie wykonuje zaplanowanych zadań. Budowę pliku unit szczegółowo wyjaśniamy we wpisie o tworzeniu usługi systemd, tutaj gotowa wersja:

[Unit]
Description=Pterodactyl Queue Worker
After=redis-server.service

[Service]
User=www-data
Group=www-data
Restart=always
RestartSec=5s
ExecStart=/usr/bin/php /var/www/pterodactyl/artisan queue:work --queue=high,standard,low --sleep=3 --tries=3

[Install]
WantedBy=multi-user.target

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

Do tego wpis w crontabie roota, szczegóły składni znajdziesz we wpisie Jak skonfigurować cron w Linuksie:

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

Instalacja Wings na węźle

Od tego miejsca pracujesz na maszynie, która ma uruchamiać serwery gier. Może to być ten sam serwer, ale nie musi. Wymagany jest Docker, jego konfigurację opisaliśmy we wpisie Instalacja Dockera na Debianie i Ubuntu.

mkdir -p /etc/pterodactyl
curl -L -o /usr/local/bin/wings https://github.com/pterodactyl/wings/releases/latest/download/wings_linux_amd64
chmod u+x /usr/local/bin/wings
wings version

Na serwerach ARM plik nazywa się wings_linux_arm64. Jeśli pobierzesz zły pakiet, powłoka zgłosi po prostu cannot execute binary file: Exec format error. Nie dziw się wynikowi ostatniej linijki: wings version odpowiada podwójnym v, czyli na przykład wings vv1.13.1. Tak to przychodzi od producenta i nie jest oznaką zepsutej instalacji.

Pliku /etc/pterodactyl/config.yml nie piszesz sam. Powstanie za chwilę automatycznie. Na razie utwórz tylko usługę:

[Unit]
Description=Pterodactyl Wings Daemon
After=docker.service
Requires=docker.service
PartOf=docker.service

[Service]
User=root
WorkingDirectory=/etc/pterodactyl
LimitNOFILE=4096
PIDFile=/var/run/wings/daemon.pid
ExecStart=/usr/local/bin/wings
Restart=on-failure
StartLimitInterval=180
StartLimitBurst=30
RestartSec=5s

[Install]
WantedBy=multi-user.target

Jeszcze nie uruchamiaj. Bez konfiguracji Wings natychmiast przerywa pracę i zgłasza komunikat, który wskazuje na brakujący plik konfiguracyjny w /etc/pterodactyl/config.yml. Na tym etapie jest to całkowicie normalne i nie jest błędem.

Słowo o pliku wymiany: wiele starszych poradników wymaga swapaccount=1 w /etc/default/grub. Dotyczy to wyłącznie systemów z cgroup v1. Debian 12 i 13 oraz Ubuntu 22.04 i 24.04 domyślnie używają cgroup v2, tam ten wpis jest zbędny. Sprawdzisz to poleceniem docker info. Jeśli pojawi się tam WARNING: No swap limit support, ograniczenie pamięci nie obejmuje przestrzeni wymiany. Jak w ogóle sensownie dobrać rozmiar przestrzeni wymiany, opisuje wpis Konfiguracja swapa.

Certyfikat dla węzła, nie tylko dla panelu

Najczęstszy błąd w rozumowaniu: ktoś załatwia certyfikat dla panel.example.com i dziwi się, że węzeł nie działa. Wings potrzebuje własnego certyfikatu dla własnej nazwy domeny, na przykład node1.example.com. Obie nazwy mogą wskazywać na ten sam adres IP, ale to są dwie nazwy.

Na czystym węźle nie działa żaden serwer WWW, dlatego samodzielny tryb Certbota jest najprostszą drogą. Port 80 musi być na ten czas osiągalny z zewnątrz:

apt -y install certbot
certbot certonly --standalone -d node1.example.com

Jeśli prowadzisz wiele węzłów, wyjdziesz lepiej na certyfikacie wieloznacznym, opisujemy go we wpisie Certyfikat wildcard Let's Encrypt.

Dwie przeszkody, które kosztują dużo czasu:

• Wings czyta pliki certyfikatu przy starcie. Po odnowieniu usługę trzeba przeładować. Umieść w /etc/letsencrypt/renewal-hooks/deploy/ mały skrypt z systemctl restart wings. Bez tego węzeł działa bez zarzutu przez 90 dni, a potem pozornie bez powodu przestaje.
• Wyłącz proxy Cloudflare dla nazwy węzła. Pomarańczowa chmurka rozszywa połączenie TLS i podmienia certyfikat. Panel dostaje wtedy certyfikat, który nie pasuje do oczekiwanego wystawcy, a połączenie konsoli przez WebSocket zachowuje się nieprzewidywalnie. Rekord A dla węzła należy przestawić na szary.

Zakładanie i podłączanie węzła

W panelu w Admin, Locations załóż najpierw lokalizację, a potem w Nodes sam węzeł. Pola, które faktycznie się liczą:

• FQDN: node1.example.com, dokładnie ta nazwa co w certyfikacie.
• Communicate over SSL: włączone, jeśli panel działa po HTTPS. Inaczej nie ma sensu nawet zaczynać.
• Behind Proxy: włącz tylko wtedy, gdy przed Wings faktycznie stoi reverse proxy i to ono kończy TLS.
• Daemon Port: 8080. Daemon SFTP Port: 2022.
• Memory i Disk: limity, których panel przestrzega przy rozdzielaniu serwerów.

Po zapisaniu otwórz zakładkę Configuration węzła. Panel generuje tam polecenie z jednorazowym tokenem. Wykonaj je na węźle:

cd /etc/pterodactyl
wings configure --panel-url https://panel.example.com --token TOKEN --node 1

Wings pobiera w ten sposób pełną konfigurację i zapisuje /etc/pterodactyl/config.yml. Sprawdź zawartość: jeśli przy adresie panelu stoi tam http:// zamiast https://, to polecenie zostało skopiowane ze środowiska, w którym adres panelu jest zapisany błędnie. Popraw to u źródła poleceniem php artisan p:environment:setup, a nie ręcznie w pliku YAML.

Potem w zakładce Allocations wpisz adres IP węzła i żądane zakresy portów, na przykład od 25565 do 25600 dla Minecrafta. Bez co najmniej jednej wolnej alokacji nie da się utworzyć serwera.

Dopiero teraz uruchamiaj:

systemctl enable --now wings
systemctl status wings

Porty muszą być otwarte w firewallu. Za pomocą ufw, którego podstawy omawiamy we wpisie Konfiguracja firewalla ufw:

ufw allow 8080/tcp
ufw allow 2022/tcp
ufw allow 25565:25600/tcp
ufw allow 25565:25600/udp

Gdy Wings się nie łączy

Panel pokazuje przy węźle czerwoną ikonę albo zwraca błąd przy zakładaniu serwera. Przerabiaj komunikaty po kolei, są zaskakująco jednoznaczne.

cURL error 7: Failed to connect ... Connection refused

Serwer panelu nie osiąga portu. Albo Wings nie działa, albo blokuje firewall, albo usługa nasłuchuje na złym adresie. Sprawdzaj w tej kolejności:

systemctl status wings
ss -tlnp | grep 8080
journalctl -u wings -n 50 --no-pager

Oraz z serwera panelu, to jest decydujący test:

curl -v https://node1.example.com:8080

Odpowiedź HTTP, nawet 404 z treścią JSON, jest w tym miejscu sukcesem. Dowodzi, że DNS, firewall, port i TLS współgrają ze sobą.

cURL error 60: SSL certificate problem

Certyfikat węzła nie zostaje zaakceptowany. Przy self signed certificate używasz certyfikatu wystawionego samodzielnie, z czym panel sobie nie poradzi, bo biblioteka pod spodem nie zna wyjątków. Przy unable to get local issuer certificate brakuje zwykle łańcucha pośredniego, wtedy twoja konfiguracja Wings wskazuje na cert.pem zamiast na fullchain.pem. Przy certificate has expired odnowienie wprawdzie się wykonało, ale Wings trzyma w pamięci jeszcze stary plik, patrz haczyk z restartem powyżej.

cURL error 28: Operation timed out

Brak odpowiedzi, brak resetu. To pachnie firewallem, który po cichu porzuca pakiety zamiast je odrzucać, albo węzłem za NAT. Przypadek szczególny: panel i Wings na tym samym serwerze, a panel odpytuje własny publiczny adres IP. Niektóre sieci nie zawracają takiej pętli. Pomaga wpis w /etc/hosts na serwerze panelu, kierujący nazwę węzła na adres wewnętrzny.

Cannot connect to the Docker daemon at unix:///var/run/docker.sock

Wings działa, Docker nie. systemctl status docker wyjaśnia to w jednej linijce. Węzeł mimo to często pokazuje się w panelu jako osiągalny, bo odpytywanie stanu działa, ale każde uruchomienie serwera kończy się niepowodzeniem.

Węzeł odpowiada, ale każda akcja zostaje odrzucona

Token się nie zgadza. Zdarza się to po ponownym wings configure ze starym tokenem albo po tym, jak węzeł został w panelu usunięty i założony na nowo. Rozwiązanie: w panelu w zakładce Configuration wygeneruj świeży token, wykonaj polecenie jeszcze raz, uruchom Wings ponownie. Nie zgaduj po omacku w pliku YAML.

We wszystkich przypadkach, w których komunikat pozostaje niejasny, zatrzymaj usługę i uruchom Wings na pierwszym planie. Wypisuje wtedy znacznie więcej niż dziennik:

systemctl stop wings
wings --debug

Pomocny jest też wbudowany tryb raportu, który zbiera konfigurację, stan Dockera i dane systemowe:

wings diagnostics

Różnica czasu między panelem a węzłem

Ten błąd jest podstępny, bo wygląda jak problem sieciowy. Objawy: węzeł pokazuje się w panelu jako osiągalny, serwery da się zakładać, ale konsola zawiesza się przy nawiązywaniu połączenia, a dostęp SFTP odrzuca poprawne dane logowania.

Powód tkwi w samej konstrukcji. Panel podpisuje krótko żyjące tokeny, których ważność liczy się w minutach. Wings sprawdza czas wystawienia i wygaśnięcia względem własnego zegara. Jeśli oba systemy rozjadą się o więcej niż kilka minut, Wings odrzuci każdy token jako wygasły albo jeszcze nieważny, mimo że powstał przed chwilą.

Ważne dla zrozumienia: nie chodzi o strefę czasową. Panel i węzeł mogą mieć ustawione różne strefy czasowe, to bez znaczenia. Chodzi o bezwzględny moment w czasie. Sprawdź na obu maszynach:

date -u
timedatectl status

W wyniku timedatectl musi widnieć System clock synchronized: yes oraz NTP service: active. Jeśli nie:

timedatectl set-ntp true

Na systemach bez systemd-timesyncd, na przykład po instalacji minimalnej, zainstaluj chrony i sprawdź synchronizację:

apt -y install chrony
chronyc tracking

Wartość przy System time powinna mieścić się w zakresie milisekund. Maszyny wirtualne sklonowane z obrazu albo odtworzone ze snapshotu to najczęstsze źródło większych odchyleń.

Po czym poznasz, że naprawdę działa

Zielona ikona w panelu to dopiero pierwszy z pięciu dowodów. Przejdź całą listę, wtedy będziesz mieć pewność:

1. systemctl is-active wings zwraca active, a journalctl -u wings -n 20 nie pokazuje powtarzających się błędów.
2. Węzeł w przeglądzie zgłasza rzeczywistą pojemność pamięci i dysku serwera docelowego, a nie tylko limity wpisane w panelu. Te liczby przychodzą na żywo z węzła i są dowodem na działającą komunikację.
3. Zakładasz serwer testowy. W przeglądzie przechodzi on przez stan Installing i potem wyświetla się normalnie. Na węźle docker ps -a pokazuje odpowiadający mu kontener.
4. Uruchamiasz serwer i widzisz w przeglądarce bieżące wyjście konsoli. To dowód na połączenie WebSocket, a tym samym jednocześnie na certyfikat i na czas.
5. Łączysz się przez SFTP na porcie 2022 danymi logowania z panelu i widzisz pliki serwera. Tym samym potwierdzony jest też drugi port Wings.

Dopiero gdy wszystkie pięć punktów się zgadza, instalacja jest kompletna. Punkt czwarty i piąty z doświadczenia zawodzą najczęściej, chociaż panel do tego momentu wygląda zupełnie niepodejrzanie.

Panel i Wings razem albo osobno

Możliwe jest jedno i drugie. Na pojedynczym serwerze musisz zwrócić uwagę tylko na dwie rzeczy: użyj dwóch różnych nazw domen na tym samym adresie IP, jednej dla panelu na porcie 443 i drugiej dla węzła na porcie 8080. I licz się z tym, że apetyt serwerów gier na pamięć przyhamuje przy okazji panel, gdy zrobi się ciasno.

Rozdzielenie i tak jest normą od drugiego węzła wzwyż i ma przyjemny efekt uboczny: przeciążony albo atakowany serwer gry nie pociąga za sobą interfejsu zarządzania. Przy podstawowym zabezpieczeniu obu maszyn warto zajrzeć do naszej listy kontrolnej dla nowych serwerów root oraz do wpisów o zabezpieczaniu SSH i o fail2ban.

Na koniec praktyczna wskazówka do eksploatacji: obrazy Dockera dla serwerów gier przynoszą własne środowisko Javy. Nie musisz instalować Javy na węźle. Jeśli mimo to chcesz kiedyś przetestować coś poza Pterodactylem, odpowiednie drogi znajdziesz w naszych wpisach o Javie 21 na Debianie i o serwerze Minecraft na Debianie. Miej też na oku miejsce na dysku, obrazy i kopie zapasowe rosną szybko, pasuje do tego wpis Dysk pełny w Linuksie.