Zum Hauptinhalt springen

Das Ressourcenpaket selbst hosten

ResourcePackManager liefert einen eigenen kleinen HTTP-Server mit. Wenn autoHost: true (Standard) und preferSelfHost: true (Standard) gesetzt sind, versucht das Plugin, das zusammengeführte Paket aus derselben JVM wie der Minecraft-Server selbst zu hosten — kein externer Datei-Host, kein separater Webserver, kein manuelles Einfügen einer URL.

Diese Seite behandelt, wie dieser Selbst-Hosting-Pfad funktioniert, was die Plausibilitätsprüfungen tun, wie Port und Hostname gewählt werden und was zu konfigurieren ist, wenn die Standardwerte nicht zu deinem Setup passen.

Um einen HTTPS-Reverse-Proxy vor RSPM zu schalten und die automatische Auslieferung beizubehalten, verwende selfHostExternalUrl wie unten beschrieben. Setze autoHost: false nur, wenn ein anderes System sowohl das Hosting als auch die Auslieferung an Spieler übernimmt.

Auslieferungs-Entscheidungsbaum​

Wenn ein Spieler beitritt, wählt RSPM eine Auslieferungs-URL nach dieser Rangfolge:

Die normale automatische Auslieferung benötigt autoHost: true. Bei autoHost: false wird nur mit der ausdrücklichen Übersteuerung selfHostForce: true eine URL gesendet.

  1. selfHostForce: true — direkt zum Selbst-Hosting, ohne Prüfungen oder Remote-Upload. Hauptsächlich zum Testen dieses Pfads. Übersteuert autoHost und selfHostEnabled; URL-Prüfung und Start des HTTP-Listeners müssen weiterhin erfolgreich sein.
  2. preferSelfHost: true UND selfHostEnabled: true: Self-Hosting mit den folgenden Prüfungen versuchen, auch auf Proxy-Backends. Bei einem Fehlschlag auf Remote-Hosting zurückfallen.
  3. Andernfalls — das Paket auf https://magmaguy.com/rsp/ wiederverwenden oder hochladen und diese URL ankündigen. Schlagen Initialisierung, SHA1-Prüfung oder Upload fehl, verifiziertes Selbst-Hosting versuchen (sofern selfHostEnabled: true). SESSION_NOT_FOUND löscht auch die Remote-Sitzung, damit ein späterer Versuch sie neu initialisieren kann. Dieser automatische Fallback führt dieselben Prüfungen wie bevorzugtes Selbst-Hosting aus; schlagen beide Pfade fehl, wird keine neue Auslieferungs-URL angekündigt.

Der Remote-Host akzeptiert Java-Pakete bis 50.000 KiB (51.200.000 Bytes). RSPM prüft die Größe vor dem Hochladen. Ein größeres Paket wird nie hochgeladen: Die Konsole gibt Automatic hosting skipped: resource pack is <size> bytes; the limit is 51200000 bytes. aus. RSPM verwendet für dieses Paket dann kein Remote-Hosting mehr und versucht weiterhin geprüftes Selbst-Hosting (bei selfHostEnabled: true), bis das Hosting für ein neues Paket oder nach einem Neuladen neu startet. Verkleinere das Paket oder mache das Selbst-Hosting erreichbar und führe dann /rspm reload aus.

Sobald eine URL vorliegt, verwendet RSPM Minecrafts Multi-Pack-API, sodass sein Java-Paket mit anderen vom Server gesendeten Paketen koexistieren kann. Der aktuelle Bukkit-Plugin-Deskriptor verlangt Minecraft 1.21.4 oder neuer.

Die drei Plausibilitätsprüfungen​

RSPM führt diese Prüfungen der Reihe nach aus, bevor es automatisches Selbst-Hosting auswählt, auch beim Fallback nach einem Remote-Hosting-Fehler. Nur selfHostForce: true umgeht sie:

Ebene 1 — Heuristische Prüfung des aufgelösten externen Hosts​

Ist der aufgelöste Host (siehe „Erkennung des externen Hosts“) RFC1918 (10.*, 172.16-31.*, 192.168.*), Loopback (127.* oder localhost), Link-Local (169.254.*) oder unspezifiziert (0.0.0.0), wird Selbst-Hosting übersprungen. Unspezifizierte IPv6-Adressen sowie IPv6-Loopback, Link-Local, Site-Local und Unique-Local werden ebenfalls abgelehnt. Diese Heuristik prüft den Host-Text; ein Hostname muss weiterhin die folgenden Download-Prüfungen bestehen.

Das fängt den sehr häufigen Fehlermodus „ipify-Lookup fehlgeschlagen, auf LAN-IP zurückgefallen" ab.

Ebene 2 — Downloads über localhost und die angekündigte URL​

RSPM sendet eine GET-Anfrage mit einem Bytebereich zuerst an http://127.0.0.1:<port>/rspm.zip, dann an genau die URL, die Spieler erhalten würden. Bis zum ersten KiB wird mit dem lokalen Paket verglichen. HTTP 200 oder 206 wird akzeptiert; angegebene Längen müssen übereinstimmen und eine 206-Antwort muss den erwarteten Content-Range enthalten. Weiterleitungen werden abgelehnt. Das erkennt:

  • Port-Bind-Kollisionen (etwas anderes belegt den gewählten Port)
  • fehlende Paketdatei (die Route ist registriert, aber das ZIP liegt noch nicht auf der Festplatte)
  • falsche Routen, HTML-Fehlerseiten oder abweichende Paketbytes
  • eine angekündigte URL, die der Server selbst nicht herunterladen kann, etwa bei defektem NAT-Loopback

Für jede Verbindung und jeden Lesevorgang gilt ein Timeout von 3 s, zusätzlich eine eigene Frist von 3 s zum Lesen der Stichprobe. Dies sind begrenzte Stichprobenprüfungen, keine vollständigen Client-Downloads.

Ebene 3 — Externer Erreichbarkeitstest​

Die angekündigte URL per POST /rsp/probe an den magmaguy.com-Hoster senden. Der Hoster ruft die URL von einem öffentlichen Netzwerk aus ab (mit SSRF-Schutz und einem knappen Timeout) und meldet zurück, ob sie erreichbar ist.

Fängt den häufigsten Produktions-Fehlermodus ab: Der Server hat eine öffentliche IP, aber der HTTP-Port ist am Router oder an der Firewall nicht weitergeleitet. Ebene 2 besteht (der Server antwortet auf 127.0.0.1), aber kein echter Client könnte das Paket jemals herunterladen.

Entscheidungsregeln je nach Testergebnis:

  • reachable=true mit HTTP 200 oder 206 → der Test konnte die URL aus seinem öffentlichen Netzwerk erreichen. Selbst-Hosting auswählen.
  • reachable=false oder ein anderer HTTP-Status → die Verifikation ist fehlgeschlagen. Die vorgesehene Java-URL zurückziehen und Remote-Hosting über magmaguy.com versuchen. Im Netzwerkmodus bleibt der HTTP-Listener des Backends für die Artefaktabfragen des Proxys verfügbar.
  • die Test-Kommunikation schlägt fehl (IOException) oder der Prüfclient ist nicht verfügbar → die Erreichbarkeit ist nicht verifiziert. Remote-Hosting versuchen; ein nicht erreichbarer Prüfdienst beweist nicht, dass auch der Upload fehlschlägt. Der automatische Fallback darf diese Prüfung nicht umgehen.

Was die Prüfungen weiterhin nicht erkennen​

Der Download über die angekündigte URL erkennt jetzt NAT-Loopback-Fehler aus dem Netzwerk des Servers. Er belegt weder die Erreichbarkeit aus jedem Spielernetzwerk noch einen erfolgreichen vollständigen Minecraft-Download. Prüfe den vollständigen Download und die Annahme des Pakets mit einem echten Client; verwende für den öffentlichen Zugriff ein separates externes Netzwerk.

Für einen schnellen Test vom Host-Rechner aus setze preferSelfHost: false und nutze den Remote-Fallback, oder teste die öffentliche URL aus einem Mobilfunk-/externen Netz. Für ein dauerhaftes Selbst-Hosting-Setup verwende Split-Horizon-DNS (derselbe öffentliche Hostname löst innerhalb deines Netzes auf die LAN-Adresse des Servers auf). Setze selfHostExternalHost nicht auf 127.0.0.1: Loopback- und private Hosts werden von der Plausibilitätsprüfung des öffentlichen Hosts abgelehnt und können externe Clients nicht bedienen.

Port-Auflösung​

Zwei Einstellungen wirken zusammen:

  • selfHostPort — expliziter Port von 1 bis 65535 oder -1 (Standard) für die automatische Ableitung. Auch der abgeleitete Port muss in diesem Bereich liegen; andere Werte verhindern den Start des Listeners.
  • networkHttpOffset-v2 — wird nur herangezogen, wenn selfHostPort = -1. Wird zum Minecraft-Server-Port addiert, um den HTTP-Port abzuleiten. Standard 1. (In Proxy-Netzwerken ist derselbe Wert auch die Fallback-Vermutung des Proxys für den HTTP-Port eines Backends — siehe unten.)

Der Standard ist selfHostPort: -1 + networkHttpOffset-v2: 1, also:

  • MC-Port 25565 → HTTP-Port 25566
  • MC-Port 25584 → HTTP-Port 25585

Eindeutige Minecraft-Ports ergeben eindeutige abgeleitete HTTP-Ports. Ein solcher Port kann aber weiterhin mit dem Minecraft-Port eines anderen Backends oder mit einem anderen Dienst kollidieren. Prüfe alle Listener und die von deinem Anbieter zugewiesenen Ports.

Warum Offset 1?​

Shared- und Managed-Hosting weisen einem Container möglicherweise nur wenige Ports zu. Ein Offset von 1 hält den abgeleiteten Port nahe am Spielport, reserviert ihn aber nicht und garantiert weder seine Zuweisung noch seine Freigabe durch den Anbieter. Prüfe den genauen HTTP-Port in deinem Verwaltungsportal.

Selbst gehostete Admins mit voller Port-Kontrolle können dies auf einen beliebigen Wert erhöhen. In einem Proxy-Netzwerk kündigt das Backend dem Proxy automatisch den genauen gebundenen HTTP-Port an, sodass der Proxy mitzieht, selbst wenn du den Offset änderst oder einen expliziten selfHostPort setzt. Das network-http-offset-v2 des Proxys zur Übereinstimmung zu erhöhen, ist nur als Fallback relevant — für das kurze Zeitfenster, bevor ein Backend etwas angekündigt hat (oder falls die Ankündigung den Proxy nicht erreicht).

Achtung: RCON-Kollision​

Wenn dein Host RCON standardmäßig auf MC-Port + 1 aktiviert, wähle Offset 2 oder 3, um eine Port-Kollision zu vermeiden. Prüfe server.properties auf rcon.port=.

Versionierter Konfigurationsschlüssel​

Die Einstellung in der config.yml heißt genau networkHttpOffset-v2. Der v1-Schlüssel hieß networkHttpOffset und hatte den Standardwert 100, wodurch der Listener außerhalb der zugewiesenen Hosting-Ports liegen konnte. Der v2-Standard ist 1; auch dieser Port muss verfügbar und erreichbar sein.

Wenn du von v1 aktualisierst, sitzt der tote v1-Schlüssel als harmloses Artefakt in deiner Konfiguration, bis du ihn aufräumst — RSPM liest ihn absichtlich nicht.

Erkennung des externen Hosts​

selfHostExternalHost steuert, welchen Hostnamen Clients in der URL sehen. Leer lassen (Standard) für die automatische Erkennung in dieser Prioritätsreihenfolge:

  1. api.ipify.org / checkip.amazonaws.com — gibt die öffentliche IPv4 dieses Hosts zurück. Wird einmal pro /rspm reload gecacht, damit die IP-Dienste nicht überlastet werden.
  2. Bukkit.getIp() — die Bind-Adresse des Servers, wenn nicht leer und nicht 0.0.0.0. Üblicherweise eine LAN-Adresse.
  3. InetAddress.getLocalHost() — Best Effort.
  4. localhost — letzter Notbehelf. Clients außerhalb des Rechners erreichen dies nicht.

Wenn die automatische Erkennung auf einer nicht routbaren Adresse landet und preferSelfHost: true, schlägt die heuristische Prüfung von Ebene 1 fehl und das Plugin wechselt zu Remote-Hosting.

Für das zuverlässigste Selbst-Hosting-Setup setze selfHostExternalHost explizit auf deinen öffentlichen Hostnamen (z. B. play.example.com). Das überspringt die ipify-/AWS-Erkennung vollständig und der Test läuft gegen den expliziten Wert.

Konfigurationsreferenz​

HTTPS und Reverse Proxys​

Setze selfHostExternalUrl auf die vollständige öffentliche Download-URL:

autoHost: true
selfHostEnabled: true
preferSelfHost: true
selfHostPort: 25566
selfHostExternalUrl: "https://packs.example.com/rspm.zip"

Konfiguriere deinen Reverse Proxy so, dass er diesen öffentlichen Pfad an RSPMs interne Route http://<server>:25566/rspm.zip weiterleitet und TLS terminiert. RSPM betreibt weiterhin einen HTTP-Listener; diese Einstellung installiert kein Zertifikat und konfiguriert deinen Webserver nicht.

Die genaue URL wird an Java-Spieler gesendet und für den externen Erreichbarkeitstest verwendet. Es wird kein Suffix /rspm.zip angehängt. Sie überschreibt für die Java-Auslieferung selfHostExternalHost und die Erkennung der öffentlichen IP; selfHostPort steuert weiterhin den internen Listener. Der Proxy ruft Bedrock-Artefakte weiterhin über den HTTP-Endpunkt des Backends ab.

Akzeptiert werden nur vollständige HTTP- oder HTTPS-URLs mit Host und ohne eingebettete Zugangsdaten oder Fragmente. Ein expliziter URL-Port muss zwischen 1 und 65535 liegen. Eine ungültige URL verhindert Selbst-Hosting. Das normale automatische Hosting kann auf den Remote-Host zurückfallen, erzwungenes Selbst-Hosting nicht. Lasse die Einstellung leer, um die Host- und Port-Erkennung zu verwenden.

Einstellungen​

# Whether the built-in HTTP server may be used as a delivery path at all.
# When false, ordinary self-host attempts are disabled. selfHostForce still overrides it.
selfHostEnabled: true

# Port for the self-host HTTP server.
# -1 (default) = auto-derive: HTTP port = Minecraft server port + networkHttpOffset-v2.
# Set to a value from 1 to 65535 to force an explicit port.
selfHostPort: -1

# Added to the Minecraft server port when selfHostPort = -1.
# Default 1 (MC 25565 -> HTTP 25566). On a proxy network this is only a FALLBACK:
# the backend announces the exact HTTP port it actually bound to the proxy, so
# you no longer have to match this against the proxy's network-http-offset-v2.
networkHttpOffset-v2: 1

# Public hostname or IP clients use to reach the self-host server.
# Leave empty for auto-detect (api.ipify.org / checkip.amazonaws.com).
selfHostExternalHost: ""

# Optional complete public Java-pack URL, including the path.
# Your reverse proxy supplies HTTPS and forwards to the internal /rspm.zip route.
selfHostExternalUrl: ""

# Try self-host FIRST with three sanity checks, fall back to remote if any fail.
# When false, use the legacy order: remote upload first, self-host only on upload failure.
preferSelfHost: true

# Skip ALL other delivery paths and force self-hosting.
# Bypasses sanity checks AND remote upload. Mainly for testing.
selfHostForce: false

# Print every step of pack preparation and the hosting handshake.
# Default false — see "What the console actually prints" below.
# `/rspm verbose on|off` flips this same key at runtime and saves it here.
verboseLogging: false

Was die Konsole tatsächlich ausgibt​

Bei Fehlern im entfernten Java-Hosting oder Bedrock-Relay steigen die Wartezeiten exponentiell mit zufälliger Streuung. Jeder Ablauf erlaubt einen aktiven Versuch und bis zu fünf Wiederholungen; danach wartet er 15–30 Minuten vor einer neuen Serie. Erfolg setzt das Wiederholungsbudget zurück. Der HTTP-Client fügt keine eigenen automatischen Wiederholungen hinzu. Java-Hosting prüft vor dem Upload den entfernten SHA-1. Bedrock-Wiederholungen verwenden erfolgreich hochgeladene, unveränderte Dateien bis zu 20 Minuten lang erneut. Die reguläre Relay-Erneuerung alle 25 Minuten lädt weiterhin hoch, um die Gültigkeit auf dem Server zu verlängern.

RSPM gibt bei einem normalen Boot bewusst eine Zeile zum Hosting aus — das Ergebnis, nicht den Weg dorthin:

[ResourcePackManager] Resource pack is live via self-hosting — http://play.example.com:25566/rspm.zip

oder, wenn der Remote-Pfad gewonnen hat:

[ResourcePackManager] Resource pack is live via automatic hosting — https://magmaguy.com/rsp/<uuid>

Diese Zeile wird jedes Mal einmal ausgegeben, wenn ein Auslieferungspfad frisch initialisiert wird, nicht bei Spieler-Wiederholungen oder Keep-Alive-Ticks. Ein Reload, dessen Paket unverändert ist, kann die bestehende Hosting-Registrierung wiederverwenden, statt ein neues Ergebnis auszugeben.

Fehlgeschlagene Erreichbarkeitsprüfungen werden als Detail protokolliert. Zum Beispiel: Self-host check: local pack link is not public. This is OK. Die Host- und die localhost-Prüfung enden mit This is OK.; der Download über die angekündigte URL und die externe Verifikation melden ihr Scheitern ohne diesen Zusatz. Ungültige URL-Einstellungen, fehlgeschlagene Listener-Starts und Remote-Kommunikationsfehler können weiterhin Warnungen erzeugen. Eine fehlgeschlagene Prüfung belegt für sich allein keinen erfolgreichen Remote-Fallback; prüfe den endgültigen Auslieferungsstatus.

Um die gesamte Entscheidungskette zu sehen — welche Prüfung fehlgeschlagen ist, die Test-URL, den Grundcode, jedes bereitgestellte Paket und jeden zusammengeführten Cluster — führe aus:

/rspm verbose on

Dann /rspm reload. Das ist der Schalter, den du umlegst, bevor du einen Fehlerbericht zum Hosting eröffnest. Der Befehl schreibt verboseLogging: true in die config.yml, und die Einstellung bleibt über Neustarts hinweg erhalten — führe also /rspm verbose off aus, wenn du fertig bist; den Konfigurationsschlüssel von Hand zu bearbeiten hat exakt denselben Effekt.

Beachte, dass verboseLogging die Paketvorbereitung und das Hosting abdeckt. Der Bedrock-Konverter hat seinen eigenen, separaten Schalter bedrockConverterDebug — siehe Bedrock-Konvertierung.

Routen des Backend-HTTP-Servers​

Der eingebaute HTTP-Server liefert das Paket-ZIP immer aus unter:

http://<host>:<port>/rspm.zip

Im Netzwerkmodus (RSPM läuft hinter einem Velocity-/BungeeCord-Proxy) werden zusätzliche Routen registriert, die das Proxy-Plugin abholen kann:

http://<host>:<port>/bedrock.zip   # the Bedrock-converted pack
http://<host>:<port>/mappings.json # the Geyser custom-mappings JSON
http://<host>:<port>/rspm-update.jar # the universal RSPM update jar (authenticated)

Die Paket- und Bedrock-Routen sind dateigestützt und bestimmen bei jeder Anfrage das aktuell veröffentlichte Artefakt. Ein erfolgreich veröffentlichter neuer Mix wird ohne Neustart des HTTP-Servers verfügbar; das bloße Ersetzen einer Datei autorisiert sie nicht. Routen antworten mit 404, wenn kein aktuelles Artefakt autorisiert ist, die Datei fehlt oder ihre Bytes nicht mehr dem Veröffentlichungs-Hash entsprechen. Die Bedrock-Routen setzen außerdem weiterhin aktivierte Konvertierung voraus. Starke ETags unterstützen If-None-Match, das Vorrang vor der kompatiblen Prüfung über If-Modified-Since hat; unveränderte Abfragen können ein 304 ohne Body erhalten. Die Update-Route ist gesondert durch ein Bearer-Token geschützt, das aus dem gemeinsamen Netzwerkschlüssel abgeleitet wird, und steht nur zur Verfügung, wenn eine gültige Update-Jar angeboten werden kann.

Prüfen, ob Selbst-Hosting aktiv ist​

/rspm status zeigt:

  • Active delivery: SELF-HOSTED — Selbst-Hosting ist in Verwendung
  • Active delivery: REMOTE (magmaguy.com) — Remote-Auto-Hosting ist in Verwendung
  • URL: ... — die tatsächliche URL, die Clients sehen
  • Resolved external host — worauf selfHostExternalHost aufgelöst wurde
  • Public IP (auto-detected) — was ipify/AWS gemeldet hat, falls überhaupt etwas
  • selfHostPort — automatisch vs. explizit und der aufgelöste Wert

Wenn du Selbst-Hosting erwartet hast, aber Remote siehst, ist /rspm status die richtige Anlaufstelle — das Boot-Log schweigt zu selbst behobenen Test-Fehlschlägen, und zwar absichtlich. Führe /rspm verbose on und /rspm reload aus, um zu sehen, welche Plausibilitätsprüfung fehlgeschlagen ist und warum.

Häufige Fehler​

  • Eine erfolgreiche Prüfung als vollständigen Client-Test ansehen — die lokale Stichprobe und der öffentliche Test decken bestimmte Netzwerkpfade ab. Prüfe einen vollständigen Download und die Paketannahme mit einem echten Spieler; erzwungenes Selbst-Hosting überspringt diese Prüfungen vollständig.
  • networkHttpOffset-v2 über den Port-Bereich deines Hosting-Anbieters hinaus erhöhen — das Symptom ist ein für immer stilles CONNECT_FAILED auf der Proxy-Seite. Backends kündigen dem Proxy ihren echten gebundenen Port an, aber der HTTP-Server muss trotzdem an einen erreichbaren Port binden und der Proxy muss ihn trotzdem erreichen können; wenn mcPort + offset außerhalb des deinem Container zugewiesenen Port-Bands landet, schlägt das Binden/die Firewall unabhängig von der Ankündigung fehl. Prüfe vor dem Erhöhen des Offsets, dass der Port im zugewiesenen Band deines Containers liegt.