diff --git a/README.md b/README.md index 1e449e6..08edcc0 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,248 @@ # 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 ` - Detailansicht einer Welt +- `/serverpulse entities [welt]` - Entity-Übersicht +- `/serverpulse reload` - Konfiguration neu laden +- `/serverpulse debug` - Debug- und Laufzeitinfos +- `/serverpulse clear [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