Pular para conteúdo

Instalação

O instalador grava o log completo de cada execução em .install/logs/<data>-<etapa>.log e o resultado das verificações em .install/preflight.json. Depois de corrigir a causa, rode o mesmo comando de novo: a instalação é idempotente e preserva segredos e dados.

tail -n 80 .install/logs/$(ls -t .install/logs | head -1)
./install.sh install --verbose          # mostra toda a saída do Ansible

Antes de instalar (preflight)

Mensagem Causa Solução
Sistema operacional … (suportados: …) distribuição fora da lista RHEL/Rocky/Alma/Oracle 8–9, Ubuntu 22.04/24.04 ou SLES/openSUSE Leap 15
vCPUs/Memória/Disco com ✖ abaixo do mínimo absoluto aumente a VM; para piloto, use o porte small
Disco … livres em / o data-root do Docker está no disco do sistema monte o disco de dados e use docker_data_root
Portas HTTP/HTTPS em uso por outro serviço: httpd Apache/nginx/outro na 80/443 pare o serviço ou mude QV_HTTPS_PORT/QV_HTTP_PORT (variáveis avançadas)
Acesso a download.docker.com … sem acesso sem internet ou proxy https_proxy, espelho em docker_repo_base_url, ou Docker pré-instalado com docker_install: never
Acesso a registry-1.docker.io … 403/timeout registro bloqueado registro interno (image_source: registry + registry), ou pacote offline (bundle)
Pacote offline … não encontrado caminho errado bundle_file com caminho absoluto no controlador
Compose 2.24+ é necessário e docker_install=never plugin compose antigo atualize docker-compose-plugin
DNS do endereço público (aviso) registro DNS ausente crie o registro; até lá, acesse pelo IP e aceite o alerta do certificado
Relógio (NTP) (aviso) chrony/NTP desativado sudo systemctl enable --now chronyd (RHEL) ou systemd-timesyncd (Ubuntu)

Durante a instalação

Sintoma Causa provável Solução
UNREACHABLE / Permission denied (publickey) usuário, chave ou porta SSH teste ssh -p <porta> <usuario>@<host>; informe ssh_key
Missing sudo password sudo exige senha ./install.sh install -K ou export QV_BECOME_PASSWORD=…
Host key verification failed chave do host mudou confira o servidor e remova a linha antiga de ~/.ssh/known_hosts
falha em Construir imagem do backend com Forbidden/timeout build sem acesso a Docker Hub/PyPI/npm libere os destinos ou use bundle
Imagens ausentes no servidor: … pacote offline incompleto ou registro sem a imagem gere o pacote de novo com ./install.sh bundle; para infraestrutura, espelhe postgres, clickhouse, nats
pull access denied for quantix/quantix-vision-… image_source: registry sem as imagens do Quantix no registro publique-as (make build push REGISTRY=…) ou use build/bundle
range of CPUs is from 0.01 to N limite de CPU acima do servidor o instalador ajusta automaticamente; rode de novo. Valores manuais no .env acima de N também são corrigidos
tempo esgotado em Aguardar API saudável banco/ClickHouse sem recursos ou disco lento no servidor: cd /opt/quantix && sudo docker compose ps e sudo docker compose logs --tail=100 api clickhouse postgres
Verificar acesso pelo nginx falha certificado ausente/ilegível ou porta bloqueada pelo firewall local sudo docker compose logs web (procure 40-quantix-tls); firewall-cmd --add-service=https

Depois de instalar

Sintoma Solução
Página abre o login em vez de /setup o assistente já foi concluído, ou QV_ADMIN_PASSWORD estava definido (veja Assistente)
token de instalação inválido copie o token de ./install.sh setup-link; o link deve conter #token=
muitas tentativas com token inválido aguarde 15 minutos ou reinicie o serviço api
Certificado aplicado, mas o navegador mostra o antigo aguarde 15 s e recarregue com Ctrl+F5; veja docker compose logs web \| grep 40-quantix-tls
o nginx recusou o certificado novo cadeia ou chave inválidas para o OpenSSL do nginx; o certificado anterior continua ativo
Perdi a senha do administrador local no servidor: cd /opt/quantix && sudo docker compose exec api quantix reset-admin --username <usuario>

Reinstalar do zero (laboratório)

Apaga todos os dados

Use somente em ambiente de teste. Em produção, prefira restaurar um backup.

cd /opt/quantix && sudo docker compose down -v      # remove containers e volumes
sudo rm -f /opt/quantix/.env                         # novos segredos e novo token
sudo ./install.sh install --yes                      # a partir do controlador