Produção com Docker Compose¶
Prefira o instalador
./install.sh executa estes passos com verificações, gera o .env sem edição manual e deixa a
criação do administrador para o assistente de primeira execução.
Veja Instalador. Esta página descreve o caminho manual.
Host único¶
git clone … quantix-vision-ai && cd quantix-vision-ai
make gen-env # gera .env a partir de .env.example (segredos fortes; preserva existentes)
vi .env # QV_PUBLIC_URL, QV_REGISTRY/QV_VERSION, proxy, limites de recursos
make certs # certificado autoassinado em deploy/certs (ou copie tls.crt / tls.key)
make build # ou: make pull (registro interno)
make up # sobe e aguarda /api/health
Acesse https://<servidor>/ com admin e a senha QV_ADMIN_PASSWORD do .env (se estiver vazia, use
make admin-password). Na primeira vez, defina Configurações › Geral › URL pública.
Serviços (docker-compose.yml): postgres, clickhouse, nats, api (4 workers), ingestor
(2 réplicas), engine, collector (coletor local), automation e web (único que publica portas:
443 e 80). Bancos e barramento ficam na rede internal (sem rota externa). api, engine,
collector, automation e web também participam da rede egress.
Guarde o .env e a QV_MASTER_KEY
O .env contém todos os segredos e não entra no backup. Sem a mesma chave mestra, as
credenciais de dispositivos não podem ser decifradas após uma restauração.
Ambiente grande¶
O override aplica PostgreSQL com 4 GB de shared_buffers e 500 conexões, ClickHouse com 32 vCPU
e 128 GB, ingestor ×4, engine com 8 vCPU/16 GB, API com 8 workers, coletor com concorrência 64 e
pool de conexões 15. Coletores adicionais no mesmo host: --profile multi-collector
(collector-2, collector-3), cada um com token próprio emitido na GUI (QV_COLLECTOR_TOKEN_2/_3).
ClickHouse em cluster: make up CLUSTER=1 (detalhes). Ambos combinados:
make up SCALE=1 CLUSTER=1.
Variáveis principais do .env¶
Todas estão documentadas em .env.example e na referência.
As que você normalmente ajusta:
| Variável | Uso |
|---|---|
QV_PUBLIC_URL |
URL pública (coletores remotos, automação) |
QV_REGISTRY, QV_VERSION |
imagens da plataforma |
QV_HTTPS_PORT, QV_HTTP_PORT, QV_*_BIND, QV_CERTS_DIR |
publicação do nginx |
QV_API_WORKERS, QV_INGESTOR_REPLICAS, QV_PG_POOL_SIZE |
escala dos serviços |
*_CPUS, *_MEMORY, PG_* |
limites de cgroup e tuning do PostgreSQL |
QV_HTTPS_PROXY, QV_NO_PROXY |
proxy de saída |
QV_LOG_LEVEL, QV_LOG_JSON, QV_LOG_MAX_SIZE, QV_LOG_MAX_FILE |
logs |
Conexões PostgreSQL: cada processo abre até 2 × QV_PG_POOL_SIZE. Garanta que
(QV_API_WORKERS + réplicas de ingestor + engine + automação) × 2 × QV_PG_POOL_SIZE seja menor que
PG_MAX_CONNECTIONS. Com o padrão: (4 + 2 + 1 + 1) × 2 × 10 = 160 < 300.
Operação do dia a dia (Makefile)¶
| Alvo | Ação |
|---|---|
make ps / make logs S=api |
estado e logs (todos ou de um serviço) |
make restart |
reinicia api, ingestor, engine, collector, automation, web |
make down |
para e remove containers (volumes preservados) |
make backup / make restore FROM=… |
backup e restauração |
make config |
mostra o compose final |
make lint |
valida compose, Ansible, Helm e Dockerfiles |
Documentação embutida¶
make build-web inclui docs/site (saída de cd docs && mkdocs build --strict) na imagem web,
servida em https://<servidor>/docs/. Rode python docs/gen_reference.py && python docs/gen_api.py
antes, para atualizar as páginas geradas do código.