Řešení problémů - EmbedDataFeed

📋 Obsah

Základní diagnostika
Problémy se službami
API chyby
Výkonnostní problémy
SSL/HTTPS problémy
Problémy s daty
Údržba systému

🔍 Základní diagnostika

✅ Rychlý checklist

Všechny Docker kontejnery běží Dashboard je dostupný na http://localhost:8085/ API endpointy odpovídají Qdrant databáze obsahuje data Traefik má platný SSL certifikát

🩺 Diagnostické příkazy

# Stav všech služeb
cd /srv/projects/embedDataFeed
docker compose ps

# Health check všech API
curl -s http://localhost:8085/api/proxy?url=http://localhost:8001/health
curl -s http://localhost:8002/health

# Počet produktů v databázi
curl -s http://localhost:8085/api/qdrant-stats | jq '.collections[0].points_count'

# Test vyhledávání
curl -X POST "http://localhost:8085/api/search" \
  -H "Content-Type: application/json" \
  -d '{"message": "test", "limit": 1}'
            

🐳 Problémy se službami

❌ Problém: Služba se neustále restartuje

Symptomy: Container status ukazuje "Restarting" nebo časté restarty

✅ Řešení:

# Zkontrolujte logy služby
docker compose logs [service-name] --tail=50

# Nejčastější příčiny:
# 1. Chybí závislosti - zkontrolujte requirements.txt
# 2. Port již používán - změňte port v .env
# 3. Nedostatek paměti - zkontrolujte RAM
# 4. Chybná konfigurace - zkontrolujte environment proměnné

# Restartujte pouze problematickou službu
docker compose restart [service-name]
            

❌ Problém: Embedding service nelze načíst model

Symptomy: "Failed to load model" nebo "CUDA out of memory"

✅ Řešení:

# Zkontrolujte dostupnou paměť
free -h

# Vynuťte CPU mode (pokud GPU nedostupné)
# V docker-compose.yml embedding-service environment:
- CUDA_VISIBLE_DEVICES=""
- USE_CUDA=False

# Restartujte službu
docker compose restart embedding-service
            

❌ Problém: Qdrant není dostupný

Symptomy: "Connection refused" nebo "Unable to connect to Qdrant"

✅ Řešení:

# Zkontrolujte Qdrant health
curl http://localhost:6335/health

# Restartujte Qdrant
docker compose restart qdrant

# Zkontrolujte data volume
docker volume inspect embedDataFeed-qdrant

# Nouzový restart celého stack
docker compose down && docker compose up -d
            

🌐 API chyby

❌ Chyba 500: Internal Server Error

Symptomy: API vrací 500 status code

✅ Řešení:

# Zkontrolujte logy služby
docker compose logs embedding-service --tail=20
docker compose logs xml-processor --tail=20

# Nejčastější příčiny:
# 1. Model se nenačetl - restart embedding-service
# 2. Qdrant nedostupný - restart qdrant
# 3. Chybný request format - zkontrolujte JSON

# Test základní funkcionality
curl -X POST "http://localhost:8001/search" \
  -H "Content-Type: application/json" \
  -d '{"text": "test", "limit": 1}'
            

❌ Chyba 400: Chybí povinné parametry

Symptomy: "Chybí text pro vyhledávání" nebo "Chybí zpráva uživatele"

✅ Řešení:

# Správný formát pro /search endpoint:
{
  "text": "váš dotaz",
  "limit": 5
}

# Správný formát pro /n8n/search endpoint:
{
  "message": "váš dotaz",
  "limit": 3
}

# Zkontrolujte Content-Type header:
-H "Content-Type: application/json"
            

❌ Unexpected token '<' in JSON

Symptomy: JavaScript chyba v dashboardu

✅ Řešení:

# API vrací HTML místo JSON - obvykle znamená:
# 1. Služba není dostupná
# 2. Špatná URL nebo routing
# 3. Proxy problém

# Testujte API přímo:
curl -v http://localhost:8001/health
curl -v http://localhost:8002/health

# Restartujte web dashboard:
docker compose restart web-dashboard
            

⚡ Výkonnostní problémy

❌ Pomalé vyhledávání

Symptomy: API response time > 5 sekund

✅ Řešení:

# Zkontrolujte system resources
htop
df -h

# Optimalizace embedding service:
# 1. Snižte batch_size v konfiguraci
# 2. Omezte počet workers
# 3. Zvažte použití GPU

# Optimalizace Qdrant:
# 1. Zkontrolujte počet segmentů
# 2. Optimalizujte index parametry
# 3. Zvyšte dostupnou RAM
            

❌ Vysoká spotřeba paměti

Symptomy: System má málo volné RAM

✅ Řešení:

# Zkontrolujte spotřebu podle kontejnerů
docker stats

# Optimalizace:
# 1. Snižte MAX_WORKERS v embedding service
# 2. Použijte menší model (pokud možno)
# 3. Omezte batch size pro XML processor
# 4. Zvažte swap file

# Vyčištění cache
docker system prune -f
            

🔒 SSL/HTTPS problémy

❌ Error 526: Invalid SSL certificate

Symptomy: Cloudflare vrací 526 chybu

✅ Řešení:

# Zkontrolujte Traefik konfiguraci
docker logs traefik-traefik-1 --tail=20

# Zkontrolujte certificate resolver
grep -r "certificatesResolvers" /srv/infra/traefik/

# Opravte resolver název v docker-compose.yml:
traefik.http.routers.embedDataFeed.tls.certresolver=letsencrypt

# Restartujte služby
docker compose up -d nginx
            

❌ Let's Encrypt rate limit

Symptomy: "too many failed authorizations" v Traefik logs

✅ Řešení:

# Použijte staging certifikáty pro testování:
# V traefik.yml:
certificatesResolvers:
  letsencrypt:
    acme:
      caServer: https://acme-staging-v02.api.letsencrypt.org/directory

# Počkejte na reset rate limitu (1 hodina)
# Nebo použijte jinou doménu pro testování
            

📊 Problémy s daty

❌ Žádné výsledky vyhledávání

Symptomy: API vrací prázdný results array

✅ Řešení:

# Zkontrolujte počet produktů v databázi
curl http://localhost:8085/api/qdrant-stats

# Pokud je points_count = 0, spusťte XML processing
curl -X POST "http://localhost:8085/api/process-xml" \
  -H "Content-Type: application/json" \
  -d '{"max_items": 1000}'

# Zkontrolujte kolekci v Qdrant
curl http://localhost:6335/collections/heureka_products
            

❌ XML processing selhává

Symptomy: "Failed to process XML" nebo timeout

✅ Řešení:

# Zkontrolujte logy XML processoru
docker compose logs xml-processor --tail=50

# Nejčastější příčiny:
# 1. XML feed není dostupný - zkontrolujte URL
# 2. Timeout při zpracování - snižte max_items
# 3. Chybí embedding service - zkontrolujte connectivity

# Test s menším počtem produktů
curl -X POST "http://localhost:8002/process" \
  -H "Content-Type: application/json" \
  -d '{"max_items": 10}'
            

🛠️ Údržba systému

⚠️ Pravidelná údržba

Denně: Zkontrolujte stav služeb a logy
Týdně: Aktualizujte XML data, vyčistěte logy
Měsíčně: Backup Qdrant dat, aktualizace Docker images

🔄 Údržbové skripty

# Restart všech služeb
cd /srv/projects/embedDataFeed
docker compose restart

# Vyčištění Docker cache
docker system prune -f

# Backup Qdrant dat
docker run --rm -v embedDataFeed-qdrant:/data -v $(pwd):/backup \
  ubuntu tar czf /backup/qdrant-backup-$(date +%Y%m%d).tar.gz /data

# Aktualizace XML dat
curl -X POST "http://localhost:8085/api/process-xml" \
  -H "Content-Type: application/json" \
  -d '{}'

# Monitoring disk space
df -h
du -sh /var/lib/docker/
            

📋 Monitoring checklist

# Health check script
#!/bin/bash
echo "=== EmbedDataFeed Health Check ==="

# Docker services
echo "Docker services:"
docker compose ps

# API endpoints
echo -e "\nAPI Health:"
curl -s http://localhost:8085/api/proxy?url=http://localhost:8001/health | jq .
curl -s http://localhost:8002/health | jq .

# Database stats
echo -e "\nDatabase:"
curl -s http://localhost:8085/api/qdrant-stats | jq .

# System resources
echo -e "\nSystem:"
free -h
df -h /
            

📞 Kontakt a podpora

🆘 Pokud nic nepomůže

Zkontrolujte dashboard pro aktuální stav
Prohledejte API dokumentaci
Zkuste full restart: docker compose down && docker compose up -d
Vytvořte issue s logy a error zprávami

📊 Užitečné logy pro podporu

# Exportujte logy všech služeb
docker compose logs > embedDataFeed-logs-$(date +%Y%m%d).txt

# System info
uname -a > system-info.txt
docker version >> system-info.txt
docker compose version >> system-info.txt
            

🔧 Řešení problémů

📋 Obsah

🔍 Základní diagnostika

✅ Rychlý checklist

🩺 Diagnostické příkazy

🐳 Problémy se službami

❌ Problém: Služba se neustále restartuje

✅ Řešení:

❌ Problém: Embedding service nelze načíst model

✅ Řešení:

❌ Problém: Qdrant není dostupný

✅ Řešení:

🌐 API chyby

❌ Chyba 500: Internal Server Error

✅ Řešení:

❌ Chyba 400: Chybí povinné parametry

✅ Řešení:

❌ Unexpected token '<' in JSON

✅ Řešení:

⚡ Výkonnostní problémy

❌ Pomalé vyhledávání

✅ Řešení:

❌ Vysoká spotřeba paměti

✅ Řešení:

🔒 SSL/HTTPS problémy

❌ Error 526: Invalid SSL certificate

✅ Řešení:

❌ Let's Encrypt rate limit

✅ Řešení:

📊 Problémy s daty

❌ Žádné výsledky vyhledávání

✅ Řešení:

❌ XML processing selhává

✅ Řešení:

🛠️ Údržba systému

⚠️ Pravidelná údržba

🔄 Údržbové skripty

📋 Monitoring checklist

📞 Kontakt a podpora

🆘 Pokud nic nepomůže

📊 Užitečné logy pro podporu

🔗 Související odkazy