Troubleshooting — TOP 15¶

Problemas comuns e como diagnosticar rapidamente.

1. Cliente diz "EA não opera"¶

Diagnóstico em ordem:

# 1. Está conectado? (heartbeat)
curl https://api.quantfx.com.br/api/ea-status \
  -H "X-API-Key: $CLIENT_KEY" | jq .

# 2. Está recebendo sinais?
curl https://api.quantfx.com.br/api/account/signals?days=1 \
  -H "X-API-Key: $CLIENT_KEY" | jq '.count'

# 3. Há trades reportados?
curl https://api.quantfx.com.br/api/account/executions?days=1 \
  -H "X-API-Key: $CLIENT_KEY" | jq '.executions | length'

Causa típica: AutoTrading desligado no MT5. Confirmar com cliente que botão "Auto Trading" está verde.

2. UptimeRobot vermelho — `/api/health` retorna 503¶

Ver Runbook §1.

ssh henrique@10.8.0.1 "sudo docker ps | grep forex_api"
ssh henrique@10.8.0.1 "sudo docker logs forex_api --tail 50"

Causas comuns:

db: down → ver §3
pred_lag_minutes > 30 → ver §5 (worker)
stale_pred_count alto → algum slot parou (M5 desativado é normal)

3. DB connection failed¶

ssh henrique@10.8.0.1 "sudo docker exec forex_db pg_isready -U forex"
# expected: forex_db:5432 - accepting connections

Se "no response":

ssh henrique@10.8.0.1 "sudo docker logs forex_db --tail 30"

OOM? Aumentar memory limit no docker-compose.vps.yml. Reiniciar:

ssh henrique@10.8.0.1 "cd /opt/quantfx && sudo docker compose -f docker-compose.vps.yml restart db"

4. WireGuard tunnel caído¶

Sintoma: psql falha conectando a 10.8.0.1:5432 do PC local.

# Status interface
Get-NetAdapter | Where-Object {$_.Name -like "*WireGuard*"}

Se "Disconnected":

# Restart WireGuard
& "C:\Program Files\WireGuard\wireguard.exe" /uninstalltunnelservice wg0
& "C:\Program Files\WireGuard\wireguard.exe" /installtunnelservice "C:\Program Files\WireGuard\Data\Configurations\wg0.conf.dpapi"

Se IP mudou (ISP), atualizar UFW na VPS:

ssh henrique@10.8.0.1
sudo ufw status
sudo ufw delete allow from <ip_antigo> to any port 51820 proto udp
sudo ufw allow 51820/udp comment 'WireGuard'

5. Worker não está produzindo predições¶

docker logs forex_worker --tail 100 | grep -E "predict|ERROR|WARN"

Causas:

DB connection refused → .env DB_HOST correto? WireGuard up?
Modelos não encontrados → models/ populado? Champions ativos?
MT5 collector parado → docker logs forex_worker | grep collector
Memory OOM → reduzir batch size de retrain

6. Modelos não estão sendo aplicados (champions degradados)¶

docker exec forex_db psql -U forex -d forex -c "
  SELECT s.symbol, t.tf_code, mr.model_v, mr.is_active, mr.auc_wf, mr.pf_wf
  FROM model_registry mr
  JOIN symbols s USING(symbol_id)
  JOIN timeframes t USING(tf_id)
  WHERE mr.is_active = TRUE
  ORDER BY mr.auc_wf DESC LIMIT 20;"

Se nenhum active:

docker exec forex_worker python scripts/rescreen_champions.py --dry-run

Re-screening com gates atuais. Se necessário:

docker exec forex_worker python scripts/rescreen_champions.py --apply

7. Webhook Eduzz não está provisionando¶

docker logs forex_api --tail 100 | grep -i eduzz

Causas:

HMAC fail: verificar EDUZZ_SECRET no .env da VPS bate com Eduzz dashboard
productId não mapeado: ver PRODUCT_MAP em webhooks.py
Status != "paid": Eduzz só dispara "myeduzz.invoice_paid" se realmente pago

Teste manual:

curl -X POST https://api.quantfx.com.br/webhooks/eduzz \
  -H "x-signature: <hmac_calculado>" \
  -H "Content-Type: application/json" \
  -d '{"event":"myeduzz.invoice_paid","data":{...}}'

8. Email não chega para o assinante¶

docker logs forex_api --tail 200 | grep -i "smtp\|email"

Causas:

App password vencida → renovar no Google Account
Gmail rate limit (500/dia) → migrar pra SendGrid
Email do cliente em spam → orientar a marcar como "Não é spam"
SMTP_USER/SMTP_PASS vazio → conferir .env VPS

Teste manual:

docker exec forex_api python -c "
from app.api.routers.webhooks import _send_email
_send_email('teste@exemplo.com', 'Teste SMTP', '<p>hello</p>')
"

9. Cliente diz que regenerou chave mas EA continua usando antiga¶

Causa: cliente esqueceu de atualizar InpApiKey no MT5.

Validar:

docker exec forex_db psql -U forex -d forex -c "
  SELECT user_name, api_key, last_seen_at, EXTRACT(EPOCH FROM (NOW()-last_seen_at))/60 AS mins_ago
  FROM api_keys
  WHERE email = 'cliente@email.com';"

Se last_seen_at é antigo → realmente o EA não está chamando com a nova chave. Se é recente → chave nova está sendo usada (basta o cliente conferir trade).

10. Sinais de confluência não estão saindo no Telegram¶

docker logs forex_worker --tail 100 | grep -i "confluenc\|broadcast"

Causas:

telegram.yaml channel_id errado
Bot foi removido do canal
Sinais H1/H4 não estão coincidindo (raro mas possível)

Teste manual:

docker exec forex_worker python scripts/_test_telegram.py

11. Partição mensal não foi criada¶

Sintoma: INSERT INTO predictions falha com "no partition matches".

docker exec forex_db psql -U forex -d forex -c "
  SELECT relname FROM pg_class
  WHERE relname LIKE 'predictions_%'
  ORDER BY relname DESC LIMIT 12;"

Se faltar partição do mês corrente:

docker exec forex_db psql -U forex -d forex -c "
  SELECT create_predictions_partition(NOW()::DATE);"

Schtask QuantFX-AutoPartition deveria fazer no dia 25. Verificar:

schtasks /Query /TN QuantFX-AutoPartition /v /fo LIST

12. `pred_id` retorna null¶

Causa rara: sequence predictions_pred_id_seq quebrada após migração.

docker exec forex_db psql -U forex -d forex -c "
  CREATE SEQUENCE IF NOT EXISTS predictions_pred_id_seq;
  ALTER TABLE predictions ALTER COLUMN pred_id SET DEFAULT nextval('predictions_pred_id_seq');
  SELECT setval('predictions_pred_id_seq', (SELECT MAX(pred_id) FROM predictions));"

13. Frontend `/minha-conta` em branco¶

// Console do browser
fetch('/api/account/me', {headers: {'X-API-Key': 'sua-key'}}).then(r => r.json())

401: chave inválida → cliente digitou errado
403: rate limit → aguardar 1 min
500: erro server → ver docker logs forex_api
CORS error: origem não permitida → conferir CORS_ORIGINS no .env

14. Backup B2 falhando¶

schtasks /Query /TN QuantFX-Backup-Diario /v /fo LIST

Ver "Last Result":

0 = sucesso
1 ou outro = erro

Rodar manualmente para ver o erro:

cd C:\Users\henri\Documents\PROJETOS\ML-Forex
.venv\Scripts\python.exe scripts\backup_to_b2.py --full --verbose

Causas comuns:

B2_APP_KEY revogada → gerar nova no Backblaze
Espaço local cheio → limpar backup/local/ antigos
Bucket suspended → conferir billing B2

15. `/api/scan` retorna lista vazia¶

# Confirmar que predictions estão sendo geradas
docker exec forex_db psql -U forex -d forex -c "
  SELECT COUNT(*) FROM predictions
  WHERE created_at >= NOW() - INTERVAL '1 hour';"

Se > 0 mas scan retorna 0:

Filtro de confiança alto demais? prediction.min_probability em model.yaml
Chave do cliente é Basic? Pode estar filtrando todos os símbolos
Worker recém-bootou e ainda não rodou cycle completo

Logs úteis¶

# API requests (FastAPI)
docker logs forex_api --tail 100 | grep -E "GET|POST"

# Worker activity
docker logs forex_worker --tail 100 | grep -E "predict|trained|broadcast"

# DB slow queries (se log_min_duration_statement habilitado)
docker logs forex_db --tail 50 | grep -i "duration"

# Nginx (na VPS, fora dos containers)
ssh henrique@10.8.0.1 "sudo tail -50 /var/log/nginx/access.log"

Troubleshooting — TOP 15¶

1. Cliente diz "EA não opera"¶

2. UptimeRobot vermelho — /api/health retorna 503¶

3. DB connection failed¶

4. WireGuard tunnel caído¶

5. Worker não está produzindo predições¶

6. Modelos não estão sendo aplicados (champions degradados)¶

7. Webhook Eduzz não está provisionando¶

8. Email não chega para o assinante¶

9. Cliente diz que regenerou chave mas EA continua usando antiga¶

10. Sinais de confluência não estão saindo no Telegram¶

11. Partição mensal não foi criada¶

12. pred_id retorna null¶

13. Frontend /minha-conta em branco¶

14. Backup B2 falhando¶

15. /api/scan retorna lista vazia¶

Logs úteis¶

2. UptimeRobot vermelho — `/api/health` retorna 503¶

12. `pred_id` retorna null¶

13. Frontend `/minha-conta` em branco¶

15. `/api/scan` retorna lista vazia¶