Pular para conteúdo

Plataforma

Administração › Plataforma é a tela do superadministrador para cuidar da própria instalação: ver a versão, dimensionar o ambiente para os próximos 24 meses, atualizar de versão (com rollback) e construir ou expandir o cluster de vários servidores. Outros papéis, inclusive Administrador, não veem o item no menu e recebem HTTP 403 na API.

Toda ação fica no log de auditoria (platform_sizing, platform_package_uploaded, platform_operation_requested, platform_operation_cancelled, platform_operation_finished).

Agente do host

Os containers do Quantix não têm acesso ao Docker do servidor. Quem executa atualização e cluster é o agente do host, um serviço systemd (quantix-agent) que busca o trabalho na API pelo nginx local e devolve o log ao vivo. O painel Versão e agente do host mostra:

Campo Significado
Versão em execução versão da API que respondeu à tela
Versão no .env do servidor QV_VERSION do .env da instalação
Agente conectado (heartbeat nos últimos 90 s) ou desconectado, servidor e versão do agente
Pasta da instalação / Instalador onde estão o .env e o install.sh (necessário para o cluster)
Espaço livre disco livre na pasta da instalação

Instalar o agente pela interface

Se o agente ainda não estiver conectado, clique em Instalar agente do host (ou, quando já conectado, em Reinstalar / atualizar agente). A janela guia a única etapa que precisa ser feita no servidor:

  1. Baixar instalador — gera e baixa o install-quantix-agent.sh já preenchido para esta instalação (URL pública da plataforma e token do agente). O arquivo contém o token: trate-o como segredo e use só neste servidor.
  2. Copie o comando e rode no servidor, como root:
sudo bash install-quantix-agent.sh
  1. A janela mostra o estado ao vivo e muda para conectado assim que o agente faz o primeiro heartbeat — nada mais precisa ser configurado no host.

O instalador é idempotente: quando encontra a pasta da instalação (com o install.sh), reaproveita o ./install.sh agent (detecta o Python, define a pasta de origem para futuras atualizações do agente e recria a API se faltar o token); caso contrário, instala o programa e a unidade systemd diretamente (baixando o programa da API, autenticado pelo token, quando necessário). Ele sempre grava /etc/quantix/agent.env com QV_API_URL, QV_AGENT_TOKEN e QV_AGENT_TLS_VERIFY=auto (permissão 0600, root) e executa systemctl enable --now quantix-agent. Quem preferir a linha de comando pode continuar usando sudo ./install.sh agent na pasta da instalação.

Detalhes de instalação e configuração em Atualização › Pela interface.

Dimensionamento

Informe quantos ativos a plataforma deve monitorar daqui a 24 meses. Ativo é a unidade monitorada:

Ativo O que conta
Máquinas virtuais cada VM (vSphere, Nutanix/AHV); hosts e datastores vêm junto
TB de armazenamento capacidade útil dos arrays de storage e NAS, em TB
Portas de SAN portas Fibre Channel dos switches e diretores (Brocade, Cisco MDS)

Os campos vêm preenchidos com o inventário atual (VMs e portas de switch monitoradas; TB somados da capacidade dos sistemas de storage ou, na falta dela, dos pools). Calcular mostra:

  • o porte (pequeno, médio, grande em host único ou cluster distribuído), séries e pontos por dia;
  • os servidores com vCPU, memória, disco e tipo de disco;
  • os containers com réplicas e recursos de cada um;
  • as orientações de alocação (disco dedicado para o ClickHouse, reservas de CPU/memória, coletores, retenção e backup);
  • no porte cluster, os registros DNS a criar e a recomendação de VIP/balanceador.

O cálculo é o mesmo do instalador (backend/quantix/common/sizing.py).

Atualizar versão

  1. Enviar pacote: escolha o .zip da nova versão (até 2 GB). A API confere se é um pacote do Quantix, lê a versão e calcula o SHA-256.
  2. Atualizar: confirme. Opcionalmente inclua o histórico de métricas no backup.
  3. Acompanhe o log. O agente baixa o pacote, confere o SHA-256 e executa quantix-update.sh update: backup “antes de atualizar”, ponto de rollback (arquivos e imagens), aplicação da nova versão, construção das imagens e verificação de saúde. Se a nova versão não ficar saudável, a anterior volta sozinha.

Durante a atualização a API e a interface reiniciam: a tela avisa e retoma o log quando a API volta. Ao terminar, recarregue a página para usar a nova interface. Uma atualização em andamento não pode ser cancelada (a instalação ficaria pela metade).

Rollback

O painel mostra o ponto de rollback da última atualização. Voltar para <versão> restaura arquivos e imagens anteriores mantendo os dados atuais. Marque Restaurar também os dados (e digite RESTAURAR) para voltar o PostgreSQL ao backup feito antes da atualização — tudo o que mudou depois é perdido.

Construir / expandir cluster

Assistente em cinco passos; os servidores vêm preenchidos a partir do plano de dimensionamento.

  1. Servidores — nome e IP de cada servidor, papel (aplicação ou ClickHouse), shard e réplica dos nós ClickHouse e onde roda o ClickHouse Keeper (número ímpar, recomendado 3). Um domínio DNS opcional é acrescentado aos nomes curtos.
  2. Nome público e DNS — nome público do Quantix e IP do VIP/balanceador (TCP/443 na frente dos nós de aplicação). Escolha entre DNS da empresa (você cria os registros mostrados) e /etc/hosts (o instalador grava as entradas em todos os servidores). Verificar DNS resolve os nomes a partir do próprio servidor (o resolvedor do host, não o dos containers) e compara com os IPs informados.
  3. Acesso SSH — usuário com sudo, porta e o caminho de uma chave privada no servidor, ou senha (exige sshpass). Senhas de SSH e de sudo são cifradas na operação, entregues uma única vez ao agente (que as repassa ao instalador só por variável de ambiente) e apagadas em seguida; nunca aparecem em telas, logs ou auditoria.
  4. Verificação — install.sh preflight confere acesso, sistema, recursos, discos, portas e nomes em todos os servidores sem alterar nada.
  5. Construir / expandir — liberado só depois de uma verificação bem-sucedida, nas últimas 24 h, com exatamente os mesmos dados (a API confere). Executa install.sh expand; não pode ser interrompido no meio. Faça um backup antes.

Histórico

Lista as últimas operações (quem pediu, situação, início e fim) com o log completo de cada uma. Se o agente for reiniciado no meio de uma operação, ela é marcada como falha com a orientação de conferir o estado da instalação (deploy/scripts/quantix-update.sh status).

Segurança

  • Rotas /api/v1/admin/platform/* exigem superadministrador; rotas /api/v1/agent/* aceitam só o cabeçalho X-Agent-Token (QV_AGENT_TOKEN, comparado por hash em tempo constante) e, no nginx, apenas redes internas.
  • Só a API recebe QV_AGENT_TOKEN; o agente o lê do .env (root).
  • O agente valida o certificado sempre que a URL não for loopback (QV_AGENT_TLS_VERIFY=auto) e recusa http:// fora de loopback.
  • Parâmetros (nomes, IPs, usuário, porta, caminho da chave) são validados na API antes de chegar ao host; os comandos são executados sem shell, com argumentos fixos.