104 lines
7.3 KiB
Markdown
104 lines
7.3 KiB
Markdown
# DeskHub-Minecraft
|
|
|
|
Legt in **DeskHub** automatisch ein Ticket an, wenn dein Minecraft-Server offline geht. **Eine Jar** für **Spigot, Paper und BungeeCord**. Abteilung und Priorität stellst du in der `config.yml` ein.
|
|
|
|
## Wie der Ausfall erkannt wird
|
|
|
|
Ein Server, der abstürzt, kann nicht mehr selbst "Hilfe" rufen. Deshalb gibt es zwei Wege, die du am besten kombinierst:
|
|
|
|
| Wo das Plugin liegt | Was es tut | Wann das Ticket kommt |
|
|
|---|---|---|
|
|
| **BungeeCord-Proxy** (empfohlen) | Prüft deine Server von außen (Server-Ping, alle 30 s) | Nach 3 Fehlschlägen in Folge **und** erst, wenn der Server mindestens die Schonfrist (5 Minuten) nicht erreichbar war |
|
|
| **Spigot / Paper** (jeder Server) | Schreibt regelmäßig ein Lebenszeichen und markiert es beim normalen Beenden | Beim **nächsten Start**, wenn der Server zuvor abgestürzt, hart beendet oder vom Strom getrennt wurde |
|
|
|
|
**Geplante Neustarts:** Der Proxy kann von außen nicht erkennen, ob ein Server neu startet oder abgestürzt ist. Deshalb gibt es die **Neustart-Schonfrist** (`monitor.restart-grace-minutes`, Standard 5 Minuten): Ist der Server vorher wieder erreichbar, entsteht kein Ticket. Stelle sie etwas höher ein, als dein Neustart dauert. Die Einstellung `backend.ticket-on-shutdown` gilt nur für das Plugin auf dem Spigot/Paper-Server, nicht für den Proxy.
|
|
|
|
**Geplante Neustarts melden (ab 1.2.0):** Der Server kann dem Proxy beim Herunterfahren selbst sagen, dass der Neustart geplant ist. Der Proxy wartet dann die längere Frist `monitor.planned-restart-grace-minutes` (Standard 15 Minuten), bevor er ein Ticket anlegt; bleibt der Server länger weg, kommt das Ticket trotzdem. Einrichten:
|
|
1. Auf dem **Proxy** in der `config.yml`: `monitor.notify-port` (zum Beispiel `25590`) und `monitor.notify-secret` (mindestens 16 zufällige Zeichen) eintragen, `/deskhubmc reload`. Der Anschluss sollte nur aus dem Netz deiner Server erreichbar sein (Firewall); ohne richtige Signatur nimmt der Proxy nichts an.
|
|
2. Auf jedem **Server** (Spigot/Paper): `backend.proxy-notify` (`Adresse-des-Proxys:25590`), `backend.proxy-secret` (dasselbe Geheimnis) und `backend.proxy-server-name` (der Name dieses Servers in der Proxy-Konfiguration, zum Beispiel `lobby`) eintragen, `/deskhubmc reload`.
|
|
Die Meldung ist mit HMAC-SHA256 signiert und muss frisch sein (höchstens eine Minute alt), alte Meldungen lassen sich nicht nachspielen. Stürzt der Server ab, meldet er nichts: Dann gilt die normale Schonfrist.
|
|
|
|
Gegen Ticket-Fluten: ein einzelner Aussetzer macht kein Ticket, pro Ausfall höchstens eines, und pro Server frühestens nach der eingestellten Wartezeit (30 Minuten) wieder eines. Server, die seit dem Start des Proxys nie online waren (z. B. absichtlich abgeschaltet), werden ignoriert.
|
|
|
|
**Automatisch lösen:** Das Plugin setzt das Ausfall-Ticket in DeskHub auf „Gelöst“ und hinterlässt eine Notiz mit der Ausfalldauer. Die Ticketnummer merkt es sich in `offene-tickets.properties`, auch ein Neustart währenddessen schadet nicht. Abschalten mit `ticket.resolve-on-recovery: false`. Voraussetzung: DeskHub **1.0.48 oder neuer** (API-Aktion „resolve“) und der API-Schlüssel mit dem Recht „Tickets anlegen“; gelöst werden nur Tickets, die dieser Schlüssel über die API angelegt hat.
|
|
|
|
- **BungeeCord:** Sobald der Server wieder auf Pings antwortet.
|
|
- **Spigot/Paper:** Beim nächsten Start. Ein Absturz-Ticket wird dort gleich nach dem Anlegen gelöst (der Server läuft ja wieder, die Notiz nennt die Ausfalldauer). Ein Herunterfahren-Ticket (falls eingeschaltet) wird beim nächsten Start gelöst.
|
|
|
|
Normales Herunterfahren (`/stop`, geplanter Neustart) erzeugt **kein** Ticket (auf Wunsch einstellbar).
|
|
|
|
## Installation
|
|
|
|
1. **API-Schlüssel in DeskHub:** Adminportal → Verwalten → **API-Schlüssel** → neuen Schlüssel mit dem Recht **„Tickets anlegen“** erzeugen (er wird nur einmal angezeigt). Trage unter „IP-Beschränkung“ die IP-Adresse deines Minecraft-Servers ein, dann ist der Schlüssel nur von dort nutzbar.
|
|
2. **Abteilung und Priorität:** Öffne im Adminportal die Abteilung bzw. Priorität. Die Zahl am Ende der Adresse (`…?id=4`) ist die ID für die config.
|
|
3. **Jar kopieren:** `DeskHub-Minecraft-1.2.0.jar` in den Ordner `plugins` deines Servers bzw. Proxys. Server einmal starten, damit `plugins/DeskHub-Minecraft/config.yml` entsteht.
|
|
4. **config.yml ausfüllen** (mindestens `url`, `api-key`, `requester-email`; optional `department-id`, `priority-id`), dann `/deskhubmc reload`.
|
|
5. **Testen:** `/deskhubmc test` legt ein Testticket an und zeigt die Ticketnummer oder den Grund für einen Fehler.
|
|
|
|
Der Absender der Tickets (`requester-email`) bekommt von DeskHub wie bei jedem Ticket eine Eingangsbestätigung. Nimm deshalb eine Adresse, die bei dir ankommt (z. B. eine Sammeladresse für Technik).
|
|
|
|
## Befehle
|
|
|
|
| Befehl | Wirkung |
|
|
|---|---|
|
|
| `/deskhubmc test` | Testticket anlegen |
|
|
| `/deskhubmc status` | Einstellungen und (auf BungeeCord) den Zustand der Server anzeigen |
|
|
| `/deskhubmc reload` | `config.yml` neu laden |
|
|
|
|
Alias: `/dhmc`. Berechtigung: `deskhubmc.admin` (Standard: nur Operatoren; in der Konsole immer erlaubt).
|
|
|
|
## Wichtige Einstellungen
|
|
|
|
```yaml
|
|
deskhub:
|
|
url: "https://support.example.de"
|
|
api-key: "dh_…"
|
|
requester-email: "minecraft@example.de"
|
|
ticket:
|
|
department-id: 4 # 0 = Standard von DeskHub
|
|
priority-id: 3
|
|
monitor: # nur BungeeCord
|
|
interval-seconds: 30
|
|
failures-before-ticket: 3
|
|
restart-grace-minutes: 5 # Ticket erst, wenn der Server so lange weg ist (Neustarts)
|
|
planned-restart-grace-minutes: 15 # wenn der Server den Neustart selbst gemeldet hat
|
|
notify-port: 0 # Meldungen der Server annehmen (0 = aus), dazu notify-secret
|
|
cooldown-minutes: 30
|
|
servers: [] # leer = alle Server des Proxys
|
|
backend: # nur Spigot/Paper
|
|
ticket-on-crash: true
|
|
ticket-on-shutdown: false
|
|
```
|
|
|
|
Betreff und Text der Tickets sind in der `config.yml` anpassbar (Platzhalter `{server}`, `{time}`, `{source}`, `{lastSeen}`, `{downtime}`).
|
|
|
|
## Sicherheit
|
|
|
|
- Der API-Schlüssel steht in der `config.yml`. Dateirechte so setzen, dass nur der Server-Benutzer sie lesen kann, und die Datei nie weitergeben. Bei Verdacht den Schlüssel in DeskHub löschen und einen neuen erzeugen.
|
|
- Nutze **https**. Bei `http://` warnt das Plugin, weil der Schlüssel dann unverschlüsselt übertragen würde.
|
|
- Das Plugin folgt keinen Weiterleitungen, damit der Schlüssel nie an eine andere Adresse geht.
|
|
- DeskHub begrenzt die API auf 60 Tickets pro Minute und wendet eure Ticket-Regeln an.
|
|
|
|
## Bauen
|
|
|
|
Voraussetzungen: JDK 17 oder neuer, Maven.
|
|
|
|
```bash
|
|
cd minecraft-plugin
|
|
mvn package # Tests und Jar: target/DeskHub-Minecraft-1.2.0.jar
|
|
```
|
|
|
|
Zusätzlicher Test des Spigot/Paper-Teils gegen einen simulierten Paper-Server (braucht JDK 21):
|
|
|
|
```bash
|
|
mvn install -DskipTests
|
|
cd integration-test
|
|
mvn test
|
|
```
|
|
|
|
## Grenzen
|
|
|
|
- Auf einem **einzelnen** Spigot/Paper-Server ohne Proxy kommt das Ticket erst, wenn der Server wieder startet (und wird dann gleich gelöst). Wer eine Meldung in Echtzeit braucht, lässt zusätzlich das Plugin auf dem Proxy laufen oder überwacht den Server von außen.
|
|
- **Velocity** wird nicht unterstützt (eigenes Plugin-System). Auf Waterfall läuft die BungeeCord-Variante.
|
|
- Das Plugin ist kompiliert für Java 8 und die Spigot-API 1.16.5. Es sollte auf älteren und neueren Versionen laufen, geprüft sind Paper 1.21.11 (simuliert) und BungeeCord (echt).
|