Pular para conteúdo

Cluster distribuído (vários servidores)

Quando o volume previsto para os próximos 24 meses passa da capacidade de um servidor (faixa cluster do dimensionamento, acima de ~1,2 × 10⁹ pontos/dia), o instalador monta o Quantix Vision AI em vários servidores: o ClickHouse fica em nós dedicados (shards × réplicas, com ClickHouse Keeper) e a aplicação roda em um ou mais nós de aplicação. Tudo é feito pelo ./install.sh, com Ansible, a partir das respostas do administrador. Nenhum arquivo precisa ser editado nos servidores.

flowchart LR
  U[usuários / coletores remotos] -->|HTTPS 443| VIP[VIP ou balanceador<br/>quantix.empresa.com.br]
  VIP --> A1 & A2
  subgraph A1["quantix-app1 (primário)"]
    W1[web · api · engine · ingestores] --- PG[(PostgreSQL)] --- N[(NATS JetStream)]
    C[coletor local · automação]
  end
  subgraph A2["quantix-app2 (secundário)"]
    W2[web · api · engine · ingestores]
  end
  A2 -->|5432 · 4222| A1
  subgraph CH["qv_cluster"]
    S1R1[(ch-s1r1 + Keeper)] <--> S1R2[(ch-s1r2 + Keeper)]
    S2R1[(ch-s2r1 + Keeper)] <--> S2R2[(ch-s2r2)]
  end
  A1 & A2 -->|8123 HTTP| CH

Topologia

Nó Grupo do inventário O que roda Portas que recebe
Aplicação primário (1º nó app) quantix_server, quantix_app docker compose completo sem o ClickHouse local: PostgreSQL, NATS, api, web, engine, ingestores, coletor local, automação 443/80 (usuários/VIP); 5432 e 4222 (só dos secundários)
Aplicação secundário quantix_app api, web, engine, ingestores (PostgreSQL e NATS do primário) 443/80
ClickHouse quantix_clickhouse clickhouse-server em /opt/quantix-ch (rede do host); ClickHouse Keeper nos 3 primeiros 9000, 9009, 8123 (outros nós ClickHouse e nós de aplicação); 9181, 9234 (Keeper, entre nós ClickHouse)
  • Cada shard guarda as entidades com cityHash64(entity_id) % shards; cada réplica é uma cópia completa do shard. Com 2 réplicas, a perda de um nó ClickHouse não interrompe a plataforma.
  • O backend usa QV_CH_HOST=<todos os nós ClickHouse> (failover entre eles) e QV_CH_CLUSTER=qv_cluster; ele mesmo cria o schema Replicated* + Distributed (ClickHouse em cluster).
  • Os nós de aplicação recebem o arquivo gerado /opt/quantix/docker-compose.distributed.yml, que desliga o ClickHouse local (perfil nunca ativado), aponta o backend para o cluster, dá aos serviços a rede egress (a rede internal não tem rota para fora do host) e, com dns_mode: hosts, adiciona extra_hosts. Nos secundários ele também aponta PostgreSQL/NATS para o primário.
  • Os nós ClickHouse recebem 20-cluster.xml (remote_servers com os nomes reais, macros de shard e réplica do nó, Keeper) e keeper.xml (raft_configuration com os 3 nós), gerados pelo Ansible. Os segredos (CLICKHOUSE_PASSWORD, CLICKHOUSE_INTERSERVER_PASSWORD) são os do .env do primário.

Dimensionamento

O instalador começa perguntando os ativos previstos para 24 meses (VMs, TB de armazenamento, portas de SAN) e mostra o plano. Exemplo para 50 mil VMs, 300 PB e 60 mil portas:

Servidor vCPU RAM Disco Serviços
quantix-app1 32 64 GB 400 GB SSD web, api, engine, ingestores, coletor local, automação, PostgreSQL, NATS
quantix-app2 32 64 GB 400 GB SSD web, api, engine, ingestores
quantix-ch-s1r1, -s1r2, -s2r1 34 132 GB 5,1 TB NVMe clickhouse-server + Keeper
quantix-ch-s2r2 32 128 GB 5,1 TB NVMe clickhouse-server

./install.sh plan mostra o plano sem instalar (--json para automação). O preflight compara vCPUs, memória e disco livre de cada nó com o que o plano pede para ele.

Instalação nova

./install.sh            # etapa 1: ativos → plano "cluster" → topologia cluster
  1. Servidores: quantos nós de aplicação, quantos shards e réplicas; nome e IP de cada servidor (sugestões do plano) e o acesso SSH (mesmo usuário com sudo, porta e chave em todos os nós).
  2. Nome público e DNS: VIP/balanceador do nome público (opcional com um nó de aplicação) e se os nomes já existem no DNS. O instalador resolve cada nome a partir do controlador e mostra os registros que faltam (veja abaixo). Sem DNS, escolha hosts.
  3. Imagens, certificado, proxy e diretórios, como no host único.
  4. Preflight do cluster (cluster-preflight.yml) em todos os nós; falhas interrompem.
  5. Instalação (cluster.yml): /etc/hosts (se hosts), Docker e ajustes de kernel em todos os nós → .env, segredos e imagens no primário → nós ClickHouse e Keeper (espera o quórum e confere system.clusters) → aplicação no primário (/api/health) → nós secundários (mesmo .env e mesmo certificado do primário) → backup agendado e resumo.

Não interativo: ./install.sh install --answers cluster.yml --yes (chaves em Instalador › Modo não interativo).

Registros DNS

Um registro A por servidor e um para o nome público (no VIP/balanceador, ou no primário quando há um só nó de aplicação). O instalador imprime exatamente estas linhas com os seus nomes e IPs:

quantix-app1.empresa.com.br.             IN A    10.10.0.21
quantix-app2.empresa.com.br.             IN A    10.10.0.22
quantix-ch-s1r1.empresa.com.br.          IN A    10.10.0.31
quantix-ch-s1r2.empresa.com.br.          IN A    10.10.0.32
quantix-ch-s2r1.empresa.com.br.          IN A    10.10.0.33
quantix-ch-s2r2.empresa.com.br.          IN A    10.10.0.34
quantix.empresa.com.br.                  IN A    10.10.0.30

Se o VIP for informado por nome, o nome público vira CNAME para ele. Os nomes dos nós são usados entre os servidores (replicação, Keeper, remote_servers, PostgreSQL/NATS do primário); use os mesmos nomes no certificado só se for acessar os nós diretamente.

Com dns_mode: hosts o instalador grava em /etc/hosts de todos os nós (bloco marcado Quantix Vision AI - nós do cluster) e em extra_hosts dos containers:

10.10.0.21       quantix-app1.empresa.com.br quantix-app1
10.10.0.31       quantix-ch-s1r1.empresa.com.br quantix-ch-s1r1
…

O nome público continua precisando existir no DNS dos usuários. Ao trocar para dns, o bloco é removido na próxima execução.

Preflight do cluster

./install.sh preflight (ou automaticamente antes do install/expand). Somente leitura; o teste de firewall abre escutas temporárias (Python, ~2 minutos) nas portas ainda livres de cada nó.

Verificação Falha quando Aviso quando
Acesso SSH e sudo nó inacessível ou sudo negado —
Sistema operacional fora de RHEL/Rocky/Alma/Oracle 8–9, Ubuntu 22.04/24.04, SLES/openSUSE Leap 15 —
vCPUs, memória, disco livre (dados do Docker) abaixo da metade do plano do nó (disco: 25 %) abaixo do plano
Portas locais (8123, 9000, 9009, 9181, 9234, 9182 · 80/443 · 5432/4222) em uso por outro serviço —
Acesso aos outros nós (TCP) porta sem resposta (firewall) —
Latência entre nós — acima de 2 ms
NTP e diferença de relógio — não sincronizado ou diferença > 2 s
Resolução dos nomes em cada nó (dns_mode: dns) nome não resolve para o IP informado —

Relatório: .install/cluster-preflight.json. Com --answers, o preflight verifica outra configuração (por exemplo, os nós de um expand) sem alterar a instalação registrada.

Expansão de host único para cluster

./install.sh expand                               # guiado
./install.sh expand --answers cluster.yml --yes   # não interativo (agente do host)

O servidor atual vira o nó de aplicação primário (se não estiver em cluster_nodes, o instalador o inclui como primeiro nó app). Sequência (deploy/ansible/expand.yml):

  1. Confere a instalação existente (/opt/quantix/.env, ClickHouse de nó único) e faz o backup completo com o script de host único (quantix-backup.sh: PostgreSQL, ClickHouse, volumes).
  2. Preflight de todos os nós; Docker e /etc/hosts; prepara o primário (arquivos, .env, imagens, override distribuído) sem reiniciar a aplicação.
  3. Sobe os nós ClickHouse e Keeper e confere o cluster.
  4. Migra o histórico (roles/quantix_cluster/tasks/migrate.yml):
    • lê a retenção configurada na GUI e gera o DDL do cluster com a própria aplicação (schema_statements(..., cluster="qv_cluster")), executado ON CLUSTER;
    • para api, web, engine, ingestores e automação. Coletor, NATS e PostgreSQL continuam: as métricas coletadas durante a migração ficam no JetStream (até 6 h) e são gravadas no cluster depois da troca;
    • desanexa as views de rollup no cluster (senão os dados brutos copiados gerariam agregados em dobro);
    • liga temporariamente o container ClickHouse antigo à rede egress e, para cada tabela (health_history, metrics_latest, metrics_1d, metrics_1h, metrics) e cada shard, executa INSERT INTO FUNCTION remote('<réplica 1 do shard>:9000', 'qv_local', '<tabela>', …) SELECT * FROM qv.<tabela> WHERE cityHash64(entity_id) % <shards> = <índice> — o mesmo critério das tabelas Distributed; a replicação copia para as demais réplicas;
    • confere as contagens (tabelas brutas iguais; agregadas podem ter menos linhas depois dos merges), reanexa as views e para o ClickHouse antigo — o volume quantix_clickhouse-data fica intacto.
  5. Troca a aplicação para o cluster (docker-compose.distributed.yml) e espera /api/health. Se não ficar saudável, volta sozinha para o host único.
  6. Instala os nós de aplicação secundários, troca o backup agendado e grava /opt/quantix/.quantix-expand.json (um novo expand reaplica a configuração sem migrar de novo).

Em qualquer falha da migração as views são reanexadas, a rede é desligada e a instalação de host único volta a subir: nada é apagado. Tempo de indisponibilidade da interface: a duração da cópia (ordem de dezenas de minutos por centena de GB comprimidos, limitada pela rede e pelos discos).

Limites e alternativas

  • Migração offline para a interface (a coleta continua). Bases muito grandes podem ultrapassar as 6 h de retenção do JetStream: nesse caso migre sem histórico e copie depois (abaixo).
  • O nó primário precisa alcançar a porta 9000 da réplica 1 de cada shard.
  • Se o cluster já tiver dados (expand repetido após rollback), o expand para. Para recopiar do zero: QV_ANSIBLE_EXTRA_VARS='{"quantix_expand_truncate": true}' ./install.sh expand … (apaga os dados do cluster).
  • Sem migração (cluster começa vazio, histórico consultável só pelo rollback): QV_ANSIBLE_EXTRA_VARS='{"quantix_migrate_history": false}'. Para copiar depois, com a aplicação no ar, rode a mesma consulta INSERT INTO FUNCTION remote(...) a partir de um container ClickHouse temporário que monte o volume antigo, tabela a tabela, com as views de rollup desanexadas.
  • Alternativa por arquivo: restaure o clickhouse-qv.zip do backup do expand em um nó avulso e copie com remote(); ou exporte cada tabela em formato Native e importe nas tabelas Distributed (INSERT INTO qv.<tabela> FORMAT Native).
  • O ClickHouse em cluster no mesmo host (clickhouse_cluster: true) não é ponto de partida do expand.

Rollback

./install.sh expand --rollback

O primário volta ao compose de host único com o volume ClickHouse preservado (expand-rollback.yml), o backup diário de host único é reinstalado e topology volta a single em .install/answers.yml. Métricas gravadas no cluster depois da troca não voltam. Os nós ClickHouse continuam no ar, sem uso: desligue-os com docker compose --project-directory /opt/quantix-ch down em cada nó. Confira o size nas respostas antes do próximo ./install.sh install (o expand pode tê-lo aumentado).

Depois de validar o cluster por alguns dias, libere o espaço do ClickHouse antigo no primário: docker volume rm quantix_clickhouse-data (a partir daí não há rollback).

Operação

Tarefa Como
Estado ./install.sh status (nó primário); em cada nó ClickHouse: docker compose --project-directory /opt/quantix-ch ps
Atualizar versão ./install.sh upgrade reaplica cluster.yml com a nova versão (sem backup prévio: faça antes)
Backup diário no primário (quantix-backup-cluster.sh: PostgreSQL, quantix-data, certificado). Métricas: replicadas nos nós; para cópia externa use BACKUP DATABASE qv_local ON CLUSTER qv_cluster TO S3(...)/disco NFS
Agente do host ./install.sh agent (no primário)
Firewall libere 9000/9009/8123 entre nós ClickHouse e dos nós de aplicação; 9181/9234 entre nós Keeper; 5432/4222 do primário só para os secundários

Limitações conhecidas

  • PostgreSQL e NATS ficam só no primário (sem alta disponibilidade): a perda do primário para a coleta e a interface até ele voltar; o ClickHouse replicado preserva as métricas.
  • O certificado enviado pela GUI fica no volume do primário; com vários nós de aplicação, termine o TLS no balanceador ou reinstale (./install.sh install) para copiar o certificado do instalador.
  • A validação foi feita com renderização dos templates, docker compose config dos arquivos gerados e o preflight executado contra nós simulados; o DDL distribuído vem do mesmo código já validado em ClickHouse em cluster.