Aller au contenu principal

Auto-hébergement du pack de ressources

ResourcePackManager embarque son propre petit serveur HTTP. Lorsque autoHost: true (par défaut) et preferSelfHost: true (par défaut), le plugin tente d'héberger le pack fusionné depuis la même JVM que le serveur Minecraft lui-même — pas d'hébergeur de fichiers externe, pas de serveur web séparé, pas de collage manuel d'URL.

Cette page explique comment fonctionne ce chemin d'auto-hébergement, ce que font les contrôles de cohérence, comment le port et le nom d'hôte sont choisis, et que configurer quand les valeurs par défaut ne conviennent pas à votre installation.

Pour placer un proxy inverse HTTPS devant RSPM tout en conservant la distribution automatique, utilisez selfHostExternalUrl comme indiqué ci-dessous. N'utilisez autoHost: false que lorsqu'un autre système prend en charge à la fois l'hébergement et la distribution aux joueurs.

Arbre de décision de distribution​

Quand un joueur se connecte, RSPM choisit une URL de distribution selon cet ordre de priorité :

La distribution automatique normale exige autoHost: true. Avec autoHost: false, seule la dérogation explicite selfHostForce: true envoie une URL.

  1. selfHostForce: true — directement vers l'auto-hébergement, sans sondes ni téléversement distant. Principalement pour tester cette voie. Remplace autoHost et selfHostEnabled ; la validation de l'URL et le démarrage du serveur HTTP doivent toujours réussir.
  2. preferSelfHost: true ET selfHostEnabled: true : essayer l’auto-hébergement avec les vérifications ci-dessous, y compris sur les backends de proxy. En cas d’échec, utiliser l’hébergement distant.
  3. Sinon — réutilise ou téléverse le pack vers https://magmaguy.com/rsp/ et annonce cette URL. Si l'initialisation, la vérification SHA1 ou le téléversement échoue, tente l'auto-hébergement vérifié (avec selfHostEnabled: true). SESSION_NOT_FOUND efface aussi la session distante pour permettre une nouvelle initialisation ultérieure. Ce repli automatique exécute les mêmes contrôles que l'auto-hébergement prioritaire ; si les deux voies échouent, aucune nouvelle URL de distribution n'est annoncée.

L'hôte distant accepte les packs Java jusqu'à 50 000 Kio (51 200 000 octets). RSPM vérifie la taille avant le téléversement. Un pack plus volumineux n'est jamais téléversé : la console affiche Automatic hosting skipped: resource pack is <size> bytes; the limit is 51200000 bytes. RSPM cesse alors d'utiliser l'hébergement distant pour ce pack et continue de retenter l'auto-hébergement vérifié (lorsque selfHostEnabled: true) jusqu'à ce que l'hébergement redémarre pour un nouveau pack ou un rechargement. Réduisez la taille du pack ou rendez l'auto-hébergement accessible, puis exécutez /rspm reload.

Une fois l'URL en main, RSPM utilise l'API multi-pack de Minecraft, de sorte que son pack Java peut coexister avec les autres packs envoyés par le serveur. Le descripteur de plugin Bukkit actuel exige Minecraft 1.21.4 ou plus récent.

Les trois contrôles de cohérence​

RSPM exécute ces contrôles dans l'ordre avant de choisir l'auto-hébergement automatique, y compris après un échec de l'hébergement distant. Seul selfHostForce: true les contourne :

Couche 1 — Contrôle heuristique sur l'hôte externe résolu​

Si l'hôte résolu (voir « Détection de l'hôte externe ») est RFC1918 (10.*, 172.16-31.*, 192.168.*), loopback (127.* ou localhost), link-local (169.254.*) ou non spécifié (0.0.0.0), l'auto-hébergement est écarté. Les adresses IPv6 non spécifiées, loopback, link-local, site-local et unique-local sont également rejetées. Cette heuristique examine le texte de l'hôte ; un nom d'hôte doit encore passer les contrôles de téléchargement ci-dessous.

Ce contrôle détecte notamment le cas courant où la recherche ipify échoue et où l'adresse du réseau local est utilisée à sa place.

Couche 2 — Téléchargements local et depuis l'URL annoncée​

RSPM envoie une requête GET avec une plage d'octets à http://127.0.0.1:<port>/rspm.zip, puis à l'URL exacte que recevraient les joueurs. Il compare jusqu'au premier Kio au pack local. HTTP 200 ou 206 est accepté ; les longueurs indiquées doivent correspondre et une réponse 206 doit contenir le Content-Range attendu. Les redirections sont rejetées. Cela détecte :

  • les collisions de liaison de port (autre chose tourne sur le port choisi)
  • le fichier de pack manquant (la route est enregistrée mais le zip n'est pas encore sur le disque)
  • les routes incorrectes, pages d'erreur HTML ou octets d'un autre pack
  • une URL annoncée que le serveur lui-même ne peut pas télécharger, notamment en cas de NAT loopback défaillant

Chaque connexion et lecture a un délai de 3 s, avec une limite distincte de 3 s pour lire l'échantillon. Ces contrôles portent sur des échantillons limités, pas sur des téléchargements complets par un client.

Couche 3 — Sonde d'accessibilité externe​

L'URL annoncée est envoyée à POST /rsp/probe sur l'hébergeur magmaguy.com. Celui-ci essaie d'y accéder depuis un point d'observation public, avec des protections SSRF et un délai court, puis indique si elle est joignable.

Attrape le mode d'échec en production le plus courant : le serveur a une IP publique mais le port HTTP n'est pas redirigé au niveau du routeur ou du pare-feu. La couche 2 passe (le serveur répond sur 127.0.0.1), mais aucun vrai client ne pourrait jamais télécharger le pack.

Politique de décision sur les résultats de sonde :

  • reachable=true avec HTTP 200 ou 206 → la sonde a atteint l'URL depuis son point d'observation public. L'auto-hébergement est retenu.
  • reachable=false ou un autre statut HTTP → la vérification échoue. L'URL Java candidate est retirée et l'hébergement distant via magmaguy.com est essayé. En mode réseau, le serveur HTTP du backend reste disponible pour les interrogations d'artefacts par le proxy.
  • la communication de la sonde échoue (IOException), ou son client est indisponible → l'accessibilité n'est pas vérifiée. L'hébergement distant est essayé ; l'impossibilité de contacter la sonde ne prouve pas que le téléversement échouera. Le repli automatique ne peut pas contourner ce contrôle.

Limites de ces contrôles​

Le téléchargement depuis l'URL annoncée détecte désormais les défaillances de NAT loopback depuis le réseau du serveur. Il ne prouve ni l'accessibilité depuis le réseau de chaque joueur ni la réussite d'un téléchargement complet par Minecraft. Vérifiez le téléchargement complet et l'acceptation du pack avec un vrai client ; utilisez un réseau externe distinct pour vérifier l'accès public.

Pour un test rapide depuis la machine hôte, définissez preferSelfHost: false et utilisez le repli distant, ou testez l'URL publique depuis un réseau cellulaire/externe. Pour une installation auto-hébergée permanente, utilisez un DNS à horizon partagé (le même nom d'hôte public se résout vers l'adresse LAN du serveur à l'intérieur de votre réseau). Ne définissez pas selfHostExternalHost sur 127.0.0.1 : les hôtes loopback et privés sont rejetés par le contrôle de cohérence de l'hôte public et ne peuvent pas servir des clients externes.

Résolution du port​

Deux paramètres interagissent :

  • selfHostPort — port explicite entre 1 et 65535, ou -1 (par défaut) pour le calcul automatique. Le port calculé doit également rester dans cette plage ; les autres valeurs empêchent le serveur HTTP de démarrer.
  • networkHttpOffset-v2 — consulté uniquement quand selfHostPort = -1. Ajouté au port du serveur Minecraft pour dériver le port HTTP. Par défaut 1. (Sur les réseaux proxy, cette même valeur est aussi l'estimation de repli du proxy pour le port HTTP d'un backend — voir ci-dessous.)

La valeur par défaut est selfHostPort: -1 + networkHttpOffset-v2: 1, donc :

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

Des ports Minecraft distincts donnent des ports HTTP calculés distincts, mais l'un de ces ports peut encore entrer en conflit avec le port Minecraft d'un autre backend ou avec un autre service. Vérifiez tous les services en écoute et les ports alloués par votre hébergeur.

Pourquoi un décalage de 1 ?​

Les hébergements mutualisés ou gérés peuvent n'allouer qu'un petit ensemble de ports à chaque conteneur. Un décalage de 1 garde le port calculé proche du port de jeu, mais ne le réserve pas et ne garantit ni son attribution ni son ouverture par l'hébergeur. Confirmez le port HTTP exact dans votre panneau d'administration.

Les administrateurs en auto-hébergement avec un contrôle total des ports peuvent l'augmenter à n'importe quelle valeur. Sur un réseau proxy, le backend annonce automatiquement au proxy le port HTTP exact auquel il s'est lié, donc le proxy suit même si vous changez l'offset ou définissez un selfHostPort explicite. Augmenter le network-http-offset-v2 du proxy pour correspondre ne compte que comme repli pour la brève fenêtre avant qu'un backend ait annoncé (ou si l'annonce ne peut pas atteindre le proxy).

Attention : collision avec RCON​

Si votre hébergeur active RCON par défaut sur MC port + 1, choisissez un offset de 2 ou 3 pour éviter une collision de port. Vérifiez rcon.port= dans server.properties.

Clé de configuration versionnée​

Le paramètre de config.yml se nomme exactement networkHttpOffset-v2. La clé v1 était networkHttpOffset, avec une valeur par défaut de 100, ce qui pouvait placer le port d'écoute en dehors de l'allocation de l'hébergeur. La valeur par défaut v2 est 1 ; ce port doit toujours être disponible et joignable.

Si vous mettez à niveau depuis v1, la clé v1 morte reste dans votre configuration comme un artefact inoffensif jusqu'à ce que vous la nettoyiez — RSPM ne la lit délibérément pas.

Détection de l'hôte externe​

selfHostExternalHost contrôle le nom d'hôte que les clients voient dans l'URL. Laissez vide (par défaut) pour une auto-détection dans cet ordre de priorité :

  1. api.ipify.org / checkip.amazonaws.com — renvoie l'IPv4 publique de cet hôte. Mis en cache une fois par /rspm reload afin de ne pas marteler les services d'IP.
  2. Bukkit.getIp() — l'adresse de liaison du serveur, quand non vide et différente de 0.0.0.0. Habituellement une adresse LAN.
  3. InetAddress.getLocalHost() — meilleur effort.
  4. localhost — repli de dernier recours. Les clients en dehors de la machine ne pourront pas l'atteindre.

Si l'auto-détection aboutit à une adresse non routable et que preferSelfHost: true, le contrôle heuristique de la couche 1 échoue et le plugin bascule sur l'hébergement distant.

Pour l'installation d'auto-hébergement la plus fiable, définissez explicitement selfHostExternalHost sur votre nom d'hôte public (par exemple play.example.com). Cela contourne entièrement la détection ipify/AWS et la sonde s'exécute contre la valeur explicite.

Référence de configuration​

HTTPS et proxies inverses​

Définissez selfHostExternalUrl avec l'URL publique complète de téléchargement :

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

Configurez votre proxy inverse pour transmettre ce chemin public à la route interne http://<server>:25566/rspm.zip de RSPM et gérer la terminaison TLS. RSPM continue d'écouter en HTTP ; ce réglage n'installe aucun certificat et ne configure pas votre serveur web.

Cette URL exacte est envoyée aux joueurs Java et utilisée par la sonde d'accessibilité externe. Aucun suffixe /rspm.zip n'est ajouté. Elle remplace selfHostExternalHost et la détection d'IP publique pour la distribution Java ; selfHostPort continue de contrôler le port d'écoute interne. Le proxy récupère toujours les ressources Bedrock depuis le point d'accès HTTP du backend.

Seules les URL HTTP ou HTTPS complètes avec un hôte, sans identifiants intégrés ni fragment, sont acceptées. Un port explicite dans l'URL doit être compris entre 1 et 65535. Une URL invalide empêche l'auto-hébergement. L'hébergement automatique normal peut utiliser l'hébergement distant de secours ; l'auto-hébergement forcé ne le peut pas. Laissez ce réglage vide pour utiliser la détection d'hôte et de port.

Réglages​

# 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

Ce que la console affiche réellement​

Les échecs de l'hébergement Java distant et du relais Bedrock entraînent des délais exponentiels avec une variation aléatoire. Chaque processus autorise une tentative active et jusqu'à cinq nouvelles tentatives, puis attend 15 à 30 minutes avant une nouvelle série. Une réussite réinitialise ce quota ; le client HTTP n'ajoute aucune tentative automatique. L'hébergement Java vérifie le SHA-1 distant avant l'envoi. Les nouvelles tentatives Bedrock réutilisent pendant 20 minutes au maximum les fichiers inchangés déjà envoyés avec succès. Le renouvellement habituel du relais toutes les 25 minutes envoie toujours les fichiers pour prolonger leur validité sur le serveur.

RSPM affiche délibérément une seule ligne concernant l'hébergement lors d'un démarrage normal — le résultat, pas le parcours :

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

ou, lorsque le chemin distant l'a emporté :

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

Cette ligne s'affiche une fois à chaque initialisation neuve d'un chemin de distribution, et non à chaque nouvelle tentative d'un joueur ou à chaque tic de keep-alive. Un rechargement dont le pack est inchangé peut réutiliser l'enregistrement d'hébergement existant au lieu d'afficher un nouveau résultat.

Les échecs des contrôles d'accessibilité sont journalisés au niveau détail. Par exemple : Self-host check: local pack link is not public. This is OK. Les contrôles de l'hôte et de localhost se terminent par This is OK. ; le téléchargement depuis l'URL annoncée et la vérification externe signalent leur échec sans ce suffixe. Une URL invalide, un échec du démarrage HTTP ou de communication distante peut toujours produire des avertissements. Un contrôle échoué ne prouve pas à lui seul la réussite du repli distant ; vérifiez l'état final de distribution.

Pour voir toute la chaîne de décision — quel contrôle a échoué, l'URL de la sonde, le code de raison, chaque pack préparé et chaque cluster fusionné — exécutez :

/rspm verbose on

Puis /rspm reload. C'est l'interrupteur à activer avant d'ouvrir un rapport de bogue sur l'hébergement. La commande écrit verboseLogging: true dans config.yml et le réglage persiste entre les redémarrages : exécutez donc /rspm verbose off quand vous avez terminé. Éditer la clé de configuration à la main a exactement le même effet.

Notez que verboseLogging couvre la préparation du pack et l'hébergement. Le convertisseur Bedrock possède son propre interrupteur distinct, bedrockConverterDebug — voir Conversion Bedrock.

Routes du serveur HTTP backend​

Le serveur HTTP intégré sert toujours le zip du pack à :

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

En mode réseau (RSPM est derrière un proxy Velocity / BungeeCord), des routes supplémentaires sont enregistrées pour que le plugin proxy les récupère :

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)

Les routes du pack et des artefacts Bedrock reposent sur des fichiers et déterminent l'artefact publié actuel à chaque requête. Un nouveau mix publié avec succès devient disponible sans redémarrer le serveur HTTP ; remplacer simplement un fichier sur disque ne l'autorise pas. Les routes renvoient 404 en l'absence d'artefact actuel autorisé, si le fichier manque ou si ses octets ne correspondent plus à l'empreinte de publication. Les routes Bedrock exigent aussi que la conversion reste activée. Les ETags forts prennent en charge If-None-Match, prioritaire sur le contrôle de compatibilité If-Modified-Since ; les interrogations sans changement peuvent recevoir un 304 sans corps. La route de mise à jour est protégée séparément par un jeton bearer dérivé de la clé réseau partagée et n'est disponible que lorsqu'un jar de mise à jour valide peut être proposé.

Vérifier que l'auto-hébergement est actif​

/rspm status affiche :

  • Active delivery: SELF-HOSTED — l'auto-hébergement est utilisé
  • Active delivery: REMOTE (magmaguy.com) — l'hébergement automatique distant est utilisé
  • URL: ... — l'URL réelle que les clients verront
  • Resolved external host — ce vers quoi selfHostExternalHost a été résolu
  • Public IP (auto-detected) — ce qu'ipify/AWS a rapporté, s'il y a quelque chose
  • selfHostPort — auto vs explicite, et la valeur résolue

Si vous attendiez l'auto-hébergement mais voyez le distant, /rspm status est l'endroit où regarder — le log de démarrage reste silencieux à propos des échecs de sonde qu'il corrige lui-même, par conception. Exécutez /rspm verbose on puis /rspm reload pour voir quel contrôle de cohérence a échoué et pourquoi.

Erreurs courantes​

  • Assimiler une sonde réussie à un test client complet — l'échantillon local et la sonde publique couvrent certains chemins réseau. Vérifiez un téléchargement complet et l'acceptation du pack avec un vrai joueur ; l'auto-hébergement forcé ignore entièrement ces contrôles.
  • Augmenter networkHttpOffset-v2 au-delà de la plage de ports de votre hébergeur — le symptôme est un CONNECT_FAILED silencieux à vie du côté du proxy. Les backends annoncent au proxy le vrai port auquel ils se sont liés, mais le serveur HTTP doit quand même se lier à un port joignable et le proxy doit quand même pouvoir l'atteindre ; si mcPort + offset tombe en dehors de la bande de ports allouée à votre conteneur, la liaison/le pare-feu échoue indépendamment de l'annonce. Vérifiez que le port est dans la bande allouée à votre conteneur avant d'augmenter l'offset.