Solicitar Demonstração

Guia de Solução de Problemas

Este guia ajuda a diagnosticar e resolver problemas comuns no PKIGuardian.

Índice

Problemas na Interface Web

Não Consigo Acessar a Interface Web

Sintomas: O navegador não consegue acessar a interface web

Soluções:

  1. Verifique se a URL está correta
  2. Verifique se o serviço está em execução: 
    # Verificar status do serviço
systemctl status pkiguardian-web  # Linux
# Ou
docker ps | grep pkiguardian      # Docker
  3. Verifique se as regras de firewall permitem a porta 5001 (HTTPS) ou 5000 (HTTP)
  4. Verifique se o certificado SSL é válido (ou aceite o autoassinado para desenvolvimento)

Páginas Carregam Lentamente

Sintomas: Páginas demoram mais de 5 segundos para carregar

Soluções:

  1. Verifique a latência de rede para o servidor
  2. Limpe o cache do navegador (Ctrl+Shift+Delete)
  3. Desative extensões do navegador temporariamente
  4. Verifique os recursos do servidor (CPU, memória)
  5. Revise os filtros — conjuntos de resultados grandes podem tornar a renderização mais lenta

Atualizações em Tempo Real Não Funcionam

Sintomas: O dashboard não atualiza automaticamente

Soluções:

  1. Verifique a conexão WebSocket nas ferramentas de desenvolvimento do navegador (F12 > Network > WS)
  2. Verifique se o firewall permite conexões WebSocket
  3. Verifique se o hub SignalR está em execução: 
    curl https://seu-servidor/hubs/notifications
  4. Recarregue a página forçando atualização (Ctrl+Shift+R)

Gráficos Não São Exibidos

Sintomas: Gráficos de análises aparecem em branco ou com erros

Soluções:

  1. Verifique o console do navegador para erros JavaScript (F12)
  2. Certifique-se de que o JavaScript está habilitado
  3. Verifique se existem dados para o intervalo de tempo selecionado
  4. Tente um navegador diferente
  5. Limpe o cache do navegador

Loop de Redirecionamento no Login

Sintomas: Após o login, redireciona de volta para a página de login

Soluções:

  1. Limpe os cookies do navegador para o domínio
  2. Verifique se o serviço de autenticação está em execução
  3. Verifique a configuração do token JWT no appsettings.json
  4. Verifique se a hora do sistema está sincronizada (a expiração do JWT depende da hora)

Problemas na CLI

Comando Não Encontrado

Sintomas: pkiguardian: command not found

Soluções:

  1. Verifique a instalação: 
    which pkiguardian
ls -la /usr/local/bin/pkiguardian
  2. Adicione ao PATH: 
    export PATH=$PATH:/usr/local/bin
# Adicione ao ~/.bashrc ou ~/.zshrc para persistência
  3. Use o caminho completo: /usr/local/bin/pkiguardian
  4. Reinstale a CLI

Autenticação Falha

Sintomas: Erro 401 Unauthorized

Soluções:

  1. Verifique se a chave de API está correta: 
    pkiguardian config get api-key
  2. Regere a chave de API na Interface Web (Configurações > Chaves de API)
  3. Verifique a configuração do perfil: 
    pkiguardian config profile list
  4. Teste a conexão: 
    pkiguardian config test

Timeout de Conexão

Sintomas: Connection timeout ou 504 Gateway Timeout

Soluções:

  1. Verifique se a URL da API está correta: 
    pkiguardian config get api-url
  2. Teste a conectividade: 
    curl https://api.pkiguardian.com/health
  3. Aumente o timeout: 
    pkiguardian config set timeout 60
  4. Verifique as configurações de firewall/proxy

Problemas de Formato de Saída

Sintomas: Saída ilegível ou inesperada

Soluções:

  1. Especifique o formato explicitamente: 
    pkiguardian certificate list --format json
  2. Desative as cores para uso em pipe: 
    pkiguardian certificate list --no-color | grep "algo"
  3. Verifique o encoding do terminal (deve ser UTF-8)

Problemas no Aplicativo MAUI

Aplicativo Não Instala

iOS:

  1. Verifique a versão do iOS (requer 15.0+)
  2. Certifique-se de ter espaço de armazenamento suficiente
  3. Tente excluir e reinstalar
  4. Verifique se o Apple ID está conectado

Android:

  1. Verifique a versão do Android (requer 8.0+)
  2. Habilite “Instalar de fontes desconhecidas” se instalando manualmente
  3. Certifique-se de ter espaço de armazenamento suficiente
  4. Limpe o cache do Google Play

Aplicativo Fecha ao Iniciar

Soluções:

  1. Forçar fechamento e reiniciar:
    • iOS: Deslize para cima no alternador de apps
    • Android: Configurações > Apps > PKIGuardian > Forçar Parada
  2. Limpar cache do app:
    • iOS: Excluir e reinstalar
    • Android: Configurações > Apps > PKIGuardian > Limpar Cache
  3. Verificar logs:
    • iOS: Configurações > Privacidade > Análises > Dados de Análise
    • Android: Use logcat: adb logcat | grep PKIGuardian
  4. Reinstalar o aplicativo

Sincronização Não Funciona

Sintomas: Fila offline não é enviada

Soluções:

  1. Verifique a conectividade com a internet
  2. Sincronização manual: Configurações > Sincronizar > Sincronizar Agora
  3. Verifique as configurações de sincronização: Configurações > Sincronizar > Sincronização Automática
  4. Revise a fila offline por erros: Configurações > Fila Offline
  5. Faça login novamente se a autenticação tiver expirado

Scanner de QR Code Não Funciona

Sintomas: A câmera não lê os QR codes

Soluções:

  1. Conceder permissão à câmera:
    • iOS: Configurações > Privacidade > Câmera > PKIGuardian
    • Android: Configurações > Apps > PKIGuardian > Permissões > Câmera
  2. Melhorar as condições de leitura:
    • Melhor iluminação
    • Limpar a lente da câmera
    • Ajustar distância (10–30cm)
    • Manter a câmera estável
  3. Use a entrada manual se a leitura do QR code falhar

Login Biométrico Falha

iOS:

  1. Configurações > Face ID & Código > Verifique se o PKIGuardian tem permissão
  2. Registre novamente o Face ID/Touch ID nas configurações do sistema
  3. Desative e reative nas Configurações do PKIGuardian > Segurança

Android:

  1. Configurações > Segurança > Impressão Digital/Face > Registrar novamente
  2. Certifique-se de que o sensor de impressão digital está limpo
  3. Desative e reative nas Configurações do PKIGuardian > Segurança

Problemas de Certificados

Solicitação de Certificado Presa em Pendente

Sintomas: A solicitação não avança além do status “Pendente”

Soluções:

  1. Verifique se a aprovação é necessária:
    • Interface Web: Certificados > Solicitações > Ver detalhes
    • CLI: pkiguardian approval list --pending
  2. Verifique se a CA está acessível: 
    curl https://ca.exemplo.com/health
  3. Verifique os logs de auditoria por erros:
    • Interface Web: Relatórios > Logs de Auditoria
    • CLI: pkiguardian audit log --recent
  4. Contate o administrador se estiver presa por mais de 24 horas

Renovação de Certificado Falhou

Sintomas: Tentativa de renovação resulta em erro

Soluções:

  1. Verifique se o certificado pode ser renovado:
    • Não expirado
    • Não revogado
    • Dentro da janela de renovação (tipicamente 30 dias antes da expiração)
  2. Verifique a disponibilidade da CA
  3. Verifique se a política de renovação permite renovação
  4. Revise a mensagem de erro nos logs de auditoria
  5. Renovação manual como alternativa: 
    pkiguardian certificate renew <id> --force

Não Consigo Revogar o Certificado

Sintomas: A revogação falha ou é rejeitada

Soluções:

  1. Verifique as permissões: Precisa da permissão de revogação
  2. Certificado já revogado: Verifique o status primeiro
  3. Forneça um motivo válido: Deve selecionar o motivo de revogação
  4. Verifique os serviços CRL/OCSP em execução
  5. Revise os logs de auditoria para o erro específico

Certificado Não é Confiável

Sintomas: Navegador mostra “Não Seguro” ou erro de certificado

Soluções:

  1. Verifique se a cadeia de certificados está completa
  2. Instale o certificado CA raiz no repositório de confiança:
    • Windows: certmgr.msc > Autoridades de Certificação Raiz Confiáveis
    • macOS: Acesso às Chaves > Sistema > Adicionar certificado
    • Linux: Copie para /usr/local/share/ca-certificates/ e execute update-ca-certificates
  3. Verifique as datas do certificado (não expirado, não data futura)
  4. Verifique se o hostname corresponde ao Common Name ou SAN

Problemas com Dispositivos IoT

Cadastro do Dispositivo Falha

Sintomas: O cadastro Zero-Touch não é concluído

Soluções:

  1. Verifique se o QR code não está danificado ou obstruído
  2. Verifique se a URL de cadastro está acessível a partir do dispositivo
  3. Verifique se o dispositivo é suportado (LoRaWAN, CoAP, TPM)
  4. Verifique a política do grupo de dispositivos permite cadastro
  5. Revise os logs do dispositivo para erros específicos
  6. Cadastro manual como alternativa

Atestação TPM Falhou

Sintomas: A verificação de atestação falha

Soluções:

  1. Verifique se o TPM está habilitado no BIOS/firmware do dispositivo
  2. Verifique a versão do TPM (2.0 é obrigatório)
  3. Verifique se o certificado EK é válido e de fabricante confiável
  4. Verifique as configurações de política de atestação
  5. Revise os logs de atestação para o erro específico

Certificado do Dispositivo Expirou

Sintomas: O dispositivo não consegue se comunicar por causa do certificado expirado

Soluções:

  1. Renovação imediata: 
    pkiguardian iot device renew <device-id> --emergency
  2. Verifique se a renovação automática está habilitada:
    • Interface Web: IoT > Grupos de Dispositivos > Política do Grupo
  3. Atualize a configuração do dispositivo para buscar o novo certificado
  4. Verifique se a hora do dispositivo está sincronizada (NTP)

Dispositivo LoRaWAN Não Conecta

Sintomas: O dispositivo LoRaWAN não consegue ingressar na rede

Soluções:

  1. Verifique se o DevEUI está correto e registrado
  2. Verifique se o AppKey/AppEUI corresponde à configuração do Join Server
  3. Verifique se o endpoint do Join Server está acessível
  4. Verifique a cobertura do gateway — o dispositivo deve estar no alcance
  5. Revise os logs do Join Server para tentativas de entrada

Problemas de Desempenho

Consulta/Pesquisa Lenta

Sintomas: Pesquisa ou filtragem leva mais de 10 segundos

Soluções:

  1. Reduza o conjunto de resultados usando filtros
  2. Verifique os índices do banco de dados: 
    -- Verificar índices ausentes
SELECT * FROM sys.dm_db_missing_index_details;
  3. Manutenção do banco de dados: 
    -- Reconstruir índices
ALTER INDEX ALL ON Certificates REBUILD;
-- Atualizar estatísticas
UPDATE STATISTICS Certificates;
  4. Aumente o tamanho do cache no appsettings.json
  5. Habilite paginação na UI/API

Alto Uso de Memória

Sintomas: Aplicação usando mais de 2GB de RAM

Soluções:

  1. Verifique vazamentos de memória nos logs
  2. Reinicie o aplicativo: 
    systemctl restart pkiguardian-web
  3. Reduza o tamanho do cache na configuração
  4. Verifique conjuntos de resultados grandes sem paginação
  5. Revise consultas/relatórios personalizados para ineficiências

Dashboard de Análises Lento

Sintomas: Páginas de análises carregam muito lentamente

Soluções:

  1. Reduza o intervalo de tempo das consultas
  2. Use dados agregados em vez de dados brutos
  3. Pré-calcule estatísticas com tarefas em segundo plano
  4. Verifique o desempenho do modelo de ML — pode precisar de retreinamento
  5. Considere arquivamento de dados antigos

Problemas de Autenticação

MFA Não Funciona

Sintomas: Não consigo completar a autenticação de dois fatores

Soluções:

  1. Verifique a sincronização de hora no dispositivo com o aplicativo autenticador
  2. Use códigos de backup se disponíveis
  3. Regere o segredo MFA:
    • Interface Web: Configurações > Segurança > MFA > Redefinir
  4. Contate o administrador para desabilitar o MFA temporariamente

Sessão Expira Rapidamente

Sintomas: Desconectado após poucos minutos

Soluções:

  1. Verifique a configuração de timeout de sessão: 
    // appsettings.json
"Authentication": {
  "JwtTokenExpiration": 480 // minutos
}
  2. Habilite “Lembrar de mim” durante o login
  3. Verifique a diferença de hora entre cliente e servidor

Não Consigo Redefinir a Senha

Sintomas: E-mail de redefinição de senha não recebido

Soluções:

  1. Verifique a pasta de spam
  2. Verifique a configuração de e-mail no appsettings.json
  3. Verifique os logs de SMTP para erros de envio
  4. Use a redefinição via administrador como alternativa
  5. Verifique se o endereço de e-mail está correto no perfil

Problemas de Rede

Erros de Certificado SSL

Sintomas: “SSL certificate problem” ou “unable to verify”

Soluções:

  1. Apenas para desenvolvimento — desabilite a verificação SSL: 
    pkiguardian config set verify-ssl false
  2. Em produção — instale um certificado SSL adequado: 
    # Exemplo com Let's Encrypt
certbot --nginx -d api.pkiguardian.com
  3. Importe o certificado CA raiz no repositório de confiança
  4. Verifique se a cadeia de certificados está completa

Conexão Recusada

Sintomas: “Connection refused” ou “Cannot connect”

Soluções:

  1. Verifique se o serviço está em execução: 
    systemctl status pkiguardian-api
netstat -tlnp | grep 5000
  2. Verifique as regras de firewall: 
    # Permitir portas
ufw allow 5000/tcp
ufw allow 5001/tcp
  3. Verifique o endereço de bind na configuração (0.0.0.0 vs localhost)
  4. Verifique a resolução de DNS

Problemas com Proxy

Sintomas: Não consigo conectar através do proxy corporativo

Soluções:

  1. Configure o proxy para a CLI: 
    export HTTP_PROXY=http://proxy.empresa.com:8080
export HTTPS_PROXY=http://proxy.empresa.com:8080
export NO_PROXY=localhost,127.0.0.1
  2. Interface Web: Configure nas configurações do navegador
  3. Aplicativo MAUI: Pode ser necessário usar VPN em vez de proxy
  4. Verifique a autenticação do proxy se necessário

Obtendo Suporte

Antes de Contatar o Suporte

Colete estas informações:

  1. Versão: pkiguardian --version ou Configurações > Sobre
  2. Mensagens de erro: Texto exato do erro e capturas de tela
  3. Passos para reproduzir: O que você estava fazendo quando o erro ocorreu
  4. Ambiente: SO, navegador, configuração de rede
  5. Logs: Logs da aplicação se disponíveis

Logs da Aplicação

Logs da Interface Web:

# Linux
tail -f /var/log/pkiguardian/web.log

# Docker
docker logs pkiguardian-web -f

# Windows
Get-Content C:\PKIGuardian\Logs\web.log -Wait

Logs da API:

# Linux
tail -f /var/log/pkiguardian/api.log

# Docker
docker logs pkiguardian-api -f

Modo de Depuração da CLI:

pkiguardian certificate list --debug --verbose 2>&1 | tee debug.log

Logs do MAUI:

  • iOS: Configurações > Privacidade > Análises > Dados de Análise
  • Android: adb logcat -s PKIGuardian:D

Canais de Suporte

  1. Documentação: docs.pkiguardian.com
  2. GitHub Issues: Reportar bugs
  3. Discussões: Fazer perguntas
  4. E-mail: support@pkiguardian.com
  5. Suporte Empresarial: Para opções de suporte enterprise, contate sales@pkiguardian.com

Última Atualização: Maio de 2026 | Versão: Phase 12

Relacionados

Primeiros Passos — Interface Web

Bem-vindo à Interface Web do PKIGuardian! Este guia irá ajudá-lo a começar a usar a interface web.

Ler mais

Primeiros Passos — CLI

Bem-vindo à Interface de Linha de Comando do PKIGuardian! Este guia irá ajudá-lo a instalar e usar

Ler mais

Primeiros Passos — Aplicativo Móvel MAUI

Bem-vindo ao PKIGuardian MAUI! Este guia irá ajudá-lo a instalar e usar o aplicativo móvel para iOS

Ler mais