Solução de problemas

Este artigo organiza as etapas de diagnóstico por sintoma. Princípio geral: primeiro execute consultas somente leitura para coletar evidências; só depois realize operações que alterem o sistema. A cada etapa, registre os sintomas observados, os comandos executados e seus códigos de saída, além das diferenças entre o resultado esperado e o obtido.

Dispositivo inacessível (não é possível conectar por SSH)

Investigue por camadas, sem confundir problemas de níveis diferentes:

1. Confira o endereço no inventário de dispositivos (endereços semelhantes não são intercambiáveis);
2. Verifique, nesta ordem, a resolução de endereços, o roteamento, a conectividade da porta SSH e o método de autenticação;
3. Se um dispositivo anteriormente acessível perder a conexão repentinamente, relacione o ocorrido aos horários das últimas atualizações ou reinicializações. Se necessário, solicite uma verificação local da porta serial ou do estado físico.

Falha de inicialização ou reinicializações repetidas

1. Colete a saída da inicialização, os logs da inicialização anterior (journalctl -b -1), a causa de reset do watchdog e os erros do sistema de arquivos;
2. Identifique a etapa da falha: carregador de inicialização, kernel, alternância de sistema, inicialização de serviços, reset pelo watchdog ou acionamento por uma aplicação;
3. Verifique o contador de inicializações (bootcount): falhas consecutivas acionam a política de recuperação automática — ao atingir os limites, o dispositivo entra sucessivamente no modo de recuperação e na reversão de partição (consulte Sistema duplo A/B e alternância);
4. Consulte o estado atual de recuperação com jelina-info e jelina-auto-recovery --state.

Não alterne partições nem execute uma reversão manual antes de identificar a causa, para não comprometer o fluxo de recuperação automática.

Sistema em estado degradado (degraded)

systemctl is-system-running
systemctl --failed --no-pager

Verifique individualmente os serviços que falharam e, depois, os serviços essenciais. Observe que a falha de serviços opcionais específicos de uma plataforma não significa necessariamente uma anomalia do sistema; também é normal que serviços de execução única fiquem inativos após terminar.

Atualização parada

1. Consulte o estado e o progresso da atualização (jelina-info --get ota_status --json, jelina-local-ota -s);
2. Verifique se há uma atualização pendente de confirmação (com confirmação local habilitada, aguardar a confirmação é um estado previsto pela política, não um travamento);
3. Verifique o serviço e os logs do agente do dispositivo;
4. Verifique o espaço em disco, o estado do instalador de atualizações e os processos;
5. Verifique a acessibilidade do pacote de atualização, o relógio do sistema, a resolução de nomes de domínio e os certificados;
6. Determine se a atualização já foi instalada e está apenas aguardando uma reinicialização ou remontagem para entrar em vigor.

Durante o diagnóstico, não submeta nem confirme repetidamente a atualização e não exclua os marcadores de estado que indicam uma reinicialização pendente.

Aplicação ou contêiner indisponível

Verifique cada etapa separadamente: estado desejado, download da imagem, criação do contêiner, integridade do processo, portas e firewall, e estado da própria aplicação. Comandos comuns:

docker ps                # Estado dos contêineres
docker logs <nome_do_contêiner>      # Logs dos contêineres

Antes de preservar as evidências da ocorrência, não recrie manualmente contêineres ou serviços gerenciados pelo sistema.

Disco cheio ou diretório raiz somente leitura

1. Compare o uso de espaço e a quantidade de arquivos nas partições raiz e de dados (df -hT, df -i);
2. Verifique se o dispositivo entrou no modo de raiz temporária (jelina-enter-tmpfs-root --status; consulte Armazenamento e partição de dados);
3. Distinga três situações: a partição do sistema é somente leitura por projeto (normal), há uma falha na partição de dados ou a camada de sobreposição não foi montada corretamente.

Não exclua diretórios do sistema ou de pacotes que você não reconheça. Não execute operações de negócio no modo de raiz temporária.

Falha de registro ou desconexão da nuvem

1. Consulte o estado do registro (jelina-manual-register --check; consulte Registro e conexão de dispositivos);
2. Verifique se o dispositivo está no modo offline;
3. Verifique o relógio do sistema, a resolução de nomes de domínio, o roteamento, os certificados e a acessibilidade do endpoint da nuvem;
4. Verifique o estado e os erros dos serviços de registro e do agente do dispositivo;
5. Identifique a categoria da falha: ativação inicial incompleta, credencial inválida, falha de rede ou rejeição pela nuvem.

O serviço não inicia

Verifique, nesta ordem: condições de inicialização do serviço, existência e permissões do arquivo do programa, interpretador de scripts e disponibilidade das montagens necessárias.

Problemas de horário ou resolução de nomes de domínio

• Problemas de horário costumam causar falhas na validação de certificados ou na autenticação com a nuvem: compare o horário do sistema, o relógio de hardware e os logs do serviço de sincronização de horário;
• Problemas de resolução de nomes de domínio: verifique o estado do serviço de resolução e as configurações da conexão de rede. Não sobrescreva manualmente os arquivos de configuração de resolução gerados pelo sistema.

Interface gráfica (GUI) indisponível

Um terminal acessado por SSH normalmente não dispõe de um ambiente de sessão de desktop. Uma variável de exibição vazia não significa falha da interface:

1. Confira a opção geral de habilitação da interface e o escopo de desabilitação;
2. Verifique o estado das instâncias e das sessões da interface (jelina-ui-ctl list, jelina-ui-ctl sessions);
3. Verifique as sessões de login gráfico ativas e consulte o estado e os logs dos processos da interface no ambiente do usuário de destino.

Evidências históricas para problemas de reinicialização

Alguns dispositivos têm arquivamento histórico de desempenho e logs persistentes habilitados, que permitem consultar o estado do sistema antes da reinicialização:

journalctl --list-boots              # Lista de inicializações
journalctl -b -1 -p warning..alert   # Logs de aviso da inicialização anterior
ls -1t /var/log/atop | head          # Arquivo histórico de desempenho

Para determinar a causa de uma reinicialização inesperada, correlacione a lista de inicializações, os logs da inicialização anterior, a causa de reset do watchdog, o tempo de atividade e o histórico de atualizações e alternâncias de partição.

Documentação relacionada

• FAQs — respostas às perguntas frequentes
• Sistema duplo A/B e alternância — contador de inicializações e reversão
• Watchdog — supervisão da integridade do sistema.
• Estado e informações do sistema — comandos de consulta de estado