Zum Hauptinhalt springen

Proxy-Netzwerke (BungeeCord / Waterfall / Velocity)

ResourcePackManager läuft auf Proxy-Netzwerken. Es gibt eine Jar — ResourcePackManager.jar — und du installierst dieselbe Jar auf jedem Backend und auf dem Proxy. Auf einem Backend läuft sie in der Backend-Rolle (zusammenführen, hosten, senden, konvertieren); auf einem Velocity- oder BungeeCord-/Waterfall-Proxy erkennt dieselbe Jar automatisch den Plattform-Loader und läuft in der Proxy-Rolle (netzwerkseitige Bedrock-Auslieferung). Die beiden Rollen finden sich automatisch über die gemeinsame Datei plugins/floodgate/key.pem — keine separate Proxy-Jar, keine zu extrahierende Proxy-Erweiterung, kein einzufügender Schlüssel.

Auf dieser Seite steht „das Proxy-Plugin" als Kurzform für dieselbe ResourcePackManager.jar, die in der Proxy-Rolle läuft.

Was das Proxy-Plugin tut​

Die Aufgabe des Proxy-Plugins ist das Zusammenführen und Ausliefern von Bedrock-Paketen. In einem Netzwerk mit mehreren Backends erzeugt jedes Backend sein eigenes Bedrock-Paket (die konvertierte Version seines zusammengeführten Java-Pakets). Das Proxy-Plugin:

  1. Pollt den kleinen HTTP-Server jedes Backends alle 5 Sekunden auf /bedrock.zip und /mappings.json, mit If-Modified-Since, sodass unveränderte Dateien nahezu null Bandbreite kosten. Jedes Backend kündigt den genauen HTTP-Port an, an den es gebunden hat, sodass der Proxy normalerweise automatisch den richtigen Port trifft (siehe Auflösung des Backend-HTTP-Ports).
  2. Wartet, bis der Zustand des Posteingangs stabil ist — es führt zusammen, sobald zwei aufeinanderfolgende Polls denselben Satz von Datei-Hashes beobachten.
  3. Führt das Bedrock-Paket jedes Backends zu einem einzigen netzwerkweiten Paket zusammen.
  4. Kopiert die zusammengeführte Datei mit den benutzerdefinierten Geyser-Mappings nach plugins/Geyser-*/custom_mappings/ auf dem Proxy.
  5. Liefert das zusammengeführte Paket bei der Verbindung über Geysers SessionLoadResourcePacksEvent an Bedrock-Clients aus.

Das Proxy-Plugin ist nur für Bedrock-Spieler nützlich. Die Java-Paketauslieferung in Netzwerken erfolgt weiterhin pro Backend über die reguläre setResourcePack-/addResourcePack-API — Java-Clients sehen das Paket, das das Backend, auf dem sie sich befinden, zu senden gewählt hat. Wenn dein Netzwerk reines Java ist, brauchst du das Proxy-Plugin nicht.

Einrichtung — Zwei Schritte​

Schritt 1: Floodgate auf dem Proxy und auf jedem Backend installieren​

Floodgate ist erforderlich, damit Bedrock-Spieler sich am Proxy authentifizieren können. RSPM nutzt Floodgates plugins/floodgate/key.pem, um die Netzwerkidentität abzuleiten — diese Datei muss auf dem Proxy UND auf jedem Backend byteweise identisch sein. Floodgate verlangt dies ohnehin für die Bedrock-Authentifizierung, falls Bedrock-Spieler also derzeit über dein Netzwerk funktionieren, ist das bereits erledigt.

Wenn du noch kein Floodgate hast, installiere es auf jeder Komponente und kopiere dann eine kanonische key.pem auf jede andere Komponente, bevor du fortfährst.

Schritt 2: ResourcePackManager.jar auf den Proxy kopieren​

Es gibt nur eine Jar. Dieselbe ResourcePackManager.jar, die du auf Bukkit-/Paper-Backends installierst, ist auch das Proxy-Plugin — sie liefert die Velocity- und BungeeCord-/Waterfall-Implementierungen gemeinsam in einer geshadeten Jar und erkennt automatisch, auf welcher Plattform sie läuft. Es gibt keine separate, plattformspezifische Proxy-Jar zum Extrahieren.

Kopiere dieselbe ResourcePackManager.jar in den plugins/-Ordner deines Proxys:

Proxy-SoftwareDiese Jar verwenden
VelocityResourcePackManager.jar
BungeeCordResourcePackManager.jar
Waterfall (Bungee-Fork)ResourcePackManager.jar

Du kannst dies jederzeit von einem Backend aus bestätigen, indem du /rspm status ausführst; der Abschnitt Proxy deployment gibt Network proxy jar: ResourcePackManager.jar und Use the same jar on Bukkit/Paper, Velocity, and BungeeCord/Waterfall. aus.

Starte den Proxy neu. Das war's.

Es gibt absichtlich keine Konfiguration zu bearbeiten und keinen Schlüssel einzufügen. Das Proxy-Plugin liest beim Booten plugins/floodgate/key.pem auf dem Proxy und leitet daraus die Netzwerkidentität ab. Da Floodgate ohnehin verlangt, dass diese Datei auf jedem Backend und auf dem Proxy gleich ist, stimmt der abgeleitete Schlüssel automatisch mit dem jedes Backends überein.

Der erste Poll des Proxys feuert ~2 Sekunden nach dem Booten, danach alle 5 Sekunden. In Kombination mit dem Stabilitäts-Gate über einen einzigen Zyklus wird der erste Merge rund 7 Sekunden nachdem der Proxy mindestens ein Backend sehen kann, das bereits Inhalt produziert, veröffentlicht.

Verifizieren, dass es funktioniert​

Proxy-Konsole​

Innerhalb von ~10 Sekunden nach dem Neustart (vorausgesetzt, die Backends laufen) solltest du Folgendes sehen:

[ResourcePackManager] Network-key auto-derived from Floodgate key.pem ✓
[ResourcePackManager] NetworkSync starting (poll interval 5000 ms, network-http-offset 1 - endpoint announcements preferred, fallback HTTP port = mcPort + offset)
[ResourcePackManager] NetworkSync: inbox stabilized — merging 2 Bedrock zip(s) and 2 mappings file(s) across 2 backend(s).
[ResourcePackManager] Merged Bedrock pack published at .../merged/Bedrock.zip (sha1=...).
[ResourcePackManager] ✔ Network resource pack is now ready (... KB, sha1 ABCD1234)

/rspm status auf dem Proxy​

Gibt eine Momentaufnahme aus: Backend-Liste, Abrufergebnisse pro Backend und pro Pfad (200 / 304 / 404 / CONNECT_FAILED), Zähler aufeinanderfolgender leerer Polls, aktueller Pfad + Größe des zusammengeführten Pakets, network-http-offset und Floodgate-/Geyser-Präsenz auf dem Proxy. Erfordert resourcepackmanager.command.status oder resourcepackmanager.*. Die Konsole hat immer beide; vergib eine davon über dein Berechtigungs-Plugin an Spieler, wenn sie den Befehl ausführen können sollen. Die Ausgabe enthält keine Geheimnisse (der Netzwerkschlüssel ist maskiert, keine Auth-Tokens), daher sind großzügige Vergaben unbedenklich.

/rspm status auf einem Backend​

Die Zeile Deploy mode sollte network-backend anzeigen. Die Zeile Network key sollte einen maskierten Schlüssel zeigen (die letzten 4 Zeichen sind sichtbar) — gleiche ihn mit dem maskierten Schlüssel des Proxys ab, um zu bestätigen, dass beide Seiten übereinstimmen.

Bedrock-Client​

Verbinde dich über Bedrock. Du solltest die Aufforderung zum Herunterladen des Ressourcenpakets sehen, bevor du die Welt erreichst. Custom-Items werden mit ihren beabsichtigten Modellen dargestellt statt mit schlichten Rüstungsständern.

Konfigurationsreferenz​

Backend plugins/ResourcePackManager/config.yml​

Der Netzwerkmodus wird automatisch erkannt — es gibt kein networkMode: true-Flag zu setzen. Erkennungssignale (eines genügt):

  1. Floodgate vorhanden, Geyser-Spigot nicht vorhanden — stärkstes Signal für den Bedrock-über-Proxy-Fall.
  2. spigot.yml: settings.bungeecord: true — der ältere BungeeCord-/Waterfall-IP-Forwarding-Schalter.
  3. paper-global.yml: proxies.velocity.enabled: true — modernes Velocity-Forwarding.

Die einzige Stellschraube, die speziell für den Netzwerkmodus relevant ist, ist networkHttpOffset-v2, die den Fallback-HTTP-Port steuert, den der Proxy auf jedem Backend pollt (der Port, den der Proxy vermutet, bevor ein Backend den tatsächlich gebundenen Port angekündigt hat). Standard 1 funktioniert auf praktisch jedem Hosting. Siehe Selbst-Hosting für die vollständige Geschichte zur Port-Auflösung.

Im Normalbetrieb kündigt jedes Backend dem Proxy seinen echten HTTP-Port automatisch an (über die magmaguy.com-Endpunkt-Registry), sodass der Offset nur als Start-/Fehler-Fallback herangezogen wird. Siehe Auflösung des Backend-HTTP-Ports weiter unten.

Proxy plugins/ResourcePackManager/config.yml​

Das Proxy-Plugin schreibt beim ersten Booten eine minimale Standardkonfiguration:

# Clients zwingen, das Paket anzunehmen (Kick bei Ablehnung). Standard: false.
force-resource-pack: false

# FALLBACK-Offset, der zum Minecraft-Port jedes Backends addiert wird, um den
# HTTP-Port abzuleiten, den dieser Proxy für /bedrock.zip und /mappings.json
# ansteuert, BEVOR das Backend seinen echten ResourcePackManager-HTTP-Port
# angekündigt hat. Standard 1.
# Im Normalbetrieb kündigt das Backend den genauen gebundenen Port an, sodass
# dieser Wert nur beim Start oder bei fehlgeschlagener Ankündigung verwendet wird
# — wird er ABER verwendet, sollte er mit dem networkHttpOffset-v2 jedes Backends
# übereinstimmen.
network-http-offset-v2: 1

Es gibt absichtlich keinen network-key-Eintrag — dieser wurde vor dem Release abgeschafft, weil das manuelle Einfügen eine Hauptquelle für Fehlkonfigurationen war (Tippfehler haben die Proxy↔Backend-Verbindung stillschweigend zerstört). Der Schlüssel wird automatisch aus plugins/floodgate/key.pem abgeleitet.

Auflösung des Backend-HTTP-Ports​

Der Proxy muss wissen, welchen HTTP-Port er auf jedem Backend für /bedrock.zip und /mappings.json pollen soll. Er löst diesen Port in dieser Reihenfolge auf:

  1. Vom Backend angekündigter Endpunkt (bevorzugt). Jedes Backend lädt den genauen gebundenen HTTP-Port in die magmaguy.com-Endpunkt-Registry hoch, indiziert nach dem Netzwerkschlüssel. Bei jedem Poll aktualisiert der Proxy diese Liste und ordnet den angekündigten Port eines Backends dem Server-Listen-Eintrag über den Minecraft-Port zu (und den Host, wenn verfügbar). Das bedeutet, dass ein Admin, der auf einem Backend einen expliziten selfHostPort setzt oder dessen Backend automatisch auf mcPort + 1 landet, identisch behandelt wird — der Proxy verwendet, woran das Backend tatsächlich gebunden hat.
  2. mcPort + network-http-offset-v2 (Fallback). Wird nur verwendet, wenn keine passende Ankündigung verfügbar ist (z. B. beim ersten Poll, bevor ein Backend etwas angekündigt hat, oder wenn die Endpunkt-Registry kurzzeitig nicht erreichbar ist). Deshalb sollten die beiden Offsets weiterhin übereinstimmen, wenn du dich auf den Fallback verlässt.

Der Proxy port-scannt ein Backend bewusst nicht als Fallback — das sieht für den Host nach missbräuchlichem Verhalten aus. Wenn ein direkter Abruf überhaupt nicht möglich ist, ist der Relay-Pfad (unten) die kategorische Antwort.

/rspm status auf dem Proxy zeigt pro Backend, welcher Port gewählt wurde und ob er aus einer Ankündigung oder dem Offset-Fallback stammt.

Stabilität und Merge-Takt​

Der Proxy wartet, bis der Zustand des Posteingangs stabil ist, bevor er zusammenführt: Der erste Poll legt den Basissatz der Datei-Hashes fest, und der nächste Poll, der denselben Satz beobachtet, löst den Merge aus (ein Stabilitäts-Gate über einen Zyklus). Mit der ~2 s langen Anfangsverzögerung und dem 5 s langen Poll-Intervall liegt der erste Merge ~7 s nachdem der Proxy mindestens ein Backend sehen kann, das Inhalt produziert. Nachfolgende Merges zippen nur dann neu, wenn sich der SHA-1-Satz der Posteingangsdateien ändert, sodass eine lange ruhige Phase praktisch nichts kostet.

Backends schreiben ihre bedrock.zip in eine temporäre Datei und benennen sie atomar um, sodass die /bedrock.zip-Route immer eine vollständige ZIP ausliefert — der Proxy muss sich nie gegen halb geschriebene Lesevorgänge absichern, weshalb das Gate ein einzelner Zyklus statt zwei ist.

Direkter Abruf vs. Relay-Fallback​

Der Standardpfad ist der direkte Abruf: Der Proxy macht für jedes Backend ein HTTP-GET an http://<backend-host>:<mcPort + offset><path>.

Wenn der Proxy den HTTP-Port eines Backends nicht direkt erreichen kann (typisch für Shared-/Managed-Minecraft-Hosting, wo MC-Ports freigegeben sind, benachbarte Ports aber durch eine Firewall blockiert werden), schiebt das Backend seine bedrock.zip und mappings.json an einen Relay-Endpunkt auf magmaguy.com unter dem Namespace des Netzwerks (abgeleitet vom Floodgate-Schlüssel). Der Proxy listet und lädt vom Relay, wenn der direkte Abruf hart fehlschlägt.

Beide Pfade münden in denselben Merge-Schritt, sodass der Betreiber nie wählen muss — der direkte Abruf wird bevorzugt (keine Bandbreitenkosten für magmaguy.com), das Relay springt bei Bedarf transparent ein.

Das Relay hat serverseitig eine TTL von 30 Minuten. Backends schieben alle 25 Minuten, um den Eintrag am Leben zu halten; ein sauberes Herunterfahren entfernt den Eintrag sofort, statt auf die TTL zu warten.

Häufige Probleme beheben​

„Floodgate key.pem missing" beim Booten des Proxys​

Das Proxy-Plugin konnte plugins/floodgate/key.pem nicht finden und ist in den Leerlauf gegangen. RSPM kann sich ohne diese Datei nicht mit einem Backend verbinden.

Lösung: Installiere Floodgate auf dem Proxy und stelle dann sicher, dass plugins/floodgate/key.pem auf dem Proxy byteweise identisch mit derselben Datei auf jedem Backend ist. Floodgate generiert standardmäßig pro Installation unterschiedliche Schlüssel — kopiere eine kanonische key.pem von einem beliebigen Backend auf jede andere Komponente und starte alles neu.

Warnung „No merged pack content" nach ~20 Sekunden​

Nach 4 aufeinanderfolgenden leeren Poll-Zyklen protokolliert der Proxy eine einmalige mehrzeilige Warnung, die jedes gepollte Backend, die versuchte URL und das Ergebnis auflistet. Die Warnung erklärt die häufigsten Lösungen:

  • CONNECT_FAILED bei jedem Backend — der Proxy kann den Backend-HTTP-Port überhaupt nicht erreichen. Prüfe, ob die Adresse in velocity.toml / config.yml eine ist, die der Proxy tatsächlich erreichen kann (kein Docker-interner Name, der aus dem Netzwerk des Proxys nicht aufgelöst wird), und dass der HTTP-Port des Backends zwischen Proxy und Backend offen ist. Die Warnung gibt für jedes Backend den genauen HTTP-host:port aus, den sie versucht hat, und ob dieser Port aus der Ankündigung des Backends oder dem mcPort + networkHttpOffset-v2-Fallback stammt. Wenn du keine Möglichkeit hast, diesen Port zu öffnen (Managed-Hosting), siehe den Abschnitt zum Relay-Fallback oben — das Backend sollte automatisch in das Relay hochladen.
  • NOT_FOUND_404 bei jedem Backend — die Backends laufen, produzieren aber kein Bedrock-Paket. Führe /rspm status auf jedem Backend aus; der Diagnoseblock für das Bedrock-Paket sagt dir, warum (am häufigsten: keine Items-Definitionen im zusammengeführten Paket oder der erste Mix-Zyklus ist noch nicht abgeschlossen).

Die Warnung feuert einmal pro Hänger-Phase. Eine Zeile NetworkSync: recovered wird protokolliert, sobald mindestens ein Backend wieder Inhalt zurückgibt.

Bedrock-Spieler sehen beim ersten Proxy-Boot keine Custom-Modelle​

Geyser registriert seine Custom-Item-Tabelle nur beim Proxy-Start. Wenn der Proxy gestartet wurde, bevor ein Backend ein Bedrock-Paket produziert hat, läuft Geyser mit einer leeren Mappings-Tabelle und bleibt für den Rest der Session so.

Lösung: Starte den Proxy einmal neu, nachdem das Backend seine erste Merged Bedrock pack published-Zeile protokolliert hat. RSPM stellt bei jedem Proxy-Boot die Mappings des vorherigen Laufs vorab bereit, sodass dies nur bei einer brandneuen Installation zum Problem wird — bei nachfolgenden Boots ist etwas bereit, bevor Geyser scannt.

Warnungen „Duplicate bedrock_identifier" beim Booten des Proxys​

Zwei Backends haben denselben Bedrock-Identifikator für dasselbe Basis-Item ausgegeben. „Letzter Schreiber gewinnt"; harmlos, wenn nur ein Backend dieses Item bereitstellen muss. Wenn beide Backends unter demselben Basis-Item unterschiedliche Custom-Items hosten sollen, benenne eines der Quell-Java-Modelle um, damit sich die automatisch generierten Hashes unterscheiden.

Bedrock-Spieler ist verbunden, sieht aber das Paket nicht​

Der Proxy feuert ein Chat-Banner an alle online befindlichen Java-Spieler, wenn eine Bedrock-Session ohne ein nutzbares RSPM-Paket lädt:

⚠ [RSPM] Bedrock player Alice connected before the resource pack was ready — they're seeing plain armor stands instead of custom models. Tell them to disconnect and reconnect; the pack will load on their next session. (Cause: ...)

Der Bedrock-Spieler selbst erhält außerdem ein modales Popup, und die Proxy-Konsole erhält ein Banner. Wenn du tiefer graben musst, aktiviere den Debug-Stream (verfügbar sowohl auf Velocity als auch auf BungeeCord):

/rspm debug bedrock on

Das aktiviert ausführliche [RSPM-BedrockDebug]-Protokollzeilen des GeyserBinder. Reproduziere das Problem und schalte es dann wieder aus:

/rspm debug bedrock off

Die Einstellung wird bei einem Proxy-Neustart auf „aus" zurückgesetzt, damit sie nicht versehentlich aktiviert bleiben kann.

RSPM in einem Netzwerk aktualisieren​

Nachdem du die Backend-RSPM-Jar aktualisiert hast, kopiere auch dieselbe ResourcePackManager.jar erneut in den plugins/-Ordner des Proxys und starte den Proxy neu. Es ist dieselbe Jar auf jedem Backend und auf dem Proxy, halte also alle Komponenten auf derselben Version.

Was noch nicht unterstützt wird​

  • Java-Pakete in Netzwerken über das Proxy-Plugin. Java-Clients erhalten Pakete direkt von jedem Backend über die reguläre API. Es gibt keinen proxy-seitigen Java-Paket-Mixer.
  • Backend-übergreifendes Zusammenführen von Java-Paketen. Das Java-Paket jedes Backends ist unabhängig. Wechselt ein Spieler das Backend, erhält er das Paket des neuen Backends.
  • Live-Rekonfiguration des Netzwerkschlüssels. Der Schlüssel ist an Floodgates key.pem gebunden. Ihn zu ändern erfordert einen Neustart des Proxys UND jedes Backends (was du beim Rotieren des Floodgate-Schlüssels ohnehin tun würdest).