Arquitetura
← Voltar ao índice da documentação
Minecraft Server Manager é uma aplicação Node.js renderizada no servidor, de processo único. Ela gerencia
servidores Minecraft que rodam como contêineres Docker usando a imagem
itzg/docker-minecraft-server, comunicando-se com o
daemon Docker via sua API (nunca executando o CLI docker externamente).
Estrutura de tempo de execução
Seção intitulada “Estrutura de tempo de execução”- Express + Handlebars renderizam páginas no lado do servidor. Não há SPA; o JavaScript do navegador em
public/js/é uma melhoria progressiva escrita manualmente. Um passo de esbuild (pnpm run build:js) o agrupa e minifica empublic/dist/js/; o aplicativo serve esse bundle quando ele está presente e o código-fonte bruto caso contrário, então uma execução de desenvolvimento sem build ainda funciona. node:sqlite(embutido no Node; o painel requer Node ≥ 24) é o banco de dados - síncrono, zero módulos nativos, modo WAL. Um pequeno executor de migrações versionadas aplicasrc/db/migrations/*na inicialização. Declarações preparadas são cacheadas emsrc/db/index.jscom chave pelo texto SQL.wscarrega os fluxos de console e estatísticas ao vivo. Ambos são intermediados: um upstreamdocker logs --follow(oudocker stats) por servidor, desmultiplexado uma vez e distribuído para cada aba conectada, em vez de um upstream por visualizador. O intermediador de console mantém um pequeno buffer de repetição para abas que entram atrasadas e descarta um assinante cujo socket fica muito para trás em vez de atrasar o fluxo compartilhado.dockerodeé a única forma como o aplicativo se comunica com o Docker. O endpoint é detectado automaticamente por plataforma (pipe nomeado do Windows vs. socket Unix).- Todo o estado persistente vive em um único diretório (
$DATA_DIR, padrão./data). Copiar esse diretório migra o painel inteiro.
Camadas
Seção intitulada “Camadas”As dependências fluem em uma única direção:
┌─────────────────────────────┐ HTTP ───────▶│ web/routes/* (+ middleware)│ analisa e valida a entrada, molda as respostas └──────────────┬──────────────┘ │ ┌──────────────▼──────────────┐ │ services/* │ lógica de domínio (as funcionalidades reais) └───┬─────────┬─────────┬─────┘ │ │ │ ┌────────────▼──┐ ┌────▼────┐ ┌──▼──────────┐ │ docker/* │ │ db/* │ │ storage/* │ infraestrutura └───────────────┘ └─────────┘ └─────────────┘web/routes/- um roteador por domínio (players,worlds,crashes,blueprints,files, …).web/app.jsmonta os de nível superior (api.js, a API JSON de sessão que também contém as rotas principais do servidor e monta os roteadores de domínio por servidor;index.js, as páginas;auth,account,tasks, …). Os roteadores validam com zod, chamam um serviço e retornam JSON ou renderizam uma visualização. A lógica de negócios não pertence aqui. Dois roteadores são montados na **zona pública **, antes derequireAuth:routes/status.js(páginas de status por servidor opcionais) eroutes/apiV1.js(/api/v1, uma API JSON somente leitura autenticada por um token Bearer emitido pelo admin deservices/apiTokens.js, desativada a menos que habilitada em Configurações; vejadocs/public-api.md).services/- o coração do aplicativo. Cada serviço possui um domínio e pode depender de infraestrutura e de outros serviços.docker/- wrappers do dockerode:connect(detecção de endpoint + saúde do daemon),containers(criar/iniciar/parar/recriar com bind mounts, limites de memória/CPU e rótulos),logs,stats,images,networks(descoberta de rede do host),hostPath(re-raiz de caminhos de bind sobDATA_DIR_HOST), e umwatcherque transforma eventos Docker em histórico + detecção de falhas.db/- o wrapper SQLite e o executor de migrações.storage/- o bootstrap./data, o guardião de caminhos (safeJoin, a espinha dorsal de segurança de arquivos), e o indexador de tamanho em segundo plano + aplicação de cotas.
Transversal:
config/- configuração de ambiente mais o catálogo de campos: a única fonte de verdade para configurações do servidor. Cada variável de ambiente itzg é catalogada (rótulo, ajuda, tipo, unidade, padrão, validação, seção, flags de perigo). O assistente, os formulários de configurações e a validação zod são todos derivados dele, então expor uma nova configuração é uma mudança de dados, não uma nova infraestrutura de UI.events/-recordEvent()é o único ponto de entrada para o log de histórico; eventos de ciclo de vida também capturam trechos de logs de contêineres paradata/logs/<id>/events/.ws/- WebSockets de console + estatísticas autenticados (cookie de sessão verificado no upgrade,Originverificado para bloquear sequestro entre sites), intermediados por servidor (veja “Estrutura de tempo de execução”).logger.js+instrument.js-require('./logger')(label)retorna um logger Pino por módulo; nível deLOG_LEVEL,makeFailureThrottle()mantém um loop em segundo plano persistentemente falhando em uma linha de log mais uma linha “recuperada”.src/utils/logSanitize.jsreda a chave com formato de credenciais e tokens de webhook dos metadados estruturados;src/config/logLevel.jsé a lista de permissões de nível compartilhada (mantida separada para evitar um ciclo de require comconfig).src/instrument.jsé uma costura Sentry dormente, carregada primeiro emsrc/server.js.src/web/middleware/requestLog.jsescreve uma linha de log de acesso por requisição (pulando/healthze ativos estáticos). ESLint impõeno-consoleemsrc/**, compreflight.js,instrument.js, econfig/index.jsisentos (eles rodam antes do logger existir).- Limitação de taxa -
src/web/middleware/rateLimit.jscolocaexpress-rate-limitna frente de/api(RATE_LIMIT_API_PER_MIN, padrão 1200) e os POSTs de login / 2FA / configuração (RATE_LIMIT_AUTH_PER_15MIN, padrão 100);0desativa um limitador. Ele usareq.ipcomo chave, entãoTRUST_PROXYimporta atrás de um proxy./api/v1tem seus próprios limitadores: um limite por IP de cliente (cinco vezes o orçamento por token) que roda antes que o token seja verificado, depois um orçamento por token (RATE_LIMIT_PUBLIC_API_PER_MIN, padrão 120) com chave no ID do token verificado. Um contador suave separado por conta emsrc/web/middleware/auth.jslida com o bloqueio de login (por IP e global da conta, decaindo). - Autorização: duas camadas. A função global (
requireAuth→requireRole/requireWriteemsrc/web/middleware/auth.js) controla ações em todo o painel e é o padrão em todos os servidores. Permissões por servidor (src/services/permissions.js, nove capacidades armazenadas como uma lista JSON por(usuário, servidor)emuser_server_permissions) refinam esse padrão para um servidor; cada rota/api/servers/:id, montagem de sub-roteador, página, WebSocket e listagem em toda a frota passam porsrc/web/middleware/serverAccess.js(serverScope, montado no prefixo/servers/:idda API e do roteador de páginas, esconde um servidor semviewcomo um 404;requireCap(cap)nomeia a capacidade que uma rota precisa). Escritas que nomeiam seu servidor no corpo (agendamentos, extração e instalação de mundo, exportação de blueprint) são abertas para visualizadores porrequireWriteapenas para aquele servidor, e cada rota dessas verifica a capacidade em si.test/permissions-routes.test.jspercorre as pilhas de roteadores ao vivo e falha se uma rota de escrita com escopo de servidor, montagem ou página não tiver um portão.
Comportamentos chave de domínio
Seção intitulada “Comportamentos chave de domínio”- Modpacks são sempre fixados. A imagem atualiza automaticamente packs não fixados a cada reinicialização, então o
painel resolve “latest” para um ID de versão concreto no momento da instalação e o fixa. Atualizações são um
fluxo orquestrado explícito (
updates/): pré-visualização → backup pré-atualização → parada graciosa → re-fixação → recriação → monitor de saúde → rollback com um clique. - A sobreposição de mods personalizados é gerenciada pelo painel: mods adicionados pelo usuário vão para a biblioteca deduplicada
e são hard-linked no servidor para que sobrevivam às atualizações do pack. Desabilitar é ciente da classe. Como
a biblioteca mantém cada build que baixou, uma atualização registra o build que substituiu
(
server_content.previous_*) e pode ser revertida apenas a partir de arquivos locais. Desabilitar um mod do pack escreve a variável de ambiente de exclusão do pack em vez disso;packs.applyPackcarrega isso e o restante do ajuste do pack (PACK_TUNING_KEYS) durante uma mudança de versão do mesmo pack, e o descarta quando o pack muda. - Uma atualização de versão do Minecraft tem que ser conquistada.
services/compat.jsescaneia os mods de um servidor - resolvidos a partir de linhas instaladas pelo painel, depois do manifesto do pack CurseForge, depois por hash de conteúdo contra Modrinth/CurseForge - e constrói uma matriz de suporte (loader, versão Minecraft) por projeto a partir doslatestFilesIndexesdo CurseForge (200 projetos por requisição) e da lista de versões por projeto do Modrinth (uma requisição por projeto, que é o que mantém o loader e a versão pareados). O verificador de atualizações oferece apenas a versão mais recente que CADA mod suporta, e não oferece nada quando a resposta não pode ser estabelecida: sem escaneamento, um escaneamento para uma versão ou loader diferente, um que nunca terminou, ou um jar que nenhum dos registros reconhece. Escaneamentos são manuais apenas, e seu progresso e resultados parciais vivem emversion_compat(não noservices/tasks.jsem memória), então uma atualização ou reinicialização do painel retoma em vez de travar em um spinner;reconcileScans()marca escaneamentos órfãos por um desligamento na próxima inicialização. - A versão do mod loader é um pin, como tudo mais.
services/loaderPin.jslê o build instalado do próprio manifesto de instalação da imagem (.forge-manifest.jsone similares) e escreve o pin: a variável itzg do loader em um servidor simples (FORGE_VERSION, …), ouCF_MOD_LOADER_VERSIONem um pack CurseForge Forge ou Fabric, que substitui a versão que o pack declara. O instalador CurseForge da imagem ignora essa substituição para NeoForge, e packs Modrinth e FTB não têm nenhuma, então seu loader segue o pack.packs.applyPackremove todas as variáveisCF_em uma atualização ou rollback de pack, que descarta uma substituição com o restante. Um build tipado é verificado contra a lista completa do registro primeiro (services/loaderVersions.js; o do Forge vem de seus metadados maven, que pula números; uma falha é re-verificada uma vez contra o próprio registro), então a mudança é backup → pin (sobre o env como está após o backup) → reconstrução. - Portas são alocadas a partir de um esquema base (jogo a partir de
PORT_GAME_STARTpara cima, RCON = jogo +PORT_RCON_OFFSET, Bedrock a partir dePORT_BEDROCK_START), sondadas quanto à disponibilidade e reservadas no DB. “Ocupado” é a união das reivindicações de cada servidor (portas ao vivo, mais um par pendente abaixo), cada porta do host que qualquer contêiner Docker publica (containers.publishedHostPorts: ligações ao vivo de contêineres em execução mais as configuradas de cada contêiner parado, porque uma sonda de bind do SO de dentro do próprio contêiner do painel vê apenas o namespace de rede desse contêiner), e a sonda do SO. A parte Docker é cacheada por 3 s e limitada: uma lista que não responde em 2.5 s descarta apenas a parte Docker, e uminspectlento custa apenas as portas desse contêiner. Criações de servidor eservers.changeGamePortescolhem portas através de uma única cadeia de serialização que cobre apenas a escolha e sua reivindicação (a escrita da linha para uma criação, a reserva em memória para uma mudança de porta); o seletor de portas do BlueMap e as substituições de porta extra não estão nele e não consultam o Docker. Uma mudança de porta em um servidor existente (servers.changeGamePort, sob o lock de operação do servidor) é aplicada de uma vez, porque o Docker corrige as ligações de porta na criação do contêiner: o novo par (RCON sempre jogo +PORT_RCON_OFFSET) é verificado e reservado em memória (ports.reserve, tanto o par antigo quanto o novo, honrados por cada outra escolha) sob o lock de porta. É recusado (409PENDING_CHANGES) enquanto outras configurações esperam por uma reconstrução, então ele apenas reconstrói um contêiner que já rodou, em uma nova porta; e um servidor em execução só é alterado quando a requisição dizrestart: true(caso contrário, 409NEEDS_CONFIRM). A imagem é baixada e um nome de contêiner personalizado é verificado antes que qualquer coisa seja tocada. Um servidor em execução é parado; então o novo par é escrito compending_recreate = 1(então uma falha do painel a partir daí deixa um “rebuild pendente” honesto), o contêiner é removido, reconstruído no novo par e iniciado. Se qualquer passo após a parada falhar,putBackOnOldPortescreve o par antigo de volta, reconstrói (e reinicia, se estava em execução) nele e registra qual passo falhou; o histórico e os alertas dizem se mesmo isso falhou, o que deixa o servidor parado até que alguém o inicie. A capacidadesettingsé suficiente, incluindo o servidor em execução. Não administradores só podem escolher a partir dePORT_GAME_STARTpara cima. (As colunasport_*_pendingda migração 029 pertencem a um design anterior, não lançado, e são não utilizadas; 031 as limpa.) Uma colisão de lock responde 409 comcode: 'BUSY', que os chamadores que tentam novamente verificam em vez da mensagem. Uma reinicialização automática após falha (watcher.restartAfterCrash) e um backup ou início agendado (scheduler.runTaskWithRetry) que encontram o servidor ocupado com outra ação tentam novamente a cada 20 s / 60 s por até 30 minutos, e uma atualização ou rollback de pack tenta novamente seus passos bloqueados da mesma forma (opLock.retryWhileBusy); uma reinicialização após falha ou um início agendado em espera desiste assim que alguém parou, matou ou iniciou o servidor desde (events.lifecycleActionSince), e a reinicialização após falha também quando a reinicialização automática está desativada ou o servidor desapareceu. Reinicializações, paradas e comandos agendados não são retentados, e um agendamento cuja última execução ainda está esperando pula seu próximo disparo. - Cotas de disco são aplicadas pelo painel porque o Docker não pode limitar o uso de bind-mount: o indexador armazena em cache tamanhos por diretório e operações de crescimento de disco são controladas por eles.
- Segredos (senhas RCON, chaves de API, segredos TOTP, URL do webhook Discord) são criptografados em repouso
com AES-256-GCM usando uma chave aleatória dedicada em
$DATA_DIR/.secret-key(modo0600, gerada automaticamente). É independente deSESSION_SECRET; uma chave derivada deSESSION_SECRETé mantida como fallback apenas para descriptografia para valores escritos antes que a chave dedicada existisse, esrc/services/secretsMigration.jsre-criptografa esses sob a chave dedicada uma vez na inicialização. Um.secret-keyque existe mas não pode ser analisado é um erro de inicialização grave (ele nunca é silenciosamente regenerado por cima). Blueprints removem todos os segredos na exportação. server.propertiesé de propriedade do painel, mas ofuscado pelo env. A imagem itzg reafirma cada propriedade baseada em env a cada início (OVERRIDE_SERVER_PROPERTIESpadrão true), então um valor que o painel edita diretamente - PvP/dificuldade do World Controls, o toggle de whitelist, o editor de Arquivos - seria silenciosamente revertido no próximo início, a menos que a variável de ambiente correspondente seja removida e o contêiner recriado. Cada escrita direta de propriedade passa porwriteServerProperties()(arquivo inteiro) ousetServerProperty()(uma chave) emsrc/services/servers.js, que reescrevem atomicamente o arquivo, desdefinem a variável de ambiente por trás de cada chave alterada (via o atributoprop:nos campos do catálogo , verificado em testes contra as próprias definições de propriedade da imagem), e marcampending_recreate. A dificuldade é escrita no arquivo, bem como enviada via RCON, porque um servidor dedicado reaplica a propriedadedifficultya cada inicialização. O próprio Minecraft ressalva server.properties de seus valores de inicialização emwhitelist on/off, o que desfaria edições feitas enquanto o servidor está em execução, então o toggle de whitelist em execução captura o arquivo primeiro e o reescreve com apenaswhite-listalterado. O env vars permanecem totalmente configuráveis na criação (o assistente os renderiza e eles se aplicam uma vez); eles apenas desfixam na primeira vez que o painel edita a propriedade subjacente. MOTD tem o mesmo contrato: uma edição direta do arquivomotdo desdefine, então a última escrita vence.
Formatos de dados e de comunicação
Seção intitulada “Formatos de dados e de comunicação”data/panel.db- o banco de dados SQLite. Snapshotted diariamente viaVACUUM INTOparadata/backups/_panel/(os 14 mais recentes mantidos);PRAGMA integrity_checkroda na inicialização.data/.session-secret- o segredo de assinatura de cookie gerado automaticamente, criado na primeira execução seSESSION_SECRETnão estiver definido. Deletá-lo rotaciona o segredo (o que invalida sessões).data/.secret-key- a chave de criptografia dedicada de 32 bytes em repouso (modo0600), criada automaticamente na primeira execução. Independente deSESSION_SECRET; deletá-lo torna todas as credenciais armazenadas indecriptografáveis, então pertence aos seus backups.- Blueprints (
.mcserver.zip) - um zip com ummanifest.jsondescrevendo configuração, recursos, a referência do pack fixado, o manifesto da sobreposição (URLs de origem + sha256), arquivos de configuração escolhidos e opcionalmente um mundo. A importação re-baixa e verifica o hash de cada mod e atribui novas portas. - Contêineres Docker criados pelo painel são nomeados e rotulados para que o watcher possa encontrá-los; o painel possui todo o seu ciclo de vida.
Sequência de inicialização
Seção intitulada “Sequência de inicialização”require('./instrument')(a costura Sentry) antes de qualquer outra coisa, depoisrequire('./preflight')para falhar claramente em uma versão Node não suportada.- Carrega a configuração; garante/gera
.session-secrete.secret-key. ensureDataRoot()- cria o layout./data, limpatmp/.- Executa migrações do DB, depois
PRAGMA integrity_check(loga ruidosamente, aponta paradata/backups/_panelem caso de falha). - Re-criptografa quaisquer segredos legados com chave
SESSION_SECRETsob.secret-key(secretsMigration). - Importa chaves de API do ambiente uma vez (
apiKeys.importFromEnvOnce()), fixa qualquer servidor que ainda esteja carregando um seletor de modpack não fixado (packPins.pinUnpinnedServers()), marca escaneamentos de compatibilidade de versão deixados em execução por um processo anterior como interrompidos (compat.reconcileScans()), então semeia blueprints iniciais (protegido). - Inicia o servidor HTTP + WS. Em um bind exposto, imprime o PIN
/setupda primeira execução. - Instala o guardião de tempo de execução pós-inicialização (captura falhas não tratadas;
MSM_EXIT_ON_FATAL=1faz com que ele saia abruptamente para implantações supervisionadas). - Inicia serviços em segundo plano: intermediador WS, indexador de armazenamento, watchers de falha + inventário, agendador,
ponte de eventos Discord, watcher de alcance de chatbot e o temporizador de manutenção diária (poda linhas antigas de análise, transcrições de chatbot, histórico de eventos (365 dias) e linhas de cache de API, então tira um snapshot de
panel.db). - Inicializa o Docker em segundo plano. A UI é totalmente utilizável enquanto o daemon está inativo;
as funcionalidades do Docker são ativadas quando ele se torna alcançável. Uma vez conectado,
refreshStatuses({ boot })reconcilia os status em cache, emite um evento únicooffline-after-restartpara um servidor que estava ativo antes da reinicialização do painel e não será trazido de volta, e o loop de inicialização inicia servidoresauto_startmais recupera servidoresauto_restartencontrados com falha durante a interrupção (respeitando o backoff de loop de falha).
A ordem instrument-antes-de-preflight é um trade-off deliberado: permite que uma futura fiação Sentry corrija o tempo de execução primeiro, ao custo de uma mensagem ligeiramente menos amigável em um Node verdadeiramente antigo.
Pipeline de build
Seção intitulada “Pipeline de build”pnpm run build = build:css (Tailwind → public/css/app.css) + build:js (esbuild →
public/dist/js/, ESM com code-splitting). postinstall executa apenas CSS. public/css/app.css
e public/dist/ são artefatos de build ignorados pelo git; o estágio de build do Dockerfile executa o pnpm run build completo
e copia public/ para a imagem em tempo de execução. Ativos estáticos são servidos
immutable/cache longo para arquivos com fingerprint, cache curto para CSS/JS, e no-cache para HTML e
/api.