Saltar para o conteúdo principal

Alojamento próprio do pacote de recursos

O ResourcePackManager inclui um pequeno servidor HTTP. Com autoHost: true e preferSelfHost: true, ambos predefinidos, tenta alojar o pacote combinado na mesma JVM do servidor Minecraft, sem serviço externo, servidor web separado ou introdução manual do URL.

Esta página explica a escolha da via de entrega, as verificações, a porta, o endereço público e as opções para instalações que precisam de ajustes.

Para colocar um proxy inverso HTTPS à frente do RSPM e manter a entrega automática, use selfHostExternalUrl, conforme descrito abaixo. Use autoHost: false apenas quando outro sistema gerir tanto o alojamento como a entrega aos jogadores.

Decisão da via de entrega​

Quando um jogador entra, o RSPM escolhe um URL com a seguinte precedência. A entrega automática normal exige autoHost: true. Com autoHost: false, só a opção explícita selfHostForce: true envia um URL.

  1. selfHostForce: true: usa diretamente o alojamento próprio, sem verificações nem envio remoto. Destina-se sobretudo a testar esta via. Sobrepõe-se a autoHost e selfHostEnabled; a validação do URL e o arranque do serviço HTTP têm de continuar a funcionar.
  2. preferSelfHost: true e selfHostEnabled: true: tenta o alojamento próprio com as verificações abaixo, incluindo nos backends de proxy. Se alguma falhar, recorre ao alojamento remoto.
  3. Caso contrário: reutiliza ou envia o pacote para https://magmaguy.com/rsp/ e anuncia esse URL. Se a inicialização, a verificação SHA1 ou o envio falhar, tenta alojamento próprio verificado, desde que selfHostEnabled: true. SESSION_NOT_FOUND também limpa a sessão remota para permitir nova inicialização numa tentativa posterior. Esta alternativa automática executa as mesmas verificações do alojamento próprio preferencial; se ambas as vias falharem, não é anunciado um novo URL de entrega.

O alojamento remoto aceita pacotes Java até 50 000 KiB (51 200 000 bytes). O RSPM verifica o tamanho antes de enviar. Um pacote maior nunca é enviado: a consola apresenta Automatic hosting skipped: resource pack is <size> bytes; the limit is 51200000 bytes. O RSPM deixa então de usar o alojamento remoto para esse pacote e continua a tentar o alojamento próprio verificado (com selfHostEnabled: true) até o alojamento recomeçar para um novo pacote ou após um recarregamento. Reduza o tamanho do pacote ou torne o alojamento próprio acessível e depois execute /rspm reload.

Depois de obter um URL, usa a API de múltiplos pacotes do Minecraft, permitindo que o seu pacote Java coexista com outros enviados pelo servidor. O descritor Bukkit atual exige Minecraft 1.21.4 ou posterior.

As três verificações​

O RSPM verifica estas condições por ordem antes de escolher alojamento próprio automático, incluindo como alternativa após uma falha de alojamento remoto. Só selfHostForce: true as ignora.

Camada 1: verificação do endereço externo resolvido​

Se o endereço resolvido, conforme a deteção descrita abaixo, pertencer a RFC1918 (10.*, 172.16-31.*, 192.168.*), loopback (127.* ou localhost), ligação local (169.254.*) ou for não especificado (0.0.0.0), o alojamento próprio é descartado. Também são rejeitados endereços IPv6 não especificados, loopback, link-local, site-local e unique-local. Esta heurística examina o texto do endereço; um nome de servidor continua a precisar das verificações de transferência seguintes.

Isto deteta o caso comum em que a consulta ao ipify falha e a deteção recorre ao IP da rede local.

Camada 2: transferências locais e do URL anunciado​

O RSPM envia um pedido GET com um intervalo de bytes primeiro para http://127.0.0.1:<port>/rspm.zip e depois para o URL exato que os jogadores receberiam. Compara até ao primeiro KiB com o pacote local. Aceita HTTP 200 ou 206; os comprimentos indicados têm de coincidir e uma resposta 206 tem de incluir o Content-Range esperado. Rejeita redirecionamentos. Deteta:

  • Conflitos de porta, quando outro serviço ocupa a porta escolhida.
  • Ausência do pacote, quando a rota está registada mas o ZIP ainda não existe.
  • Rotas incorretas, páginas de erro HTML ou bytes de outro pacote.
  • Um URL anunciado que o próprio servidor não consegue transferir, incluindo falhas de NAT loopback.

Cada ligação e leitura tem um limite de 3 s, com um prazo separado de 3 s para ler a amostra. São verificações de amostras limitadas, não transferências completas pelo cliente.

Camada 3: acessibilidade externa​

O URL anunciado é enviado a POST /rsp/probe no serviço de alojamento magmaguy.com. Este tenta obter o URL a partir de uma localização pública, com proteções contra SSRF e um limite de tempo curto, e devolve o resultado.

Deteta um problema comum: o servidor tem IP público, mas a porta HTTP não está encaminhada no router ou firewall. A verificação local passa, mas os clientes externos não conseguem transferir o pacote.

Decisões conforme o resultado:

  • reachable=true com HTTP 200 ou 206: a verificação conseguiu aceder ao URL a partir da sua localização pública. O RSPM usa alojamento próprio.
  • reachable=false ou outro estado HTTP: a verificação falhou. O RSPM retira o URL Java candidato e tenta alojamento remoto em magmaguy.com. Em modo de rede, mantém o serviço HTTP do backend disponível para as consultas de artefactos pelo proxy.
  • Falha de comunicação da verificação, IOException, ou cliente de verificação indisponível: a acessibilidade não foi verificada. O RSPM tenta alojamento remoto; não conseguir contactar a verificação não demonstra que o envio vá falhar. A alternativa automática não pode ignorar esta verificação.

Limitações das verificações​

A transferência do URL anunciado já deteta falhas de NAT loopback a partir da rede do próprio servidor. Não demonstra a acessibilidade a partir da rede de cada jogador nem o sucesso de uma transferência completa pelo cliente Minecraft. Verifique a transferência completa e a aceitação do pacote com um cliente real; use uma rede externa separada ao verificar o acesso público.

Para um teste rápido nessa máquina, use preferSelfHost: false e o alojamento remoto, ou teste o URL público a partir de dados móveis ou outra rede externa. Para uma solução permanente, use DNS com respostas diferentes dentro e fora da rede, fazendo o mesmo nome público resolver para o IP local no interior da rede. Não defina selfHostExternalHost como 127.0.0.1: os endereços privados e loopback são rejeitados pela verificação pública e não servem clientes externos.

Resolução da porta​

Duas definições interagem:

  • selfHostPort: porta explícita entre 1 e 65535, ou -1, predefinido, para cálculo automático. A porta calculada também tem de ficar nesse intervalo; outros valores impedem o arranque do serviço HTTP.
  • networkHttpOffset-v2: só é consultado com selfHostPort = -1. É somado à porta Minecraft para obter a porta HTTP; o valor predefinido é 1. Numa rede, também serve de estimativa de recurso do proxy para a porta HTTP do backend.

Com selfHostPort: -1 e networkHttpOffset-v2: 1:

  • Minecraft 25565 dá HTTP 25566.
  • Minecraft 25584 dá HTTP 25585.

Portas Minecraft diferentes produzem portas HTTP calculadas diferentes. Contudo, uma porta calculada pode coincidir com a porta Minecraft de outro backend ou com outro serviço. Verifique todos os serviços em escuta e as portas atribuídas pelo fornecedor.

Porquê um desvio de 1?​

O alojamento partilhado ou gerido pode atribuir poucas portas a cada contentor. Um desvio de 1 mantém a porta HTTP perto da porta do jogo, mas não a reserva nem garante que esteja atribuída ou aberta. Confirme a porta exata no painel de alojamento.

Os administradores com controlo total das portas podem escolher outro valor. Numa rede, o backend anuncia automaticamente ao proxy a porta HTTP real, mesmo que altere o desvio ou defina selfHostPort explicitamente. Ajustar network-http-offset-v2 no proxy só interessa como alternativa durante o período anterior ao anúncio ou se o anúncio não chegar.

Conflitos com RCON​

Se o fornecedor ativar RCON na porta Minecraft mais 1, escolha um desvio de 2 ou 3. Consulte rcon.port= em server.properties.

Chave de configuração versionada​

A chave em config.yml chama-se exatamente networkHttpOffset-v2. A antiga networkHttpOffset usava 100 por predefinição, podendo colocar o serviço fora das portas atribuídas. A versão v2 usa 1; essa porta continua a precisar de estar disponível e acessível.

Ao atualizar da v1, a chave antiga permanece inofensiva até a remover manualmente. O RSPM não a lê.

Deteção do endereço externo​

selfHostExternalHost controla o nome ou IP que os clientes veem no URL. Deixe vazio para deteção automática, pela seguinte ordem:

  1. api.ipify.org / checkip.amazonaws.com: devolvem o IPv4 público da máquina. O resultado é guardado uma vez por /rspm reload, evitando consultas excessivas.
  2. Bukkit.getIp(): endereço de escuta do servidor, se não estiver vazio nem for 0.0.0.0. Normalmente é um endereço local.
  3. InetAddress.getLocalHost(): tenta obter o endereço local.
  4. localhost: último recurso, inacessível a clientes fora da máquina.

Se a deteção escolher um endereço não encaminhável e preferSelfHost: true, a primeira verificação falha e o plugin usa alojamento remoto.

Para uma configuração mais previsível, defina selfHostExternalHost com o nome público, por exemplo play.example.com. Isto ignora a deteção ipify/AWS e verifica diretamente o valor indicado.

Referência de configuração​

HTTPS e proxies inversos​

Defina selfHostExternalUrl com o URL público completo de transferência:

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

Configure o proxy inverso para terminar o TLS e encaminhar esse caminho público para http://<server>:25566/rspm.zip. O RSPM continua a escutar HTTP. Esta definição não instala certificados nem configura o servidor web.

O URL exato é enviado aos jogadores Java e usado pela verificação externa. Não é acrescentado /rspm.zip. Sobrepõe-se a selfHostExternalHost e à deteção de IP público na entrega Java; selfHostPort continua a controlar a porta interna. As consultas do proxy aos recursos Bedrock continuam a usar o endereço HTTP do backend.

Só são aceites URLs HTTP ou HTTPS completos, com nome de servidor, sem credenciais incorporadas nem fragmentos. Uma porta explícita no URL tem de ficar entre 1 e 65535. Um URL inválido impede o alojamento próprio. O alojamento automático normal pode recorrer ao serviço remoto; o alojamento próprio forçado não pode. Deixe vazio para usar a deteção de endereço e porta.

Definições​

# 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

Mensagens da consola​

As falhas do alojamento Java remoto e do relay Bedrock usam esperas exponenciais com variação aleatória. Cada fluxo permite uma tentativa ativa e até cinco repetições; depois espera 15–30 minutos antes de iniciar outra série. O sucesso reinicia este limite e o cliente HTTP não acrescenta repetições automáticas. O alojamento Java verifica o SHA-1 remoto antes do envio. As repetições Bedrock reutilizam, durante até 20 minutos, os ficheiros sem alterações que já foram enviados com sucesso. A renovação habitual do relay a cada 25 minutos continua a enviar os ficheiros para prolongar a validade no servidor.

Num arranque normal, o RSPM apresenta uma linha com o resultado do alojamento:

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

Ou, se usar alojamento remoto:

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

A linha aparece uma vez por inicialização de uma via de entrega, sem se repetir nas tentativas dos jogadores ou nos ciclos de manutenção. Um recarregamento sem alterações ao pacote pode reutilizar o alojamento existente, sem anunciar outro resultado.

As falhas de acessibilidade são registadas ao nível de detalhe. Por exemplo: Self-host check: local pack link is not public. This is OK. As verificações do endereço e de localhost terminam com This is OK.; a transferência do URL anunciado e a verificação externa comunicam a falha sem esse sufixo. Um URL inválido, uma falha ao iniciar o serviço HTTP ou uma falha de comunicação remota podem continuar a gerar avisos. Uma verificação falhada não demonstra por si só que a alternativa remota funcionou; consulte o estado final da entrega.

Para ver a sequência de decisões, a verificação que falhou, o URL, o código de motivo, os pacotes preparados e os grupos combinados, execute:

/rspm verbose on

Depois execute /rspm reload. Ative esta opção antes de comunicar um problema de alojamento. O comando escreve verboseLogging: true em config.yml e mantém a escolha após reinícios. Execute /rspm verbose off quando terminar. Editar a chave manualmente produz o mesmo efeito.

verboseLogging cobre a preparação e o alojamento. O conversor Bedrock tem a opção separada bedrockConverterDebug, descrita em Conversão Bedrock.

Rotas HTTP do backend​

O servidor integrado disponibiliza o ZIP em:

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

Em modo de rede, atrás de Velocity ou BungeeCord, regista rotas adicionais para o plugin do proxy:

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)

As rotas do pacote e dos artefactos Bedrock usam ficheiros e resolvem o artefacto publicado atual em cada pedido. Uma nova combinação publicada com sucesso fica disponível sem reiniciar o servidor HTTP; substituir um ficheiro no disco não o autoriza por si só. As rotas devolvem 404 se não existir um artefacto atual autorizado, se faltar o ficheiro ou se os seus bytes já não corresponderem ao resumo da publicação. As rotas Bedrock também exigem que a conversão continue ativa. Os ETags fortes suportam If-None-Match, que tem prioridade sobre a verificação de compatibilidade If-Modified-Since; consultas sem alterações podem receber um 304 sem corpo. A rota de atualização tem proteção separada por token bearer derivado da chave partilhada da rede e só está disponível quando pode fornecer um JAR de atualização válido.

Confirmar o alojamento próprio​

/rspm status apresenta:

  • Active delivery: SELF-HOSTED: alojamento próprio em utilização.
  • Active delivery: REMOTE (magmaguy.com): alojamento remoto automático em utilização.
  • URL: ...: URL real apresentado aos clientes.
  • Resolved external host: resultado de selfHostExternalHost.
  • Public IP (auto-detected): resultado de ipify/AWS, se existir.
  • selfHostPort: seleção automática ou explícita e valor resolvido.

Se esperava alojamento próprio mas aparece remoto, consulte o estado. O registo normal omite as falhas de verificação recuperadas. Execute /rspm verbose on e /rspm reload para identificar a verificação e o motivo.

Erros comuns​

  • Tratar uma verificação bem-sucedida como um teste completo do cliente. A amostra local e a verificação pública cobrem percursos de rede específicos. Verifique uma transferência completa e a aceitação do pacote com um jogador real; o alojamento próprio forçado ignora estas verificações por completo.
  • Aumentar networkHttpOffset-v2 para fora das portas atribuídas pelo fornecedor. Pode causar CONNECT_FAILED persistente no proxy. Os backends anunciam a porta real, mas o serviço precisa de conseguir escutar nela e o proxy precisa de a alcançar. Se mcPort + offset ficar fora das portas do contentor, o anúncio não resolve a falha de escuta ou firewall. Confirme a atribuição antes de aumentar o desvio.