VulCode
Blog

Instalacja panelu Pterodactyl krok po kroku: panel, Wings i pierwszy serwer

Stawiasz panel Pterodactyl 1.15 na Ubuntu 24.04 z PHP 8.3, MariaDB, Redis i Nginx, a potem węzeł Wings na Dockerze, który uruchamia serwery gier. Według oficjalnej dokumentacji, z kolejnością, w której nic nie trzeba poprawiać.

VulCodeVulCode15 min czytania
Instalacja panelu Pterodactyl krok po kroku: panel, Wings i pierwszy serwer - VulCode
Co zbudujeszBash, 10 kroków
  1. PHP, MariaDB, RedisPanelPanel 1.15 za Nginx z SSL.
  2. Kolejka i cronTłopteroq i schedule:run co minutę.
  3. WingsWęzełDemon na Dockerze, który uruchamia serwery.
  4. Pierwszy serwerWynikAlokacja, egg i serwer gry w panelu.

Poradnik w skrócie

Pterodactyl to panel do zarządzania serwerami gier: panel w PHP, w którym klienci i administratorzy zarządzają serwerami, oraz Wings, demon na każdym węźle, który uruchamia serwery w kontenerach Docker. Po tym poradniku masz panel pod własną domeną z certyfikatem SSL, pierwszy węzeł i możesz założyć pierwszy serwer.

Instalacja panelu Pterodactyl

Grupa
Serwery i hosting
Poziom
zaawansowany
Czas czytania
około 15 min
Kod
Bash

Pliki: crontab, pteroq.service, pterodactyl.conf, wings.service; do tego polecenia w terminalu.

Kroki
10 kroków

W 10 z nich kod albo polecenia do skopiowania.

Sprawdzenie
API GitHuba, wydania pterodactyl/panel i pterodactyl/wings

Najnowsze wydania: panel v1.15.1 i Wings v1.13.3; panelu nie instalowaliśmy

Dokumentacja
4 oficjalne dokumenty

Pterodactyl: Getting Started (panel); Pterodactyl: Webserver Configuration; Pterodactyl: Creating SSL Certificates; Pterodactyl: Installing Wings

Z naszego kodu
WaveHost

wave-panel-backend/src/lib/pterodactyl.ts

Zanim zaczniesz

Kolejność kroków różni się od dokumentacji w jednym miejscu: certyfikat SSL zakładamy, zanim podmienimy konfigurację Nginx. Dokumentacja ostrzega, że konfiguracja SSL bez certyfikatu nie pozwoli Nginx wystartować, więc tak unikasz poprawiania czegokolwiek po drodze.

Co musisz mieć
Instalacja panelu Pterodactyl
Serwer z Ubuntu 24.04 albo Debianem 12 lub 13
Dokumentacja obsługuje Ubuntu 22.04 i 24.04, Debiana 11, 12 i 13 oraz RHEL, Rocky i AlmaLinux 8 i 9. Polecenia w poradniku są dla Ubuntu 24.04, na którym MariaDB instaluje się bez dodatkowego repozytorium.
Wirtualizacja KVM albo serwer dedykowany na węzeł
Wings potrzebuje Dockera. Na OpenVZ, Virtuozzo i LXC najpewniej nie zadziała, chyba że dostawca włączył zagnieżdżoną wirtualizację. KVM działa na pewno.
Domena i rekord DNS
panel.twojadomena.pl musi wskazywać na serwer, zanim poprosisz o certyfikat. Gdy panel działa z SSL, węzeł Wings też musi mieć certyfikat dla swojej domeny.
Dostęp root
Instalacja zakłada konto root albo sudo. Panel na koniec działa jako www-data, a Wings jako root, bo zarządza Dockerem.

Wymagania panelu

SkładnikWersjaUwagi
PHP8.2 lub 8.38.3 zalecane; rozszerzenia cli, openssl, gd, mysql, PDO, mbstring, tokenizer, bcmath, xml, curl, zip, fpm
Baza danychMySQL 5.7.22+ / MariaDB 10.2+MySQL 8 zalecany
Redisredis-servercache i kolejka
Composerv2instalacja zależności PHP

Krok po kroku

10 kroków z poleceniami i plikami do skopiowania. Spis obok pokazuje, gdzie jesteś.

Zainstaluj zależności

Na Ubuntu 24.04 PHP 8.3 jest w repozytorium systemu, a dodatkowe repozytorium ondrej/php jest potrzebne tylko na 22.04. Redis instalujesz z oficjalnego repozytorium Redis, a Composer instalatorem z getcomposer.org.

bashbash, 11 linii
# Ubuntu 24.04apt -y install software-properties-common curl apt-transport-https ca-certificates gnupg # Oficjalne repozytorium Rediscurl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpgecho "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/redis.list apt updateapt -y install php8.3 php8.3-{common,cli,gd,mysql,mbstring,bcmath,xml,fpm,curl,zip} mariadb-server nginx tar unzip git redis-server curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer

Pobierz pliki panelu

Panel pobierasz jako gotowe archiwum z najnowszego wydania na GitHubie. Katalogi storage i bootstrap/cache muszą być zapisywalne, bo panel trzyma tam pliki i cache.

bashbash, 5 linii
mkdir -p /var/www/pterodactylcd /var/www/pterodactylcurl -Lo panel.tar.gz https://github.com/pterodactyl/panel/releases/latest/download/panel.tar.gztar -xzvf panel.tar.gzchmod -R 755 storage/* bootstrap/cache/

Utwórz bazę i użytkownika

Użytkownik bazy łączy się z 127.0.0.1, nie z localhost: w MariaDB to dwa różne konta. Hasło zmień na własne, unikalne.

mariadbsql, 6 linii
mariadb -u root -p CREATE USER 'pterodactyl'@'127.0.0.1' IDENTIFIED BY 'unikalne-silne-haslo';CREATE DATABASE panel;GRANT ALL PRIVILEGES ON panel.* TO 'pterodactyl'@'127.0.0.1' WITH GRANT OPTION;exit

Zainstaluj panel i zapisz klucz

key:generate tworzy APP_KEY, którym panel szyfruje wrażliwe dane, na przykład klucze API. Uruchamiasz je tylko przy pierwszej instalacji. Skopiuj klucz do menedżera haseł albo zaszyfrowanego pliku poza serwerem: bez niego zaszyfrowanych danych nie odzyskasz nawet z kopii bazy.

bashbash, 6 linii
cp .env.example .envCOMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloaderphp artisan key:generate --force # Zapisz klucz poza serwerem: bez niego zaszyfrowanych danych nie odzyskaszgrep APP_KEY /var/www/pterodactyl/.env

Skonfiguruj środowisko, bazę i pierwszego administratora

Trzy polecenia p:environment pytają o adres panelu, cache, sesje, dane bazy i serwer poczty. migrate --seed tworzy tabele i dodaje domyślne gniazda i eggi: nie przerywaj go w trakcie. p:user:make zakłada konto administratora.

bashbash, 8 linii
php artisan p:environment:setupphp artisan p:environment:databasephp artisan p:environment:mail     # smtp dla własnego serwera poczty php artisan migrate --seed --forcephp artisan p:user:make            # hasło: 8 znaków, wielkie i małe litery, cyfra chown -R www-data:www-data /var/www/pterodactyl/*

Uruchom kolejkę i cron

Cron co minutę uruchamia zadania panelu, na przykład czyszczenie sesji i zaplanowane zadania serwerów. Usługa pteroq przetwarza kolejkę: maile i inne zadania w tle. Na RHEL, Rocky i AlmaLinux zamień redis-server.service na redis.service w linii After.

crontab, pteroq.serviceini, 19 linii
# sudo crontab -e* * * * * php /var/www/pterodactyl/artisan schedule:run >> /dev/null 2>&1 # /etc/systemd/system/pteroq.service[Unit]Description=Pterodactyl Queue WorkerAfter=redis-server.service [Service]User=www-dataGroup=www-dataRestart=alwaysExecStart=/usr/bin/php /var/www/pterodactyl/artisan queue:work --queue=high,standard,low --sleep=3 --tries=3StartLimitInterval=180StartLimitBurst=30RestartSec=5s [Install]WantedBy=multi-user.target
bash
sudo systemctl enable --now redis-serversudo systemctl enable --now pteroq.service

Załóż certyfikat SSL, zanim zmienisz Nginx

Certbot z wtyczką Nginx wystawi certyfikat, dopóki działa domyślna konfiguracja Nginx i port 80 jest otwarty. Dopiero potem podmieniasz konfigurację na wersję z SSL, która od razu znajdzie pliki certyfikatu.

bashbash, 5 linii
sudo apt install -y certbot python3-certbot-nginxcertbot certonly --nginx -d panel.twojadomena.pl # odnawianie codziennie o 23:00, z restartem nginx po udanym odnowieniu0 23 * * * certbot renew --quiet --deploy-hook "systemctl restart nginx"

Skonfiguruj Nginx

Konfiguracja przekierowuje HTTP na HTTPS, kieruje żądania PHP do gniazda php8.3-fpm i pozwala wysyłać pliki do 100 MB. Ścieżka gniazda musi pasować do wersji PHP, którą zainstalowałeś.

/etc/nginx/sites-available/pterodactyl.confnginx, 46 linii
server {    listen 80;    server_name panel.twojadomena.pl;    return 301 https://$server_name$request_uri;} server {    listen 443 ssl http2;    server_name panel.twojadomena.pl;     root /var/www/pterodactyl/public;    index index.php;     client_max_body_size 100m;    client_body_timeout 120s;    sendfile off;     ssl_certificate /etc/letsencrypt/live/panel.twojadomena.pl/fullchain.pem;    ssl_certificate_key /etc/letsencrypt/live/panel.twojadomena.pl/privkey.pem;    ssl_session_cache shared:SSL:10m;    ssl_protocols TLSv1.2 TLSv1.3;     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;    }}
bash
rm /etc/nginx/sites-enabled/default# zapisz konfigurację jako /etc/nginx/sites-available/pterodactyl.confsudo ln -s /etc/nginx/sites-available/pterodactyl.conf /etc/nginx/sites-enabled/pterodactyl.confsudo systemctl restart nginx

Zainstaluj Docker i Wings na węźle

Najpierw sprawdź wirtualizację: systemd-detect-virt nie może pokazać openvz ani lxc. Docker instalujesz skryptem get.docker.com, a Wings to pojedynczy plik wykonywalny z najnowszego wydania. Jeśli jądro kończy się na -grs-ipv6-64 albo -mod-std-ipv6-64, poproś dostawcę o standardowe jądro dystrybucji.

bashbash, 8 linii
systemd-detect-virt        # kvm albo none: Docker zadziała; openvz albo lxc: najpewniej nie curl -sSL https://get.docker.com/ | CHANNEL=stable bashsudo systemctl enable --now docker sudo mkdir -p /etc/pterodactylcurl -L -o /usr/local/bin/wings "https://github.com/pterodactyl/wings/releases/latest/download/wings_linux_$([[ "$(uname -m)" == "x86_64" ]] && echo "amd64" || echo "arm64")"sudo chmod u+x /usr/local/bin/wings

Dodaj węzeł w panelu i uruchom Wings

W panelu administratora wybierz Nodes i Create New. Po utworzeniu węzła zakładka Configuration pokazuje gotowy config.yml: wklej go do /etc/pterodactyl albo użyj przycisku Generate Token, który daje polecenie do wklejenia w terminalu. Pierwszy start wings --debug pokaże ewentualne błędy, potem uruchamiasz usługę.

Alokacja to para adres IP i port, którą przypisujesz serwerowi. Każdy serwer potrzebuje co najmniej jednej. Za NAT-em podajesz adres wewnętrzny.

/etc/systemd/system/wings.serviceini, 20 linii
# /etc/systemd/system/wings.service[Unit]Description=Pterodactyl Wings DaemonAfter=docker.serviceRequires=docker.servicePartOf=docker.service [Service]User=rootWorkingDirectory=/etc/pterodactylLimitNOFILE=4096PIDFile=/var/run/wings/daemon.pidExecStart=/usr/local/bin/wingsRestart=on-failureStartLimitInterval=180StartLimitBurst=30RestartSec=5s [Install]WantedBy=multi-user.target
bash
# config.yml z zakładki Configuration węzła w panelu wklej do /etc/pterodactyl/config.ymlsudo wings --debug          # pierwszy start na pierwszym planie; Ctrl+C, gdy działa bez błędówsudo systemctl enable --now wingshostname -I | awk '{print $1}'   # adres IP do alokacji

Sprawdź, czy działa

Panelu nie instalowaliśmy na potrzeby tego poradnika. Polecenia porównaliśmy 6 października 2026 r. z dokumentacją Pterodactyla w wersji 1, a najnowsze wydania sprawdziliśmy w API GitHuba: panel v1.15.1 i Wings v1.13.3, oba z 14 sierpnia 2026 r. Polecenia curl z latest/download pobierają właśnie te wersje.

terminal6 października 2026API GitHuba, wydania pterodactyl/panel i pterodactyl/wings
$ curl -s https://api.github.com/repos/pterodactyl/panel/releases/latest
v1.15.1 2026-08-14 panel.tar.gz
$ curl -s https://api.github.com/repos/pterodactyl/wings/releases/latest
v1.13.3 2026-08-14 wings_linux_amd64, wings_linux_arm64
Najnowsze wydania: panel v1.15.1 i Wings v1.13.3; panelu nie instalowaliśmy
Co znaczą linie wyniku
  1. linie 1-2Panel v1.15.1

    Najnowsze wydanie panelu z 14 sierpnia 2026 r. Polecenie curl z latest/download w kroku 2 pobiera właśnie ten panel.tar.gz.

  2. linie 3-4Wings v1.13.3

    Wydanie Wings z tego samego dnia, w plikach dla amd64 i arm64.

  3. linie 1-4Co tu sprawdziliśmy

    Wersje, a nie instalację: polecenia porównaliśmy z dokumentacją Pterodactyla w wersji 1.

Po czym poznasz, że działa u Ciebie

  • https://panel.twojadomena.pl pokazuje stronę logowania z ważnym certyfikatem.
  • systemctl status pteroq i wings pokazuje active (running).
  • Węzeł w panelu ma zielone serce, czyli panel łączy się z Wings.
  • Nowy serwer z domyślnego eggu instaluje się i startuje.

Najczęstsze błędy

Ta sama droga co w "Co zbudujesz" na górze strony, z miejscami, w których praca staje najczęściej. Przy każdym błędzie: objaw, przyczyna i co zrobić.

Gdzie staje i dlaczego

PHP, MariaDB, Redis

Panel

Panel 1.15 za Nginx z SSL.

  • Zatrzymuje się: 502 Bad Gateway na stronie panelu

    fastcgi_pass wskazuje gniazdo innej wersji PHP niż zainstalowana albo php-fpm nie działa. Co zrobić: Sprawdź ls /run/php/ i popraw ścieżkę w pterodactyl.conf.

  • Zatrzymuje się: Nginx nie startuje po zmianie konfiguracji

    Konfiguracja z SSL wskazuje certyfikat, którego jeszcze nie ma. Co zrobić: Najpierw certbot certonly, potem konfiguracja SSL.

Kolejka i cron

Tło

pteroq i schedule:run co minutę.

  • Zatrzymuje się: Maile z panelu nie wychodzą

    Usługa pteroq nie działa albo linia After wskazuje nieistniejącą usługę Redis. Co zrobić: systemctl status pteroq; na RHEL użyj redis.service, bez Redis usuń linię After.

Wings

Węzeł

Demon na Dockerze, który uruchamia serwery.

  • Zatrzymuje się: Węzeł w panelu ma czerwone serce

    Wings nie działa albo panel z SSL łączy się z Wings bez certyfikatu dla jego domeny. Co zrobić: Uruchom wings --debug i załóż certyfikat dla domeny węzła.

  • Zatrzymuje się: Docker nie działa na węźle

    Wirtualizacja OpenVZ lub LXC albo zmodyfikowane jądro dostawcy. Co zrobić: Użyj KVM albo serwera dedykowanego ze standardowym jądrem.

Pierwszy serwer

Wynik

Alokacja, egg i serwer gry w panelu.

    Jak to robimy u siebie

    Ten sam temat w kodzie, który utrzymujemy: WaveHost.

    Zamówienie serwera gry z wywołaniami Application API Pterodactyla

    Serwery z Pterodactyla w panelu WaveHost

    W panelu klienta WaveHost zakup serwera gry tworzy serwer w Pterodactylu przez Application API, kluczem ptla_. Klient nie wypełnia formularza w Pterodactylu: panel pobiera z eggu obraz Dockera, polecenie startu i domyślne zmienne, nakłada limity z kupionego pakietu i przydziela alokację.

    Operacje w trakcie działania, czyli zasilanie, konsola i zasoby na żywo, idą przez Client API z kluczem ptlc_ administratora, bo Application API ich nie udostępnia. Użytkownik panelu WaveHost ma jedno konto w Pterodactylu, zapisane przy jego koncie, więc kolejne zakupy trafiają do tego samego użytkownika.

    wave-panel-backend/src/lib/pterodactyl.tsts, 32 linie
    export async function createPteroServer(input: {  name: string;  pteroUserId: number;  nest: number;  egg: number;  environmentOverrides?: Record<string, string>;  limits: { memoryMb: number; diskMb: number; cpuPercent: number };  allocationId: number;  startOnCompletion?: boolean;}) {  const eggInfo = await getEggInfo(input.nest, input.egg);  const res = await app().post(`/api/application/servers`, {    name: input.name,    user: input.pteroUserId,    egg: input.egg,    docker_image: eggInfo.dockerImage,    startup: eggInfo.startup,    environment: { ...eggInfo.environment, ...input.environmentOverrides },    limits: {      memory: input.limits.memoryMb,      swap: 0,      disk: input.limits.diskMb,      io: 500,      cpu: input.limits.cpuPercent,    },    feature_limits: { databases: 0, backups: 0, allocations: 1 },    allocation: { default: input.allocationId },    start_on_completion: input.startOnCompletion ?? true,  });  const attrs = res.data.attributes;  return { id: attrs.id as number, uuid: attrs.uuid as string, identifier: attrs.identifier as string };}

    Tworzenie serwera w panelu WaveHost.

    Powiązane strony i źródła

    Usługa, narzędzia i hasła, do których odsyła ten poradnik, i kolejne poradniki.

    Oficjalna dokumentacja

    Wolisz, żeby zrobił to ktoś, kto już to robił?

    Opisz swój system. Odpiszemy w godzinę z planem integracji i wyceną.

    Pytania

    Czy ten wpis był przydatny?

    Czytaj dalej