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
ackdas mensagens depois doINSERTno ClickHouse. Em falha, faznake o JetStream reentrega (atémax_deliver=5). Uma mensagem malformada recebetermpara 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 omax_payloadde 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 cadaanalytics.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.