🔧 Solução de Problemas (Troubleshooting)

Guia completo para resolver os problemas mais comuns do servidor de ativação iOS.

🔍 Diagnóstico Rápido

Passo 1: Verificar se o Servidor Está Respondendo

curl https://sua-url.replit.app/health

✅ Se funcionar: Você verá um JSON com "status": "healthy"
❌ Se não funcionar: Vá para Servidor Não Responde

Passo 2: Testar Geração de Payload

curl "https://sua-url.replit.app/?prd=iPhone14,5&guid=12345678-1234-1234-1234-123456789ABC&sn=TEST123"

✅ Se funcionar: Você verá uma URL de download
❌ Se retornar erro: Veja a seção do erro específico abaixo

❌ Problemas do Servidor

Servidor Não Responde

Sintomas:

Timeout ao acessar qualquer URL
"ERR_CONNECTION_REFUSED"
Página em branco

Soluções:

No Replit:
- Clique no botão "Run" para iniciar o servidor
- Aguarde até ver "PHP Development Server started"
- Verifique se há erros na aba "Console"
Hospedagem Tradicional:
- Verifique se o servidor Apache/Nginx está rodando
- Verifique logs do servidor: /var/log/apache2/error.log
- Certifique-se que o PHP está instalado: php -v
Vercel:
- Acesse o dashboard e veja se há erros de build
- Verifique os logs de deployment
- Certifique-se que vercel.json está configurado corretamente

Erro 500 - Internal Server Error

Sintomas:

Página branca com "Internal Server Error"
Erro genérico do servidor

Diagnóstico:

Ative o modo debug:

# No Replit: vá em Secrets e adicione
DEBUG_MODE=true

Verifique os logs:

# Leia o arquivo de log de hoje
cat logs/server_$(date +%Y-%m-%d).log

Causas Comuns:

Extensão SQLite3 não disponível

Como verificar:

php -m | grep sqlite3

Solução (hospedagem tradicional):

# Ubuntu/Debian
sudo apt-get install php-sqlite3

# CentOS/RHEL
sudo yum install php-sqlite3

# Reinicie o servidor
sudo service apache2 restart

Extensão ZIP não disponível

Como verificar:

php -m | grep zip

Solução:

# Ubuntu/Debian
sudo apt-get install php-zip

# CentOS/RHEL
sudo yum install php-zip

Permissões de Diretório

Como verificar:

ls -la cache/ logs/

Solução:

# Dar permissões de escrita
chmod 755 cache/ logs/

# Ou permissões totais (se necessário)
chmod 777 cache/ logs/

Erro 400 - Bad Request

Sintomas:

JSON retornando "error": "Parâmetros obrigatórios ausentes"

Causa: Faltam parâmetros na requisição

Solução: Certifique-se de enviar todos os parâmetros:

?prd=iPhone14,5&guid=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&sn=SERIAL123

Exemplo correto:

# ✅ CORRETO
curl "https://sua-url.replit.app/?prd=iPhone14,5&guid=12345678-1234-1234-1234-123456789ABC&sn=TEST123"

# ❌ ERRADO (falta guid e sn)
curl "https://sua-url.replit.app/?prd=iPhone14,5"

Erro 404 - Asset Não Encontrado

Sintomas:

{
  "error": "Asset MobileGestalt não encontrado para iPhone14-5",
  "path_expected": "assets/Maker/iPhone14-5/com.apple.MobileGestalt.plist"
}

Causa: Arquivo MobileGestalt para aquele modelo não existe no servidor

Solução:

Verifique quais modelos estão disponíveis:
```
ls assets/Maker/
```

Adicione o arquivo para o modelo desejado:

# Criar pasta (use hífen, não vírgula!)
mkdir -p assets/Maker/iPhone14-5

# Copie o arquivo .plist
cp /caminho/para/com.apple.MobileGestalt.plist assets/Maker/iPhone14-5/

Verifique se foi adicionado corretamente:

ls -la assets/Maker/iPhone14-5/
# Deve mostrar: com.apple.MobileGestalt.plist

⚠️ IMPORTANTE: Use hífen - no nome da pasta, não vírgula ,:

✅ Correto: iPhone14-5
❌ Errado: iPhone14,5

🔌 Problemas do Cliente

Cliente Não Conecta ao Servidor

Sintomas (Windows C#):

Server refused connection
HTTP Error 404
Connection timeout

Sintomas (Mac Python):

urllib.error.URLError
Connection refused

Diagnóstico:

Verifique se a URL está correta:

// C# - deve estar assim:
private const string REMOTE_API = "https://sua-url.replit.app";
// ❌ NÃO adicione / no final!
// ❌ NÃO adicione /index.php!

Teste a URL no navegador:
```
https://sua-url.replit.app/health
```
Deve retornar JSON com status "healthy"

Certifique-se que recompilou o cliente:

# Windows
csc client_windows.cs

# Verifique se o .exe foi atualizado
ls -l client_windows.exe

Soluções:

URL Incorreta: Copie a URL exata do Replit (sem adicionar / ou /index.php)
Servidor Offline: Reinicie o servidor no Replit (botão "Run")
Firewall: Verifique se o firewall não está bloqueando a conexão

Cliente Não Detecta o iPhone

Sintomas:

No device detected
Waiting for device... (infinitamente)
Could not find iOS device

⚠️ Importante: Isso não é problema do servidor! É problema de comunicação USB.

Soluções:

Windows:

Instale iTunes ou Apple Mobile Device Support:
- Baixe iTunes: https://www.apple.com/itunes/
- Ou apenas os drivers: https://support.apple.com/downloads/
Verifique se o iPhone aparece:
```
.\iOS.exe list
```
Confie no computador:
- Conecte o iPhone
- Quando aparecer popup no iPhone: "Confiar neste computador?"
- Toque em "Confiar"
- Digite a senha do iPhone

macOS:

Instale libimobiledevice:
```
brew install libimobiledevice
```
Verifique se detecta o iPhone:
```
idevice_id -l
```
Confie no computador (mesmo procedimento do Windows)

Erro "GUID not found in logs"

Sintomas:

[!] Could not locate GUID in syslog
GUID extraction failed

Causa: O GUID só aparece nos logs do sistema após o primeiro reset do iPhone.

Solução (Processo Normal):

Cliente faz o primeiro reset do iPhone
iPhone reinicia
Cliente aguarda e coleta logs do sistema
GUID é extraído dos logs
Cliente faz a requisição ao servidor com o GUID

Se continuar falhando:

Aguarde mais tempo (pode levar 2-3 minutos)
Verifique se o syslog está sendo coletado
No Mac, certifique-se que tem permissões: sudo python3 offline_bypass.py

📦 Problemas de Assets

Lista de Modelos Disponíveis Está Vazia

Sintomas:

{
  "available_models": []
}

Causa: Nenhum arquivo MobileGestalt foi adicionado ao servidor

Solução:

Adicione pelo menos um modelo:

mkdir -p assets/Maker/iPhone14-5
# Copie o arquivo .plist para dentro desta pasta

Verifique a estrutura:

tree assets/Maker/
# Deve mostrar:
# assets/Maker/
# └── iPhone14-5/
#     └── com.apple.MobileGestalt.plist

Arquivo .plist Corrompido

Sintomas:

Failed to parse plist
Invalid MobileGestalt file

Diagnóstico:

# Verifique se é um arquivo plist válido
file assets/Maker/iPhone14-5/com.apple.MobileGestalt.plist
# Deve mostrar: XML 1.0 document text, ASCII text

# Ou use plutil (macOS)
plutil -lint assets/Maker/iPhone14-5/com.apple.MobileGestalt.plist

Solução:

Obtenha uma cópia válida do arquivo
Certifique-se que não foi corrompido durante upload/download
Verifique se não é um arquivo de texto comum renomeado

🗂️ Problemas de Cache

Cache Não é Criado

Sintomas:

Failed to write cache file
Permission denied on cache/

Diagnóstico:

ls -la cache/
# Verifique as permissões

Solução:

# Dar permissões de escrita
chmod 755 cache/

# Se ainda não funcionar
chmod 777 cache/

# Verifique se há espaço em disco
df -h

Arquivos de Cache Não São Servidos

Sintomas:

404 Not Found ao baixar do /cache/

Causa (hospedagem tradicional): Apache/Nginx bloqueando acesso

Solução (.htaccess):

# Em public/.htaccess
<Directory "../cache">
    Options -Indexes
    Require all granted
</Directory>

Solução (Nginx):

location /cache/ {
    alias /caminho/completo/para/cache/;
    autoindex off;
}

🌐 Problemas de Deploy

Vercel: Arquivos Desaparecem

Causa: Vercel é serverless, arquivos em /cache são efêmeros

Solução: Use Vercel Blob Storage para persistência:

npm install @vercel/blob

Veja detalhes em docs/deployment/DEPLOY_VERCEL.md

Hospedagem Tradicional: Document Root Errado

Sintomas:

Código PHP é exibido como texto
Download de arquivos .php ao invés de executar

Solução:

Configure Document Root para /public:
- No cPanel: Domínios → Editar → Document Root: /public_html/public

Adicione .htaccess:

# Em public/.htaccess
AddHandler application/x-httpd-php .php

📊 Como Ver Logs Detalhados

No Replit:

Ative modo debug em "Secrets":
```
DEBUG_MODE=true
```
Veja logs na aba "Console"
Leia o arquivo: logs/server_YYYY-MM-DD.log

Hospedagem Tradicional:

# Logs do PHP
tail -f /var/log/php_errors.log

# Logs do Apache
tail -f /var/log/apache2/error.log

# Logs da aplicação
tail -f logs/server_$(date +%Y-%m-%d).log

Vercel:

Acesse: https://vercel.com/seu-usuario/seu-projeto
Vá em "Deployments"
Clique no deployment mais recente
Vá em "Functions" → Veja os logs

✅ Checklist de Diagnóstico Completo

Use este checklist quando tiver problemas:

Servidor:

Endpoint /health retorna status "healthy"?
Extensão SQLite3 está habilitada? (php -m | grep sqlite3)
Extensão ZIP está habilitada? (php -m | grep zip)
Diretórios cache/ e logs/ têm permissão de escrita?
Há espaço em disco disponível?

Assets:

Pasta assets/Maker/ existe?
Há pelo menos um modelo com arquivo .plist?
Nome da pasta usa hífen (iPhone14-5) e não vírgula?
Arquivo .plist é válido e não está corrompido?

Cliente:

URL do servidor está correta (sem / no final)?
Cliente foi recompilado após mudar a URL?
iPhone está conectado via USB?
iPhone confia no computador?
Drivers Apple (Windows) ou libimobiledevice (Mac) instalados?

Rede:

Firewall não está bloqueando?
Servidor é acessível pela internet?
CORS está configurado (se necessário)?

🆘 Ainda Não Resolveu?

Ative DEBUG_MODE e capture os logs completos
Reproduza o problema e anote a mensagem de erro exata
Verifique a seção específica deste guia
Consulte a documentação em README.md e docs/API_REFERENCE.md

Lembre-se: A maioria dos problemas é relacionada a permissões, configuração de URL ou falta de assets!

FilesExpand file tree

TROUBLESHOOTING.md

Latest commit

History

TROUBLESHOOTING.md

File metadata and controls

🔧 Solução de Problemas (Troubleshooting)

🔍 Diagnóstico Rápido

Passo 1: Verificar se o Servidor Está Respondendo

Passo 2: Testar Geração de Payload

❌ Problemas do Servidor

Servidor Não Responde

Erro 500 - Internal Server Error

Extensão SQLite3 não disponível

Extensão ZIP não disponível

Permissões de Diretório

Erro 400 - Bad Request

Erro 404 - Asset Não Encontrado

🔌 Problemas do Cliente

Cliente Não Conecta ao Servidor

Cliente Não Detecta o iPhone

Windows:

macOS:

Erro "GUID not found in logs"

📦 Problemas de Assets

Lista de Modelos Disponíveis Está Vazia

Arquivo .plist Corrompido

🗂️ Problemas de Cache

Cache Não é Criado

Arquivos de Cache Não São Servidos

🌐 Problemas de Deploy

Vercel: Arquivos Desaparecem

Hospedagem Tradicional: Document Root Errado

📊 Como Ver Logs Detalhados

No Replit:

Hospedagem Tradicional:

Vercel:

✅ Checklist de Diagnóstico Completo

🆘 Ainda Não Resolveu?