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.