Passa al contenuto principale

MinIO Object Storage

MinIO è stato integrato come soluzione di object storage compatibile con S3 per gestire i risultati del crawling, i file temporanei e altri dati binari della piattaforma Tidiko AI.

🎯 Caratteristiche Principali​

✅ Compatibilità S3​

  • API standard S3 per facilità di integrazione
  • Supporto completo per operazioni CRUD
  • Compatibilità con librerie AWS SDK
  • Facile migrazione da/verso AWS S3

✅ Storage Risultati Crawling​

  • Salvataggio persistente dei contenuti estratti
  • Gestione URL lists (processati e falliti)
  • Metadati strutturati per ogni risultato
  • Organizzazione gerarchica per resource UUID

✅ Console Web Amministrativa​

  • Interfaccia grafica per gestione bucket
  • Monitoraggio utilizzo spazio
  • Gestione policy di accesso
  • Visualizzazione file e metadati

✅ Integrazione Docker​

  • Containerizzazione completa
  • Health checks automatici
  • Volumi persistenti per dati
  • Configurazione tramite environment variables

🏗️ Architettura MinIO​

Componenti del Sistema​

Struttura Storage​

crawler-results/
├── {resource-uuid}/
│   ├── urls.json                    # Lista URL da processare
│   ├── results/
│   │   ├── {encoded-url}.json      # Risultato crawling singolo URL
│   │   └── ...
│   ├── aggregated-results.json     # Risultati aggregati
│   └── full-results.json           # Risultati completi
└── ...

🚀 Configurazione​

Docker Compose​

minio:
  profiles: ['dev', 'prod', 'staging']
  image: minio/minio:latest
  command: server /data --console-address ":9001"
  ports:
    - '${MINIO_PORT:-9000}:9000'      # API endpoint
    - '${MINIO_CONSOLE_PORT:-9001}:9001'  # Console web
  environment:
    MINIO_ROOT_USER: ${MINIO_ACCESS_KEY:-minioadmin}
    MINIO_ROOT_PASSWORD: ${MINIO_SECRET_KEY:-minioadmin}
  volumes:
    - minio_data_${DOCKER_PROFILE:-dev}:/data
  restart: unless-stopped
  healthcheck:
    test: ['CMD', 'curl', '-f', 'http://localhost:9000/minio/health/live']
    interval: 30s
    timeout: 20s
    retries: 3
    start_period: 30s
  networks:
    - internal

Variabili Ambiente​

# Configurazione MinIO
MINIO_ENDPOINT=http://minio:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET_NAME=crawler-results
MINIO_PORT=9000
MINIO_CONSOLE_PORT=9001

Inizializzazione Bucket​

// Il bucket viene creato automaticamente al primo utilizzo
await s3Service.initBucket();

📁 Operazioni Supportate​

1. Gestione URL Lists​

// Salvataggio lista URL
await s3Service.saveUrls(s3ObjectId, {
  urls: ['https://example.com/page1', 'https://example.com/page2'],
  failedUrls: []
});

// Recupero lista URL
const urlList = await s3Service.getUrls(s3ObjectId);

// Aggiornamento lista URL
await s3Service.updateUrls(s3ObjectId, updatedUrlList);

// Aggiunta URL fallito
await s3Service.addFailedUrl(s3ObjectId, 'https://failed.com', 'Timeout error');

2. Salvataggio Risultati Crawling​

// Salvataggio risultato singolo
await s3Service.saveCrawlerResult(s3ObjectId, url, markdownContent, {
  title: 'Page Title',
  description: 'Page description',
  crawledAt: new Date().toISOString(),
  url: url,
  id: resourceUuid,
  type: 'document'
});

// Salvataggio risultati aggregati
await s3Service.saveAggregatedResults(s3ObjectId, {
  s3ObjectId,
  resourceUuid,
  collectionName,
  userId,
  totalUrls: 100,
  totalUrlsProcessed: 95,
  totalSuccessCount: 90,
  totalFailureCount: 5,
  results: crawlResults,
  aggregatedAt: new Date().toISOString()
});

3. Recupero Risultati​

// Recupero risultato singolo
const result = await s3Service.getCrawlerResult({
  s3ObjectId,
  url: 'https://example.com',
  isFullKey: false
});

// Lista tutti i risultati per un S3 Object ID
const resultKeys = await s3Service.listCrawlerResults(s3ObjectId);

// Recupero risultati completi
const fullResults = await s3Service.getFullResults(s3ObjectId);

🔧 Integrazione con Crawlee Service​

Salvataggio Automatico​

Il CrawleeService salva automaticamente i risultati su MinIO durante il crawling:

// Nel request handler di CrawleeService
await s3Service.saveCrawlerResult(s3ObjectId, currentUrl, markdown, {
  title,
  description,
  crawledAt: now,
  url: currentUrl,
  id: requestContext.resourceUuid,
  type: 'document',
});

Gestione URL Falliti​

// Aggiornamento automatico degli URL falliti
await s3Service.addFailedUrl(s3ObjectId, currentUrl, errorMessage);

🌐 Accesso e Monitoraggio​

Console Web​

Accesso alla console amministrativa:

  • URL: http://localhost:9001 (dev) o https://minio-console.tidiko.ai (prod)
  • Username: minioadmin (default)
  • Password: minioadmin (default)

API Endpoint​

  • API S3: http://localhost:9000 (dev) o https://minio.tidiko.ai (prod)
  • Health Check: http://localhost:9000/minio/health/live

Monitoraggio Utilizzo​

# Controllo spazio utilizzato
docker exec minio_server du -sh /data

# Lista bucket
docker exec minio_server mc ls myminio

# Statistiche bucket
docker exec minio_server mc du myminio/crawler-results

🔒 Sicurezza​

Configurazione Produzione​

# Usa password forti in produzione
MINIO_ACCESS_KEY=your_strong_access_key
MINIO_SECRET_KEY=your_very_strong_secret_key

# Abilita SSL se necessario
MINIO_USE_SSL=true

Policy di Accesso​

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::crawler-results/*"
    }
  ]
}

🐛 Troubleshooting​

MinIO non si avvia​

# Controlla log
docker logs minio_server

# Verifica porte
netstat -tulpn | grep :9000
netstat -tulpn | grep :9001

# Riavvia servizio
docker restart minio_server

Connessione fallita​

# Test connessione API
curl -f http://localhost:9000/minio/health/live

# Test connessione console
curl -f http://localhost:9001

# Verifica configurazione endpoint
echo $MINIO_ENDPOINT

Bucket non trovato​

# Crea bucket manualmente
docker exec minio_server mc mb myminio/crawler-results

# Verifica bucket esistenti
docker exec minio_server mc ls myminio

Permessi file​

# Verifica permessi volume
docker exec minio_server ls -la /data

# Correggi permessi se necessario
docker exec minio_server chown -R minio:minio /data

📊 Performance e Ottimizzazione​

Configurazione Memoria​

# Nel docker-compose.yml
minio:
  deploy:
    resources:
      limits:
        memory: 2G
      reservations:
        memory: 1G

Backup e Persistenza​

# Backup manuale
docker exec minio_server mc mirror myminio/crawler-results /backup/

# Backup automatico (cron job)
0 2 * * * docker exec minio_server mc mirror myminio/crawler-results /backup/$(date +\%Y\%m\%d)

Cleanup Risorse​

// Implementazione cleanup automatico
async cleanupOldResults(daysOld: number = 30) {
  const cutoffDate = new Date();
  cutoffDate.setDate(cutoffDate.getDate() - daysOld);
  
  // Logica per rimozione risultati vecchi
  // Implementazione specifica basata su metadati
}

🔗 Link Utili​