Installare il pannello Pterodactyl e Wings
Installa Pterodactyl sul tuo server Linux: pannello, database, HTTPS, Docker, Wings, nodo, porte, allocazioni, primo server di gioco, aggiornamenti e risoluzione dei problemi.
In questa pagina
I tuoi valori
Inseriscili una volta: i comandi della guida si aggiornano.
Questa guida spiega come installare Pterodactyl sul tuo server Linux per gestire i tuoi server di gioco da un'interfaccia web. Copre il pannello, Wings, l'HTTPS, le porte, le allocazioni e un primo server di gioco.
HostMyServers non offre hosting di giochi gestito: installi e amministri Pterodactyl da solo. Questa guida segue la documentazione ufficiale del progetto per il branch stabile 1.x.
Ordina un Server
Pterodactyl funziona su un VPS o su un server dedicato:
Prevedi le risorse per il pannello, per Docker e per tutti i server di gioco che intendi avviare.
Come funziona
| Componente | Ruolo |
|---|---|
| Pannello | Applicazione web PHP: account, server, permessi. Usa MariaDB e Redis |
| Wings | Servizio installato su ogni macchina che ospita giochi. Controlla Docker |
| Nodo | Macchina che esegue Wings, dichiarata nel pannello |
| Allocazione | Coppia indirizzo IP e porta assegnata a un server di gioco |
| Egg | Modello che descrive come installare e avviare un gioco |
Questa guida installa il pannello e Wings sulla stessa macchina. Per mettere Wings su un'altra macchina, segui lì i passi da 9 a 13, aprici le porte del nodo e ottieni il suo certificato con certbot certonly --standalone, perché lì non serve alcun server web.
Prerequisiti
- Un server a 64 bit con Debian 12 o 13, oppure Ubuntu 22.04 o 24.04
- Un accesso
rooto un utentesudo - Due sottodomini che puntano al server, con un record DNS
A:panel.tuo-dominio.comenode1.tuo-dominio.com - Una virtualizzazione compatibile con Docker
Controlla il tipo di virtualizzazione e il DNS:
systemd-detect-virt
getent hosts panel.tuo-dominio.com node1.tuo-dominio.comKVM e none (macchina fisica) vanno bene. Con openvz o lxc, Wings probabilmente non funzionerà.
I comandi seguenti si eseguono come root. Apri una sessione con:
sudo -iPorte utilizzate
| Porta | Protocollo | Servizio | Accesso |
|---|---|---|---|
| 22 | TCP | SSH | Amministrazione |
| 80 | TCP | Nginx, validazione Let's Encrypt e reindirizzamento | Pubblico |
| 443 | TCP | Pannello in HTTPS | Pubblico |
| 8080 | TCP | API di Wings, usata dal pannello e dai browser | Pubblico |
| 2022 | TCP | SFTP di Wings, per i file dei server | Pubblico |
| Allocazioni | TCP e UDP | Giochi, ad esempio da 27015 a 27020 |
Pubblico |
MariaDB (3306) e Redis (6379) restano in locale: non aprirli.
Passo 1: aprire le porte
Con UFW, autorizza SSH prima di attivare il firewall, adattando la porta se hai cambiato quella di SSH:
ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw allow 8080/tcp
ufw allow 2022/tcp
ufw enable
ufw statusCon iptables o nftables, apri le stesse porte TCP. Non salvare l'intero set di regole dopo aver installato Docker, perché vi aggiunge le sue: aggiungi le tue regole al tuo file di configurazione.
Passo 2: installare le dipendenze del pannello
Il pannello richiede PHP 8.2 o 8.3 (8.3 consigliato), MariaDB 10.2 o superiore, Redis, un server web e Composer 2. Lancia solo il blocco del tuo sistema.
Debian 13
apt update
apt install -y curl ca-certificates gnupg2 sudo lsb-release
echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" | tee /etc/apt/sources.list.d/sury-php.list
curl -fsSL https://packages.sury.org/php/apt.gpg | gpg --dearmor -o /etc/apt/trusted.gpg.d/sury-keyring.gpg
apt update
apt install -y php8.3 php8.3-{common,cli,gd,mysql,mbstring,bcmath,xml,fpm,curl,zip} mariadb-server nginx tar unzip git redis-serverDebian 12
apt update
apt install -y curl ca-certificates gnupg2 sudo lsb-release
echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" | tee /etc/apt/sources.list.d/sury-php.list
curl -fsSL https://packages.sury.org/php/apt.gpg | gpg --dearmor -o /etc/apt/trusted.gpg.d/sury-keyring.gpg
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
curl -LsS https://r.mariadb.com/downloads/mariadb_repo_setup | bash
apt update
apt install -y php8.3 php8.3-{common,cli,gd,mysql,mbstring,bcmath,xml,fpm,curl,zip} mariadb-server nginx tar unzip git redis-serverUbuntu 24.04
apt update
apt install -y software-properties-common curl apt-transport-https ca-certificates gnupg lsb-release
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
apt install -y php8.3 php8.3-{common,cli,gd,mysql,mbstring,bcmath,xml,fpm,curl,zip} mariadb-server nginx tar unzip git redis-serverUbuntu 22.04
apt update
apt install -y software-properties-common curl apt-transport-https ca-certificates gnupg lsb-release
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
apt install -y php8.3 php8.3-{common,cli,gd,mysql,mbstring,bcmath,xml,fpm,curl,zip} mariadb-server nginx tar unzip git redis-serverComposer e verifica
Su tutti i sistemi, installa Composer, attiva Redis e controlla le versioni:
curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
systemctl enable --now redis-server
php -v
composer --version
mariadb --version
redis-cli pingphp -v deve mostrare una versione 8.3 e redis-cli ping deve rispondere PONG.
Passo 3: creare il database
Genera una password e conservala:
openssl rand -base64 24Apri MariaDB. Se viene richiesta una password e non ne hai definita una, premi Invio.
mariadb -u root -pCREATE USER 'pterodactyl'@'127.0.0.1' IDENTIFIED BY 'PasswordGenerata';
CREATE DATABASE panel;
GRANT ALL PRIVILEGES ON panel.* TO 'pterodactyl'@'127.0.0.1' WITH GRANT OPTION;
exitPasso 4: scaricare il pannello
mkdir -p /var/www/pterodactyl
cd /var/www/pterodactyl
curl -Lo panel.tar.gz https://github.com/pterodactyl/panel/releases/download/v1.15.2/panel.tar.gz
tar -xzvf panel.tar.gz
chmod -R 755 storage/* bootstrap/cache/Passo 5: configurare il pannello
Installa le dipendenze PHP e genera la chiave di cifratura:
cp .env.example .env
COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader
php artisan key:generate --force
grep APP_KEY /var/www/pterodactyl/.envLancia poi le procedure guidate di configurazione:
php artisan p:environment:setup
php artisan p:environment:database
php artisan p:environment:mail| Domanda | Risposta consigliata |
|---|---|
| Egg Author Email | Il tuo indirizzo e-mail |
| Application URL | https://panel.tuo-dominio.com |
| Application Timezone | Europe/Paris o il tuo fuso orario |
| Cache Driver, Session Driver e Queue Driver | redis |
| Enable UI based settings editor? | yes |
| Enable sending anonymous telemetry data? | A tua scelta |
| Redis Host e porta | 127.0.0.1 e 6379, senza password su un'installazione locale predefinita |
| Database Host e Database Port | 127.0.0.1 e 3306 |
| Database Name | panel |
| Database Username | pterodactyl |
| Database Password | La password del passo 3 |
Per le e-mail, il progetto consiglia un server SMTP anziché l'invio interno di PHP. La telemetria del pannello è anonima e documentata dal progetto.
Crea le tabelle, poi il tuo account amministratore. La migrazione può essere lunga: non interromperla.
php artisan migrate --seed --force
php artisan p:user:make
chown -R www-data:www-data /var/www/pterodactyl/*Rispondi yes alla domanda Is this user an administrator?. La password deve contenere almeno 8 caratteri, con maiuscole, minuscole e un numero.
Passo 6: attivare le attività in background
Apri il crontab di root:
crontab -eAggiungi questa riga:
* * * * * php /var/www/pterodactyl/artisan schedule:run >> /dev/null 2>&1Crea il servizio della coda:
nano /etc/systemd/system/pteroq.service# 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.targetAttivalo e controlla il suo stato:
systemctl daemon-reload
systemctl enable --now pteroq.service
systemctl is-active pteroq.serviceIl comando deve rispondere active.
Passo 7: ottenere i certificati HTTPS
Il pannello e Wings hanno ciascuno bisogno di un certificato. Se il pannello è in HTTPS, deve esserlo anche Wings.
apt install -y certbot python3-certbot-nginx
certbot certonly --nginx -d panel.tuo-dominio.com
certbot certonly --nginx -d node1.tuo-dominio.comCrea uno script per applicare i certificati rinnovati a Nginx e a Wings:
nano /etc/letsencrypt/renewal-hooks/deploy/pterodactyl.sh#!/bin/bash
systemctl reload nginx
systemctl try-restart wingschmod 750 /etc/letsencrypt/renewal-hooks/deploy/pterodactyl.sh
certbot renew --dry-runIl riavvio di Wings non arresta i server di gioco in corso. Il test di rinnovo deve concludersi senza errori.
Passo 8: configurare Nginx
Elimina il sito predefinito e crea quello del pannello:
rm /etc/nginx/sites-enabled/default
nano /etc/nginx/sites-available/pterodactyl.confserver {
listen 80;
server_name panel.tuo-dominio.com;
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
server_name panel.tuo-dominio.com;
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;
# allow larger file uploads and longer script runtimes
client_max_body_size 100m;
client_body_timeout 120s;
sendfile off;
ssl_certificate /etc/letsencrypt/live/panel.tuo-dominio.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/panel.tuo-dominio.com/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;
include /etc/nginx/fastcgi_params;
}
location ~ /\.ht {
deny all;
}
}Attiva il sito:
ln -s /etc/nginx/sites-available/pterodactyl.conf /etc/nginx/sites-enabled/pterodactyl.conf
nginx -t
systemctl restart nginxApri https://panel.tuo-dominio.com e accedi con l'account creato al passo 5. Il lucchetto del browser deve essere valido.
Passo 9: installare Docker
Wings avvia ogni server di gioco in un container Docker. Installa Docker Engine con la guida Installare Docker Engine e Docker Compose, poi verifica che si avvii con il sistema:
systemctl enable --now docker
docker info --format '{{.ServerVersion}}'Se docker info mostra WARNING: No swap limit support e il tuo kernel è anteriore alla 6.1, aggiungi swapaccount=1 a GRUB_CMDLINE_LINUX_DEFAULT in /etc/default/grub, lancia update-grub e riavvia. Questa impostazione è facoltativa.
Passo 10: installare Wings
mkdir -p /etc/pterodactyl
curl -L -o /usr/local/bin/wings "https://github.com/pterodactyl/wings/releases/download/v1.13.5/wings_linux_$([[ "$(uname -m)" == "x86_64" ]] && echo "amd64" || echo "arm64")"
chmod u+x /usr/local/bin/wings
wings versionQuesto comando fissa la versione v1.13.5, ultima versione 1.x al momento della stesura. Consulta le versioni di Wings prima dell'installazione.
Passo 11: creare il nodo nel pannello
Nell'amministrazione del pannello:
- Apri Locations, clicca su Create New e crea una posizione, ad esempio
fr - Apri Nodes, poi clicca su Create New
- Compila il modulo:
| Campo | Valore |
|---|---|
| Name | node1 |
| Location | La posizione creata |
| FQDN | node1.tuo-dominio.com |
| Communicate Over SSL | Use SSL Connection |
| Behind Proxy | Not Behind Proxy |
| Daemon Server File Directory | /var/lib/pterodactyl/volumes |
| Total Memory | Memoria riservata ai giochi, in MiB |
| Memory Over-Allocation | 0 |
| Total Disk Space | Disco riservato ai giochi, in MiB |
| Disk Over-Allocation | 0 |
| Daemon Port | 8080 |
| Daemon SFTP Port | 2022 |
Mantieni un margine per il sistema, il pannello, MariaDB e Docker.
- Dopo la creazione, apri la scheda Configuration del nodo e copia il blocco mostrato
- Incollalo sul server, poi proteggi il file, che contiene un token segreto:
nano /etc/pterodactyl/config.yml
chmod 600 /etc/pterodactyl/config.ymlIl pulsante Generate Token fornisce anche un comando che scrive questo file al posto tuo.
Passo 12: avviare Wings
Lancia prima Wings in primo piano per vedere gli eventuali errori:
wings --debugQuando funziona senza errori, fermalo con Ctrl+C, poi crea il suo servizio:
nano /etc/systemd/system/wings.service[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.targetsystemctl daemon-reload
systemctl enable --now wings
systemctl is-active wings
curl https://node1.tuo-dominio.com:8080Il servizio deve essere active. Il comando curl deve restituire un messaggio JSON che indica la mancanza di autorizzazione: dimostra che l'API risponde e che il certificato è valido. In Nodes, il nodo deve mostrare un cuore verde.
Passo 13: creare le allocazioni
Rileva l'indirizzo IP del server:
hostname -I | awk '{print $1}'In Nodes, apri il tuo nodo, poi la scheda Allocation. In Assign New Allocations:
- IP Address: l'indirizzo rilevato, mai
127.0.0.1 - IP Alias: facoltativo, ad esempio
node1.tuo-dominio.com - Ports: una porta o un intervallo, ad esempio
27015-27020
Ogni server di gioco ha bisogno di almeno un'allocazione. Wings pubblica ciascuna in TCP e in UDP.
Passo 14: creare un primo server
Il pannello fornisce egg per Minecraft, Rust, i giochi Source e i server vocali. Per provare con Garry's Mod:
- Crea un token GSLT come indicato in Creare un server Garry's Mod
- Apri Servers, poi Create New
- Indica il nome, il proprietario, il nodo e un'allocazione libera
- Definisci i limiti di memoria, disco e processore
- Seleziona il nest Source Engine e l'egg Garrys Mod
- Compila Steam Account Token con il tuo token, poi conferma
L'installazione scarica l'immagine Docker e i file del gioco. Apri poi il server nell'interfaccia e clicca su Start. È pronto quando la console passa allo stato online.
Verificare l'installazione
| Controllo | Risultato atteso |
|---|---|
systemctl is-active nginx php8.3-fpm mariadb redis-server pteroq wings docker |
active per ogni servizio |
https://panel.tuo-dominio.com |
Pagina di accesso con un certificato valido |
| Nodes | Cuore verde sul nodo |
| Console di un server | Log mostrati in diretta |
SFTP sulla porta 2022 |
Accesso ai file del server |
| Connessione al gioco | Il server risponde sulla sua allocazione |
Salvare
Fai un backup prima di ogni aggiornamento e conserva una copia fuori dal server:
install -d -m 700 /root/pterodactyl-backups
DATE=$(date +%F_%H-%M)
mariadb-dump --single-transaction panel | gzip > /root/pterodactyl-backups/panel_$DATE.sql.gz
tar -czf /root/pterodactyl-backups/file_$DATE.tar.gz -C / var/www/pterodactyl etc/pterodactyl etc/nginx/sites-available/pterodactyl.conf
ls -lh /root/pterodactyl-backupsQuesti archivi contengono dei segreti, tra cui APP_KEY e il token di Wings. I dati dei giochi si trovano a parte, in /var/lib/pterodactyl/volumes, e i backup creati dal pannello in /var/lib/pterodactyl/backups. Arresta un server di gioco prima di copiarne i file per ottenere una copia coerente.
Aggiornare
Il pannello
Fai prima un backup, poi sostituisci v1.15.2 con l'ultima versione 1.x. Non usare questi passi per passare alla 2.0, né php artisan p:upgrade senza indicare una versione: il passaggio alla 2.0 ha la sua procedura.
cd /var/www/pterodactyl
php artisan down
curl -L https://github.com/pterodactyl/panel/releases/download/v1.15.2/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 upWings
I server di gioco in corso non sono interessati. Sostituisci v1.13.5 con la versione desiderata:
cp -p /usr/local/bin/wings /usr/local/bin/wings.bak
systemctl stop wings
curl -L -o /usr/local/bin/wings "https://github.com/pterodactyl/wings/releases/download/v1.13.5/wings_linux_$([[ "$(uname -m)" == "x86_64" ]] && echo "amd64" || echo "arm64")"
chmod u+x /usr/local/bin/wings
systemctl restart wingsTornare indietro
Ripristinare il pannello
Sostituisci DATE con il timestamp dei tuoi archivi. Questi comandi controllano prima i due archivi, poi sostituiscono i file e il database. Le modifiche fatte dopo il backup vanno perse.
tar -tzf /root/pterodactyl-backups/file_DATE.tar.gz > /dev/null
gunzip -t /root/pterodactyl-backups/panel_DATE.sql.gz
cd /var/www/pterodactyl
php artisan down
cd /
rm -rf /var/www/pterodactyl
tar -xzf /root/pterodactyl-backups/file_DATE.tar.gz -C / var/www/pterodactyl
mariadb -e 'DROP DATABASE panel; CREATE DATABASE panel;'
gunzip -c /root/pterodactyl-backups/panel_DATE.sql.gz | mariadb panel
cd /var/www/pterodactyl
php artisan config:clear
php artisan view:clear
php artisan queue:restart
php artisan upRipristina sempre il file .env insieme al database, perché contiene APP_KEY. L'archivio qui sopra lo include.
Ripristinare Wings
systemctl stop wings
cp -p /usr/local/bin/wings.bak /usr/local/bin/wings
systemctl start wingsIn caso di problemi
Leggere i log
tail -n 100 /var/www/pterodactyl/storage/logs/laravel-$(date +%F).log
journalctl -u wings -n 100 --no-pager
journalctl -u pteroq -n 50 --no-pager
tail -n 50 /var/log/nginx/pterodactyl.app-error.logIl nodo resta rosso o la console mostra un errore di connessione
- Verifica Wings con
systemctl status wings, poi fermalo e lanciawings --debug - Confronta
/etc/pterodactyl/config.ymlcon la scheda Configuration del nodo - Verifica che le porte
8080e2022siano aperte - Prova
curl https://node1.tuo-dominio.com:8080 - Verifica che il pannello e Wings usino entrambi l'HTTPS, con certificati validi
- Disattiva i blocchi della pubblicità per questi domini
- Se usi Cloudflare, disattiva il proxy su questi record DNS
nginx: [emerg] cannot load certificate
Il certificato indicato non esiste oppure il dominio non corrisponde. Elenca quelli disponibili con certbot certificates.
the "listen ... http2" directive is deprecated
È solo un avviso delle versioni recenti di Nginx, senza effetto sul funzionamento.
502 Bad Gateway
PHP-FPM non risponde. Verifica systemctl status php8.3-fpm e il percorso /run/php/php8.3-fpm.sock.
failed to open stream: Permission denied
I file del pannello non appartengono all'utente giusto:
chown -R www-data:www-data /var/www/pterodactyl/*SQLSTATE[HY000] [1045] Access denied for user 'pterodactyl'
La password o l'host non corrispondono. Usa 127.0.0.1 come host e rilancia php artisan p:environment:database.
The MAC is invalid
La chiave APP_KEY del file .env non corrisponde a quella usata per cifrare i dati. Ripristina la chiave originale. Senza di essa, questi dati non sono recuperabili.
bind: address already in use all'avvio di Wings
Un altro servizio occupa la porta. Identificalo con ss -ltnp | grep -E ':8080|:2022'.
Un server di gioco non ha accesso a Internet
I container usano per impostazione predefinita i DNS 1.1.1.1 e 1.0.0.1. Se questi indirizzi sono bloccati sulla tua rete, sostituiscili nella sezione docker di /etc/pterodactyl/config.yml, poi riavvia Wings.
Le attività pianificate non vengono eseguite
Verifica la riga del crontab con crontab -l, poi il servizio con journalctl -xeu pteroq e systemctl restart pteroq.