1. Architettura di Servizio
NIS2 Agile e composto dai seguenti servizi gestiti sulla piattaforma Hetzner condivisa con gli altri prodotti della suite Agile Technology.
| Servizio | Stack | Healthcheck |
|---|---|---|
nis2-app | PHP+MySQL+Qdrant | /health |
MySQL/PostgreSQL | Database condiviso | ping |
Qdrant | Vector DB (embeddings) | HTTP 200 |
AgileHub (NEXUS) | Ticket + AI + Notifiche | /health |
2. Strategia di Resilienza a 7 Livelli
Auto-Restart Container / PM2
Ogni servizio ha restart: unless-stopped (Docker) o pm2 --watch (Node.js). Se un processo crasha, viene riavviato automaticamente entro 10-30 secondi.
Tempo di recovery: < 30 secondi
Healthcheck Nativo
Ogni servizio espone un endpoint /health o /api/health verificato ogni 30 secondi. Se il check fallisce 3 volte consecutive, il container/processo viene ricreato automaticamente.
Rileva: crash applicativo, memoria esaurita, deadlock, loop infinito.
Database Retry con Reconnect
Tutti i servizi implementano retry automatico su errori transitori del database (MySQL/PostgreSQL):
- 2006 — Server has gone away (reconnect)
- 2013 — Lost connection during query (retry)
- 1213 — Deadlock found (retry con backoff)
Strategia: 2 retry con backoff esponenziale + reconnect automatico.
Resilienza API Esterne
Le chiamate ad API esterne (Claude AI, ElevenLabs TTS, Voyage embeddings) hanno protezione a 3 livelli:
- Retry con backoff: 3 tentativi su errori transitori (429, 500, 502, 503)
- Degradazione graceful: se l'AI non risponde, il prodotto funziona con i dati locali
- Frontend fallback: messaggio "AI temporaneamente non disponibile" con suggerimenti alternativi
Error Alerting in Tempo Reale
Ogni errore critico genera una notifica AgileHub (campanella) per l'admin e, se configurato, un'email di alert. L'admin vede l'errore entro 30 secondi via polling badge.
Monitoraggio Esterno AgileHub
Il cron AgileHub (ticket-agent-cron.sh) verifica lo stato di tutti i container ogni 2 minuti. Se un prodotto non e raggiungibile, viene segnalato nel log e inviata notifica.
Complementare ai healthcheck interni: rileva problemi di rete, proxy Apache, DNS.
Manutenzione Preventiva
Script automatici prevengono il degrado:
| Operazione | Frequenza | Funzione |
|---|---|---|
| Disk monitor | Ogni 6 ore | Alert email se disco > 85% |
| Cleanup | Settimanale | Elimina file temporanei, Docker prune |
| SSL renewal | Settimanale | Rinnovo automatico Let's Encrypt |
| Claude auth | Orario | Refresh token OAuth Claude Code |
3. Protezione da Abuso
Rate Limiting
| Endpoint | Limite | Finestra | Tipo |
|---|---|---|---|
| Login | 5 tentativi | 15 min | Per IP + lockout |
| API generiche | 100 req | 1 ora | Per chiave/utente |
| Password reset | 3 req | 1 ora | Per email |
| Webhook esterni | 50 req | 1 min | Per IP |
4. Modalita Manutenzione
Quando il sistema AgileHub applica un fix approvato, il maintenance mode si attiva automaticamente:
- Il cron agent crea il flag
/tmp/maintenance-NIS2.flag - Apache rileva il flag e mostra la pagina di manutenzione a tutti gli utenti
- Il fix viene applicato (Claude nel container DevEnv)
- Il flag viene rimosso — il prodotto torna online
- La pagina di manutenzione si auto-aggiorna e reindirizza gli utenti
5. Matrice Rischi e Mitigazione
| Scenario | Probabilita | Impatto | Mitigazione | Recovery |
|---|---|---|---|---|
| Crash singolo servizio | Media | Medio | Auto-restart Docker/PM2 | < 30s |
| Database restart | Bassa | Alto | DB retry + reconnect | < 5s |
| AI non disponibile | Media | Basso | 3 retry + graceful | Funzioni base intatte |
| Disco pieno | Bassa | Alto | Monitor 6h + cleanup | Alert prima del 85% |
| SSL scaduto | Bassa | Alto | Auto-renewal certbot | Rinnovo 30gg prima |
| Attacco brute force | Media | Medio | Rate limit + lockout | Blocco 15 min |
| Errore deployment | Media | Alto | Maintenance mode + git revert | < 2 min rollback |
6. Service Level Agreement
| Metrica | Target | Misurazione |
|---|---|---|
| Uptime servizio | 99.9% (8.7h downtime/anno) | Health monitor + log |
| Recovery da crash | < 30 secondi | Docker restart + healthcheck |
| Recovery da aggiornamento | < 5 minuti | Maintenance mode + deploy |
| Rilevamento downtime | < 5 minuti | Cron monitor + email alert |
| Tempo risposta API (p95) | < 500ms | Health endpoint response time |
7. Checklist Operativa
Verifica automatica (quotidiana)
- Tutti i container/processi in stato healthy/online
- Campanella AgileHub — nessuna notifica di errore sistema
- Email — nessun alert da health monitor
Prima di un aggiornamento manuale
- Verificare che non ci siano utenti attivi (o attivare maintenance mode)
- Eseguire l'aggiornamento
- Verificare tutti i servizi:
docker compose psopm2 list - Controllare i log per errori