Configurar o BungeeCord: ligar servidores Minecraft com segurança

O BungeeCord liga vários servidores Minecraft Java sob um endereço comum. O proxy autentica o jogador e encaminha-o para a lobby, Survival ou outros backends. Ele próprio não hospeda nenhum mundo. Por isso, uma rede mínima precisa de pelo menos dois processos ou instâncias de hosting separados: um proxy BungeeCord e um backend Minecraft.

A regra de segurança mais importante: os backends correm atrás do BungeeCord em Offline-Mode. Por isso, nunca devem estar livremente acessíveis a partir da Internet. ip_forward: true transmite a identidade, mas não é controlo de acesso. Conclui a proteção por firewall/rede privada antes de considerares a rede pronta.

Como é uma rede BungeeCord

Cliente Minecraft Java
        |
        | endereço público do proxy
        v
 BungeeCord (online_mode=true, ip_forward=true)
        |
        | apenas caminho de proxy permitido
        +---------------------+
        v                     v
 Lobby / Paper          Survival / Paper
 online-mode=false      online-mode=false
 bungeecord=true        bungeecord=true

O proxy trata do login, endereço público, routing e comandos de proxy. Os backends guardam mundos, inventários e dados de plugins Bukkit/Paper. O BungeeCord não sincroniza estes dados automaticamente. Rank, bans ou inventários em toda a rede precisam de plugins adequados e, normalmente, de uma base de dados comum.

Que topologia combina contigo?

A configuração do BungeeCord é parecida em todas as variantes, mas o caminho de rede seguro não é. Decide a topologia antes de introduzires endereços em config.yml.

Proxy e backend na mesma node

Duas instâncias de hosting na mesma node continuam a ser containers separados. O proxy pode alcançar o backend através do endereço interno previsto para isso; uma instância alheia na mesma bridge não deve poder fazê-lo. Liberar toda a sub-rede Docker seria, por isso, demasiado amplo. A proteção tem de ficar vinculada à fonte concreta do proxy e resolver-se de novo após um reinício do container.

Proxy e backend em nodes diferentes

Aqui, o caminho passa pela rede da node. Permite no backend exatamente a fonte do proxy associado e a porta TCP concreta. Não abras por engano UDP, um intervalo de portas ou o IP completo da node para outras instâncias de clientes. Testa o caminho positivo a partir do proxy e o caminho negativo a partir de uma fonte independente na mesma janela temporal.

Backend externo

Um backend fora da plataforma de hosting precisa de uma rota que o proxy BungeeCord consiga alcançar. O operador do sistema externo é responsável pela firewall dele. Um túnel reverso ou VPN pode criar o transporte, mas só é seguro se o backend continuar vinculado localmente e apenas o caminho autorizado do proxy for encaminhado. Textos de produto só devem chamar esta variante de segura quando o caminho positivo e o negativo tiverem sido verificados para a configuração concreta.

Vários proxies

Vários proxies para alta disponibilidade são um design próprio. Cada caminho de origem permitido, a gestão comum de plugins/dados e o tratamento de sessões têm de ser planeados explicitamente. Não copies simplesmente mais um IP para uma allowlist ampla. Este guia descreve de propósito um proxy associado por cada caminho de backend.

Requisitos e modelo de custos

Precisas de:

• uma instância BungeeCord;
• pelo menos um servidor Paper/Spigot separado como backend;
• uma porta TCP única por processo;
• um caminho acessível do proxy para o backend;
• uma firewall, uma rede privada ou um controlo de acesso comparável e verificado;
• um backup testado antes de converter um servidor existente.

Na game-serverhosting, o BungeeCord é um software de servidor próprio. Planeia proxy e backends como instâncias separadas. Se ainda não tens instâncias, começa pela encomenda de servidor Minecraft. A base de código atual do BungeeCord compila com Java 17; o Egg oferecido corre com Java 21. Não confies em afirmações antigas e genéricas como “512 MB para 500 jogadores”: plugins, taxa de ligações, compressão e ataques alteram bastante a necessidade.

Passo 1: anotar arquitetura e portas

Dá a cada instância um nome e uma função. Um exemplo simples:

127.0.0.1 só funciona se proxy e backend partilharem o mesmo namespace de rede. Dois containers Pterodactyl no mesmo host não ficam automaticamente ligados por loopback. Usa exatamente o endereço do backend que o teu proxy consegue alcançar e, por isso, nunca abras preventivamente uma sub-rede inteira de containers.

Passo 2: proteger servidores existentes com backup

Antes de alterações ao Online-Mode ou ao forwarding, faz backup dos mundos, playerdata, bases de dados de plugins e ficheiros de configuração. Executa pelo menos um restauro de teste. Ao mudar de UUIDs offline para online, os jogadores podem aparecer como contas novas, embora os ficheiros antigos ainda existam. O guia para uma mudança de versão segura explica o caminho de backup, cópia e rollback que também deves usar para esta migração.

Passo 3: iniciar o proxy e editar config.yml

Inicia o BungeeCord uma vez e depois para o proxy corretamente. Assim é criada uma config.yml compatível com a versão instalada. Encontras a referência completa dos campos em BungeeCord config.yml explicada.

Um modelo mínimo e abreviado fica assim:

online_mode: true
ip_forward: true
player_limit: -1

servers:
  lobby:
    address: <LOBBY-ADRESSE>:<LOBBY-PORT>
    motd: '&aLobby'
    restricted: false
  survival:
    address: <SURVIVAL-ADRESSE>:<SURVIVAL-PORT>
    motd: '&aSurvival'
    restricted: false

listeners:
  - host: 0.0.0.0:<PROXY-PORT>
    priorities:
      - lobby
      - survival
    force_default_server: true
    max_players: 100

max_players influencia o número de slots apresentado. O limite global rígido é player_limit; valores de zero ou menores significam ilimitado nesse campo. Os nomes dos backends em priorities têm de coincidir exatamente com as chaves em servers.

Passo 4: configurar backends para forwarding

Em cada backend Paper/Spigot:

# server.properties
online-mode=false

# spigot.yml
settings:
  bungeecord: true

No Paper atual, verifica adicionalmente em config/paper-global.yml:

proxies:
  bungee-cord:
    online-mode: true

Este valor do Paper descreve o Online-Mode do proxy e deve corresponder a ele. Não contradiz o online-mode=false em server.properties. Os quatro valores e as consequências para UUID/backup são explicados em detalhe em configurar o BungeeCord IP Forwarding com segurança.

Passo 5: proteger o acesso ao backend

Agora vem o passo que falta em muitos tutoriais antigos. Permite a porta TCP do backend exclusivamente a partir do proxy associado ou vincula-a a uma rede privada realmente comum. Um simples IP interno, restricted: true ou bungeecord: true não é prova de segurança.

Na game-serverhosting, o caminho de proxy permitido para topologias BungeeCord suportadas é derivado da instância de proxy concreta pelo Backend-Guard ativo. Se a fonte faltar ou parar, o caminho permanece drop-only. Para um backend operado externamente, tens de configurar a respetiva firewall por tua conta para permitir apenas o caminho de proxy verificado.

O BungeeGuard pode fornecer proteção adicional por token em Shared Hosting. Usa pelo menos a versão 1.4.0; instalações afetadas mais antigas têm de fazer upgrade e rodar o token. O token nunca deve aparecer em tickets, screenshots ou logs. O BungeeGuard complementa a proteção de rede e não torna automaticamente invisível uma superfície de ataque acessível.

Passo 6: ordem de arranque e testes reais

Inicia primeiro os backends e depois o proxy. Verifica mais do que uma porta aberta:

1. O processo do proxy corre e escuta na alocação atribuída.
2. O proxy alcança o endereço da lobby por TCP.
3. O ping Minecraft através do endereço público do proxy funciona.
4. Uma conta de teste real entra na lobby e consegue mudar de servidor.
5. IP e UUID online chegam corretamente ao backend.
6. Um acesso direto independente à porta do backend falha.

Só o ponto 6 transforma um caminho de forwarding funcional num resultado protegido. Se a entrada falhar, percorre a árvore de diagnóstico para “Could not connect to a default or fallback server”, sem abrir a firewall de forma genérica.

Planear routing, fallback e manutenção

priorities não é apenas uma lista para o primeiro join. Também determina que destinos o BungeeCord tenta por ordem quando um servidor falha. Coloca em primeiro lugar um backend pequeno e fiavelmente compatível. Um servidor Survival com um modpack pesado raramente é o melhor fallback técnico.

forced_hosts pode enviar domínios diferentes para destinos iniciais diferentes. Exemplo: creative.example.net inicia em creative, enquanto play.example.net começa na lobby. Ambos os nomes DNS apontam para o mesmo proxy. Testa cada hostname separadamente, porque um default funcional não diz nada sobre um erro de digitação no mapping de Forced-Host.

restricted: true faz sentido para servidores de manutenção ou de equipa. A permission correspondente bungeecord.server.<name> tem de ser avaliada ao nível do proxy. Ela impede que um jogador normal mude através do BungeeCord, mas não protege contra acesso TCP direto ao backend.

Para manutenção, recomenda-se este fluxo:

1. Remover o servidor de destino da prioridade usada publicamente ou bloqueá-lo por permission.
2. Mover jogadores ligados de forma controlada para um backend saudável.
3. Fazer backup e manutenção do backend.
4. Verificar TCP do proxy para o backend e um join de teste real.
5. Só então liberar novamente o routing.

Um reinício do proxy desconecta todos os jogadores ligados através dele. Os mundos continuam a correr nos backends, mas o reinício continua a ser uma interrupção visível e deve entrar numa janela de manutenção.

Revisão de segurança antes da liberação

Percorre esta fronteira uma vez do ponto de vista de um atacante:

• Apenas o proxy está documentado como endereço público do Minecraft?
• Todas as portas de backend estão bloqueadas a partir de uma workstation independente?
• Outra instância na mesma Shared-Node/Bridge consegue alcançar a porta?
• A fonte atual do proxy é reavaliada após Stop/Start?
• Um proxy parado ou não resolvível de forma inequívoca permanece fail-closed?
• Tokens, IPs completos e key.pem foram removidos de screenshots e logs de suporte?
• Apenas um pequeno grupo de pessoas tem permissions como /ip, /send, /alert e /end?
• Todos os backends registados são confiáveis? Backends podem influenciar a rede através de Plugin Messaging.

Se não consegues responder a uma pergunta com um teste ou uma regra concreta, o estado é unverified, não “provavelmente seguro”. Isto é especialmente importante em Shared Hosting: um endereço que parece interno ainda não prova separação entre clientes.

Backups, updates e monitoring

O BungeeCord não tem mundo, mas o seu estado continua a ser relevante para recuperação. Antes de updates, faz backup de:

• config.yml e modules.yml;
• plugins/ do proxy com as respetivas configurações;
• bases de dados locais ou externas de plugins de forma consistente;
• versão de build do BungeeCord e versão Java usadas;
• documentação redigida dos nomes dos backends, portas e regras de proteção.

Mundos, playerdata e dados de plugins Bukkit/Paper são guardados separadamente nos backends. Um backup do proxy não substitui um backup de mundo. Depois de um restauro, verifica não só se os ficheiros existem, mas também se join na lobby, UUID, permissions e mudança de servidor voltaram a estar corretos.

Para um update, para o proxy corretamente, substitui apenas o JAR ou usa o instalador previsto e verifica primeiro o log de arranque. Depois seguem-se ping Minecraft, join real, identidade, fallback e o caminho direto ainda bloqueado. Mantém o último JAR funcional com a configuração correspondente pronto para rollback.

O monitoring separa pelo menos estes sinais:

Observa também heap/GC, bloqueios do event loop, exceções de plugins, timeouts de backend e taxas de ligação invulgares. Um campo verde no dashboard não deve juntar vários destes estados num “online” genérico.

Evitar erros comuns de setup

• Porta do proxy e porta do backend trocadas: os jogadores entram diretamente no backend em Offline-Mode ou o BungeeCord liga-se a si próprio.
• Domínio público como endereço do backend: o proxy entra num loop de DNS/routing. Usa o endereço interno de destino concreto.
• max_players lido como limite rígido: a lista de servidores mostra o valor, enquanto player_limit pode continuar ilimitado.
• Apenas um teste TCP feito: o listener está aberto, mas lobby, forwarding ou protocolo falham.
• Firewall desativada para debug: o join positivo funciona, enquanto ao mesmo tempo fica aberto um bypass de identidade.
• Plugin Bukkit instalado no proxy: plataforma ou dependências não batem certo; lê o descriptor e a página do projeto.
• /greload após alterações profundas: partes da configuração ou plugins ficam no estado antigo. Usa um reinício completo.
• Backup sem teste de restauro: só em caso de erro se percebe que base de dados, mundos ou estado de plugins não foram guardados de forma consistente.

Apontar domínio e SRV para o proxy

O DNS aponta sempre para o proxy público. Com uma porta Java diferente, um registo SRV _minecraft._tcp pode mapear a porta. O target SRV tem de ser um hostname, não um IP. Os passos exatos de A/CNAME/SRV estão no guia ligar o teu próprio domínio ao teu gameserver.

Forced Hosts não mudam isso: usam o hostname pedido pelo cliente apenas como informação de routing. Também survival.example.net aponta primeiro para o proxy; só depois o BungeeCord encaminha internamente para survival.

Distribuir plugins e permissions corretamente

• Plugins BungeeCord pertencem ao plugins/ do proxy.
• Plugins Bukkit/Paper pertencem ao backend respetivo.
• Alguns plugins de rede precisam de componentes nos dois níveis.
• Permissions de proxy não existem automaticamente num plugin de permissions puramente de backend.
• Após alterações de plugins, um reinício completo planeado é mais fiável do que /greload.

Usa apenas plugins de fontes confiáveis e verifica plataforma, versão, dependências e avisos de segurança. O guia de plugins mostra o caminho no painel para plugins Paper/Spigot; plugins de proxy têm de ser reconhecidos explicitamente como compatíveis com BungeeCord.

Crossplay Bedrock com Geyser

Numa rede BungeeCord, instalas o Geyser no proxy, não em cada backend. Java usa TCP, o listener Bedrock usa UDP. O Floodgate basta no proxy, desde que plugins de backend não precisem da API dele nem do suporte adicional de skins. key.pem é um segredo de autenticação.

A verificação de porta e join continua separada para TCP e UDP. Usa o guia de crossplay Geyser/Floodgate depois de o caminho Java puro funcionar com segurança.

BungeeCord ou Velocity?

O BungeeCord continua a ser construído ativamente em 2026. O Waterfall, o antigo fork da PaperMC, por outro lado, está End of Life. A PaperMC recomenda Velocity para novas redes e nota ela própria que a comparação dela pode ser enviesada a favor do próprio produto.

Para uma rede existente com plugins BungeeCord importantes, o BungeeCord pode ser a escolha de menor risco. Para uma nova rede em versões Paper atuais, o Velocity oferece Modern Forwarding com um formato secreto protegido por MAC. Não decidas com base em números genéricos de performance, mas sim em versões, API de plugins, forwarding e migração. O artigo BungeeCord vs Velocity 2026 contém a matriz de decisão.

FAQ

O BungeeCord é um servidor Minecraft?

Não. O BungeeCord é um proxy. Mundos, chunks, mobs e modos de jogo correm em backends separados.

De quantos servidores preciso?

Pelo menos dois processos ou instâncias: proxy e um backend. Para lobby mais modo de jogo, três instâncias fazem sentido.

O proxy tem de correr em Online-Mode?

Para uma rede autenticada normal, sim: online_mode: true no proxy. Os backends usam online-mode=false, porque o proxy já autenticou.

O ip_forward é seguro?

É necessário para IPs reais e UUIDs online, mas sozinho não é seguro. Legacy-Forwarding não tem nenhum segredo de assinatura específico do proxy. A porta do backend tem de estar protegida contra fontes untrusted.

Um reinício do proxy reinicia os meus mundos?

Não. Os backends continuam a correr, mas os jogadores ligados através do proxy são desconectados.

Preciso de uma lobby?

Não obrigatoriamente. É necessário pelo menos um destino acessível em priorities; uma lobby própria torna o fallback e a manutenção geralmente mais claros.

Que portas o BungeeCord precisa?

O listener Java público usa TCP. Cada backend precisa da sua própria porta TCP, acessível apenas pelo proxy. Query e Geyser/Bedrock usam portas UDP separadas quando ativados; não as abras se a função não for usada.

Posso instalar plugins Paper no BungeeCord?

Não de forma genérica. Plugins Paper/Bukkit pertencem aos backends. O proxy precisa de plugins criados explicitamente para BungeeCord. Plugins de rede podem fornecer dois componentes separados.

Porque é que o meu backend só vê o IP do proxy?

Normalmente, ip_forward no proxy ou settings.bungeecord no backend está desativado. Verifica ambos os lados e reinicia completamente. Altera valores relevantes para UUID apenas depois de fazer backup.

Posso usar vários domínios?

Sim. Todos os domínios apontam para o proxy. forced_hosts pode depois associar o hostname pedido a um backend inicial.

O crossplay funciona automaticamente em todos os backends?

O Geyser traduz Bedrock no proxy. Os backends têm de aceitar a versão do protocolo Java emulada pelo Geyser; com diferenças de versão, pode ser necessário um setup ViaVersion verificado de propósito. A acessibilidade UDP é testada separadamente do TCP Java.

Verificação final

A rede só está pronta quando o join real através do proxy funciona e um join direto independente ao backend em Offline-Mode está bloqueado. Documenta endereços e regras de forma redigida, guarda configuração e dados de mundo separadamente e agenda a próxima revisão técnica antes da data indicada se BungeeCord, Java, BungeeGuard, Paper, Velocity ou Geyser publicarem uma release relevante.

Para casos de suporte futuros, guarda também a hora e o fuso horário do teste, versões do proxy/backend e a primeira mensagem de erro concreta. Mascara endereços IP de jogadores e remove completamente secrets. Assim, uma diferença posterior entre erro de processo, rede, protocolo, identidade e plugin pode ser compreendida sem integrar dados sensíveis de clientes numa base de conhecimento permanente.

Fontes primárias

• BungeeCord: Instalação
• BungeeCord: Guia de configuração
• BungeeCord: IP Forwarding
• BungeeCord: repositório e aviso de segurança
• Paper: configuração global
• BungeeGuard: segurança