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) eQV_CH_CLUSTER=qv_cluster; ele mesmo cria o schemaReplicated*+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 redeegress(a redeinternalnão tem rota para fora do host) e, comdns_mode: hosts, adicionaextra_hosts. Nos secundários ele também aponta PostgreSQL/NATS para o primário. - Os nós ClickHouse recebem
20-cluster.xml(remote_serverscom os nomes reais, macros de shard e réplica do nó, Keeper) ekeeper.xml(raft_configurationcom os 3 nós), gerados pelo Ansible. Os segredos (CLICKHOUSE_PASSWORD,CLICKHOUSE_INTERSERVER_PASSWORD) são os do.envdo 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¶
- 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).
- 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. - Imagens, certificado, proxy e diretórios, como no host único.
- Preflight do cluster (
cluster-preflight.yml) em todos os nós; falhas interrompem. - Instalação (
cluster.yml):/etc/hosts(sehosts), 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 conferesystem.clusters) → aplicação no primário (/api/health) → nós secundários (mesmo.enve 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):
- 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). - 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. - Sobe os nós ClickHouse e Keeper e confere o cluster.
- 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")), executadoON 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
egresse, para cada tabela (health_history,metrics_latest,metrics_1d,metrics_1h,metrics) e cada shard, executaINSERT 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 tabelasDistributed; 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-datafica intacto.
- lê a retenção configurada na GUI e gera o DDL do cluster com a própria aplicação
(
- 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. - Instala os nós de aplicação secundários, troca o backup agendado e grava
/opt/quantix/.quantix-expand.json(um novoexpandreaplica 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 consultaINSERT 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.zipdo backup do expand em um nó avulso e copie comremote(); ou exporte cada tabela em formato Native e importe nas tabelasDistributed(INSERT INTO qv.<tabela> FORMAT Native). - O ClickHouse em cluster no mesmo host (
clickhouse_cluster: true) não é ponto de partida do 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 configdos 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.