Pterodactyl Panel: vollständige Installation auf dem eigenen VPS

Wir installieren Pterodactyl Panel, eine Weboberfläche zur Verwaltung von Gameservern, auf Ihrem VPS. Am Ende läuft es unter https://panel.example.cz mit einem Let's-Encrypt-Zertifikat, einer Job-Warteschlange, cron und Ihrem Admin-Konto.

So funktioniert es#

Pterodactyl hat zwei Teile. Das Panel ist eine Webanwendung (PHP, Framework Laravel), in der Sie Benutzer und Server anlegen und in der Spieler die Konsole steuern. Wings ist der Dienst, der die Gameserver tatsächlich in Docker-Containern betreibt. Panel und Wings können auf demselben VPS laufen. Diese Anleitung installiert das Panel; Wings fügen Sie in der Folgeanleitung Pterodactyl Wings hinzu.

Das Panel braucht mehrere weitere Programme:

Das Panel selbst ist leichtgewichtig. Sollen Gameserver auf demselben VPS laufen, planen Sie Ihren RAM vor allem für sie und rechnen Sie eine Reserve für System, Datenbank und Panel ein (grob 1–⁠2 GB).

Installationsplan#

Domain und DNS#

Das Panel braucht eine eigene Domain oder Subdomain. HTTPS-Zertifikate werden für Domains ausgestellt, nicht für IP-Adressen.

1. Öffnen Sie im Kundenbereich Meine Dienste, klicken Sie auf Ihren VPS und kopieren Sie in der Registerkarte Netzwerk die IPv4-⁠Adresse (und optional die IPv6-⁠Adresse).

2. Erstellen Sie bei Ihrem DNS-Anbieter einen A-Eintrag für panel.example.cz mit der IPv4-⁠Adresse des VPS (zum Beispiel 203.0.113.10).

3. Erstellen Sie optional auch einen AAAA-Eintrag mit der IPv6-⁠Adresse des VPS (zum Beispiel 2001:db8::10). Die Nginx-Konfiguration unten lauscht auch auf IPv6.

4. Prüfen Sie auf dem VPS, dass die Domain bereits auf die richtige Stelle zeigt:

   getent hosts panel.example.cz

   • getent hosts – fragt das System-DNS nach der Adresse der Domain und gibt sie aus.

   Sie sehen eine Zeile mit der IP-Adresse Ihres VPS. Wird nichts ausgegeben, warten Sie einige Minuten (je nach TTL des Eintrags) und versuchen Sie es erneut.

Firewall#

Der Browser verbindet sich mit dem Panel auf Port 443 (HTTPS). Port 80 (HTTP) wird für die Domain-Prüfung beim Ausstellen des Zertifikats und für die Weiterleitung auf HTTPS gebraucht.

• Firewall im Kundenbereich: Steht eingehender Verkehr auf Alles blockieren außer Erlaubtem, fügen Sie die Regeln Eingehend · Erlauben · TCP · Port 80,443 hinzu. Die SSH-Regel (Port 22) muss bleiben. Anleitung: Firewall im Kundenbereich.

• UFW auf dem VPS: Verwenden Sie es, erlauben Sie die Ports auch dort:

  ufw allow 80/tcp
  ufw allow 443/tcp

  • ufw allow 80/tcp – erlaubt eingehende TCP-Verbindungen zu Port 80.
  • ufw allow 443/tcp – dasselbe für Port 443.

Die Ports für Wings (8080 und 2022) und für Gameserver öffnen Sie in der Anleitung Pterodactyl Wings.

Abhängigkeiten installieren#

Aktualisieren Sie zuerst das System, damit Sie auf einer aktuellen Basis installieren:

apt update && apt -y upgrade

• apt update – lädt die aktuelle Paketliste herunter.
• apt -y upgrade – installiert verfügbare Updates; -y beantwortet die Bestätigung mit „ja“.

Installieren Sie dann die Abhängigkeiten. Die Schritte hängen vom System ab: Ubuntu 24.04 hat PHP 8.3 direkt im Repository, während das Standard-Repository von Debian 13 PHP 8.4 hat, das das Panel nicht unterstützt (das aktuelle Panel erfordert PHP 8.2 oder 8.3). Unter Debian fügen Sie daher das Repository packages.sury.org hinzu, das auch die offizielle Pterodactyl-Dokumentation empfiehlt.

Was der Installationsbefehl enthält:

Prüfen Sie, dass Sie die richtige PHP-Version haben:

php -v

PHP 8.3.x (cli) …

Die erste Zeile muss PHP 8.3 lauten. Sehen Sie PHP 8.4, siehe Fehlerbehebung.

Prüfen Sie, dass die Dienste laufen:

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

• systemctl is-active – gibt den Zustand jedes aufgeführten Dienstes aus.

Sie sehen viermal active. Ist einer inactive, starten Sie ihn und aktivieren Sie ihn beim Booten mit systemctl enable --now <DIENSTNAME>, zum Beispiel systemctl enable --now redis-server.

Composer#

Composer lädt die PHP-Bibliotheken des Panels herunter. Installieren Sie ihn mit dem offiziellen Installer:

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

• curl -sS https://getcomposer.org/installer – lädt das Composer-Installationsskript herunter.
• | php -- – übergibt das Skript zur Ausführung an PHP; -- trennt die Parameter von PHP von denen des Installers.
• --install-dir=/usr/local/bin – wohin Composer installiert wird (ein Verzeichnis, in dem das System nach Programmen sucht).
• --filename=composer – der Programmname, sodass Sie ihn dann mit dem Befehl composer ausführen.

Prüfung: composer --version gibt Composer version 2.… aus. Als root sehen Sie auch die Warnung Do not run Composer as root/super user! und möglicherweise die Frage Continue as root/super user [yes]?. Bestätigen Sie sie mit Eingabe. Bei der Panel-Installation unten unterdrückt die Variable COMPOSER_ALLOW_SUPERUSER=1 die Warnung.

Panel herunterladen#

1. Legen Sie ein Verzeichnis für das Panel an und wechseln Sie hinein:

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

   • mkdir -p – legt das Verzeichnis an (einschließlich übergeordneter); existiert es bereits, gibt es keinen Fehler aus.
   • cd – wechselt in das Verzeichnis. Führen Sie alle weiteren php artisan-Befehle darin aus.

2. Laden Sie das neueste Panel-Release herunter und entpacken Sie es:

   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 … – lädt das Archiv des neuesten Release von GitHub herunter und speichert es als panel.tar.gz.
   • tar -xzvf – entpackt das Archiv (x entpacken, z gzip-Format, v Dateien auflisten, f aus einer Datei).

3. Setzen Sie Berechtigungen auf die Verzeichnisse, in die das Panel schreibt:

   chmod -R 755 storage/* bootstrap/cache/

   • chmod -R 755 – der Besitzer darf die Verzeichnisse lesen, schreiben und betreten; alle anderen nur lesen und betreten. -R gilt für den gesamten Inhalt.
   • storage/ – Logs, Cache und hochgeladene Dateien; bootstrap/cache/ – die kompilierte Konfiguration.

Eine Datenbank für das Panel#

Das Panel braucht eine eigene Datenbank und einen eigenen Benutzer. Die Pterodactyl-Autoren verbieten ausdrücklich, den Datenbankbenutzer root für das Panel zu verwenden: Kompromittierte jemand das Panel, erhielte er Zugriff auf alle Datenbanken auf dem VPS.

1. Erzeugen Sie ein starkes Passwort für den Datenbankbenutzer, zum Beispiel mit dem Passwortgenerator. Verwenden Sie nur Buchstaben und Ziffern (mindestens 24 Zeichen), damit Sie sich in SQL und in .env nicht mit Sonderzeichen herumschlagen müssen. Speichern Sie das Passwort; Sie brauchen es gleich wieder.

2. Melden Sie sich als Administrator an MariaDB an:

   mariadb

   • mariadb – der Datenbankclient. Sowohl unter Ubuntu als auch unter Debian meldet sich der Systembenutzer root ohne Passwort an MariaDB an (über Unix-Socket-Authentifizierung). Sie sehen die Eingabeaufforderung MariaDB [(none)]>.

3. Legen Sie Benutzer und Datenbank an. Ersetzen Sie <PANEL_DB_PASSWORT> durch das Passwort aus Schritt 1 (behalten Sie die einfachen Anführungszeichen darum):

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

Umgebungskonfiguration (.env)#

Die Einstellungen des Panels liegen in /var/www/pterodactyl/.env. Sie erstellen sie aus einer Vorlage, installieren die Bibliotheken und erzeugen einen Verschlüsselungsschlüssel.

1. Kopieren Sie die Vorlage:

   cp .env.example .env

2. Installieren Sie die PHP-Bibliotheken des Panels:

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

   • COMPOSER_ALLOW_SUPERUSER=1 – lässt Composer als root laufen, ohne nachzufragen.
   • composer install – lädt die Bibliotheken in genau den Versionen herunter, die das Panel vorgibt (die Datei composer.lock).
   • --no-dev – überspringt Entwicklerwerkzeuge, die Sie auf einem Produktivserver nicht brauchen.
   • --optimize-autoloader – bereitet schnelleres Laden der PHP-Klassen vor.

   Die Installation dauert einige Minuten und endet ohne Fehlermeldungen (eine gelbe Warnung zu veralteten Paketen ist in Ordnung).

3. Erzeugen Sie den Verschlüsselungsschlüssel:

   php artisan key:generate --force

   • php artisan – das Befehlszeilen-Verwaltungswerkzeug des Panels.
   • key:generate – erzeugt einen zufälligen APP_KEY und schreibt ihn in .env.
   • --force – führt den Befehl ohne Bestätigung aus (das Panel läuft im Produktionsmodus, wo es sonst nachfragen würde).

4. Zeigen Sie den Schlüssel an und speichern Sie die ganze Zeile irgendwo außerhalb des Servers (in einem Passwort-Manager oder einer verschlüsselten Datei auf Ihrem Computer):

   grep APP_KEY /var/www/pterodactyl/.env

   APP_KEY=base64:…

Der Assistent p:environment:setup#

Ein Assistent übernimmt die Grundeinrichtung. Führen Sie ihn aus:

php artisan p:environment:setup

Er stellt nacheinander die folgenden Fragen (der Standardwert steht in eckigen Klammern; bestätigen Sie ihn mit Eingabe):

Wenn Sie eine mit https:// beginnende Adresse eingeben, schaltet der Assistent von selbst sichere Cookies ein (SESSION_SECURE_COOKIE=true).

Der Assistent p:environment:database#

php artisan p:environment:database

Der Assistent versucht sofort, sich zu verbinden. Sind die Angaben falsch, gibt er Unable to connect to the MySQL server… aus, speichert nichts und fragt, ob Sie es erneut versuchen möchten.

Der Assistent p:environment:mail#

Das Panel sendet E-Mails (Einladungen für neue Benutzer, Passwort-Zurücksetzungen). Ohne Mail-Einstellungen funktioniert das Panel, aber diese E-Mails gehen nicht hinaus. Sie können das auch später mit demselben Befehl einrichten:

php artisan p:environment:mail

Wichtige Schlüssel in .env#

Die Assistenten schreiben diese Werte in .env. Sie können die Datei auch von Hand bearbeiten (nano /var/www/pterodactyl/.env); führen Sie nach einer manuellen Änderung php artisan config:clear aus.

Datenbanktabellen und der erste Administrator#

1. Legen Sie die Tabellen an und laden Sie die Standarddaten:

   php artisan migrate --seed --force

   • migrate – legt alle Tabellen in der Datenbank panel an.
   • --seed – füllt sie mit Standarddaten, einschließlich Spielvorlagen (Minecraft, Rust und andere).
   • --force – führt den Befehl im Produktionsmodus ohne Bestätigung aus.

   Der Befehl kann mehrere Minuten dauern. Unterbrechen Sie ihn nicht, sonst bleibt die Datenbank halb angelegt.

2. Legen Sie das Admin-Konto an:

   php artisan p:user:make

Am Ende sehen Sie eine Tabelle mit den Kontodaten und der Zeile Admin | Yes.

Dateiberechtigungen#

Die Panel-Dateien gehören jetzt root. Der Webserver läuft als Benutzer www-data und muss in die Verzeichnisse storage und bootstrap/cache schreiben:

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

• chown -R – ändert den Besitzer der Dateien und des gesamten Inhalts der Verzeichnisse.
• www-data:www-data – Benutzer und Gruppe, unter denen Nginx und PHP-FPM unter Ubuntu und Debian laufen.

Cron und die Job-Warteschlange#

Cron#

Cron führt jede Minute den Scheduler des Panels aus (Aufräumen alter Anmeldungen, geplante Serveraufgaben).

1. Öffnen Sie die Crontab von root:

   crontab -e

   Beim ersten Lauf fragt er, welcher Editor verwendet werden soll. Wählen Sie nano (seine Nummer eingeben und Eingabe drücken). Meldet das System crontab: command not found, fehlt cron. Installieren Sie es mit apt -y install cron und wiederholen Sie diesen Schritt.

2. Fügen Sie am Ende der Datei diese Zeile hinzu:

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

3. Speichern Sie (Strg+O, Eingabe) und schließen Sie den Editor (Strg+X). Sie sehen crontab: installing new crontab.

Der Warteschlangendienst pteroq#

Die Warteschlange erledigt Hintergrundarbeit: das Senden von E-Mails und die Aufgaben, die Benutzer für ihre Server planen (der Bereich Schedules, zum Beispiel ein nächtlicher Neustart oder ein Backup). Ohne sie gehen keine E-Mails hinaus, und geplante Aufgaben laufen nicht.

1. Erstellen Sie die Dienstdatei:

   nano /etc/systemd/system/pteroq.service

2. Fügen Sie den Inhalt ein:

   # 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. Speichern und schließen Sie den Editor.

4. Aktivieren Sie Redis und die Warteschlange beim Booten und starten Sie sie sofort:

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

   • enable – schaltet den automatischen Start nach einem Neustart des VPS ein.
   • --now – startet den Dienst auch sofort.

5. Prüfen Sie den Status:

   systemctl status pteroq

   Sie sehen Active: active (running). Schließen Sie die Ausgabe mit q.

Das Let's-Encrypt-Zertifikat#

Die Nginx-Konfiguration unten verweist auf die Zertifikatsdateien. Nginx startet damit erst, wenn das Zertifikat existiert, also holen Sie zuerst das Zertifikat.

1. Installieren Sie Certbot und sein Nginx-Plugin:

   apt -y install certbot python3-certbot-nginx

   • certbot – das Programm, das Let's-Encrypt-Zertifikate holt und erneuert.
   • python3-certbot-nginx – ein Plugin, das die Domain über das laufende Nginx prüft, ohne es zu stoppen.

2. Holen Sie das Zertifikat. Ersetzen Sie panel.example.cz durch Ihre Domain:

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

   • certonly – holt nur das Zertifikat und speichert es, ohne die Nginx-Konfiguration zu bearbeiten (die schreiben Sie selbst).
   • --nginx – die Domain-Prüfung läuft über Nginx auf Port 80.
   • -d panel.example.cz – die Domain, für die Sie das Zertifikat möchten.

3. Beantworten Sie beim ersten Lauf die Fragen:

   • E-Mail (Enter email address…) – geben Sie Ihre E-Mail-Adresse ein. Let's Encrypt sendet wichtige Kontohinweise dorthin. Seit 2025 sendet es keine Erinnerungen an ablaufende Zertifikate mehr, die Erneuerung läuft also automatisch (siehe Schritt 5).
   • Nutzungsbedingungen (Please read the Terms of Service… Do you agree?) – antworten Sie mit Y; ohne Zustimmung erhalten Sie kein Zertifikat.
   • Weitergabe Ihrer E-Mail an die EFF (Would you be willing… to share your email address with the Electronic Frontier Foundation…) – Ihre Entscheidung; hat keine Auswirkung auf das Zertifikat.

   Am Ende sehen Sie Successfully received certificate. und die Dateipfade:

   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. Lassen Sie Nginx nach jeder Erneuerung das neue Zertifikat laden. Erstellen Sie einen Deploy-Hook (ein Skript, das Certbot nach einer erfolgreichen Erneuerung ausführt):

   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 – schreibt die Zeilen zwischen <<'EOF' und EOF in die Datei.
   • systemctl reload nginx – lädt die neue Konfiguration und die Zertifikate, ohne Verbindungen abzubrechen.
   • chmod 755 – macht das Skript ausführbar; Certbot führt im Verzeichnis renewal-hooks/deploy nur ausführbare Dateien aus.

5. Prüfen Sie, dass die automatische Erneuerung funktioniert. Sowohl unter Ubuntu als auch unter Debian enthält das Certbot-Paket einen Timer, der zweimal täglich eine Erneuerung versucht:

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

   • systemctl list-timers – listet geplante Timer auf; certbot.timer sollte darunter sein.
   • certbot renew --dry-run – probiert eine Erneuerung gegen den Staging-Server von Let's Encrypt, ohne das echte Zertifikat anzufassen.

   Der Test endet mit Congratulations, all simulated renewals succeeded.

Das Zertifikat ist 90 Tage gültig (Stand Oktober 2026; Let's Encrypt verkürzt die Gültigkeit schrittweise). Certbot erneuert es von selbst, wenn noch etwa ein Drittel der Gültigkeit übrig ist.

Nginx#

1. Deaktivieren Sie die Standard-Website von Nginx:

   rm /etc/nginx/sites-enabled/default

   • Das löscht nur den Link in sites-enabled; die Datei selbst bleibt in sites-available. Andernfalls würde die Standard-Website Port 80 statt des Panels bedienen.

2. Erstellen Sie die Panel-Konfiguration:

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

3. Fügen Sie den Inhalt ein und ersetzen Sie alle vier Vorkommen von panel.example.cz durch Ihre Domain:

   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;
   
       # groessere Uploads und laengere Skriptlaufzeiten
       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;
       }
   }

Die Konfiguration basiert auf der offiziellen Pterodactyl-Dokumentation. Wir haben das Lauschen auf IPv6 (listen [::]:…) ergänzt und die Nginx-Version verborgen. Was die einzelnen Teile tun:

4. Aktivieren Sie die Konfiguration, testen Sie sie und starten Sie Nginx neu:

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

   • ln -s – erstellt einen Link auf die Datei in sites-enabled; Nginx lädt nur Konfigurationen in sites-enabled.
   • nginx -t – prüft die Syntax. Es muss mit der Zeile test is successful enden. Falls nicht, starten Sie Nginx nicht neu; korrigieren Sie die Zeile, auf die der Fehler zeigt.
   • systemctl restart nginx – lädt die neue Konfiguration.

Erste Anmeldung#

1. Öffnen Sie https://panel.example.cz in Ihrem Browser. Sie sehen die Anmeldeseite des Panels mit einem Schloss (gültiges Zertifikat) in der Adressleiste.
2. Melden Sie sich mit Benutzername oder E-Mail-Adresse und Passwort des Admins an.
3. Klicken Sie oben rechts auf das Zahnradsymbol (Admin-Bereich). Legen Sie im Bereich Settings den Panel-Namen fest (Company Name).
4. Schalten Sie die Zwei-Faktor-Authentifizierung ein: Klicken Sie oben rechts auf Ihr Konto, öffnen Sie Account und scannen Sie im Zwei-Faktor-Bereich den QR-Code mit einer App (zum Beispiel Google Authenticator oder Aegis). Das Admin-Konto steuert alle Server, schützen Sie es also mit mehr als einem Passwort.

Überprüfung#

Prüfen Sie die gesamte Installation:

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

• Der erste Befehl muss fünfmal active ausgeben.
• curl -sI lädt nur die Antwort-Header herunter; die erste Zeile lautet HTTP/2 302 (Weiterleitung zur Anmeldung) oder HTTP/2 200.

Das Panel ist bereit. Der nächste Schritt ist das Hinzufügen einer Node mit dem Dienst Wings, auf der die Gameserver laufen: Pterodactyl Wings.

Panel hinter Cloudflare#

Sie können das Panel hinter den Cloudflare-Proxy (orangefarbene Wolke) setzen. Das gilt nur für das Panel, nicht für Wings (siehe Pterodactyl Wings).

1. Stellen Sie in Cloudflare den SSL/TLS-Modus auf Full (strict). Cloudflare verbindet sich dann über HTTPS mit dem VPS und prüft Ihr Let's-Encrypt-Zertifikat.

2. Schalten Sie den Eintrag panel.example.cz auf Proxied.

3. Fügen Sie die IP-Bereiche von Cloudflare in einer einzigen Zeile zu .env hinzu. Hinter dem Proxy erreichen alle Anfragen das Panel von den Adressen von Cloudflare. Das Panel nimmt die echte IP-Adresse des Besuchers dann aus dem Header X-Forwarded-For, aber nur von Adressen, denen es vertraut. Ohne diese Zeile würde das Panel für alle Benutzer nur die Adressen von Cloudflare sehen, sowohl in Aktivitätsprotokollen als auch im Brute-Force-Schutz, der Versuche pro IP-Adresse zählt. Die Liste unten ist aktuell mit Stand 1. Oktober 2026; die neueste finden Sie unter cloudflare.com/ips (öffnet sich in einem neuen Fenster):

   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 – eine Liste von Adressen und Bereichen (durch Kommas getrennt, ohne Leerzeichen), von denen das Panel X-Forwarded-*-Header mit der echten IP-Adresse und dem Protokoll des Besuchers akzeptiert. Von jeder anderen Adresse ignoriert es diese Header, sodass niemand sie fälschen kann.

4. Laden Sie die neue Konfiguration: cd /var/www/pterodactyl && php artisan config:clear.

Panel aktualisieren#

Neue Panel-Versionen beheben Fehler und Sicherheitslücken, aktualisieren Sie also regelmäßig. Lesen Sie vor dem Update die Versionshinweise auf GitHub und prüfen Sie, welche PHP-Version das neue Release erfordert (php -v).

• mariadb-dump --single-transaction panel – exportiert die Datenbank panel in eine SQL-Datei, ohne Tabellen zu sperren.
• $(date +%F) – fügt das heutige Datum (zum Beispiel 2026-10-01) in den Dateinamen ein.

Führen Sie dann das Update aus:

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

Aktualisieren Sie nach dem Panel auch Wings; die Schritte stehen in der Anleitung Pterodactyl Wings. Die Versionen von Panel und Wings sollten zusammenpassen, verwenden Sie also das neueste Release von beiden.

Panel-Backups#

Zur Wiederherstellung des Panels brauchen Sie zwei Dinge: die Datenbank panel und die Datei .env (vor allem APP_KEY). Gameserver-Daten liegen auf der Wings-Node, nicht im Panel, sichern Sie sie also separat. Wie Sie Backups automatisieren und vom Server wegbekommen, behandelt Backups auf einem VPS.

Fehlerbehebung#

502 Bad Gateway#

Nginx konnte PHP-FPM nicht erreichen. Prüfen Sie, dass PHP-FPM läuft und der Socket-Pfad passt:

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

Die Ausgabe von ls muss php8.3-fpm.sock enthalten, und derselbe Pfad muss in der Direktive fastcgi_pass stehen. Läuft der Dienst nicht, starten Sie ihn: systemctl enable --now php8.3-fpm.

Fehler 500 oder eine leere Seite#

Sehen Sie in das Log des Panels:

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

• tail -n 100 – gibt die letzten 100 Zeilen des heutigen Logs aus.

Suchen Sie eine Zeile mit Datum und dem Wort ERROR. Die häufigsten Ursachen:

• Permission denied – falscher Dateibesitzer. Führen Sie chown -R www-data:www-data /var/www/pterodactyl/* erneut aus.
• No application encryption key has been specified. – APP_KEY fehlt. Führen Sie bei der Erstinstallation php artisan key:generate --force aus. Hat das Panel bereits Daten, stellen Sie den ursprünglichen Schlüssel aus Ihrem Backup wieder her.
• SQLSTATE[HY000] [1045] Access denied – Datenbankpasswort oder -benutzer in .env ist falsch.

The MAC is invalid#

Die Datenbank wurde mit einem anderen APP_KEY verschlüsselt als dem, der jetzt in .env steht. Das passiert typischerweise nach der Wiederherstellung der Datenbank auf einer neuen Installation. Die einzige Lösung ist, den ursprünglichen APP_KEY wieder in .env einzutragen. Ohne ihn lassen sich die verschlüsselten Daten nicht wiederherstellen.

E-Mails werden nicht gesendet#

Meist läuft die Warteschlange nicht. Prüfen Sie den Dienst und sein Log:

systemctl status pteroq
journalctl -u pteroq -n 50

• journalctl -u pteroq -n 50 – die letzten 50 Zeilen des Dienst-Logs.

Prüfen Sie auch, dass Redis läuft (systemctl status redis-server). Führen Sie nach der Behebung systemctl restart pteroq aus. Läuft die Warteschlange, prüfen Sie die Mail-Einstellungen (php artisan p:environment:mail) und Fehler im Panel-Log (siehe Fehler 500).

Ein Server hängt bei der Installation#

Die Serverinstallation erledigt Wings, nicht das Panel. Siehe den Abschnitt „Fehlerbehebung“ der Anleitung Pterodactyl Wings (meist kaputtes DNS in Containern oder eine unerreichbare Node).

Geplante Serveraufgaben laufen nicht#

Prüfen Sie, dass die Warteschlange läuft (systemctl status pteroq), die Cron-Zeile (crontab -l) und die Zeitzonen: die des Systems (timedatectl) und die des Panels (APP_TIMEZONE in .env). Auch das Leeren des Scheduler-Caches kann helfen:

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

Nginx startet nicht: cannot load certificate#

Das Zertifikat für die Domain in der Konfiguration existiert nicht: Sie haben es nicht geholt, oder die Domain in server_name und im Pfad /etc/letsencrypt/live/… unterscheidet sich von der, für die es ausgestellt wurde. certbot certificates listet Ihre Zertifikate auf.

Certbot: Timeout during connect (likely firewall problem)#

Let's Encrypt konnte Port 80 Ihres VPS nicht erreichen. Prüfen Sie, dass der A-Eintrag der Domain auf die IPv4-⁠Adresse des VPS zeigt, dass Port 80 sowohl in der Firewall des Kundenbereichs als auch in UFW erlaubt ist und dass Nginx läuft. Hat die Domain einen AAAA-Eintrag, muss er auf die IPv6-⁠Adresse dieses VPS zeigen, weil Let's Encrypt auch IPv6 versucht.

Composer oder artisan meldet die falsche PHP-Version#

Die Meldung lautet etwa requires php ^8.2 || ^8.3 but your php version (8.4…) does not satisfy that requirement. Der Befehl php führt eine andere Version als 8.3 aus, typischerweise unter Debian 13, nachdem das Standardpaket php installiert wurde. Setzen Sie das Standard-PHP auf 8.3:

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

• update-alternatives --set php … – legt fest, welche Version der Befehl php ausführt.

Existiert /usr/bin/php8.3 nicht, ist PHP 8.3 nicht installiert. Gehen Sie zurück zu Abhängigkeiten installieren.

Die Seite dreht sich hinter Cloudflare in Weiterleitungen (ERR_TOO_MANY_REDIRECTS)#

Cloudflare steht im Modus Flexible. Schalten Sie es auf Full (strict) und prüfen Sie auch TRUSTED_PROXIES, wie unter Panel hinter Cloudflare beschrieben.

Die Serverkonsole funktioniert hinter Cloudflare nicht#

Die Domain der Node läuft über den Cloudflare-Proxy (orangefarbene Wolke). Das passiert typischerweise, wenn die Node dieselbe Domain wie das Panel verwendet. Schalten Sie die Domain der Node auf DNS only oder geben Sie der Node eine eigene Subdomain.

Weiterführende Links#

• Pterodactyl: Getting Started (öffnet sich in einem neuen Fenster)
• Pterodactyl: Webserver Configuration (öffnet sich in einem neuen Fenster)
• Pterodactyl: Updating the Panel (öffnet sich in einem neuen Fenster)
• Pterodactyl: Additional Configuration (öffnet sich in einem neuen Fenster)
• Pterodactyl: Troubleshooting (öffnet sich in einem neuen Fenster)
• Certbot: User Guide (öffnet sich in einem neuen Fenster)