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.

Wenn du das ZIP stattdessen über deinen eigenen, bestehenden Webserver außerhalb von RSPM hosten möchtest, siehe den Abschnitt zu autoHost: false auf der Fehlerbehebungs-Seite.

Auslieferungs-Entscheidungsbaum​

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

  1. selfHostForce: true — direkt zum Selbst-Hosting, keine Prüfungen, kein Remote-Upload. Hauptsächlich, um den Selbst-Hosting-Pfad zu testen. Umgeht jedes andere Flag.
  2. preferSelfHost: true UND selfHostEnabled: true UND nicht im Netzwerkmodus — Selbst-Hosting mit drei Plausibilitätsprüfungen versuchen (siehe unten). Bestehen alle, auf Selbst-Hosting festlegen. Schlägt eine fehl, auf den Remote-Pfad zurückfallen.
  3. Andernfalls — das Paket auf https://magmaguy.com/rsp/ hochladen und diese URL ankündigen. Wenn der Upload fehlschlägt oder die SHA1-Prüfung SESSION_NOT_FOUND meldet, auf Selbst-Hosting zurückfallen (sofern selfHostEnabled: true).

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​

Wenn preferSelfHost: true, führt RSPM diese Prüfungen der Reihe nach aus, bevor es sich auf Selbst-Hosting festlegt:

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

Wenn der aufgelöste Host (siehe „Erkennung des externen Hosts" unten) RFC1918 (10.*, 172.16-31.*, 192.168.*), Loopback (127.*), Link-Local (169.254.*) oder unspezifiziert (0.0.0.0) ist, kann Selbst-Hosting für Internet-Clients unmöglich funktionieren. Sofort überspringen und Remote-Hosting verwenden.

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

Ebene 2 — Localhost-Selbsttest​

Eine HEAD-Anfrage an http://127.0.0.1:<port>/rspm.zip öffnen, HTTP 200 und einen nicht leeren Body verifizieren. Fängt ab:

  • 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)
  • Fehler bei der Routen-Registrierung

Läuft aggressiv ab (3 s), damit ein langsamer Test das Booten nicht in die Länge zieht.

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 Aussichtspunkt 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 → externe Clients können unsere URL erreichen. Auf Selbst-Hosting festlegen.
  • reachable=false → externe Clients können es nicht. Selbst-Hosting abbauen und Remote-Hosting verwenden (das von magmaguy.com aus universell erreichbar ist).
  • die Test-Kommunikation selbst schlägt fehl (IOException) → konnte in keine Richtung verifiziert werden. Standardmäßig Selbst-Hosting beibehalten: Eine Ablehnung wegen Unfähigkeit zu testen wäre paradox, weil der Remote-Pfad ebenfalls magmaguy.com benötigt.

Was die Prüfungen weiterhin nicht erkennen​

Der NAT-Hairpin-Sonderfall, bei dem der Port zum öffentlichen Internet offen ist (Ebene 3 besteht), aber der eigene Router des Betreibers den Verkehr von innerhalb des LANs nicht zurückschleift. Externe Clients funktionieren, aber der Betreiber, der vom selben Rechner aus testet, scheitert.

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 (beliebige positive Ganzzahl) oder -1 (Standard) für die automatische Ableitung.
  • 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

Das staffelt die HTTP-Ports über die Backends in einem Single-Host-Netzwerk automatisch, ohne jegliche Admin-Konfiguration — jedes Backend hat bereits einen eindeutigen MC-Port, also erhält jedes einen eindeutigen HTTP-Port.

Warum Offset 1?​

Die meisten Shared-/Managed-Minecraft-Hostings (Pterodactyl-basierte Panels usw.) weisen pro Container einen schmalen Port-Bereich zu (oft nur 4–10 Ports). Größere Offsets landen außerhalb des Bereichs, und die Host-Firewall blockiert den HTTP-Port stillschweigend. Offset 1 passt selbst in enge Zuweisungen.

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 buchstäblich networkHttpOffset-v2. Der v1-Schlüssel hieß networkHttpOffset mit Standard 100 — dieser Standard ging auf Shared-/Managed-Hosting kaputt, wo jeder Spiel-Container nur ~4–10 aufeinanderfolgende Ports erhält, MC + 100 fiel aus dem Bereich, der HTTP-Server band intern, aber die Host-Firewall verwarf externen Verkehr, und der Proxy bekam für immer ein stilles CONNECT_FAILED. v2 wird mit Standard 1 ausgeliefert, sodass MC + 1 selbst innerhalb der engsten Container-Zuweisungen gut liegt.

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​

# 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 any positive value 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: ""

# 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​

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 Plausibilitätsprüfungen sind keine Warnungen. Ein fehlgeschlagener Test ist ein Zustand, von dem sich RSPM selbst erholt, und wird daher als Detail protokolliert, nicht als Fehler, wobei jede Meldung das ausdrücklich sagt (Self-host check: local pack link is not public. This is OK.). Du siehst sie nicht, außer du fragst danach — eine Warnung über etwas, das das Plugin bereits behandelt hat, wirkt wie ein Fehler und schickt Betreiber auf die Jagd nach einem Nicht-Problem.

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-/Waterfall-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 Routen für das Paket und die Bedrock-Artefakte sind dateigestützt: Jede Route liest ihre Datei bei jeder Anfrage frisch ein, sodass ein erneuter Mix, der denselben Pfad neu schreibt, automatisch erkannt wird, ohne den HTTP-Server neu zu starten. Die Bedrock-Routen verwenden starke ETags und unterstützen zur Kompatibilität außerdem If-Modified-Since, sodass unveränderte Proxy-Polls ein 304 mit nahezu null Bandbreite erhalten. Diese Routen geben sauber 404 zurück, wenn die zugrunde liegende Datei fehlt (z. B. bevor der erste Mix abgeschlossen ist). 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.

Verifizieren, dass 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​

  • Dem Test von Ebene 3 mit einem Router mit defektem Hairpin vertrauen — der Test läuft vom Aussichtspunkt von magmaguy.com aus, kann also den Fall nicht abfangen, in dem externe Clients funktionieren, das eigene LAN des Betreibers aber nicht zurückschleift. Teste von einem Handy im Mobilfunknetz, wenn du unsicher bist.
  • 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.