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.

Si vous préférez héberger le zip via votre propre serveur web existant en dehors de RSPM, voyez la section sur autoHost: false de la page de dépannage.

Arbre de décision de livraison​

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

  1. selfHostForce: true — directement vers l'auto-hébergement, sans sondes, sans téléversement distant. Principalement pour tester le chemin d'auto-hébergement. Contourne tous les autres drapeaux.
  2. preferSelfHost: true ET selfHostEnabled: true ET hors mode réseau — essaie l'auto-hébergement avec trois contrôles de cohérence (voir ci-dessous). Si tous passent, s'engage sur l'auto-hébergement. Si l'un échoue, repli sur le chemin distant.
  3. Sinon — téléverse le pack vers https://magmaguy.com/rsp/ et annonce cette URL. Si le téléversement échoue ou que la vérification SHA1 signale SESSION_NOT_FOUND, repli sur l'auto-hébergement (en supposant selfHostEnabled: true).

Une fois l'URL en main, RSPM utilise l'API multi-pack de Minecraft sur 1.20.3+ (afin de coexister avec d'autres packs envoyés par le serveur) et l'ancienne méthode mono-pack sur les versions plus anciennes.

Les trois contrôles de cohérence​

Quand preferSelfHost: true, RSPM exécute ces contrôles dans l'ordre avant de s'engager sur l'auto-hébergement :

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 » ci-dessous) est RFC1918 (10.*, 172.16-31.*, 192.168.*), loopback (127.*), link-local (169.254.*), ou non spécifié (0.0.0.0), l'auto-hébergement ne peut pas fonctionner pour les clients sur internet. Sauter immédiatement et utiliser l'hébergement distant.

Cela attrape le mode d'échec très courant « la recherche ipify a échoué, repli sur l'IP du LAN ».

Couche 2 — Auto-sonde localhost​

Ouvre une requête HEAD vers http://127.0.0.1:<port>/rspm.zip, vérifie HTTP 200 et un corps non vide. Attrape :

  • 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 bugs d'enregistrement de route

Le délai d'attente est agressif (3 s) afin qu'une sonde lente ne puisse pas faire traîner le démarrage.

Couche 3 — Sonde d'accessibilité externe​

POST l'URL annoncée vers POST /rsp/probe sur l'hébergeur magmaguy.com. L'hébergeur récupère l'URL depuis un point d'observation public (avec des protections SSRF et un délai serré) et rapporte 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 → les clients externes peuvent atteindre notre URL. S'engager sur l'auto-hébergement.
  • reachable=false → les clients externes ne peuvent pas. Démonter l'auto-hébergement et utiliser l'hébergement distant (qui est universellement joignable depuis magmaguy.com).
  • la communication de la sonde elle-même échoue (IOException) → impossible de vérifier dans un sens ou dans l'autre. Par défaut, conserver l'auto-hébergement : refuser en raison de l'incapacité à sonder serait paradoxal puisque le chemin distant a aussi besoin de magmaguy.com.

Ce que les contrôles ne détectent toujours pas​

Le cas limite NAT-hairpin où le port est ouvert sur l'internet public (la couche 3 passe) mais où le propre routeur de l'opérateur ne fait pas boucler le trafic depuis l'intérieur du LAN. Les clients externes fonctionnent, mais l'opérateur qui teste depuis la même machine échoue.

Solution de contournement pour l'instant : lors des tests depuis la machine hôte avec un routeur sans hairpin fonctionnel, définissez preferSelfHost: false OU selfHostExternalHost: 127.0.0.1.

Résolution du port​

Deux paramètres interagissent :

  • selfHostPort — port explicite (tout entier positif) ou -1 (par défaut) pour l'auto-dérivation.
  • networkHttpOffset-v2 — consulté uniquement quand selfHostPort = -1. Ajouté au port du serveur Minecraft. Par défaut 1.

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

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

Cela décale automatiquement les ports HTTP entre les backends d'un réseau mono-hôte sans aucune configuration de l'administrateur — chaque backend a déjà un port MC unique, donc chacun obtient un port HTTP unique.

Pourquoi un offset de 1 ?​

La plupart des hébergements Minecraft mutualisés / managés (panels basés sur Pterodactyl, etc.) allouent une plage de ports étroite par conteneur (souvent seulement 4 à 10 ports). Les offsets plus larges tombent en dehors de la plage et le pare-feu de l'hôte bloque silencieusement le port HTTP. L'offset 1 tient même dans les allocations serrées.

Les administrateurs en auto-hébergement avec un contrôle total des ports peuvent l'augmenter à n'importe quelle valeur, mais si vous exploitez un réseau proxy, vous devez également augmenter le network-http-offset-v2 du proxy pour correspondre.

Attention : collision avec RCON​

Si votre hébergeur active RCON par défaut sur port MC + 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 dans config.yml est littéralement nommé networkHttpOffset-v2. La clé v1 était networkHttpOffset avec une valeur par défaut de 100 — cette valeur par défaut cassait sur les hébergements mutualisés / managés où chaque conteneur de jeu ne reçoit que ~4 à 10 ports consécutifs, MC + 100 tombait hors plage, le serveur HTTP se liait en interne mais le pare-feu de l'hôte rejetait le trafic externe, et le proxy obtenait un CONNECT_FAILED silencieux à vie. La v2 est livrée avec la valeur par défaut 1 afin que MC + 1 reste bien à l'intérieur même des allocations de conteneurs les plus étroites.

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​

# Whether the built-in HTTP server may be used as a delivery path at all.
# When false, self-host is never attempted regardless of the other flags.
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). Must match the proxy's network-http-offset-v2
# in proxy networks.
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

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 / Waterfall), deux 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

Les trois routes sont basées sur des fichiers : la route lit le fichier à chaud à chaque requête, donc un re-mix qui réécrit le même chemin de zip est repris automatiquement sans redémarrer le serveur HTTP. Les routes Bedrock prennent en charge If-Modified-Since afin que le poller du proxy paie quasiment zéro bande passante quand rien n'a changé. Toutes les routes renvoient proprement 404 quand le fichier sous-jacent est absent (par exemple avant la fin du premier mix).

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'auto-hébergement 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, le log de démarrage explique quel contrôle de cohérence a échoué et pourquoi.

Erreurs courantes​

  • Définir selfHostPort à une valeur arbitraire et l'oublier sur le proxy — en mode réseau, le proxy utilise mcPort + network-http-offset-v2 pour calculer le port HTTP de chaque backend. Un selfHostPort explicite remplace l'auto-dérivation mais le proxy ne le sait pas, donc il interrogera toujours mcPort + offset. Laissez selfHostPort: -1 en mode réseau à moins d'être prêt à coordonner.
  • Faire confiance à la sonde de couche 3 avec un routeur sans hairpin fonctionnel — la sonde s'exécute depuis le point d'observation de magmaguy.com, elle ne peut donc pas attraper le cas où les clients externes fonctionnent mais où le propre LAN de l'opérateur ne fait pas boucler le trafic. Testez depuis un téléphone en réseau cellulaire si vous avez un doute.
  • 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. Vérifiez que mcPort + offset est dans la bande de ports allouée à votre conteneur avant d'augmenter l'offset.