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:
- Baixar instalador — gera e baixa o
install-quantix-agent.shjá 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. - Copie o comando e rode no servidor, como root:
- 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¶
- Enviar pacote: escolha o
.zipda nova versão (até 2 GB). A API confere se é um pacote do Quantix, lê a versão e calcula o SHA-256. - Atualizar: confirme. Opcionalmente inclua o histórico de métricas no backup.
- 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.
- 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.
- 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.
- 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. - Verificação —
install.sh preflightconfere acesso, sistema, recursos, discos, portas e nomes em todos os servidores sem alterar nada. - 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çalhoX-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 recusahttp://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.