Proxy-Netzwerke (BungeeCord / Velocity)

ResourcePackManager läuft auf Proxy-Netzwerken. Installiere dieselbe ResourcePackManager.jar auf dem Proxy und auf jedem Backend, das Ressourcenpakete bereitstellt. Andere registrierte Server können ohne RSPM bleiben. Auf einem Backend führt sie Pakete zusammen, hostet sie, liefert sie aus und konvertiert sie. Auf Velocity oder BungeeCord erkennt die Jar die Proxy-Plattform und übernimmt die netzwerkweite Bedrock-Auslieferung. Der Proxy besitzt den Netzwerkschlüssel und sendet ihn an jedes Backend, sobald sich dort erstmals ein Spieler verbindet.

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. Erkennt, welche registrierten Backends RSPM ausführen, und fragt diese Teilnehmer anschließend alle 5 Sekunden nach /bedrock.zip und /mappings.json ab. Dabei bevorzugt es starke ETags mit If-None-Match und erhält die If-Modified-Since-Kompatibilität für ältere Backends. Unveränderte Dateien liefern 304. Jedes Backend kündigt seinen tatsächlich gebundenen HTTP-Port an, den der Proxy normalerweise automatisch verwendet. 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, sofern Item-Mappings existieren, 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.

Die Java-Paketauslieferung in Netzwerken erfolgt pro Backend über die reguläre setResourcePack-/addResourcePack-API. Neben dem Zusammenführen von Bedrock-Paketen übernimmt die Proxy-Rolle die Bereitstellung des Netzwerkschlüssels und die authentifizierte Weitergabe von RSPM-Updates. Ein reines Java-Netzwerk benötigt sie nicht für die Java-Paketauslieferung.

Einrichtung

Floodgate

Mit Floodgate können sich Bedrock-Spieler ohne kostenpflichtiges Java-Edition-Konto authentifizieren. Geyser unterstützt auch die Online-Authentifizierung mit einem Java-Konto; folge der Geyser-Einrichtungsanleitung für deinen gewählten Authentifizierungsmodus. RSPM kann Proxy und Backends ohne Floodgate verbinden.

Ist Floodgate beim ersten RSPM-Start auf dem Proxy installiert, leitet RSPM seinen Netzwerkschlüssel aus plugins/floodgate/key.pem ab und erhält damit die Identität eines bestehenden Netzwerks. Spätere Starts verwenden RSPMs Datei network-key, solange sie einen gültigen Schlüssel enthält. Fehlt dieser oder ist er ungültig, versucht RSPM erneut den Floodgate-Schlüssel, bevor es einen zufälligen Schlüssel erzeugt.

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-Implementierungen gemeinsam in einer geshadeten Jar und erkennt automatisch, auf welcher Plattform sie läuft. Es gibt keine separate, plattformspezifische Proxy-Jar zum Extrahieren.

Wenn du die Backends bereits gestartet hast, ohne RSPM auf den Proxy zu legen, musst du nicht nach dem Download suchen: Jedes Backend hinter einem Proxy, das noch keinen Schlüssel hat, legt eine byteweise identische Kopie seiner eigenen Jar unter plugins/ResourcePackManager/proxy-extension/ResourcePackManager.jar ab und gibt genau diesen Pfad in der Konsole aus. Mit dieser Datei installierst du die Version, die gerade auf diesem Backend läuft. Aktualisiere auch die übrigen Backends, damit das Netzwerk auf demselben Stand bleibt.

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

Proxy-Software	Diese Jar verwenden
Velocity	ResourcePackManager.jar
BungeeCord	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. aus.

Starte den Proxy neu. Das war's.

Es gibt keine erforderliche Konfiguration zu bearbeiten und keinen Schlüssel einzufügen. Der Proxy legt den Netzwerkschlüssel beim Booten selbst fest und versorgt jedes Backend automatisch damit — siehe Wie sich Proxy und Backends verbinden weiter unten. Die generierte Proxy-config.yml enthält nur zwei optionale Einstellungen, beide weiter unten beschrieben.

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.

Backend-Erkennung

Der Proxy prüft registrierte Server auf RSPM, ohne die Paketsynchronisierung auf Server warten zu lassen, die es nicht ausführen. Endpunkt-Ankündigungen und zuvor validierte Cache-Inhalte können Teilnehmer sofort identifizieren. Andernfalls prüft die Erkennung den aufgelösten HTTP-Endpunkt im Hintergrund, mit höchstens zwei gleichzeitigen Prüfungen und einem Timeout von fünf Sekunden. Nicht bestätigte Server werden nach etwa einer Minute erneut geprüft.

/rspm status zeigt die Zahl bestätigter Teilnehmer und den Erkennungszustand jedes übrigen Servers. RSPM not confirmed bedeutet, dass die Erkennung RSPM noch nicht nachgewiesen hat; es beweist nicht, dass das Plugin fehlt. Prüfe Backend-Adresse, HTTP-Port und Erreichbarkeit, wenn ein Server teilnehmen sollte. Wird RSPM auf einem weiteren Backend installiert, erkennt der Proxy dies automatisch.

Sobald ein Backend bestätigt ist, werden Verbindungsfehler als fehlgeschlagene Aktualisierungen dieses Teilnehmers gemeldet. Verfügbare, bereits übernommene Inhalte bleiben erhalten, und direkte sowie Relay-Ergebnisse bleiben in /rspm status sichtbar. Ein Zählerstand von null bei leeren Polls bedeutet, dass Inhalt verfügbar ist, nicht dass jede Backend-Verbindung funktioniert.

Die Erkennung gewährt keinen Update-Zugriff. Für automatische Plugin-Updates gelten weiterhin die Authentifizierung per Netzwerkschlüssel und die Jar-Validierung.

Wie sich Proxy und Backends verbinden

Alles, was jetzt folgt, geschieht ohne Konfiguration. Es ist hier dokumentiert, weil das Wissen um diese Abfolge die gesamte Diagnose ausmacht, wenn sich ein Netzwerk nicht verbindet.

1. Der Proxy legt den Schlüssel fest. Beim Booten löst er genau einen Wert auf, in dieser Reihenfolge:

1. seine gespeicherte Datei network-key im eigenen Datenordner des Proxy-Plugins — der Normalzustand bei jedem Boot nach dem ersten;
2. eine einmalige Initialisierung, abgeleitet aus plugins/floodgate/key.pem auf dem Proxy, falls diese Datei existiert;
3. ein frisch erzeugter Zufallsschlüssel.

Der ermittelte Schlüssel wird in network-key gespeichert und wiederverwendet, solange er gültig ist. Die Konsole meldet seine Herkunft (Network key loaded ✓, adopted from Floodgate key.pem oder New network key generated). Eine fehlerhafte network-key-Datei wird ersetzt. Kann RSPM einen neuen Schlüssel nicht speichern oder eine vorhandene network-key-Datei nicht lesen, bricht der Start der Proxy-Rolle mit Could not establish persistent RSPM network identity bzw. Cannot read established RSPM network identity ab, statt mit einem Schlüssel zu laufen, der sich beim nächsten Neustart ändern könnte. Behebe die Ordnerberechtigungen und starte den Proxy neu.

2. Der Proxy schiebt den Schlüssel an jedes Backend. Sobald ein Spieler zu einem Backend verbindet, sendet der Proxy ihm den Schlüssel über den Plugin-Kanal rspm:network. Die Richtung ist Absicht: Ein Backend kann physisch nicht danach fragen, weil ein Proxy keine Plugin-Nachricht auf einem Kanal weiterleitet, den der Client des Spielers selbst nie registriert hat.

3. Das Backend übernimmt und speichert ihn. Es sichert den Schlüssel in seiner data.yml und meldet Network key received from the proxy; this backend is now linked. Zuweisungen werden nur akzeptiert, solange das Backend noch keinen Schlüssel besitzt — ein bereits etabliertes Backend protokolliert eine Warnung und behält das, was es hat, statt sich von einer Nachricht auf ein anderes Netzwerk umlenken zu lassen.

Auf Velocity mit modernem Forwarding werden Zuweisungen mit einem HMAC über das forwarding.secret des Proxys signiert, und ein für modernes Forwarding konfiguriertes Backend verlangt diese Signatur. Auf BungeeCord und mit Legacy-Forwarding gibt es kein gemeinsames Geheimnis zum Signieren, daher sind Zuweisungen unsigniert und werden auch so akzeptiert.

Ein Backend, das Schritt 2 erreicht, aber nie Schritt 3, behält als Schlüsselquelle not set. Genau dieser Zustand löst das Ablegen unter proxy-extension/ und das Bedrock-spezifische Warnbanner aus.

Prüfen, ob es funktioniert

Proxy-Konsole

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

[ResourcePackManager] Network key loaded ✓
[ResourcePackManager] Network key provisioning ready on rspm:network; backends are keyed as players connect.
[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: Fingerabdruck des Netzwerkschlüssels, Backend-Liste, Abrufergebnisse pro Backend und pro Pfad (200 / 304 / 404 / CONNECT_FAILED) für /bedrock.zip, /mappings.json und /rspm-update.jar, die empfangenen Endpunkt-Ankündigungen, die sichtbaren Relay-Einträge, den Zähler aufeinanderfolgender leerer Polls, ob das zusammengeführte Bedrock-Paket und die zusammengeführten Mappings auf der Festplatte liegen (mit ihren Größen) sowie das SHA-1-Präfix des aktuellen zusammengeführten Pakets, den network-http-offset-Fallback, den erkannten Geyser-Plugin-Ordner und die bereitgestellte Mappings-Datei sowie die Floodgate-/Geyser-Präsenz auf dem Proxy. Velocity akzeptiert resourcepackmanager.command.status oder resourcepackmanager.*; BungeeCord registriert exakt den Knoten resourcepackmanager.command.status, den Berechtigungs-Plugins über Wildcard-Erweiterung erfüllen können. Die Konsole kann den Befehl ausführen. Die Ausgabe enthält keine Geheimnisse (der Netzwerkschlüssel erscheint nur als kurzer Einweg-Hash-Fingerabdruck, und es werden keine Auth-Tokens ausgegeben), daher sind großzügige Vergaben unbedenklich.

/rspm status auf einem Backend

Die Zeile Deploy mode sollte network-backend anzeigen. Network key fingerprint sollte einen kurzen Hash zeigen — er muss mit dem Fingerabdruck übereinstimmen, den der Proxy ausgibt. Network key source sagt dir, wie dieses Backend an den Schlüssel gekommen ist:

Quellzeile	Bedeutung
provided by the proxy	Der normale verbundene Zustand. Der Proxy hat den Schlüssel bei einer Spielerverbindung zugewiesen.
saved on this server	Bereits bei einem früheren Start mit einem Schlüssel versorgt (oder ein eigenständiger Server, der seinen eigenen erzeugt hat).
adopted from Floodgate's key	Einmalig aus der lokalen plugins/floodgate/key.pem dieses Backends initialisiert.
not set — the proxy sends one when a player next connects here	Nicht verbunden. Entweder hat seit dem Start des Proxys niemand verbunden, oder auf dem Proxy fehlt RSPM / es ist ein nicht unterstützter Proxy.

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-IP-Forwarding-Schalter.
3. paper-global.yml: proxies.velocity.enabled: true — modernes Velocity-Forwarding.

Die Port-Fallback-Einstellung für den Netzwerkmodus ist networkHttpOffset-v2. Sie steuert den Fallback-HTTP-Port, den der Proxy auf jedem Backend abfragt, bevor das Backend seinen tatsächlich gebundenen Port angekündigt hat. Der Standard ist 1; der entsprechende Port muss weiterhin zwischen Proxy und Backend erreichbar sein, oder der Relay-Pfad muss zur Verfügung stehen. Die vollständige Erklärung der Port-Auflösung findest du unter Selbst-Hosting.

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 config.yml

Das Proxy-Plugin schreibt beim ersten Booten eine minimale Standardkonfiguration. Der Ordner unterscheidet sich je nach Plattform, weil jeder Proxy ihn aus seiner eigenen Plugin-Kennung ableitet:

Proxy-Software	Konfigurationspfad
Velocity	plugins/resourcepackmanager/config.yml
BungeeCord	plugins/ResourcePackManager/config.yml

Sie enthält genau zwei Einstellungen, beide optional:

# FALLBACK offset added to each backend's Minecraft port to derive the HTTP
# port this proxy will hit for /bedrock.zip and /mappings.json BEFORE that
# backend has announced its real ResourcePackManager HTTP port. Default 1.
# In normal operation the backend announces the exact port it bound, so this
# value is only used at startup or if announcement fails — but if it IS used,
# it should match each backend's networkHttpOffset-v2.
network-http-offset-v2: 1

# Installs and updates this universal ResourcePackManager.jar in the proxy's
# Geyser extensions folder, which is what makes custom Bedrock ENTITIES render.
# Default true. Setting it to false stops future installation and update
# staging; it does not delete an extension jar that is already installed —
# remove that by hand while Geyser is stopped.
geyser-extension-auto-install: true

Die Backend-Entsprechungen sind networkHttpOffset-v2 und geyserExtensionAutoInstall in der Backend-config.yml. Die beiden Seiten sind getrennte Einstellungen — die Erweiterungsinstallation auf dem Proxy abzuschalten schaltet sie nicht auf den Backends ab und umgekehrt.

Neben config.yml schreibt der Proxy network-key. Erhalte diesen generierten Zustand und kopiere ihn nicht zwischen verschiedenen Netzwerken. Löschen führt beim nächsten Start zu einer erneuten Schlüsselerkennung; eine vorhandene Floodgate-Datei kann denselben Schlüssel ergeben. Ändert er sich, behalten bereits verbundene Backends ihren alten Schlüssel und lehnen den neuen ab. Zwei Proxys vor denselben Backends müssen einen Schlüssel teilen: Kopiere die Datei zwischen diesen Proxys.

Es gibt keine proxy-seitige Einstellung force-resource-pack. Das Erzwingen der Paketannahme ist eine Backend-Entscheidung (forceResourcePack in der Backend-config.yml), weil das Proxy-Plugin nur die Bedrock-Paketauslieferung übernimmt — es sendet nie Java-Pakete. Trägt eine ältere Proxy-config.yml noch eine force-resource-pack-Zeile, wird sie schlicht ignoriert und kann gelöscht werden.

Es gibt absichtlich keinen Konfigurationseintrag network-key — ein einfügbarer Schlüssel wurde vor dem Release abgeschafft, weil Tippfehler die Proxy↔Backend-Verbindung stillschweigend zerstörten, ohne dass irgendwo ein Fehler auftauchte. Der Schlüssel wird vom Proxy festgelegt und automatisch an die Backends verteilt, wie unter Wie sich Proxy und Backends verbinden beschrieben.

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

Die Java-Hosting-Einstellungen gelten auch für Backends hinter einem Proxy. Schlägt ein Java-Selbst-Hosting-Test fehl, kann RSPM die Java-Auslieferung auf Remote-Hosting umstellen und den HTTP-Server des Backends gleichzeitig für /bedrock.zip und /mappings.json weiterlaufen lassen.

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 und 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 Netzwerkschlü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

Ein Backend bekommt nie einen Netzwerkschlüssel

Symptom: /rspm status auf dem Backend zeigt Network key source: not set — the proxy sends one when a player next connects here, und die Backend-Konsole wiederholt:

[ResourcePackManager] This backend is behind a proxy but has no network key yet, so it is not linked to the proxy.
[ResourcePackManager] The proxy sends one automatically the first time a player connects to this server.

Arbeite diese Punkte der Reihe nach ab:

1. Hat sich seit dem Start des Proxys überhaupt jemand mit diesem Backend verbunden? Die Zuweisung wird über eine Spielerverbindung übertragen. Eine Lobby, die noch niemand besucht hat, hat daher zu Recht noch keinen Schlüssel.
2. Liegt RSPM überhaupt auf dem Proxy? Das Backend legt für genau diesen Fall eine Kopie seiner eigenen Jar unter plugins/ResourcePackManager/proxy-extension/ResourcePackManager.jar ab. Kopiere sie in den plugins/-Ordner des Proxys und starte den Proxy neu.
3. Velocity mit modernem Forwarding: stimmt das Forwarding-Secret des Backends mit dem des Proxys überein? Ein für modernes Forwarding konfiguriertes Backend lehnt eine unsignierte oder falsch signierte Zuweisung absichtlich ab — diese Prüfung verhindert, dass ein unbefugter Proxy deinen Backends einen Schlüssel zuweist. Das Backend-Protokoll benennt, welcher der beiden Fälle eingetreten ist. Korrigiere das Secret auf beiden Seiten; bei der nächsten Spielerverbindung wird es automatisch erneut versucht. Dafür ist auf keiner der beiden Seiten ein Neustart nötig.
4. Ist der Proxy ein nicht unterstützter Proxy? Nur Velocity und BungeeCord führen die Proxy-Rolle aus. Waterfall wird nicht unterstützt.

Beachte, dass Floodgates key.pem hierbei keine Rolle mehr spielt. Eine fehlende plugins/floodgate/key.pem auf dem Proxy ist ein vollständig unterstützter Zustand — der Proxy erzeugt stattdessen seinen eigenen Schlüssel. Floodgate-Authentifizierung und RSPM-Netzwerkverknüpfung sind voneinander getrennt.

Zwei Proxys stehen vor denselben Backends

Beide Proxys müssen denselben Netzwerkschlüssel vorweisen, sonst verbindet sich jedes Backend mit demjenigen, der es zuerst erreicht hat, und lehnt den anderen ab (mit dem Log-Eintrag A proxy offered a network key that differs from the one this backend already uses). Kopiere die Datei network-key aus dem RSPM-Datenordner des primären Proxys in den des anderen Proxys und starte diesen neu.

Warnung „No merged pack content“ nach ~20 Sekunden

Nach vier aufeinanderfolgenden leeren Poll-Zyklen mit bestätigten RSPM-Teilnehmern protokolliert der Proxy eine Warnung mit diesen Teilnehmern, den versuchten URLs und ihren Ergebnissen. Ein frisch gestarteter Proxy, der noch seinen ersten Teilnehmer sucht, zählt andere registrierte Server nicht als fehlgeschlagene Paket-Backends. 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 konvertierbaren Item-Mappings oder Entity-Bundles 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-Start 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 der Proxy seine erste Zeile Merged Bedrock pack published protokolliert hat. RSPM stellt bei jedem Proxy-Start die Mappings des vorherigen Laufs vorab bereit, sodass gespeicherte Mappings bei späteren Starts vor Geysers Scan geladen werden können. Werden später Custom-Items hinzugefügt oder entfernt, ändert sich ebenfalls der beim Start registrierte Mapping-Satz und ein Neustart ist erforderlich. Dasselbe gilt für neue benutzerdefinierte Entity-Identifikatoren oder Property-Typen.

Warnungen „Duplicate bedrock_identifier“ beim Starten des Proxys

Unterschiedliche Bedrock-Kennungen können denselben Java-Item/Modell/Prädikat-Matcher besitzen. Nur das aufgelöste Quellmodell umzubenennen reicht dann nicht aus. Verwende für unterschiedliche Items unterschiedliche Selektoren, etwa separate Custom-Model-Data-Werte. Der aktuelle Merger bevorzugt für denselben Matcher moderne Definitionen gegenüber Legacy-Einträgen; bei gleichem Typ gewinnt der spätere Eintrag. Die Deduplizierung erhält nur ein Item.

Bedrock-Spieler ist verbunden, sieht aber das Paket nicht

Der Proxy sendet ein Chat-Banner an online befindliche Teammitglieder mit resourcepackmanager.*, wenn eine Bedrock-Session ohne nutzbares RSPM-Paket lädt:

⚠ [RSPM] Bedrock-Spielerin Alice hat sich verbunden, bevor das Ressourcenpaket bereit war, und sieht gewöhnliche Rüstungsständer statt benutzerdefinierter Modelle. Bitte sie, die Verbindung zu trennen und erneut herzustellen; das Paket wird in ihrer nächsten Sitzung geladen. (Ursache: ...)

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

Es ist dieselbe Jar auf jedem Backend und auf dem Proxy, halte also alle Komponenten auf derselben Version.

Der manuelle Weg lautet: Backend-Jar aktualisieren, dieselbe ResourcePackManager.jar erneut in den plugins/-Ordner des Proxys kopieren, Proxy neu starten.

RSPM kann die Proxy-Hälfte auch selbst erledigen. Jedes Backend bietet dem Proxy seine universelle Plugin-Jar über eine authentifizierte Route an (/rspm-update.jar, geschützt durch ein Token, das aus dem gemeinsamen Netzwerkschlüssel abgeleitet wird — der Schlüssel selbst wird nie übertragen). Der Proxy prüft, dass die angebotene Datei eine vollständige universelle RSPM-Jar mit passenden Plattform-Deskriptor-Versionen und den erwarteten Einstiegspunkten ist, lehnt Downgrades ab und verifiziert die bereitgestellten Bytes gegen die angekündigte Größe und den SHA-256, bevor er irgendetwas ersetzt. Er stellt dieselbe Jar für das Proxy-Plugin bereit und, wenn ein proxy-gehostetes Geyser erkannt wird, auch dessen mitgelieferte Geyser-Erweiterung; diese Dateien werden beim Herunterfahren des Proxys angewendet, wobei die vorherigen Dateien als Rollback-Kopien erhalten bleiben.

Das ist eine authentifizierte Netzwerk-Vertrauensgrenze, keine unabhängige Herkunftsprüfung gegen Nightbreak: Jedes Backend, das mit dem gemeinsamen Netzwerkschlüssel versorgt wurde, gilt als vertrauenswürdig genug, um eine strukturell gültige, gleich neue oder neuere RSPM-Jar anzubieten. Schütze diesen Schlüssel und behandle jedes Backend, das ihn teilt, als vertrauenswürdige Infrastruktur.

In der Praxis genügt es daher meist, die Backends zu aktualisieren und anschließend den Proxy neu zu starten — der Proxy wird sich die passende Jar bereits selbst bereitgestellt haben. Ein abgelehntes Update protokolliert Rejected backend-offered ResourcePackManager update: ... mitsamt Grund.

Authentifizierungsfehler bei ausführbaren Updates

HTTP 401 auf /rspm-update.jar pausiert nur die automatische Jar-Weitergabe dieses Backends. Bedrock-Pakete und Mappings werden weiterhin direkt abgefragt. Die Update-Route versucht es mit zunehmenden Abständen erneut, beginnend bei einer Minute bis höchstens fünfzehn Minuten. Vergleiche die Fingerabdrücke des Netzwerkschlüssels aus /rspm status auf beiden Seiten und prüfe dann, ob die gemeldete URL das richtige Backend erreicht und die Versionen übereinstimmen.

Unterscheiden sich die Fingerabdrücke, nennt /rspm status auf dem Proxy das aktuelle Vorgehen: Bestätige, dass es sich um den vorgesehenen Proxy und das vorgesehene Backend handelt, stoppe das betroffene Backend, sichere seine plugins/ResourcePackManager/data.yml, entferne nur deren Eintrag networkKey, starte es dann und tritt über diesen Proxy bei, damit es erneut mit einem Schlüssel versorgt wird. Behalte die network-key des Proxys und alle Floodgate-Schlüssel. Die 401-Konsolenwarnung auf dem Proxy empfiehlt noch, Floodgates key.pem zu kopieren; dieser Rat ist veraltet, weil RSPM seine eigene Netzwerkidentität speichert und eine Änderung an key.pem keinen bestehenden RSPM-Schlüssel ersetzt. Bewahre beide Statusausgaben für den Support auf.

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-Rotation des Netzwerkschlüssels. Ein Backend übernimmt nur dann einen Schlüssel, wenn es noch keinen hat, und lehnt Ersatznachrichten ab. Sind alle Komponenten gestoppt, erlaubt das Entfernen von network-key auf dem Proxy und networkKey aus der data.yml jedes Backends eine erneute Zuweisung. Das garantiert keinen neuen Schlüssel: Der Proxy kann aus Floodgates key.pem wieder denselben ableiten.