Bull Board - Guida Amministratore Code

Accesso alla Dashboard

La Bull Board è accessibile all’URL:


http://localhost:3000/api/admin/bull-board

Funzionalità Disponibili

1. Dashboard Principale UI

URL: /api/admin/bull-board
Descrizione: Interfaccia grafica completa per monitorare e gestire tutte le code
Funzionalità:
- Visualizzazione real-time dello stato di tutte le code
- Lista job per stato (waiting, active, completed, failed, delayed)
- Dettagli completi di ogni job
- Retry job falliti
- Rimozione job
- Pausa/ripresa code

2. API di Gestione

Metriche Complete


GET /api/admin/queues/metrics

Restituisce metriche dettagliate di tutte le code:

Contatori per stato (waiting, active, completed, failed, delayed)
Stato pausa delle code
Workers attivi

Risposta esempio:


{
  "queues": [
    {
      "name": "bankTransactionAutoMatch",
      "status": "active",
      "counts": {
        "waiting": 5,
        "active": 2,
        "completed": 150,
        "failed": 3,
        "delayed": 0,
        "paused": 0
      },
      "workersCount": 1
    }
  ],
  "totals": {
    "waiting": 15,
    "active": 4,
    "completed": 500,
    "failed": 10,
    "delayed": 2
  }
}

Stato Code (Legacy)


GET /api/admin/queue-status

Restituisce stato dettagliato con job attivi, in attesa e falliti.

Azioni sulle Code


POST /api/admin/queues/actions
Content-Type: application/json
 
{
  "queueName": "bankTransactionAutoMatch",
  "action": "pause|resume|clean|drain|obliterate",
  "status": "completed|failed",  // per action=clean
  "grace": 86400000  // millisecondi, per action=clean
}

Azioni disponibili:

pause: Mette in pausa la coda (non processa nuovi job)
resume: Riprende l’elaborazione della coda
clean: Rimuove job vecchi (completed o failed)
- status: quale tipo di job pulire
- grace: periodo di grazia in millisecondi (default: 0)
drain: Rimuove tutti i job in attesa
obliterate: ATTENZIONE - Cancella completamente la coda

Cleanup Automatico


# Preview del cleanup
GET /api/admin/queues/cleanup?gracePeriod=86400000
 
# Esegui cleanup
POST /api/admin/queues/cleanup
Content-Type: application/json
 
{
  "queueName": "bankTransactionAutoMatch",  // opzionale, se omesso pulisce tutte
  "gracePeriod": 86400000  // millisecondi (default: 24 ore)
}

Pulisce automaticamente:

Job completati più vecchi di gracePeriod
Job falliti più vecchi di gracePeriod * 7 (mantiene i failed più a lungo)

Job di una Coda Specifica


GET /api/admin/queues/{queueName}/jobs?status=waiting&start=0&end=50

Parametri:

status: waiting|active|completed|failed|delayed|all
start: indice di partenza (default: 0)
end: indice finale (default: 50)

Gestione Singolo Job


# Retry job fallito
POST /api/admin/jobs/{jobId}/retry
Content-Type: application/json
{
  "queueName": "bankTransactionAutoMatch"
}
 
# Rimuovi job
DELETE /api/admin/jobs/{jobId}/remove
Content-Type: application/json
{
  "queueName": "bankTransactionAutoMatch"
}

Code Disponibili

aiAnalysis - Analisi AI (ricette, ottimizzazione costi, analisi sprechi)
invoiceImport - Importazione fatture
cassaInCloudSync - Sincronizzazione CassaInCloud
foodcostRecalculation - Ricalcolo foodcost
dailyChecks - Controlli giornalieri
bankStatementProcess - Elaborazione estratti conto
bankTransactionImport - Importazione transazioni bancarie
bankTransactionAutoMatch - Automatch transazioni bancarie

Utilizzo Tipico

Monitoraggio Quotidiano

Aprire /api/admin/bull-board
Verificare job falliti (badge rossi)
Controllare job in attesa eccessivi
Verificare che i workers siano attivi

Gestione Job Falliti

Cliccare sul job fallito per vedere l’errore
Verificare lo stacktrace
Se correggibile, cliccare “Retry”
Altrimenti, rimuovere il job

Pulizia Periodica

Eseguire settimanalmente:


curl -X POST http://localhost:3000/api/admin/queues/cleanup \
  -H "Content-Type: application/json" \
  -d '{"gracePeriod": 604800000}'  # 7 giorni

Manutenzione Code

In caso di problemi con una coda:

Pausa temporanea:


curl -X POST http://localhost:3000/api/admin/queues/actions \
  -H "Content-Type: application/json" \
  -d '{"queueName":"bankTransactionAutoMatch","action":"pause"}'

Pulisci job vecchi:


curl -X POST http://localhost:3000/api/admin/queues/actions \
  -H "Content-Type: application/json" \
  -d '{"queueName":"bankTransactionAutoMatch","action":"clean","status":"completed","grace":0}'

Riprendi:


curl -X POST http://localhost:3000/api/admin/queues/actions \
  -H "Content-Type: application/json" \
  -d '{"queueName":"bankTransactionAutoMatch","action":"resume"}'

Troubleshooting

Bull Board non carica

Verificare che Redis sia attivo
Controllare i log del server Next.js
Verificare le variabili d’ambiente REDIS_*
Provare la dashboard alternativa: /api/admin/queue-status

Job bloccati in “active”

Probabilmente il worker è crashato. Verificare:

I log del processo workers
Riavviare i workers: npm run workers:prod
Se necessario, rimuovere manualmente i job bloccati

Memoria Redis alta

Eseguire cleanup regolare dei job completati:


curl -X POST http://localhost:3000/api/admin/queues/cleanup \
  -H "Content-Type: application/json" \
  -d '{"gracePeriod": 86400000}'

Automazione

Cron Job per Cleanup (Consigliato)

Aggiungere al crontab del server:


# Cleanup giornaliero alle 2 AM
0 2 * * * curl -X POST http://localhost:3000/api/admin/queues/cleanup

Sicurezza

IMPORTANTE: In produzione, proteggere tutte le route /api/admin/* con autenticazione!

Aggiungere middleware in middleware.ts:


if (req.nextUrl.pathname.startsWith("/api/admin/")) {
  // Verifica autenticazione admin
  const session = await getServerSession(req);
  if (!session?.user?.isAdmin) {
    return NextResponse.redirect(new URL("/login", req.url));
  }
}