Alta disponibilidade¶
| Componente | Estado | Como obter HA | O que acontece se parar |
|---|---|---|---|
web (nginx) |
sem estado | várias réplicas atrás de balanceador/Ingress (Helm: web.replicas: 2, PDB) |
interface e ingestão HTTPS indisponíveis |
api |
sem estado (segredos no Secret/.env) | várias réplicas e workers (Helm: api.replicas: 2, PDB) |
GUI/API indisponíveis. Coletores NATS continuam publicando, mas não recebem configuração nova |
ingestor |
sem estado | N réplicas no mesmo grupo de consumo durável (ingest-metrics, ingest-inventory) |
dados se acumulam no JetStream (até 6 h / 20 GiB) e são processados quando volta |
engine |
sem estado | N réplicas: cada job roda em apenas uma por vez (pg_try_advisory_lock) |
sem saúde/achados/alertas novos. A coleta segue normalmente |
automation |
sem estado | N réplicas: cada execução é obtida com SELECT … FOR UPDATE SKIP LOCKED |
execuções aprovadas aguardam na fila |
collector |
sem estado (configuração vem da API) | coletores distintos para conjuntos distintos de dispositivos. Ao reatribuir um dispositivo, outro coletor assume no próximo recarregamento (≤ 60 s) | dispositivos daquele coletor ficam sem dados novos (status do dispositivo e do coletor mostram) |
| NATS JetStream | buffer persistente | cluster NATS de 3 nós com stream replicado (QV_NATS_URL aceita lista separada por vírgula) |
ingestão para. Coletores reconectam indefinidamente (max_reconnect_attempts=-1), mas perdem os ciclos publicados enquanto o NATS estiver fora (não há fila local no coletor) |
| ClickHouse | dados | cluster 2 × 2 com Keeper (cluster) e failover de conexão (QV_CH_HOST com lista de nós) |
inserts falham → ingestor faz nak e as mensagens voltam ao stream. Dashboards e engine sem séries |
| PostgreSQL | dados | recomendado: Patroni, serviço gerenciado (RDS/Cloud SQL/Azure) ou operador k8s (CloudNativePG, Crunchy), via postgresql.mode=external no Helm ou QV_PG_DSN |
toda a plataforma depende dele (login, inventário, achados) |
Engine com várias réplicas¶
sequenceDiagram
participant E1 as engine-1
participant E2 as engine-2
participant PG as PostgreSQL
E1->>PG: pg_try_advisory_lock(hash("qv-engine-ratings"))
PG-->>E1: true
E2->>PG: pg_try_advisory_lock(hash("qv-engine-ratings"))
PG-->>E2: false (pula)
E1->>E1: run_ratings()
E1->>PG: pg_advisory_unlock(...)
- Os locks são de sessão e liberados no
finally. Se a réplica morrer, o PostgreSQL libera o lock ao encerrar a conexão, e outra réplica assume o job no próximo ciclo (~30 s). - Ressalva: o lock impede execuções simultâneas, mas não repetidas. Cada réplica mantém seu próprio relógio de jobs. Com 2 réplicas, um job de 300 s pode rodar até 2 vezes a cada 300 s (uma em cada réplica, em momentos diferentes). Os jobs são idempotentes, mas isso aumenta a carga e acelera a resolução automática de achados (o grace de 2 execuções seguidas passa a durar menos tempo). Para HA, prefira 2 réplicas em vez de mais, ou uma réplica com reinício automático (o padrão do compose e do Helm).
- O resumo diário verifica se já existe relatório do dia antes de gerar, e por isso não duplica.
Documentação anterior
deploy/README.md e um comentário em deploy/helm/quantix-vision/values.yaml diziam que a
engine deveria ter 1 réplica “por não haver eleição de líder”. O código atual usa advisory
locks por job, e o README foi corrigido. O comentário do values.yaml e a estratégia
Recreate do Deployment da engine no chart continuam conservadores (1 réplica). Para usar 2
réplicas no Kubernetes, ajuste engine.replicas (a estratégia Recreate só afeta atualizações).
Recomendações por porte¶
| Porte | Recomendação |
|---|---|
| Pequeno/médio | host único com restart: unless-stopped, backup diário e cópia do .env fora do host. RTO = tempo de restaurar o backup |
| Grande | PostgreSQL gerenciado ou com Patroni; ClickHouse 2 × 2; NATS em cluster; 2+ réplicas de api, web e ingestor; 2 de engine; coletores por site |
| Kubernetes | Helm com bancos externos (*.mode=external), PDBs habilitados, anti-afinidade para ClickHouse/NATS e ingestor.autoscaling.enabled |