Redes com proxy (BungeeCord/Velocity)

O ResourcePackManager funciona em redes com proxy. Instale o mesmo ResourcePackManager.jar no proxy e em cada backend que forneça pacotes de recursos. Os restantes servidores registados podem continuar sem RSPM. Nos backends, combina, aloja, entrega e converte pacotes. Em Velocity ou BungeeCord, o JAR deteta a plataforma e assume a entrega Bedrock da rede. O proxy gere a chave de rede e envia-a a cada backend quando um jogador se liga a este pela primeira vez.

Nesta página, «plugin do proxy» refere-se ao mesmo ResourcePackManager.jar a funcionar no proxy.

Funções do plugin do proxy

A principal função é combinar e entregar os pacotes Bedrock. Cada backend produz a versão Bedrock do seu pacote Java combinado. O proxy:

1. Descobre quais dos backends registados executam RSPM e consulta esses participantes a cada 5 segundos para obter /bedrock.zip e /mappings.json. Prefere ETags fortes com If-None-Match e mantém a compatibilidade com If-Modified-Since para backends antigos. Ficheiros inalterados devolvem 304. Cada backend anuncia a porta HTTP exata que utiliza, e o proxy normalmente usa-a de forma automática. Consulte a resolução da porta HTTP do backend.
2. Espera que a pasta de entrada estabilize: duas consultas consecutivas com o mesmo conjunto de hashes permitem iniciar a combinação.
3. Combina todos os pacotes Bedrock num pacote único para a rede.
4. Quando existem mapeamentos de objetos, copia o ficheiro combinado para plugins/Geyser-*/custom_mappings/ no proxy.
5. Entrega o pacote aos clientes Bedrock à entrada através de SessionLoadResourcePacksEvent do Geyser.

A entrega Java continua a ser feita por backend através de setResourcePack ou addResourcePack. Além da combinação Bedrock, o proxy fornece as chaves de rede e propaga atualizações RSPM autenticadas. Uma rede exclusivamente Java não precisa do plugin do proxy para entregar pacotes Java.

Instalação

Floodgate

O Floodgate permite autenticar jogadores Bedrock sem uma conta paga de Java Edition. O Geyser também pode usar autenticação online com uma conta Java; siga o guia de instalação do Geyser para o modo escolhido. O RSPM pode ligar o proxy e os backends sem Floodgate.

Se o Floodgate estiver instalado no primeiro arranque do RSPM no proxy, o RSPM deriva a chave de rede de plugins/floodgate/key.pem, preservando a identidade de uma rede existente. Os arranques seguintes usam o ficheiro network-key do RSPM enquanto contiver uma chave válida. Se faltar ou for inválida, o RSPM volta a tentar derivá-la do Floodgate antes de gerar uma chave aleatória.

Copiar ResourcePackManager.jar para o proxy

O mesmo JAR usado nos backends Bukkit/Paper inclui as implementações Velocity e BungeeCord e deteta automaticamente a plataforma. Não precisa de extrair um ficheiro próprio para o proxy.

Se os backends já arrancaram sem RSPM no proxy, cada backend que detete o proxy e ainda não tenha chave prepara uma cópia byte a byte idêntica do seu JAR em plugins/ResourcePackManager/proxy-extension/ResourcePackManager.jar. A consola apresenta esse caminho. Copiar esse ficheiro instala a versão em execução nesse backend; atualize também os restantes para alinhar toda a rede.

Copie ResourcePackManager.jar para plugins/ do proxy:

Proxy	JAR
Velocity	ResourcePackManager.jar
BungeeCord	ResourcePackManager.jar

Pode confirmar num backend com /rspm status. A secção de instalação do proxy apresenta Network proxy jar: ResourcePackManager.jar e Use the same jar on Bukkit/Paper, Velocity, and BungeeCord.

Reinicie o proxy.

Não existe configuração obrigatória nem chave para introduzir. O proxy cria ou carrega a chave no arranque e fornece-a automaticamente aos backends, conforme Ligação entre proxy e backends. O config.yml gerado contém apenas duas opções facultativas, descritas abaixo.

A primeira consulta ocorre cerca de 2 segundos após o arranque e repete-se a cada 5 segundos. Com a espera de um ciclo para confirmar estabilidade, a primeira combinação fica publicada aproximadamente 7 segundos depois de o proxy conseguir ver pelo menos um backend com conteúdo pronto.

Descoberta de backends

O proxy verifica quais dos servidores registados executam RSPM sem fazer a sincronização de pacotes esperar pelos que não o utilizam. Os anúncios de endereços e o conteúdo em cache previamente validado podem identificar participantes imediatamente. Nos restantes casos, a descoberta verifica o endereço HTTP resolvido em segundo plano, com um máximo de duas verificações simultâneas e um tempo limite de cinco segundos. Os servidores não confirmados são verificados novamente após cerca de um minuto.

/rspm status mostra o número de participantes confirmados e o estado de descoberta de cada servidor restante. RSPM not confirmed significa que a descoberta ainda não estabeleceu a presença do RSPM; não prova que o plugin esteja ausente. Verifique o endereço, a porta HTTP e a acessibilidade do backend se este devesse participar. A instalação do RSPM noutro backend é descoberta automaticamente.

Depois de um backend ser confirmado, as falhas de ligação são apresentadas como falhas de atualização desse participante. O conteúdo disponível de operações concluídas é preservado, e os resultados diretos e da retransmissão continuam visíveis em /rspm status. Um contador de consultas vazias a zero significa que existe conteúdo disponível, não que todas as ligações aos backends estejam a funcionar.

A descoberta não concede acesso às atualizações. A autenticação pela chave de rede e a validação do JAR continuam a aplicar-se às atualizações automáticas do plugin.

Ligação entre proxy e backends

Esta sequência é automática. Conhecê-la ajuda a diagnosticar falhas de ligação.

1. O proxy estabelece a chave. No arranque, escolhe um valor por esta ordem:

1. O ficheiro network-key guardado na sua pasta de dados, usado normalmente depois do primeiro arranque.
2. Uma chave derivada uma única vez de plugins/floodgate/key.pem, se existir no proxy.
3. Uma chave aleatória nova.

A chave obtida é guardada em network-key e reutilizada enquanto for válida. A consola indica a origem com Network key loaded ✓, adopted from Floodgate key.pem ou New network key generated. Um ficheiro network-key mal formado é substituído. Se o RSPM não conseguir guardar uma chave nova, ou não conseguir ler um ficheiro network-key existente, a função de proxy deixa de arrancar com Could not establish persistent RSPM network identity ou Cannot read established RSPM network identity, em vez de funcionar com uma chave que poderia mudar no próximo reinício. Corrija as permissões da pasta e reinicie o proxy.

2. O proxy envia a chave a cada backend. Assim que um jogador se liga a um backend, envia a chave pelo canal de plugin rspm:network. A direção é necessária: o backend não pode pedi-la, pois o proxy não encaminha uma mensagem num canal que o cliente do jogador não registou.

3. O backend adota e guarda a chave. Escreve-a em data.yml e regista Network key received from the proxy; this backend is now linked. Só aceita a atribuição enquanto não tiver uma chave. Um backend já associado avisa e mantém a existente, impedindo que uma mensagem o redirecione para outra rede.

No Velocity com encaminhamento moderno, a atribuição é assinada com HMAC usando forwarding.secret do proxy. Um backend configurado para esse modo exige a assinatura. BungeeCord e o encaminhamento antigo não têm um segredo partilhado para assinar; as atribuições não são assinadas e são aceites dessa forma.

Um backend que recebe a mensagem mas não adota a chave mantém a origem em not set. Esse estado aciona a cópia em proxy-extension/ e o aviso específico de Bedrock.

Verificar o funcionamento

Consola do proxy

Cerca de 10 segundos após reiniciar, com os backends em execução, deve ver algo semelhante a:

[ResourcePackManager] Network key loaded ✓
[ResourcePackManager] Network key provisioning ready on rspm:network; backends are keyed as players connect.
[ResourcePackManager] NetworkSync starting (poll interval 5000 ms, network-http-offset 1 - endpoint announcements preferred, fallback HTTP port = mcPort + offset)
[ResourcePackManager] NetworkSync: inbox stabilized — merging 2 Bedrock zip(s) and 2 mappings file(s) across 2 backend(s).
[ResourcePackManager] Merged Bedrock pack published at .../merged/Bedrock.zip (sha1=...).
[ResourcePackManager] ✔ Network resource pack is now ready (... KB, sha1 ABCD1234)

/rspm status no proxy

Apresenta a impressão digital da chave, a lista de backends, os resultados por backend e rota — 200, 304, 404 ou CONNECT_FAILED — para /bedrock.zip, /mappings.json e /rspm-update.jar, os anúncios de endereços recebidos, as entradas disponíveis na retransmissão e o número de consultas vazias consecutivas. Também mostra a presença e tamanho do pacote e mapeamentos combinados, o prefixo SHA-1 do pacote, o desvio de porta de recurso, a pasta Geyser detetada, o ficheiro de mapeamentos instalado e a presença de Floodgate e Geyser.

Velocity aceita resourcepackmanager.command.status ou resourcepackmanager.*. BungeeCord regista o nó exato resourcepackmanager.command.status, que um plugin de permissões pode satisfazer por expansão de caracteres universais. A consola também pode executar. A saída não revela segredos: a chave aparece apenas como um hash curto de sentido único e não são apresentados tokens de autenticação, permitindo conceder acesso ao diagnóstico sem os divulgar.

/rspm status num backend

Deploy mode deve indicar network-backend. O hash curto em Network key fingerprint tem de coincidir com o do proxy. Network key source explica a origem:

Linha de origem	Significado
provided by the proxy	Estado normal de ligação: a chave foi recebida quando um jogador se ligou.
saved on this server	Já estava guardada de um arranque anterior, ou foi criada pelo próprio servidor quando independente.
adopted from Floodgate's key	Derivada uma vez do plugins/floodgate/key.pem local.
not set — the proxy sends one when a player next connects here	Sem ligação. Ainda não entrou um jogador desde o arranque do proxy, falta RSPM no proxy ou o proxy não é suportado.

Cliente Bedrock

Entre por Bedrock. Deve aparecer o pedido de transferência do pacote antes de entrar no mundo. O conteúdo personalizado deve mostrar os modelos pretendidos em vez de suportes de armadura simples.

Referência de configuração

Backend: plugins/ResourcePackManager/config.yml

O modo de rede é detetado automaticamente. Não existe uma opção networkMode: true. Basta um destes sinais:

1. Floodgate presente e Geyser-Spigot ausente: sinal mais forte de Bedrock através de proxy.
2. spigot.yml: settings.bungeecord: true: encaminhamento de IP antigo de BungeeCord.
3. paper-global.yml: proxies.velocity.enabled: true: encaminhamento moderno de Velocity.

networkHttpOffset-v2 controla o desvio usado para estimar a porta HTTP antes de o backend anunciar a porta real. O valor predefinido é 1; a porta correspondente tem de estar acessível entre proxy e backend, ou a retransmissão tem de estar disponível. Consulte Alojamento próprio para os detalhes.

Normalmente, cada backend anuncia a porta real através do registo de endereços em magmaguy.com. O desvio só é usado no arranque ou se o anúncio falhar. Consulte Resolução da porta HTTP do backend.

Proxy: config.yml

O proxy escreve uma configuração mínima no primeiro arranque. A pasta depende do identificador usado pela plataforma:

Proxy	Caminho
Velocity	plugins/resourcepackmanager/config.yml
BungeeCord	plugins/ResourcePackManager/config.yml

Contém exatamente duas opções facultativas:

# FALLBACK offset added to each backend's Minecraft port to derive the HTTP
# port this proxy will hit for /bedrock.zip and /mappings.json BEFORE that
# backend has announced its real ResourcePackManager HTTP port. Default 1.
# In normal operation the backend announces the exact port it bound, so this
# value is only used at startup or if announcement fails — but if it IS used,
# it should match each backend's networkHttpOffset-v2.
network-http-offset-v2: 1

# Installs and updates this universal ResourcePackManager.jar in the proxy's
# Geyser extensions folder, which is what makes custom Bedrock ENTITIES render.
# Default true. Setting it to false stops future installation and update
# staging; it does not delete an extension jar that is already installed —
# remove that by hand while Geyser is stopped.
geyser-extension-auto-install: true

Os equivalentes no config.yml do backend são networkHttpOffset-v2 e geyserExtensionAutoInstall. São definições independentes: desativar a instalação da extensão no proxy não a desativa nos backends, nem o contrário.

Junto de config.yml, o proxy escreve network-key. Preserve este estado gerado e não o copie entre redes distintas. Apagá-lo repete a resolução no próximo arranque; um ficheiro do Floodgate disponível pode produzir a mesma chave. Se mudar, os backends já associados conservam a anterior e recusam a nova. Dois proxies que servem os mesmos backends precisam de partilhar uma chave: copie o ficheiro entre esses proxies.

Não existe force-resource-pack no proxy. A aceitação obrigatória é definida no backend por forceResourcePack, pois o proxy gere apenas a entrega Bedrock e nunca envia pacotes Java. Uma linha antiga force-resource-pack é ignorada e pode ser removida.

Também não existe uma entrada de configuração network-key. A configuração manual da chave foi retirada antes do lançamento por permitir erros de escrita que quebravam a ligação silenciosamente. O proxy fornece-a automaticamente, conforme Ligação entre proxy e backends.

Resolução da porta HTTP do backend

O proxy escolhe a porta para consultar /bedrock.zip e /mappings.json por esta ordem:

1. Endereço anunciado pelo backend, preferido. O backend envia a porta HTTP real para o registo em magmaguy.com, associado à chave de rede. Em cada consulta, o proxy atualiza a lista e associa o anúncio à entrada do servidor pela porta Minecraft e, quando disponível, pelo endereço. Assim, tanto um selfHostPort explícito como a porta automática mcPort + 1 são usados corretamente.
2. mcPort + network-http-offset-v2, alternativa. Só é usado sem anúncio correspondente, por exemplo na primeira consulta ou quando o registo está temporariamente inacessível. Os desvios dos dois lados devem coincidir se depender desta alternativa.

O proxy não procura outras portas por varrimento, pois isso pode ser interpretado como comportamento abusivo pelo fornecedor. Quando a ligação direta não é possível, usa a retransmissão descrita abaixo.

/rspm status mostra a porta escolhida para cada backend e se veio do anúncio ou do desvio.

Estabilidade e frequência da combinação

As preferências de alojamento Java também se aplicam aos backends de proxy. Uma verificação Java falhada pode mudar a entrega Java para alojamento remoto, mantendo o servidor HTTP do backend ativo para /bedrock.zip e /mappings.json.

O proxy espera que a entrada estabilize: a primeira consulta fixa o conjunto de hashes; a seguinte com o mesmo conjunto aciona a combinação. Com aproximadamente 2 segundos de atraso inicial e consultas a cada 5 segundos, a primeira combinação ocorre cerca de 7 segundos depois de existir um backend acessível com conteúdo. Depois, só volta a comprimir quando o conjunto SHA-1 dos ficheiros muda, reduzindo o trabalho durante períodos sem alterações.

Os backends escrevem bedrock.zip num ficheiro temporário e mudam-lhe o nome atomicamente. A rota /bedrock.zip fornece, por isso, um ZIP completo. Basta um ciclo de estabilidade, pois não há leitura de um ZIP parcialmente escrito.

Obtenção direta e retransmissão de recurso

A via predefinida é a obtenção direta, com um pedido HTTP GET a http://<backend-host>:<mcPort + offset><path> por backend.

Se a porta HTTP não for acessível, como em alojamentos que expõem apenas as portas Minecraft, o backend envia bedrock.zip e mappings.json para um serviço de retransmissão em magmaguy.com, sob o espaço de nomes da rede derivado da chave. O proxy lista e transfere esses ficheiros quando a obtenção direta falha definitivamente.

Ambas as vias alimentam a mesma combinação. A direta é preferida por não consumir largura de banda de magmaguy.com; a retransmissão é usada automaticamente quando necessária.

As entradas da retransmissão expiram após 30 minutos. Os backends renovam-nas a cada 25 minutos e removem-nas imediatamente num encerramento normal.

Resolução de problemas comuns

Um backend nunca recebe a chave de rede

O estado mostra Network key source: not set — the proxy sends one when a player next connects here e a consola repete:

[ResourcePackManager] This backend is behind a proxy but has no network key yet, so it is not linked to the proxy.
[ResourcePackManager] The proxy sends one automatically the first time a player connects to this server.

Verifique por ordem:

1. Entrou algum jogador nesse backend desde o arranque do proxy? A chave é enviada através de uma ligação de jogador. Um servidor ainda não visitado pode estar legitimamente sem chave.
2. O RSPM está instalado no proxy? Copie plugins/ResourcePackManager/proxy-extension/ResourcePackManager.jar do backend para plugins/ do proxy e reinicie-o.
3. No Velocity moderno, os segredos de encaminhamento coincidem? O backend rejeita atribuições sem assinatura ou com assinatura incorreta, impedindo que um proxy não autorizado o associe. O registo indica o caso. Corrija o segredo nos dois lados; a ligação seguinte de um jogador repete automaticamente a tentativa, sem exigir reinício para voltar a tentar.
4. O proxy é suportado? Apenas Velocity e BungeeCord executam esta função. O Waterfall não é suportado.

key.pem do Floodgate já não participa neste processo contínuo. A ausência de plugins/floodgate/key.pem no proxy é suportada: o proxy cria a sua própria chave. A autenticação Floodgate é separada da ligação de rede RSPM.

Dois proxies servem os mesmos backends

Ambos têm de apresentar a mesma chave. Caso contrário, cada backend associa-se ao primeiro e rejeita o outro, registando A proxy offered a network key that differs from the one this backend already uses. Copie network-key da pasta de dados RSPM do proxy principal para a do outro e reinicie este último.

Aviso de ausência de conteúdo combinado após cerca de 20 segundos

Após quatro consultas vazias consecutivas com participantes RSPM confirmados, o proxy apresenta um aviso com esses participantes, os URLs tentados e os resultados. Um proxy recém-iniciado que ainda procura o primeiro participante não conta os restantes servidores registados como backends de pacotes em falha. Os casos comuns são:

• CONNECT_FAILED em todos os backends: não consegue alcançar as portas HTTP. Confirme que os endereços em velocity.toml ou config.yml são acessíveis pela rede do proxy, sem depender de nomes internos Docker que este não resolva, e que as portas estão abertas entre os componentes. O aviso mostra o endereço e porta tentados e se vieram do anúncio ou de mcPort + networkHttpOffset-v2. Se não puder abrir a porta, consulte a retransmissão acima; o backend deverá enviar os ficheiros automaticamente.
• NOT_FOUND_404 em todos os backends: estão acessíveis, mas não produzem pacote Bedrock. Execute /rspm status em cada um. A secção Bedrock explica o motivo, normalmente ausência de mapeamentos convertíveis ou entidades, ou primeira combinação ainda incompleta.

O aviso aparece uma vez por período sem progresso. NetworkSync: recovered indica que pelo menos um backend voltou a fornecer conteúdo.

Modelos personalizados ausentes no primeiro arranque do proxy

O Geyser regista os objetos personalizados apenas no arranque do proxy. Se nenhum backend tinha produzido o pacote, a tabela de mapeamentos fica vazia durante essa execução.

Reinicie o proxy depois de este registar a primeira linha Merged Bedrock pack published. O RSPM instala antecipadamente os mapeamentos da execução anterior nos arranques seguintes, antes da leitura pelo Geyser. Acrescentar ou remover objetos posteriormente também altera os mapeamentos de arranque e exige reinício. Novos identificadores de entidades ou tipos de propriedades exigem o mesmo tratamento.

Avisos de Duplicate bedrock_identifier no arranque

Identificadores Bedrock diferentes podem partilhar o mesmo seletor Java de objeto, modelo e predicados. Mudar apenas o nome do modelo resolvido não os distingue. Dê seletores diferentes aos objetos distintos, como valores de custom-model-data separados. O combinador prefere uma definição moderna a uma antiga com o mesmo seletor; entre tipos iguais, ganha a última. A deduplicação preserva apenas um objeto.

O jogador Bedrock entrou, mas não vê o pacote

Quando uma sessão Bedrock carrega sem um pacote RSPM utilizável, o proxy avisa no chat a equipa ligada com resourcepackmanager.*, com uma mensagem equivalente a:

⚠ [RSPM] A jogadora Bedrock Alice entrou antes de o pacote estar pronto e está a ver suportes de armadura em vez dos modelos personalizados. Peça-lhe para sair e voltar a entrar; o pacote será carregado na próxima sessão. Causa: ...

O jogador Bedrock também recebe uma janela modal e a consola recebe um aviso. Para investigar em Velocity ou BungeeCord, execute:

/rspm debug bedrock on

Isto ativa os registos detalhados [RSPM-BedrockDebug] de GeyserBinder. Reproduza o problema e desative:

/rspm debug bedrock off

A opção volta a ficar desativada ao reiniciar o proxy.

Atualizar o RSPM numa rede

Mantenha o mesmo JAR e versão em todos os backends e no proxy.

Manualmente, atualize o JAR do backend, copie esse ResourcePackManager.jar para plugins/ do proxy e reinicie o proxy.

O RSPM também pode automatizar a parte do proxy. Cada backend disponibiliza o JAR universal em /rspm-update.jar, protegido por um token derivado da chave partilhada; a chave em si não é transmitida nessa rota. O proxy verifica se o ficheiro é um JAR RSPM universal completo, com versões concordantes nos descritores e os pontos de entrada esperados. Recusa versões anteriores e verifica tamanho e SHA-256 dos bytes preparados antes de substituir ficheiros. Prepara o mesmo JAR para o plugin do proxy e, se houver Geyser local, para a extensão incluída. Aplica-os no encerramento do proxy e guarda os ficheiros anteriores como cópias de recuperação.

Esta autenticação estabelece confiança entre componentes da rede; não verifica independentemente a origem no Nightbreak. Qualquer backend com a chave partilhada é considerado fiável para oferecer um JAR RSPM estruturalmente válido de versão igual ou superior. Proteja a chave e trate todos os backends que a partilham como infraestrutura de confiança.

Na prática, atualizar os backends e depois reiniciar o proxy costuma bastar, pois o proxy terá preparado o JAR correspondente. Uma atualização recusada gera Rejected backend-offered ResourcePackManager update: ... com o motivo.

Falhas de autenticação das atualizações executáveis

HTTP 401 em /rspm-update.jar pausa apenas a propagação automática do JAR desse backend. As consultas diretas de pacotes e mapeamentos Bedrock continuam. A rota de atualização volta a tentar com intervalos crescentes, começando num minuto e limitados a quinze. Compare as impressões digitais de /rspm status nos dois lados e confirme que o URL chega ao backend pretendido e as versões coincidem.

Se as impressões digitais diferirem, /rspm status no proxy indica o procedimento atual: confirme que se trata do proxy e do backend pretendidos, pare o backend afetado, faça uma cópia de segurança do seu plugins/ResourcePackManager/data.yml, remova apenas a entrada networkKey, depois inicie-o e entre através deste proxy para que volte a receber a chave. Mantenha o network-key do proxy e quaisquer chaves do Floodgate. O aviso 401 na consola do proxy ainda recomenda copiar key.pem do Floodgate; esse conselho está desatualizado, porque o RSPM guarda a sua própria identidade de rede e alterar key.pem não substitui uma chave RSPM já estabelecida. Guarde as duas saídas de estado para o suporte.

Funcionalidades ainda não suportadas

• Entrega Java através do plugin do proxy. Os clientes Java recebem pacotes diretamente dos backends pela API normal. Não existe combinador Java no proxy.
• Combinação Java entre backends. Cada backend tem o seu pacote independente; mudar de backend envia o pacote do novo servidor.
• Rotação da chave de rede em execução. Um backend só adota uma chave enquanto não tiver nenhuma e recusa mensagens de substituição. Com todos os componentes parados, apagar network-key do proxy e networkKey de data.yml em cada backend permite uma nova atribuição. Isto não garante uma chave diferente: o proxy pode voltar a derivar a mesma chave de key.pem do Floodgate.