> For the complete documentation index, see [llms.txt](https://wiki.skylix.pl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.skylix.pl/vps/stawianie-maszyn/pterodactyl.md). # Pterodactyl Jak zainstalować panel Pterodactyl oraz demona Wings na serwerze z Ubuntu, krok po kroku. ## Instalacja Pterodactyl (Panel + Wings) Pterodactyl to darmowy panel do zarządzania serwerami gier (m.in. Minecraft), który działa na kontenerach Docker. Składa się z dwóch części: * **Panel**: aplikacja webowa (PHP) do zarządzania serwerami i użytkownikami. * **Wings**: demon uruchamiający serwery w kontenerach Docker. Instalujesz go na każdej maszynie (węźle), na której mają działać serwery gier. Ten poradnik opisuje instalację obu części, w tym konfigurację SSL i usług systemowych. {% hint style="info" %} W środowisku produkcyjnym zalecamy instalację Panelu i Wings na **osobnych maszynach**. W małych wdrożeniach możesz użyć jednej, ale pamiętaj, że wtedy awaria lub przeciążenie serwerów gier wpłynie też na panel. {% endhint %} ### Wymagania * Serwer lub maszyna wirtualna z **Ubuntu 22.04 lub 24.04** (poradnik zakłada ten system) * Dostęp root przez SSH * Dwie domeny lub subdomeny skierowane na adres IP serwera (rekord A): * `panel.twojadomena.pl` dla Panelu * `node1.twojadomena.pl` dla węzła Wings * Minimum 2 vCPU i 2 GB RAM dla samego Panelu. Wings potrzebuje zasobów zależnie od liczby i rodzaju serwerów gier. {% hint style="warning" %} Wings używa Dockera i **nie działa poprawnie na wirtualizacji OpenVZ ani w kontenerach LXC**. Użyj pełnej maszyny wirtualnej (KVM) lub serwera dedykowanego. {% endhint %} {% hint style="warning" %} Domeny węzła **nie możesz** przepuszczać przez proxy Cloudflare (pomarańczowa chmurka). Proxy blokuje porty Wings i serwerów gier. Ustaw rekord DNS na tryb "DNS only". {% endhint %} *** ## Część 1: Instalacja Panelu ### 1. Zależności Zaktualizuj system i zainstaluj narzędzia pomocnicze: ```bash apt update && apt -y upgrade apt -y install software-properties-common curl apt-transport-https ca-certificates gnupg ``` Dodaj repozytoria PHP i Redis: ```bash LC_ALL=C.UTF-8 add-apt-repository -y ppa:ondrej/php curl -fsSL https://packages.redis.io/gpg | gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | tee /etc/apt/sources.list.d/redis.list apt update ``` Zainstaluj wymagane pakiety: ```bash apt -y install php8.3 php8.3-{common,cli,gd,mysql,mbstring,bcmath,xml,fpm,curl,zip} \ mariadb-server nginx tar unzip git redis-server ``` Zainstaluj Composera: ```bash curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer ``` ### 2. Pobranie plików Panelu ```bash mkdir -p /var/www/pterodactyl cd /var/www/pterodactyl curl -Lo panel.tar.gz https://github.com/pterodactyl/panel/releases/latest/download/panel.tar.gz tar -xzvf panel.tar.gz chmod -R 755 storage/* bootstrap/cache/ ``` ### 3. Baza danych Zaloguj się do MariaDB: ```bash mysql -u root -p ``` Utwórz użytkownika i bazę (zamień `SILNE_HASLO` na własne, losowe hasło): ```sql CREATE USER 'pterodactyl'@'127.0.0.1' IDENTIFIED BY 'SILNE_HASLO'; CREATE DATABASE panel; GRANT ALL PRIVILEGES ON panel.* TO 'pterodactyl'@'127.0.0.1' WITH GRANT OPTION; EXIT; ``` ### 4. Konfiguracja Panelu ```bash cd /var/www/pterodactyl cp .env.example .env COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader php artisan key:generate --force ``` {% hint style="danger" %} Klucz `APP_KEY` zapisany w pliku `.env` służy do szyfrowania danych. **Zrób jego kopię w bezpiecznym miejscu.** Jeśli go utracisz, zaszyfrowane dane (np. tokeny węzłów) będą nie do odzyskania. {% endhint %} Uruchom kreatory konfiguracji: ```bash php artisan p:environment:setup php artisan p:environment:database php artisan p:environment:mail ``` W pierwszym kreatorze podaj adres e-mail, strefę czasową (np. `Europe/Warsaw`) i adres Panelu z `https://`. Wybierz Redis jako cache, sesje i kolejki (domyślne wartości `127.0.0.1`, port `6379`). W drugim kreatorze podaj dane bazy z kroku 3. Wykonaj migracje i utwórz konto administratora: ```bash php artisan migrate --seed --force php artisan p:user:make ``` Ustaw uprawnienia do plików: ```bash chown -R www-data:www-data /var/www/pterodactyl/* ``` ### 5. Zadania cykliczne (cron) ```bash crontab -e ``` Dodaj na końcu linię: ``` * * * * * php /var/www/pterodactyl/artisan schedule:run >> /dev/null 2>&1 ``` ### 6. Obsługa kolejek (pteroq) Utwórz plik `/etc/systemd/system/pteroq.service`: ```ini [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 ``` Włącz usługi: ```bash systemctl enable --now redis-server systemctl enable --now pteroq.service ``` ### 7. Nginx i certyfikat SSL Usuń domyślną stronę: ```bash rm /etc/nginx/sites-enabled/default ``` Utwórz plik `/etc/nginx/sites-available/pterodactyl.conf` (zamień domenę na swoją): ```nginx server { listen 80; server_name panel.twojadomena.pl; root /var/www/pterodactyl/public; index index.html index.htm index.php; charset utf-8; location / { try_files $uri $uri/ /index.php?$query_string; } location = /favicon.ico { access_log off; log_not_found off; } location = /robots.txt { access_log off; log_not_found off; } access_log off; error_log /var/log/nginx/pterodactyl.app-error.log error; client_max_body_size 100m; client_body_timeout 120s; sendfile off; 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; } } ``` Włącz konfigurację i uzyskaj certyfikat Let's Encrypt (Certbot sam doda obsługę HTTPS i przekierowanie): ```bash ln -s /etc/nginx/sites-available/pterodactyl.conf /etc/nginx/sites-enabled/pterodactyl.conf nginx -t systemctl restart nginx apt -y install certbot python3-certbot-nginx certbot --nginx -d panel.twojadomena.pl ``` Panel jest już dostępny pod adresem `https://panel.twojadomena.pl`. Zaloguj się kontem utworzonym w kroku 4. *** ## Część 2: Instalacja Wings Wykonaj te kroki na maszynie, na której mają działać serwery gier (może to być ten sam serwer co Panel). ### 1. Docker ```bash curl -sSL https://get.docker.com/ | CHANNEL=stable bash systemctl enable --now docker ``` ### 2. Pobranie Wings ```bash mkdir -p /etc/pterodactyl curl -L -o /usr/local/bin/wings \ "https://github.com/pterodactyl/wings/releases/latest/download/wings_linux_$([[ "$(uname -m)" == "x86_64" ]] && echo "amd64" || echo "arm64")" chmod u+x /usr/local/bin/wings ``` ### 3. Certyfikat SSL dla węzła Skoro Panel działa po HTTPS, węzeł też musi używać SSL i domeny (nie samego adresu IP). Jeśli port 80 jest wolny (Panel jest na innej maszynie lub jest zatrzymany nginx): ```bash apt -y install certbot certbot certonly --standalone -d node1.twojadomena.pl ``` Jeśli Wings stoi na tym samym serwerze co Panel, użyj wtyczki nginx: ```bash certbot certonly --nginx -d node1.twojadomena.pl ``` ### 4. Utworzenie węzła w Panelu 1. Zaloguj się do Panelu i wejdź w **Administration → Locations**. Utwórz lokalizację (np. `PL`). 2. Wejdź w **Administration → Nodes → Create New**. 3. Uzupełnij pola: * **Name**: dowolna nazwa węzła * **FQDN**: `node1.twojadomena.pl` * **Communicate Over SSL**: `Use SSL Connection` * **Behind Proxy**: `Not Behind Proxy` * **Total Memory / Total Disk Space**: dostępne zasoby węzła * **Daemon Port**: `8080`, **Daemon SFTP Port**: `2022` 4. Zapisz węzeł i przejdź do zakładki **Configuration**. ### 5. Konfiguracja Wings W zakładce **Configuration** skopiuj wygenerowaną konfigurację (lub użyj przycisku **Generate Token** i wklej gotową komendę). Zapisz zawartość w pliku: ```bash nano /etc/pterodactyl/config.yml ``` Upewnij się, że w sekcji `ssl` ścieżki do certyfikatów wskazują na Twoją domenę: ```yaml api: ssl: enabled: true cert: /etc/letsencrypt/live/node1.twojadomena.pl/fullchain.pem key: /etc/letsencrypt/live/node1.twojadomena.pl/privkey.pem ``` Uruchom Wings w trybie debugowania, aby sprawdzić, czy łączy się z Panelem: ```bash wings --debug ``` Gdy logi nie pokazują błędów, zatrzymaj proces kombinacją `Ctrl+C`. ### 6. Usługa systemowa Wings Utwórz plik `/etc/systemd/system/wings.service`: ```ini [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 ``` Włącz i uruchom usługę: ```bash systemctl enable --now wings systemctl status wings ``` W Panelu przy węźle powinna pojawić się zielona ikona połączenia. ### 7. Firewall Otwórz potrzebne porty (przykład dla UFW): ```bash ufw allow 22/tcp # SSH ufw allow 80/tcp # HTTP (certyfikaty) ufw allow 443/tcp # HTTPS (Panel) ufw allow 8080/tcp # API Wings ufw allow 2022/tcp # SFTP ufw allow 25565/tcp # przykładowy port serwera Minecraft ufw enable ``` Dla każdego serwera gry musisz otworzyć jego port (lub zakres portów). Jeśli korzystasz z firewalla dostawcy, otwórz porty także tam. *** ## Część 3: Pierwszy serwer 1. W **Administration → Nodes → (Twój węzeł) → Allocation** dodaj adres IP i porty, np. `25565`. 2. Wejdź w **Administration → Servers → Create New**. 3. Wybierz właściciela, węzeł, alokację, limity zasobów oraz **Nest** (np. Minecraft) i **Egg** (np. Paper, Vanilla). 4. Zapisz. Serwer zainstaluje się automatycznie, a postęp zobaczysz w konsoli. *** ## Aktualizacje ### Aktualizacja Panelu ```bash 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 ``` ### Aktualizacja Wings ```bash systemctl stop wings curl -L -o /usr/local/bin/wings \ "https://github.com/pterodactyl/wings/releases/latest/download/wings_linux_$([[ "$(uname -m)" == "x86_64" ]] && echo "amd64" || echo "arm64")" chmod u+x /usr/local/bin/wings systemctl restart wings ``` {% hint style="info" %} Przed aktualizacją zrób kopię bazy danych i pliku `.env`. Zawsze sprawdź też informacje o wersji w oficjalnej dokumentacji Pterodactyl, bo niektóre aktualizacje wymagają dodatkowych kroków. {% endhint %} *** ## Zabezpieczenie 1. **Włącz 2FA** na koncie administratora (Account → Two-Factor Authentication). 2. **Używaj silnych haseł** do bazy danych i kont użytkowników. 3. **Aktualizuj system, Panel i Wings** regularnie. 4. **Ogranicz dostęp do SSH** (klucze zamiast haseł, Fail2ban). 5. **Rób kopie zapasowe** bazy danych, pliku `.env` i danych serwerów. 6. **Nie udostępniaj portów bazy danych** (3306) ani Redis (6379) z zewnątrz. ## Najczęstsze problemy | Objaw | Możliwa przyczyna | Rozwiązanie | | --------------------------------- | -------------------------------------- | --------------------------------------------------------------------------- | | Błąd 500 po wejściu na Panel | Złe uprawnienia lub brak `.env` | `chown -R www-data:www-data /var/www/pterodactyl/*`, sprawdź `storage/logs` | | Węzeł ma czerwoną ikonę | Wings nie działa lub brak połączenia | `systemctl status wings`, `wings --debug`, sprawdź FQDN i port 8080 | | Brak połączenia z węzłem po HTTPS | Błędny certyfikat lub proxy Cloudflare | Sprawdź ścieżki w `config.yml`, wyłącz proxy dla domeny węzła | | Serwer nie instaluje się | Brak miejsca lub problem z Dockerem | `systemctl status docker`, `df -h`, logi w konsoli instalacji | | Brak e-maili z Panelu | Zła konfiguracja SMTP | Uruchom ponownie `php artisan p:environment:mail` | | Nie działa konsola serwera | Zablokowany port 8080 lub WebSocket | Otwórz port 8080 w firewallu, sprawdź ustawienia Nginx i proxy | ## Potrzebujesz pomocy? Jeśli coś nie działa, napisz do nas na Discordzie lub skontaktuj się z pomocą techniczną.