Pular para conteúdo

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:

sudo bash install-quantix-agent.sh    # baixado pela interface; contém o token (segredo)

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:

  1. confere o SHA-256 do pacote;
  2. cria um backup (“antes de atualizar”) — marque a opção para incluir o histórico de métricas (mais lento e maior) quando quiser;
  3. guarda os arquivos e imagens atuais como ponto de rollback;
  4. 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.

cd /opt/quantix
bash deploy/scripts/quantix-update.sh update "/caminho/da/nova-versao.zip"
bash deploy/scripts/quantix-update.sh status          # versão em execução e último ponto de rollback
make backup
sed -i 's/^QV_VERSION=.*/QV_VERSION=8.3.0/' .env
make pull && make up
ansible-playbook upgrade.yml -e quantix_version=8.3.0

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.

helm upgrade qv deploy/helm/quantix-vision --reuse-values \
  --set image.backend.tag=8.3.0 --set image.web.tag=8.3.0

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

  1. Recarregue a interface e confira a versão em execução em Administração › Plataforma.
  2. Abra Administração › Diagnóstico: todos os serviços devem aparecer em execução.
  3. Pela linha de comando:

    curl -fsS https://<seu-host>/api/health         # "status":"ok" e a nova versão
    bash deploy/scripts/quantix-update.sh status
    

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.

bash deploy/scripts/quantix-update.sh rollback                # volta código e imagens; mantém os dados
bash deploy/scripts/quantix-update.sh rollback --with-data    # também restaura os dados do backup

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):

  1. gera QV_AGENT_TOKEN no .env se ainda não existir e recria só o container da API para lê-lo;
  2. copia deploy/agent/quantix-agent.py para /usr/local/lib/quantix-agent/ e a unidade quantix-agent.service (com um drop-in que aponta para o Python 3.9+ encontrado);
  3. grava /etc/quantix/agent.env (pasta da instalação, arquivos compose em uso, pasta do install.sh);
  4. 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 ps e ... logs api; se necessário, faça o rollback pela interface ou por CLI.
  • Agente desconectado: systemctl status quantix-agent e journalctl -u quantix-agent -f.
  • Mais em Troubleshooting › Instalação.