Troubleshooting

Wo nachschauen

Panel	docker compose logs panel
Agent	docker logs panel-agent auf dem Node (oder docker compose -f compose.agent.yml logs)
Ein Server	seine Console: Notizen des Panels beginnen mit [panel], Installationen mit [job]
Portweiterleitung	die Karte des Providers auf der Seite des Nodes: wann zuletzt angewendet, und der letzte Fehler
Webhooks	die Zustellungen des Webhooks, mit der Antwort

Ein Node bleibt offline

Schau ins Log des Agents:

• Enrollment failed: Das Token ist verbraucht oder älter als 24 Stunden. Erstelle auf der Seite des Nodes ein neues (New enrollment token), setze AGENT_ENROLLMENT_TOKEN und erstelle den Agent neu.
• Connection to the panel lost: … immer wieder:
  • Erreicht der Node das Panel? curl -I <AGENT_PANEL_URL> auf dem Node.
  • Hinter einem Reverse Proxy: Er muss WebSockets durchlassen.
  • Das Panel lehnt eine andere Protokollversion ab (protocol_mismatch): Aktualisiere den Agent (Updates).
• The panel no longer accepts this node's identity: Jemand hat ein neues Registrierungs-Token für den Node erstellt. Setze es als AGENT_ENROLLMENT_TOKEN und erstelle den Agent neu.

Eine Installation scheitert

Die Konsole zeigt die Ausgabe der Installation (Zeilen mit [job]). Häufige Ursachen:

• Das Image lässt sich nicht herunterladen: Eine private Registry braucht ein Login (Admin → Settings → Registries), und der Node muss die Registry erreichen.
• Steam: Das Konto muss das Spiel besitzen; eine Steam-Guard-Abfrage, die 5 Minuten unbeantwortet bleibt, lässt den Job scheitern. Siehe Steam-Konten.

Behebe die Ursache, dann Reinstall.

Ein Server startet nicht oder hält von selbst an

Die letzten Zeilen der Konsole sagen, warum:

Konsole	Bedeutung
[panel] The server uses … MB of its … MB disk limit. Delete files or raise the limit.	über dem Speicherlimit: Er startet nicht (oder wird im Betrieb gestoppt). Lösche Dateien, oder erhöhe das Limit unter Settings → Name and limits.
[panel] Server stopped (exit code 137).	abgeschossen: meist zu wenig Arbeitsspeicher. Erhöhe das Speicherlimit, oder senke die Einstellung des Spiels (Javas -Xmx folgt dem Limit ab dem nächsten Start).
[panel] Server stopped (exit code …).	Das Spiel hat sich selbst beendet: Seine Zeilen darüber sagen, warum.

Spieler können sich nicht verbinden

1. Die Adresse: Die Serverseite zeigt sie, aus der öffentlichen Adresse des Nodes und den Ports des Servers. Ist es die Adresse, die Spieler verwenden?
2. Der Server: Läuft er (running), und funktioniert die Spielerzahl? Dann antwortet das Spiel auf dem Node.
3. Portweiterleitung: Zeigt die Karte des Providers einen Fehler? Wird der Port mit dem richtigen Protokoll weitergeleitet (UDP für die meisten Steam-Spiele)?
4. Firewalls: Die Firewall des Nodes und die der Cloud müssen die Ports hereinlassen. Docker umgeht bei veröffentlichten Ports Host-Firewalls wie ufw; wirksam ist deshalb eine Cloud-Firewall.
5. Aus dem LAN: Manche Router leiten eine Verbindung an ihre eigene öffentliche Adresse nicht zurück nach innen. Versuche es mit der LAN-Adresse oder von aussen.

SFTP verweigert die Anmeldung

• Der Benutzername ist <email>.<server id>, genau wie im Tab Files.
• Konten mit Zwei-Faktor können ihr Passwort für SFTP nicht verwenden: Füge unter Account → SSH keys einen SSH-Schlüssel hinzu.
• Berechtigungen: Mitglieder brauchen files.sftp auf dem Server.
• Gesperrt: Nach 10 fehlgeschlagenen Anmeldungen wird die Adresse für 10 Minuten gesperrt.
• Aus: SFTP lässt sich in Admin → Settings für die ganze Installation ausschalten.

E-Mails kommen nicht an

Admin → Settings → Email → Send test mail nennt die Server-Adressen, die versucht wurden, und warum es scheiterte. Prüfe Host und Port, die Verschlüsselung (STARTTLS 587, TLS 465) und die Absenderadresse, die der Mailserver akzeptiert.

Webhooks und Benachrichtigungen

• Ein Webhook wird nicht zugestellt: Seine Zustellungen zeigen die Antwort, z. B. HTTP 400. Adressen in privaten Netzwerken werden abgelehnt, ausser Webhooks to the local network ist in Admin → Settings eingeschaltet (im Homelab standardmässig an).
• Push-Benachrichtigungen: Sie brauchen das Panel unter HTTPS. Auf iPhones muss das Panel zum Home-Bildschirm hinzugefügt sein (iOS 16.4 oder neuer). Send a test auf der Kontoseite prüft ein Gerät.