> ## 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. # Saúde e solução de problemas do armazenamento > Diagnostique falhas de prontidão, scanner, CA, permissão, canário e dead-letter Use as respostas de health para roteamento e triagem sanitizada. Use logs protegidos, métricas, registros de auditoria do provedor e o estado do banco de dados para o diagnóstico. ## Endpoints de health do web | Endpoint | Significado | Sucesso | Falha | | ------------------- | ------------------------------------------------------------------------------ | ---------------------- | -------------------------------------------------- | | `/api/health/live` | O processo web está em execução; sem verificações externas | `200 {"status":"ok"}` | Falha de processo/rede | | `/api/health/ready` | Os perfis de armazenamento estão alcançáveis e o canário profundo está recente | `200`, `status: ready` | `503`, `status: not_ready` e `category` sanitizada | As categorias de prontidão são somente `configuration`, `authentication`, `tls`, `storage`, `capability` e `canary_stale`. A resposta omite intencionalmente provedores, endpoints, nomes de bucket, chaves de objeto, credenciais e erros brutos. ```bash theme={null} curl --fail --silent --show-error \ 'https:///api/health/live' curl --fail --silent --show-error \ 'https:///api/health/ready' ``` Não use liveness para decidir que as escritas são seguras. Não coloque uma credencial em uma URL de probe. ## Canário profundo O canário profundo agendado grava bytes aleatórios em `ephemeral`, registra metadados SHA-256, lê e calcula o hash dos bytes exatos, copia e os verifica e, em seguida, exclui ambos os objetos. A prontidão relata `canary_stale` quando nenhum canário bem-sucedido existe dentro da janela de atualidade. Para um canário obsoleto: 1. confirme que a instrumentação web iniciou o agendador do canário; 2. inspecione `storage.readiness`, `storage.operation.*` e a latência do provedor; 3. confirme que `ephemeral` permite create condicional, read, copy e delete; 4. verifique o relógio de worker/web e a saturação do event-loop; 5. verifique se a política de ciclo de vida não está excluindo objetos de canário durante a transação; e 6. execute o contrato do provedor a partir do mesmo contexto de rede e identidade. Não alongue permanentemente o limiar de idade para ocultar falhas. ## Triagem por categoria ### `configuration` Valide a legibilidade/modo de `STORAGE_CONFIG_FILE` e o JSON restrito; os três perfis devem existir. Use os IDs canônicos de provedor `s3`, `gcs`, `azure` ou `local`. A produção não pode usar `local`. ### `authentication` Verifique o binding de identidade de carga de trabalho, o escopo do papel, a audiência do token, a sobreposição de rotação de credenciais e as recusas de auditoria do provedor. Web e worker precisam de acesso correspondente. Não imprima tokens, não execute `env` nem copie dados de Secret para um ticket. ### `tls` Verifique DNS/SAN do endpoint, montagem da CA privada, cadeia emissora completa, validade, confiança do proxy e reinício do pod após a rotação da CA. Mantenha a verificação habilitada; nunca use HTTP, `--insecure` ou `rejectUnauthorized: false`. ### `storage` Confirme o bucket/contêiner existente, a rota, o DNS, o egresso, a cota, o throttling, a capacidade e as operações de objeto exigidas. As verificações de health não criam armazenamento ausente. ### `capability` Quando WORM for exigido, verifique o `requireWorm` do perfil, o versionamento, a retenção/imutabilidade de objeto e o legal hold. Reexecute a qualificação live após alterações de política. ## Interrupção do scanner Os sintomas incluem aumento de `storage.quarantine.depth`, `storage.quarantine.oldest_age_seconds`, `storage.scanner.failure`, retentativas de outbox e dead letters eventuais. Verifique o socket/host do `clamd`, a CA TLS, o nome do servidor, o limite de tamanho, o timeout, a política de rede, a saúde do mecanismo e o status de atualização de assinaturas. Restaure o scanner e, em seguida, permita as retentativas idempotentes normais ou use o procedimento aprovado de replay. Os objetos devem permanecer em quarentena até um veredito limpo terminal; nunca os marque como limpos manualmente nem ignore a varredura. ## Dead letters de mutação Monitore `storage.outbox.deadletter`, `storage.outbox.pending` e `storage.outbox.deadlettered`. Inspecione registros protegidos de `StorageMutationOutbox` por ID/status/operação sem exportar payloads ou chaves de objeto desnecessariamente. 1. classifique falha de scanner, permissão, retenção, TLS, objeto ausente ou provedor; 2. corrija a causa; 3. confirme que o objeto ainda corresponde ao SHA-256 armazenado e à versão exata; 4. faça replay pela operação de fila idempotente aprovada; e 5. confirme a conclusão e a evidência de auditoria. Nunca exclua uma linha de dead-letter para deixar um dashboard verde. Exclusões bloqueadas por retenção são falhas de política a resolver, não objetos a forçar a exclusão. ## Migração e reconciliação Monitore `storage.migration.result`, `storage.reconciliation.missing`, `storage.reconciliation.orphan_observed`, `storage.reconciliation.orphan_confirmed` e as métricas de reparo do outbox de reconciliação. * Objetos esperados ausentes são movidos de volta para um estado de quarentena/integridade com falha. * Órfãos são observados primeiro e confirmados somente após o período de graça. * Retentativas de migração podem chegar a `DEAD_LETTER`; mantenha a origem e investigue antes do replay. Não exclua automaticamente órfãos confirmados. Correlacione-os com sessões de upload, ledgers de migração, versões do provedor, retenção e legal holds. ## Validação segura Use um prefixo dedicado e identidade equivalente ao workload: ```bash theme={null} STORAGE_TEST_PROVIDER=s3 \ STORAGE_TEST_BUCKET='' \ AWS_REGION='' \ ./scripts/storage/validate-storage.sh ``` Para ODF/Ceph, use `./scripts/storage/validate-ceph-rgw.sh` com a versão exata e a CA privada. Sanitize as saídas antes de anexá-las a um incidente.