Pular para conteúdo

Variáveis de ambiente

Somente a infraestrutura é configurada por ambiente. O restante fica na GUI (Variáveis da plataforma). Lidas por quantix/common/config.py (pydantic-settings, prefixo QV_, arquivo .env opcional no diretório de trabalho).

Aplicação (QV_* lidas pelo backend)

Variável Padrão no código Descrição
QV_INSTANCE_NAME Quantix Vision AI nome da instalação (o exibido na GUI vem de general.instance_name)
QV_DATA_DIR /var/lib/quantix dados locais: master.key/jwt.secret gerados, automação, chdb
QV_PG_DSN postgresql+asyncpg://quantix:quantix@postgres:5432/quantix DSN do PostgreSQL (driver asyncpg; ?ssl=require para TLS)
QV_PG_POOL_SIZE 20 (compose: 10) pool por processo (+ igual de overflow)
QV_TSDB_BACKEND clickhouse clickhouse ou chdb (embutido)
QV_CH_HOST clickhouse host(s) HTTP do ClickHouse. Lista separada por vírgula = failover
QV_CH_PORT 8123 porta HTTP
QV_CH_USER / QV_CH_PASSWORD quantix / quantix (compose: do .env) credenciais
QV_CH_DATABASE qv banco lógico (<db>_local em cluster)
QV_CH_SECURE false HTTPS para o ClickHouse
QV_CH_CLUSTER vazio nome do cluster (ativa o schema replicado/distribuído)
QV_CHDB_PATH /var/lib/quantix/chdb diretório do chdb
QV_NATS_URL nats://nats:4222 servidor(es) NATS (lista separada por vírgula)
QV_NATS_USER / QV_NATS_PASSWORD vazio autenticação NATS
QV_MASTER_KEY vazio → gerada em <data_dir>/master.key chave Fernet que cifra os segredos. Não altere após instalar
QV_JWT_SECRET vazio → gerado em <data_dir>/jwt.secret assinatura dos JWT (trocar invalida sessões)
QV_JWT_ACCESS_MINUTES 30 validade padrão do access token (a API usa security.session_minutes da GUI no login)
QV_JWT_REFRESH_DAYS 7 validade do refresh token
QV_ADMIN_USERNAME admin administrador criado no primeiro boot
QV_ADMIN_PASSWORD vazio → senha temporária no log senha inicial. O instalador deixa vazia para o assistente /setup criar o administrador
QV_SETUP_TOKEN vazio token do assistente de primeira execução (usado só com QV_ADMIN_PASSWORD vazio e enquanto a configuração estiver pendente)
QV_TLS_DIR /var/lib/quantix-tls volume compartilhado com o web para o certificado enviado pela GUI
QV_API_URL http://api:8000 URL da API usada pelo coletor
QV_COLLECTOR_TOKEN vazio token do coletor (no serviço api: registra o coletor padrão)
QV_COLLECTOR_NAME hostname nome do coletor
QV_COLLECTOR_TRANSPORT nats nats ou https
QV_COLLECTOR_CONCURRENCY 32 concorrência inicial (substituída por collection.max_parallel_devices)
QV_AUTOMATION_DIR /var/lib/quantix/automation diretórios temporários dos runbooks
QV_EMBEDDED_WORKERS false a API roda ingestor e engine (modo laboratório)
QV_LOG_LEVEL INFO nível de log
QV_LOG_JSON true log JSON
QV_API_WORKERS 2 (CLI) / 4 (compose) workers uvicorn padrão do quantix api
QV_PUBLIC_API_URL QV_API_URL URL entregue pelo runbook Implantar coletor remoto (compose: QV_PUBLIC_URL)

Variáveis padrão também respeitadas: HTTPS_PROXY/NO_PROXY (httpx), SSL_CERT_FILE (CA adicional), TZ.

Implantação (.env do compose / Makefile)

Documentadas linha a linha em .env.example:

Grupo Variáveis
Imagens QV_REGISTRY, QV_VERSION, QV_POSTGRES_IMAGE, QV_CLICKHOUSE_IMAGE, QV_CLICKHOUSE_KEEPER_IMAGE, QV_NATS_IMAGE, TZ
Acesso web QV_PUBLIC_URL, QV_SERVER_NAME, QV_HTTPS_PORT, QV_HTTP_PORT, QV_HTTPS_BIND, QV_HTTP_BIND, QV_CERTS_DIR; no container web: QV_API_UPSTREAM
PostgreSQL POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, PG_MAX_CONNECTIONS, PG_SHARED_BUFFERS, PG_EFFECTIVE_CACHE_SIZE, PG_WORK_MEM, PG_MAINTENANCE_WORK_MEM, PG_MAX_WAL_SIZE, PG_SHM_SIZE, PG_LOG_MIN_DURATION_MS, PG_MAX_WORKER_PROCESSES, PG_MAX_PARALLEL_WORKERS, PG_MAX_PARALLEL_WORKERS_PER_GATHER
ClickHouse CLICKHOUSE_USER, CLICKHOUSE_PASSWORD, CLICKHOUSE_DB, CLICKHOUSE_INTERSERVER_PASSWORD (cluster), QV_CH_HOST, QV_CH_PORT, QV_CH_SECURE, QV_CH_CLUSTER, QV_CH_HOST_CLUSTER
NATS NATS_USER, NATS_PASSWORD, QV_NATS_URL
Segurança QV_MASTER_KEY, QV_JWT_SECRET, QV_JWT_ACCESS_MINUTES, QV_JWT_REFRESH_DAYS, QV_ADMIN_USERNAME, QV_ADMIN_PASSWORD
Coletores QV_COLLECTOR_TOKEN, QV_COLLECTOR_NAME, QV_COLLECTOR_CONCURRENCY, QV_COLLECTOR_TOKEN_2/_3, QV_COLLECTOR_NAME_2/_3 (scale)
Escala e recursos QV_API_WORKERS, QV_INGESTOR_REPLICAS, QV_PG_POOL_SIZE, PG_CPUS, PG_MEMORY, CH_CPUS, CH_MEMORY, NATS_CPUS, NATS_MEMORY, API_CPUS, API_MEMORY, INGESTOR_CPUS, INGESTOR_MEMORY, ENGINE_CPUS, ENGINE_MEMORY, COLLECTOR_CPUS, COLLECTOR_MEMORY, AUTOMATION_CPUS, AUTOMATION_MEMORY, WEB_CPUS, WEB_MEMORY, LAB_API_MEMORY; no porte grande, <SERVIÇO>_CPUS_LARGE (PG, CH, NATS, API, INGESTOR, ENGINE, AUTOMATION, COLLECTOR) e KEEPER_CPUS (cluster). O instalador limita todos ao total de vCPUs do servidor
Proxy QV_HTTPS_PROXY, QV_NO_PROXY
Logs QV_LOG_LEVEL, QV_LOG_JSON, QV_LOG_MAX_SIZE, QV_LOG_MAX_FILE
Backup / demo QV_BACKUP_DIR, QV_BACKUP_RETENTION_DAYS, QV_CH_BACKUP_METHOD, QV_COMPOSE_FILES, QV_DEMO_DAYS

Valores <gerar> do .env.example são preenchidos por make gen-env (deploy/scripts/gen-env.py): senhas alfanuméricas de 32 caracteres, QV_MASTER_KEY Fernet (32 bytes base64-url), QV_JWT_SECRET de 64 caracteres, QV_COLLECTOR_TOKEN qvc_… e QV_ADMIN_PASSWORD de 20 caracteres. Valores existentes são preservados.