MClogger/README.md

MCLogger

Minecraft 1.20–1.21 · Paper + Velocity · MariaDB · Flask-Admin
Autor: SimolZimol

Umfassendes Logging-System für Minecraft-Netzwerke. Alle relevanten Events werden asynchron in einer MariaDB-Datenbank gespeichert und über ein modernes Flask-Webinterface auswertbar.

---

Projektstruktur

Log/
├── database/
│   └── schema.sql              ← MariaDB-Schema (einmalig ausführen)
│
├── paper-plugin/               ← Maven-Projekt für Paper 1.20-1.21
│   ├── pom.xml
│   └── src/main/
│       ├── java/de/simolzimol/mclogger/paper/
│       │   ├── PaperLoggerPlugin.java
│       │   ├── database/DatabaseManager.java
│       │   └── listeners/
│       │       ├── PlayerSessionListener.java
│       │       ├── PlayerChatCommandListener.java
│       │       ├── PlayerDeathListener.java
│       │       ├── PlayerMiscListener.java
│       │       ├── BlockListener.java
│       │       ├── EntityListener.java
│       │       ├── InventoryListener.java
│       │       └── WorldListener.java
│       └── resources/
│           ├── plugin.yml
│           └── config.yml
│
├── velocity-plugin/            ← Maven-Projekt für Velocity 3.x
│   ├── pom.xml
│   └── src/main/
│       ├── java/de/simolzimol/mclogger/velocity/
│       │   ├── VelocityLoggerPlugin.java
│       │   ├── database/VelocityDatabaseManager.java
│       │   └── listeners/VelocityEventListener.java
│       └── resources/
│           └── velocity-config.yml
│
└── web/                        ← Python Flask Admin-Interface
    ├── app.py
    ├── config.py
    ├── requirements.txt
    ├── templates/
    │   ├── base.html
    │   ├── login.html
    │   ├── dashboard.html
    │   ├── players.html
    │   ├── player_detail.html
    │   ├── chat.html
    │   ├── commands.html
    │   ├── blocks.html
    │   ├── deaths.html
    │   ├── proxy.html
    │   ├── sessions.html
    │   ├── server_events.html
    │   └── _pagination.html
    └── static/
        ├── css/style.css
        └── js/main.js

---

Was wird geloggt?

Paper-Server

Kategorie	Events
Sessions	Login, Logout, Kick (+ IP, Client-Version, Sprache)
Chat	Alle Chat-Nachrichten mit Welt und Server
Commands	Alle Spieler-Befehle mit Position
Tode	Ursache, Mörder, verlorene Items, XP-Level
Respawn	Bett / Ankerpunkt / Normalrespawn
Teleport	Alle Ursachen (Portal, Command, Plugin usw.)
Gamemode	Wechsel mit Ursache
Level/XP	Level-Änderungen
Blöcke	Break, Place, Ignite, Burn, Explode + Werkzeug, SilkTouch
Schilder	Alle Sign-Änderungen mit Inhalt
Entities	Spawn, Tod, Schaden (durch Spieler), Zähmen, Züchten, Explosion
PvP	Schaden zwischen Spielern
Inventar	Item aufheben/fallenlassen, Crafting, Verzauberung, Amboss, Handel
Welt	Wetter, Donner, Portal, Baum-/Pilzwachstum, Welt-Load/Unload
Server	Start, Stop, Player-Join, Player-Quit, Kick
Diverses	Bett betreten/verlassen, Hand-Item-Wechsel, Angeln, Schlafen, Entity-Interaktion, Welt-Wechsel

Velocity-Proxy

Kategorie	Events
Verbindungen	Login (+ IP, Protocol-Version, Client-Brand, Ping)
Disconnect	Grund + Sitzungsdauer
Server-Wechsel	Von → Nach-Server
Chat	Proxy-Level-Chat
Commands	Proxy-Level-Commands
Proxy	Start / Stop

---

Voraussetzungen

• Java 17+
• Maven 3.8+
• MariaDB 10.6+ / MySQL 8+
• Paper 1.20–1.21
• Velocity 3.x
• Python 3.10+

---

1. Datenbank einrichten

-- Als root in MariaDB:
SOURCE /pfad/zu/database/schema.sql;

-- Benutzer anlegen:
CREATE USER 'mclogger'@'%' IDENTIFIED BY 'sicheres_passwort';
GRANT ALL PRIVILEGES ON mclogger.* TO 'mclogger'@'%';
FLUSH PRIVILEGES;

---

2. Paper-Plugin bauen & installieren

cd paper-plugin
mvn clean package -q
cp target/mclogger-paper-1.0.0.jar /dein/paper-server/plugins/

Konfiguration bearbeiten (plugins/MCLogger/config.yml):

server:
  name: "survival-01"    # eindeutiger Name

database:
  host: "localhost"
  port: 3306
  database: "mclogger"
  username: "mclogger"
  password: "sicheres_passwort"

Server neu starten.

---

3. Velocity-Plugin bauen & installieren

cd velocity-plugin
mvn clean package -q
cp target/mclogger-velocity-1.0.0.jar /dein/velocity-proxy/plugins/

Konfiguration bearbeiten (plugins/mclogger-velocity/velocity-config.yml):

proxy:
  name: "proxy-01"

database:
  host: "localhost"
  port: 3306
  database: "mclogger"
  username: "mclogger"
  password: "sicheres_passwort"

Proxy neu starten.

---

4. Flask-Webinterface starten

cd web

# Python-Umgebung (empfohlen)
python -m venv venv
venv\Scripts\activate          # Windows
source venv/bin/activate       # Linux/Mac

pip install -r requirements.txt

# Umgebungsvariablen setzen (oder config.py direkt bearbeiten)
set MCLOGGER_DB_HOST=localhost
set MCLOGGER_DB_PASSWORD=sicheres_passwort
set MCLOGGER_ADMIN_PASSWORD=admin_passwort
set MCLOGGER_SECRET_KEY=zufaelliger_32_zeichen_schluessel

python app.py

Webinterface öffnen: http://localhost:5000

Für Produktion (Linux mit Gunicorn)

pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:5000 app:app

Oder als systemd-Service:

[Unit]
Description=MCLogger Web

[Service]
WorkingDirectory=/opt/mclogger/web
Environment=MCLOGGER_DB_HOST=localhost
Environment=MCLOGGER_DB_PASSWORD=sicheres_passwort
Environment=MCLOGGER_ADMIN_PASSWORD=admin_passwort
Environment=MCLOGGER_SECRET_KEY=...
ExecStart=/opt/mclogger/web/venv/bin/gunicorn -w 2 -b 127.0.0.1:5000 app:app
Restart=always

[Install]
WantedBy=multi-user.target

---

Webinterface-Features

Seite	Beschreibung
Dashboard	Live-Statistiken, Online-Spieler, Aktivitäts-Charts, Top-Playtime
Spieler	Suchbare Spielerliste mit Profil-Details
Spielerprofil	Sessions, Chat, Commands, Tode, Teleports, Stats, Proxy-Events in Tabs
Sessions	Alle Login-/Logout-Sitzungen mit Filterfunktion
Chat	Volltext-Suche in allen Chat-Nachrichten
Commands	Alle ausgeführten Befehle
Block-Events	Break/Place/Ignite usw. mit Positions-Info
Tode	Tode mit Ursache, Mörder und Todes-Meldung
Proxy-Events	Login, Disconnect, Server-Wechsel usw.
Server-Events	Start/Stop und reine Server-Ereignisse

---

Konfigurationsvariablen (Umgebungsvariablen)

Variable	Standard	Beschreibung
MCLOGGER_DB_HOST	localhost	MariaDB-Host
MCLOGGER_DB_PORT	3306	MariaDB-Port
MCLOGGER_DB_USER	mclogger	DB-Benutzer
MCLOGGER_DB_PASSWORD	(leer)	DB-Passwort
MCLOGGER_DB_NAME	mclogger	Datenbankname
MCLOGGER_HOST	0.0.0.0	Webserver-Bind
MCLOGGER_PORT	5000	Webserver-Port
MCLOGGER_ADMIN_USER	admin	Admin-Login
MCLOGGER_ADMIN_PASSWORD	(leer)	Admin-Passwort
MCLOGGER_SECRET_KEY	(unsicher)	Flask Session-Key

---

Performance-Hinweise

• Alle Datenbank-Writes erfolgen asynchron → kein Tick-Lag
• HikariCP Connection-Pool voreingestellt auf 10 (Paper) / 5 (Velocity)
• Entity-Spawn-Logging ist standardmäßig deaktiviert (sehr viele Events)
• Block-Events können bei Farms sehr viele Einträge erzeugen → ggf. blocks-break-only: true
• Ein regelmäßiges DB-Backup empfiehlt sich (Events wachsen schnell)
• MariaDB: Index-Tuning für timestamp-Spalten ist bereits im Schema enthalten

---

Lizenz

MIT – Frei verwendbar, SimolZimol als Autor nennen.