> ## Documentation Index > Fetch the complete documentation index at: https://docs.casebender.com/llms.txt > Use this file to discover all available pages before exploring further. # Stato di salute e risoluzione dei problemi dello storage > Diagnostica i fallimenti di readiness, scanner, CA, permessi, canary e dead-letter Usa le risposte health per il routing e il triage sanitizzato. Usa log protetti, metriche, record di audit del provider e lo stato del database per la diagnosi. ## Endpoint health del web | Endpoint | Significato | Successo | Errore | | ------------------- | ----------------------------------------------------------------- | ---------------------- | --------------------------------------------------- | | `/api/health/live` | Il processo web è in esecuzione; nessun controllo esterno | `200 {"status":"ok"}` | Fallimento di processo/rete | | `/api/health/ready` | I profili di storage sono raggiungibili e il deep canary è fresco | `200`, `status: ready` | `503`, `status: not_ready` e `category` sanitizzata | Le categorie di readiness sono solo `configuration`, `authentication`, `tls`, `storage`, `capability` e `canary_stale`. La risposta omette intenzionalmente provider, endpoint, nomi di bucket, chiavi oggetto, credenziali ed errori grezzi. ```bash theme={null} curl --fail --silent --show-error \ 'https:///api/health/live' curl --fail --silent --show-error \ 'https:///api/health/ready' ``` Non usare la liveness per decidere che le write sono sicure. Non inserire una credenziale in un URL di probe. ## Deep canary Il deep canary pianificato scrive byte casuali su `ephemeral`, registra i metadata SHA-256, legge e calcola l'hash dei byte esatti, li copia e li verifica, quindi elimina entrambi gli oggetti. La readiness riporta `canary_stale` quando non esiste un canary riuscito all'interno della finestra di freshness. Per un canary stantio: 1. conferma che l'instrumentation web abbia avviato lo scheduler del canary; 2. ispeziona `storage.readiness`, `storage.operation.*` e la latenza del provider; 3. conferma che `ephemeral` consenta create condizionale, read, copy e delete; 4. controlla l'orologio di worker/web e la saturazione dell'event-loop; 5. verifica che la policy di ciclo di vita non stia eliminando gli oggetti canary durante la transazione; e 6. esegui il contratto del provider dalla stessa rete e dallo stesso contesto di identità. Non allungare permanentemente la soglia di età per nascondere i fallimenti. ## Triage per categoria ### `configuration` Valida la leggibilità/modalità di `STORAGE_CONFIG_FILE` e il JSON rigoroso; tutti e tre i profili devono esistere. Usa gli ID provider canonici `s3`, `gcs`, `azure` o `local`. La produzione non può usare `local`. ### `authentication` Controlla il binding dell'identità del workload, l'ambito del ruolo, l'audience del token, la sovrapposizione della rotazione delle credenziali e i dinieghi di audit del provider. Web e worker necessitano di accesso corrispondente. Non stampare token, non eseguire `env` né copiare dati Secret in un ticket. ### `tls` Controlla DNS/SAN dell'endpoint, mount della CA privata, catena di emissione completa, scadenza, trust del proxy e riavvio del pod dopo la rotazione della CA. Mantieni la verifica abilitata; non usare mai HTTP, `--insecure` o `rejectUnauthorized: false`. ### `storage` Conferma il bucket/container esistente, il percorso, il DNS, l'egress, la quota, il throttling, la capacità e le operazioni oggetto richieste. I health check non creano lo storage mancante. ### `capability` Quando è richiesto WORM, verifica il profilo `requireWorm`, il versioning, la object retention/immutabilità e il legal hold. Riesegui la qualificazione live dopo le modifiche di policy. ## Interruzione dello scanner I sintomi includono l'aumento di `storage.quarantine.depth`, `storage.quarantine.oldest_age_seconds`, `storage.scanner.failure`, retry dell'outbox e, alla fine, dead letter. Controlla il socket/host `clamd`, la CA TLS, il nome del server, il limite di dimensione, il timeout, la network policy, lo stato di salute del motore e lo stato di aggiornamento delle signature. Ripristina lo scanner, quindi consenti i retry idempotenti normali oppure usa la procedura di replay approvata. Gli oggetti devono restare in quarantine fino a un verdetto pulito terminale; non marcarli mai puliti manualmente né aggirare la scansione. ## Dead letter di mutazione Monitora `storage.outbox.deadletter`, `storage.outbox.pending` e `storage.outbox.deadlettered`. Ispeziona i record protetti `StorageMutationOutbox` per ID/stato/operazione senza esportare payload o chiavi oggetto inutilmente. 1. classifica fallimento di scanner, permesso, retention, TLS, oggetto mancante o provider; 2. ripara la causa; 3. conferma che l'oggetto corrisponda ancora al suo SHA-256 memorizzato e alla versione esatta; 4. ripeti attraverso l'operazione di coda idempotente approvata; e 5. conferma il completamento e le evidenze di audit. Non eliminare mai una riga dead-letter per far diventare verde una dashboard. Le delete bloccate dalla retention sono fallimenti di policy da risolvere, non oggetti da forzare in eliminazione. ## Migrazione e riconciliazione Monitora `storage.migration.result`, `storage.reconciliation.missing`, `storage.reconciliation.orphan_observed`, `storage.reconciliation.orphan_confirmed` e le metriche di riparazione dell'outbox di riconciliazione. * Gli oggetti attesi mancanti vengono riportati in uno stato di quarantine/integrità fallita. * Gli orphan vengono prima osservati e confermati solo dopo il periodo di grazia. * I retry di migrazione possono raggiungere `DEAD_LETTER`; conserva la sorgente e indaga prima del replay. Non eliminare automaticamente gli orphan confermati. Correlali con le sessioni di upload, i ledger di migrazione, le versioni del provider, la retention e i legal hold. ## Validazione sicura Usa un prefisso dedicato e un'identità equivalente al workload: ```bash theme={null} STORAGE_TEST_PROVIDER=s3 \ STORAGE_TEST_BUCKET='' \ AWS_REGION='' \ ./scripts/storage/validate-storage.sh ``` Per ODF/Ceph, usa `./scripts/storage/validate-ceph-rgw.sh` con la versione esatta e la CA privata. Sanitizza gli output prima di allegarli a un incidente.