Pular para conteúdo

Arquitetura — visão geral

O Quantix Vision AI é um conjunto de serviços em containers. O backend usa uma única imagem (quantix-vision-backend) com um subcomando por serviço (quantix api | collector | ingestor | engine | automation). A interface web vem em uma segunda imagem (quantix-vision-web, nginx + SPA React). A infraestrutura são três componentes de mercado:

Componente Papel Por quê
NATS JetStream 2.10 barramento coletores → ingestores buffer persistente com work-queue: se os ingestores param, os coletores continuam publicando sem perda até o limite do stream
ClickHouse 24.8 séries temporais (métricas brutas, rollups, histórico de saúde) colunar, compressão de 6–7 bytes/ponto medida, rollups por materialized view, agregações sobre bilhões de linhas (detalhes)
PostgreSQL 16 inventário, topologia, configuração, usuários, achados, auditoria integridade relacional, JSONB/GIN para atributos de fabricante, pg_trgm para a busca global

Componentes

flowchart TB
  DEV["Arrays · switches FC · vCenter/Prism<br/>(REST, SSH, SDK)"]
  subgraph COL["Coletores — quantix collector"]
    C1["coletor-local<br/>transporte NATS"]
    C2["coletor remoto<br/>transporte HTTPS 443"]
  end
  DEV --> C1 & C2
  subgraph PLAT["Plataforma"]
    W["web — nginx + SPA :443"]
    API["api — FastAPI :8000"]
    N[("NATS JetStream<br/>stream QV_DATA + object store")]
    I["ingestor × N"]
    CH[("ClickHouse<br/>séries temporais")]
    PG[("PostgreSQL<br/>inventário / configuração")]
    E["engine"]
    AU["automation — Ansible"]
  end
  C1 -->|"qv.metrics.* / qv.inventory.*"| N
  C2 -->|"/api/v1/ingest/*"| W
  W --> API
  API -->|repassa| N
  N --> I
  I -->|INSERT em lote| CH
  I -->|merge do snapshot| PG
  E --> CH & PG
  API --> CH & PG
  E -->|notificações| EXT["Teams · Slack · e-mail · syslog · ServiceNow · webhook"]
  AU -->|runbooks aprovados| DEV
  U["Usuários"] --> W

Coletores também usam a API (HTTPS) para baixar a configuração e enviar heartbeat, status e o resultado das tarefas sob demanda.

Serviço Comando Responsabilidade Escala
api quantix api --workers N REST, autenticação/RBAC, bootstrap idempotente (schemas, papéis, admin, coletor padrão, runbooks, dashboards de sistema), ingestão HTTPS de coletores remotos horizontal (sem estado)
collector quantix collector executa os plugins, agenda inventário e performance, publica resultados um ou mais por site
ingestor quantix ingestor consome o JetStream: métricas → ClickHouse e inventário → PostgreSQL horizontal (consumidores duráveis compartilhados)
engine quantix engine correlação, ratings, change detection, balanceamento, previsão, regras de configuração, aplicações, alertas, resumo diário, limpeza várias réplicas: cada job roda em uma só (HA)
automation quantix automation executa runbooks Ansible aprovados (ansible-runner) réplicas competem por SELECT … FOR UPDATE SKIP LOCKED
web nginx SPA, TLS, proxy reverso /api, documentação em /docs/, cabeçalhos de segurança/CSP horizontal

No modo laboratório (QV_EMBEDDED_WORKERS=true e QV_TSDB_BACKEND=chdb), a API executa ingestor e engine no próprio processo e usa o ClickHouse embutido (chdb). Veja Laboratório.

Fluxo de dados

sequenceDiagram
  autonumber
  participant P as Plugin (coletor)
  participant N as NATS JetStream
  participant I as Ingestor
  participant CH as ClickHouse
  participant PG as PostgreSQL
  participant E as Engine
  participant U as API/GUI
  P->>P: collect_inventory() a cada inventory_interval_s
  P->>N: object store qv-inventory (snapshot zlib+msgpack) + aviso em qv.inventory.<device>
  N->>I: ingest-inventory (1 por vez por réplica)
  I->>PG: COPY em tabelas temporárias → merge entities/relations/identifiers + config_changes
  P->>P: collect_performance() alinhado à fronteira do intervalo (:00, :05…)
  P->>N: qv.metrics.<device> (lote colunar msgpack ≤ 200 mil linhas)
  N->>I: ingest-metrics (fetch 256 msgs)
  I->>CH: INSERT colunar (até 250 mil linhas ou 2 s) → ack só após o insert
  CH->>CH: MVs atualizam metrics_1h, metrics_1d, metrics_latest
  E->>PG: correlação por WWPN/NAA (relações origin=correlator)
  E->>CH: janela de 20 min / rollups horários e diários
  E->>PG: health, findings (fingerprint), forecasts
  U->>CH: QueryEngine (escolhe tabela pela janela: bruto ≤ 2 d, 1h ≤ 120 d, 1d acima)
  U->>PG: inventário, topologia, achados

Pontos de projeto:

  • IDs determinísticos. Cada objeto recebe um UUID v5 de (device_id, tipo, id nativo) (common/ids.py). Coletor e ingestor geram o mesmo ID sem consultar o banco, e por isso o caminho quente das métricas não faz nenhum lookup no PostgreSQL.
  • Snapshots completos e idempotentes. O inventário é sempre a visão completa do dispositivo. O ingestor calcula o diff (adicionado/removido/alterado, ignorando atributos voláteis) e grava a trilha de mudanças. Reaplicar o mesmo snapshot não muda nada.
  • Confirmação após persistir. O ingestor só faz ack das mensagens depois do INSERT no ClickHouse. Em falha, faz nak e o JetStream reentrega (até max_deliver=5). Uma mensagem malformada recebe term para não travar a fila.
  • Inventários grandes fora do stream. Snapshots vão para o Object Store qv-inventory (TTL de 24 h), e o stream leva só a notificação. Isso respeita o max_payload de 8 MB do NATS.
  • Correlação separada da ingestão. Cada coletor só enxerga seu equipamento. As relações entre fontes (logged_in, same_as, backed_by, zoned_with) são recalculadas pela engine a cada analytics.correlation_interval_s (padrão 900 s). Ver Engine.

Assuntos (subjects) do barramento

Subject Conteúdo Formato
qv.metrics.<device_id> lote colunar {eid[], et[], m[], v[], ts[]} + envelope ver, dev, ten, col msgpack
qv.inventory.<device_id> notificação {dev, ten, col, obj, size} com a chave no object store msgpack
qv.status.<collector> / qv.control.<collector> reservados (declarados em common/bus.py). Na v1.0.0, heartbeat, status e tarefas trafegam pela API HTTPS —

Stream QV_DATA: subjects qv.metrics.> e qv.inventory.>, retenção WORK_QUEUE, armazenamento em arquivo, max_bytes 20 GiB, max_age 6 h, max_msg_size 8 MiB, janela de duplicatas 120 s. Consumidores duráveis: ingest-metrics e ingest-inventory (ack_wait 120 s, max_ack_pending 2000, max_deliver 5).

Onde fica cada configuração

Tipo Onde Exemplos
Infraestrutura (como os containers se encontram) variáveis de ambiente QV_* DSN do PostgreSQL, host do ClickHouse, URL do NATS, chave mestra — ver Variáveis de ambiente
Operação da plataforma GUI → tabela settings intervalos, retenção, thresholds, IA, SMTP, segurança — ver Variáveis da plataforma
Objetos GUI/API → PostgreSQL dispositivos, credenciais, coletores, diretórios, alertas, dashboards

As variáveis da GUI são lidas por todos os serviços por meio de um cache com expiração de 30 s (SettingsCache). A engine recarrega o cache a cada ciclo.