Manual de atualização¶
Como atualizar o Quantix Vision AI com segurança — pela interface ou pela linha de comando —, o que conferir antes, como validar depois e como voltar atrás se algo não ficar como esperado.
Toda atualização faz um backup antes de aplicar e, se a nova versão não ficar saudável, volta sozinha para a anterior. A API aplica o DDL do PostgreSQL e do ClickHouse no boot (idempotente), por isso é atualizada primeiro; ingestores podem ser reiniciados a qualquer momento, pois mensagens não confirmadas permanecem no JetStream e são reentregues.
Qual caminho usar¶
| Situação | Caminho recomendado |
|---|---|
| Instalação padrão, com acesso à interface | Pela interface (agente do host) — envie o pacote .zip e acompanhe ao vivo |
| Acesso ao servidor por SSH, sem usar a GUI | Linha de comando — ./install.sh upgrade |
| Servidor sem internet (isolado) | Bundle offline por CLI (traz as imagens embutidas) |
| Vários servidores / cluster | Ansible ou a construção de cluster pela interface |
Pré-requisitos¶
Não há pré-requisito de número de versão. O atualizador vai direto da versão em execução para a nova, em um passo só, e pular várias versões de uma vez é suportado (as migrações são cumulativas e idempotentes no boot). Fazer downgrade não é bloqueado, mas não é recomendado; atualizar para o mesmo número é tratado como reinstalação.
Os pré-requisitos reais são operacionais:
- A API atual precisa estar respondendo (
/api/health). O atualizador aborta se a versão em execução não responde — corrija antes (docker compose -p quantix ps). - Espaço em disco no volume de dados e no host (para o backup e as imagens).
- O host consegue construir/baixar as imagens: o pacote de atualização é de código, e o host reconstrói as imagens da nova versão a partir dele — isso exige acesso para baixar as imagens-base (postgres, clickhouse, nats). Em ambiente isolado, use o bundle offline (abaixo).
- Pela interface: o agente do host precisa estar conectado (Administração › Plataforma mostra “conectado”). É ele quem executa a atualização, já que os containers não têm acesso ao Docker.
Confira o estado antes e depois
Abra Administração › Diagnóstico antes e depois de atualizar: ele mostra de uma vez o que está em execução e o que está pendente.
Pela interface (recomendado)¶
O superadministrador atualiza em Administração › Plataforma › Atualizar versão. Quem executa é o agente do host — um serviço systemd no servidor.
1. Garanta o agente conectado¶
Se a tela não mostrar o agente como conectado, instale-o pela própria interface: em
Administração › Plataforma, Instalar agente do host baixa o install-quantix-agent.sh já
preenchido (URL pública e token); rode-o uma vez no servidor, como root, e a tela acompanha a conexão
ao vivo:
2. Envie o pacote da nova versão¶
Em Atualizar versão, clique em Enviar pacote e selecione o .zip da nova versão
(ex.: Quantix_update_7.0.zip). Ao receber, a plataforma confere a estrutura e lê a versão; o pacote
aparece na lista com tamanho e SHA-256.
3. Atualize¶
Clique em Atualizar na linha do pacote e confirme. O agente então:
- confere o SHA-256 do pacote;
- cria um backup (“antes de atualizar”) — marque a opção para incluir o histórico de métricas (mais lento e maior) quando quiser;
- guarda os arquivos e imagens atuais como ponto de rollback;
- aplica a nova versão, reconstrói as imagens e espera a API responder saudável.
A tela mostra o progresso e o log ao vivo. Os serviços ficam fora do ar por alguns minutos. Se a nova versão não ficar saudável, a anterior volta automaticamente. Quando terminar, recarregue a página para usar a nova interface.
Jump de várias versões
Pode enviar o pacote da 7.0 mesmo vindo de uma 6.x anterior — não é preciso passar por versões intermediárias.
Pela linha de comando¶
A API aplica as migrações no boot; o install.sh/quantix-update.sh faz backup, aplica a nova versão,
reinicia em ondas e verifica a saúde, com rollback automático em caso de falha.
cd /opt/quantix # pasta da instalação (com o .env)
./install.sh upgrade # backup, nova versão, reinício em ondas e verificação de saúde
Usa as respostas gravadas em .install/answers.yml. Com o pacote offline da nova versão, extraia-o
e execute ./install.sh upgrade a partir dele.
Faz backup (quantix_upgrade_backup_first), atualiza arquivos e .env, baixa as imagens e reinicia
em ondas na ordem api, ingestor, engine, automation, collector, web, verificando a saúde. No fim,
mostra a versão em execução lida de /api/health.
Ambiente sem internet (offline)¶
Em servidores isolados, use o bundle offline da nova versão (traz as imagens embutidas, sem
Docker Hub nem PyPI). Gere-o em uma máquina com internet com ./install.sh bundle, leve o arquivo ao
servidor e:
tar -xf quantix-vision-ai-8.3.0-offline.tar
cd quantix-vision-ai-8.3.0
sudo ./install.sh upgrade # usa as imagens do próprio bundle
O pacote .zip enviado pela interface é de código e depende de o host alcançar as imagens-base;
por isso, em ambiente isolado, prefira o bundle offline por CLI.
Coletores remotos¶
Atualize a imagem do coletor remoto (docker pull + recriar o container, ou
ansible-playbook collector.yml -e quantix_version=8.3.0). Um coletor de versão anterior continua
funcionando enquanto o contrato da API do coletor não mudar (a versão aparece na tela Coletores).
Plugins enviados pela interface¶
Plugins enviados em Administração › Plataforma › Plugins de coleta ficam no volume de dados
(<data_dir>/plugins) e persistem entre atualizações. Depois de atualizar, os coletores
(local e remotos) ressincronizam os plugins enviados automaticamente. Veja
Plataforma.
Verificação pós-atualização¶
- Recarregue a interface e confira a versão em execução em Administração › Plataforma.
- Abra Administração › Diagnóstico: todos os serviços devem aparecer em execução.
-
Pela linha de comando:
Rollback (voltar atrás)¶
Cada atualização cria um ponto de rollback (arquivos + imagens da versão anterior) e um backup.
Em Atualizar versão, use Voltar para a versão anterior. Por padrão os dados atuais são
mantidos. Para restaurar também os dados do backup feito antes da atualização, marque a opção e
digite RESTAURAR para confirmar — tudo o que mudou desde a atualização (inventário, achados,
configurações, usuários) será perdido.
Migrações
O schema do PostgreSQL é criado com create_all (cria tabelas novas, mas não altera colunas
existentes). Versões futuras que mudem colunas trarão migrações Alembic — leia as notas de versão
no Changelog. No ClickHouse, views de rollup antigas são recriadas
automaticamente quando necessário. Por isso um rollback de código é seguro, mas, se a nova versão
tiver criado estruturas novas, o caminho totalmente limpo é o rollback --with-data.
O agente do host em detalhe¶
O agente é um serviço systemd que executa, no servidor, as operações pedidas pela interface (os containers não têm acesso ao Docker). A forma recomendada de instalar é pela própria interface (acima); pela linha de comando o resultado é o mesmo:
cd /opt/quantix # pasta da instalação (com o .env)
sudo ./install.sh agent # ou: ansible-playbook -i inventory/hosts.yml deploy/ansible/agent.yml
systemctl status quantix-agent
journalctl -u quantix-agent -f
O instalador grava /etc/quantix/agent.env (QV_API_URL, QV_AGENT_TOKEN, QV_AGENT_TLS_VERIFY=auto,
0600, root) e habilita o serviço (systemctl enable --now quantix-agent). Quando a pasta da
instalação não está presente, ele baixa o programa do agente da API (rota /api/v1/agent/program,
autenticada pelo token). O playbook deploy/ansible/agent.yml (role agent):
- gera
QV_AGENT_TOKENno.envse ainda não existir e recria só o container da API para lê-lo; - copia
deploy/agent/quantix-agent.pypara/usr/local/lib/quantix-agent/e a unidadequantix-agent.service(com um drop-in que aponta para o Python 3.9+ encontrado); - grava
/etc/quantix/agent.env(pasta da instalação, arquivos compose em uso, pasta doinstall.sh); - inicia o serviço e espera ele conectar (
quantix-agent.py --check).
O agente consulta a API pelo nginx local (https://127.0.0.1, porta QV_HTTPS_PORT) com o cabeçalho
X-Agent-Token, executa uma operação por vez e devolve o log ao vivo:
| Operação | Comando executado no host |
|---|---|
| Atualizar versão | baixa o pacote, confere o SHA-256 e roda deploy/scripts/quantix-update.sh update <pacote.zip> --yes [--with-metrics] (backup antes e rollback automático em caso de falha) |
| Rollback | deploy/scripts/quantix-update.sh rollback --yes [--with-data] |
| Plano do instalador | ./install.sh plan --answers <arquivo> --json |
| Verificar servidores do cluster | ./install.sh preflight --answers <arquivo> --yes |
| Construir/expandir cluster | ./install.sh expand --answers <arquivo> --yes |
| Verificar DNS | resolve os nomes com o resolvedor do próprio host (DNS, /etc/hosts) |
O arquivo de respostas é gravado com permissão 0600 em /var/lib/quantix-agent e apagado ao fim;
senhas de SSH/sudo digitadas na GUI só chegam ao processo pelas variáveis QV_SSH_PASSWORD e
QV_BECOME_PASSWORD. Uma cópia de cada log fica em /var/log/quantix-agent/<operação>.log.
Depois de uma atualização, se o pacote trouxer outra versão do agente, ele se substitui e o systemd o
reinicia. Parar ou reiniciar o serviço não interrompe uma atualização em andamento (KillMode=process).
Variáveis de /etc/quantix/agent.env: QV_INSTALL_DIR, QV_AGENT_SOURCE_DIR, QV_AGENT_URL,
QV_AGENT_TLS_VERIFY (auto só dispensa a validação do certificado em loopback), QV_AGENT_CA_FILE,
QV_COMPOSE_FILES, QV_COMPOSE_PROJECT, QV_AGENT_POLL e QV_AGENT_HEARTBEAT. Para remover:
ansible-playbook deploy/ansible/agent.yml -e quantix_agent_state=absent.
Se algo der errado¶
- A atualização falhou e voltou sozinha: a instalação já está de volta na versão anterior; veja o
log da operação na tela (ou
docker compose -p quantix logs api) para a causa. - A API não responde depois:
docker compose -p quantix pse... logs api; se necessário, faça o rollback pela interface ou por CLI. - Agente desconectado:
systemctl status quantix-agentejournalctl -u quantix-agent -f. - Mais em Troubleshooting › Instalação.