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.