249 lines
7.3 KiB
Markdown
249 lines
7.3 KiB
Markdown
# ServerPulse
|
||
|
||
Monitoring- und Analytics-Plugin für Minecraft-Netzwerke mit Unified-JAR-Ansatz.
|
||
Eine Datei, zwei Laufzeiten:
|
||
- Spigot/Paper-Plugin auf den Game-Servern
|
||
- BungeeCord-Plugin auf dem Proxy
|
||
|
||
ServerPulse erfasst Performance- und Entity-Daten, erkennt Grenzwertverletzungen, kann Alerts an Discord senden und stellt optional REST-Endpunkte für Grafana/Prometheus/Influx bereit.
|
||
|
||
## Features
|
||
|
||
- Live-Monitoring für TPS, MSPT, RAM, Chunks und Spieler
|
||
- Entity-Analyse pro Welt
|
||
- Schwellwertbasierte Warnungen (Warning/Critical)
|
||
- Trend-Analyse fuer Lastentwicklungen
|
||
- Notfallaktionen (Item-Clear, Mob-Clear, Auto-Diagnose)
|
||
- Discord-Integration für Alerts und tägliche Reports
|
||
- Netzwerk-Übersicht auf BungeeCord
|
||
- REST API für Metrik-Export (Prometheus, Simple JSON, Influx, JSON)
|
||
- Plugin Messaging zwischen Spigot und Bungee über `serverpulse:data`
|
||
|
||
## Voraussetzungen
|
||
|
||
- Java 17
|
||
- Spigot/Paper 1.21+
|
||
- BungeeCord (optional, für Netzwerkmodus)
|
||
|
||
Optional:
|
||
- MySQL/MariaDB (wenn Datenbank aktiv genutzt wird)
|
||
- Discord Webhook (wenn Discord-Alerts/Reports genutzt werden)
|
||
- Grafana/Prometheus/InfluxDB (wenn REST/API-Export genutzt wird)
|
||
|
||
## Installation (ohne Build)
|
||
|
||
Da die JAR von dir bereitgestellt wird, ist kein Build-Schritt nötig.
|
||
|
||
### 1) Spigot/Paper (Standalone oder Netzwerk-Server)
|
||
|
||
1. Lege die JAR in den Ordner `plugins/` deines Spigot/Paper-Servers.
|
||
2. Starte den Server einmal, damit die `config.yml` erzeugt wird.
|
||
3. Passe die Konfiguration an.
|
||
4. Führe `/serverpulse reload` aus oder starte den Server neu.
|
||
|
||
### 2) BungeeCord (Proxy)
|
||
|
||
1. Lege dieselbe JAR in den `plugins/`-Ordner des BungeeCord-Proxys.
|
||
2. Starte den Proxy einmal, damit die `config.yml` erzeugt wird.
|
||
3. Aktiviere bei Bedarf `rest-api` und `discord`.
|
||
4. Starte den Proxy neu oder nutze `/bpulse reload`.
|
||
|
||
### 3) Netzwerkbetrieb (Spigot + Bungee)
|
||
|
||
- Installiere die JAR auf Proxy und allen relevanten Sub-Servern.
|
||
- Stelle sicher, dass mindestens ein Spieler online ist, damit Plugin-Messages von Spigot zum Proxy gesendet werden können.
|
||
- Der genutzte Channel ist `serverpulse:data`.
|
||
|
||
## Schnellstart
|
||
|
||
Empfohlene Reihenfolge:
|
||
|
||
1. In `config.yml` `general.debug: true` setzen (nur für Initialtest).
|
||
2. Optional Datenbank aktivieren und Zugangsdaten setzen.
|
||
3. Optional Discord aktivieren und Webhook eintragen.
|
||
4. Optional `rest-api.enabled: true` auf dem Bungee-Proxy setzen.
|
||
5. Plugin neu laden.
|
||
6. Mit Befehlen prüfen:
|
||
- Spigot: `/serverpulse status`
|
||
- Bungee: `/bpulse status`
|
||
|
||
## Konfiguration
|
||
|
||
Die zentrale Datei ist `config.yml`.
|
||
Je nach Laufzeit (Spigot oder Bungee) werden die passenden Abschnitte genutzt.
|
||
|
||
### Wichtige Bereiche
|
||
|
||
- `general`: Debug, Intervalle, Retention
|
||
- `database`: MySQL-Settings (nur Spigot)
|
||
- `discord`: Alerts/Reports für beide Seiten
|
||
- `thresholds`: Grenzwerte fuer Performance/Entities/Netzlast
|
||
- `worlds`: Welt-spezifische Overrides (Spigot)
|
||
- `trend-analysis`: Lasttrend-Erkennung (Spigot)
|
||
- `emergency-actions`: automatische Gegenmaßnahmen (Spigot)
|
||
- `chat-monitoring`: Muster- und Spam-Erkennung (Bungee)
|
||
- `rest-api`: API und Exportformate (Bungee)
|
||
- `messages`: Prefix und Textausgaben (Spigot)
|
||
|
||
### Beispiel: Datenbank aktivieren
|
||
|
||
```yml
|
||
database:
|
||
enabled: true
|
||
host: "localhost"
|
||
port: 3306
|
||
database: "serverpulse"
|
||
username: "root"
|
||
password: "change-me"
|
||
```
|
||
|
||
### Beispiel: Discord aktivieren
|
||
|
||
```yml
|
||
discord:
|
||
enabled: true
|
||
webhook-url: "https://discord.com/api/webhooks/..."
|
||
report-webhook-url: ""
|
||
bot-name: "ServerPulse"
|
||
daily-report:
|
||
enabled: true
|
||
time: "08:00"
|
||
```
|
||
|
||
### Beispiel: REST API aktivieren (Bungee)
|
||
|
||
```yml
|
||
rest-api:
|
||
enabled: true
|
||
host: "0.0.0.0"
|
||
port: 8081
|
||
api-key: "CHANGE_ME"
|
||
formats:
|
||
prometheus:
|
||
enabled: true
|
||
endpoint: "/metrics"
|
||
simple-json:
|
||
enabled: true
|
||
endpoint: "/grafana"
|
||
influxdb:
|
||
enabled: true
|
||
endpoint: "/influx"
|
||
json:
|
||
enabled: true
|
||
endpoint: "/api"
|
||
```
|
||
|
||
## Befehle
|
||
|
||
### Spigot/Paper
|
||
|
||
Hauptbefehl: `/serverpulse`
|
||
Alias: `/pulse`
|
||
|
||
Subcommands:
|
||
- `/serverpulse status` - Aktueller Performance-Status
|
||
- `/serverpulse report` - Manueller Monitoring-Report
|
||
- `/serverpulse world <welt>` - Detailansicht einer Welt
|
||
- `/serverpulse entities [welt]` - Entity-Übersicht
|
||
- `/serverpulse reload` - Konfiguration neu laden
|
||
- `/serverpulse debug` - Debug- und Laufzeitinfos
|
||
- `/serverpulse clear <items|mobs> [welt]` - Notfallbereinigung
|
||
|
||
### BungeeCord
|
||
|
||
Hauptbefehl: `/bpulse`
|
||
Aliase: `/bsp`, `/networkpulse`
|
||
|
||
Subcommands:
|
||
- `/bpulse status` - Netzwerk-Schnellstatus
|
||
- `/bpulse network` - Netzwerk-Statistik
|
||
- `/bpulse servers` - Detailansicht aller Sub-Server
|
||
- `/bpulse report` - Daily Report sofort an Discord senden
|
||
- `/bpulse reload` - Bungee-Konfiguration neu laden
|
||
|
||
## Permissions
|
||
|
||
### Spigot/Paper
|
||
|
||
- `serverpulse.use`
|
||
- `serverpulse.admin`
|
||
- `serverpulse.status`
|
||
- `serverpulse.report`
|
||
- `serverpulse.world`
|
||
- `serverpulse.entities`
|
||
- `serverpulse.reload`
|
||
- `serverpulse.debug`
|
||
|
||
Hinweis: Für `clear` wird in der aktuellen Implementierung `serverpulse.admin` geprüft.
|
||
|
||
### BungeeCord
|
||
|
||
- `serverpulse.bungee.use`
|
||
- `serverpulse.bungee.admin` (für `/bpulse reload`)
|
||
|
||
## REST API Endpunkte (Bungee)
|
||
|
||
Bei aktiviertem REST-Server sind standardmäßig folgende Endpunkte vorgesehen:
|
||
|
||
- Prometheus: `/metrics`
|
||
- Grafana Simple JSON: `/grafana`
|
||
- Influx-Format: `/influx`
|
||
- JSON API: `/api`
|
||
|
||
Host, Port, API-Key und Endpunkte sind in `rest-api` konfigurierbar.
|
||
|
||
## Betriebsmodi
|
||
|
||
- Standalone (nur Spigot/Paper): Lokales Monitoring auf einem Server
|
||
- Netzwerkmodus (Spigot + Bungee): Aggregation und zentrale Sicht auf Proxy-Ebene
|
||
|
||
## Troubleshooting
|
||
|
||
### Keine Daten auf Bungee sichtbar
|
||
|
||
- Prüfen, ob die JAR auch auf den Spigot-Servern installiert ist.
|
||
- Prüfen, ob Spieler online sind (Plugin Messaging benötigt initial einen Spieler-Context).
|
||
- Prüfen, ob keine Firewall den Proxy-Port für REST blockiert (falls REST genutzt wird).
|
||
- `general.debug: true` aktivieren und Logs auf beiden Seiten prüfen.
|
||
|
||
### Datenbankverbindung fehlgeschlagen
|
||
|
||
- Zugangsdaten in `database` prüfen.
|
||
- Erreichbarkeit und Port der DB prüfen.
|
||
- Sicherstellen, dass der DB-User Rechte auf die angegebene Datenbank hat.
|
||
|
||
### Discord sendet keine Nachrichten
|
||
|
||
- `discord.enabled: true` gesetzt?
|
||
- Webhook-URL korrekt?
|
||
- Netzwerkzugriff vom Server auf Discord vorhanden?
|
||
|
||
### REST API nicht erreichbar
|
||
|
||
- `rest-api.enabled: true` auf Bungee gesetzt?
|
||
- Host/Port korrekt und frei?
|
||
- Firewall/Sicherheitsgruppe prüfen.
|
||
|
||
## Projektstruktur (Kurzüberblick)
|
||
|
||
- Spigot Einstieg: `de.serverpulse.spigot.SpigotPlugin`
|
||
- Bungee Einstieg: `de.serverpulse.bungee.BungeePlugin`
|
||
- Gemeinsamer Messaging-Channel: `de.serverpulse.network.NetworkMessage`
|
||
- Ressourcen: `plugin.yml`, `bungee.yml`, `config.yml`
|
||
|
||
## ⚠️ Urheberrecht & Nutzungsbedingungen
|
||
|
||
**ServerPulse ist urheberrechtlich geschützt. © M_Viper – Alle Rechte vorbehalten.**
|
||
|
||
- ❌ Die Weitergabe dieses Plugins an Dritte ist **strengstens untersagt**
|
||
- ❌ Das Verändern, Dekompilieren oder Bearbeiten des Codes ist **nicht erlaubt**
|
||
- ❌ Eine Veröffentlichung – auch in veränderter Form – ist **verboten**
|
||
- ❌ Der Verkauf oder die kommerzielle Nutzung ist **nicht gestattet**
|
||
- ✅ Die Nutzung ist ausschließlich für den privaten Serverbetrieb erlaubt
|
||
|
||
Wer gegen diese Bedingungen verstößt, macht sich strafbar und kann rechtlich belangt werden.
|
||
|
||
## Version
|
||
|
||
Aktuelle Plugin-Version laut Konfiguration: 1.0.0
|