> ## 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.

# Salud y solución de problemas del almacenamiento

> Diagnostique fallos de preparación, escáner, CA, permisos, canario y dead-letter

Use las respuestas de salud para el enrutamiento y el triaje saneado. Use
registros protegidos, métricas, registros de auditoría del proveedor y el
estado de la base de datos para el diagnóstico.

## Endpoints de salud web

| Endpoint            | Significado                                                                        | Éxito                  | Fallo                                           |
| ------------------- | ---------------------------------------------------------------------------------- | ---------------------- | ----------------------------------------------- |
| `/api/health/live`  | El proceso web está en ejecución; sin comprobaciones externas                      | `200 {"status":"ok"}`  | Fallo de proceso/red                            |
| `/api/health/ready` | Los perfiles de almacenamiento son alcanzables y el canario profundo está reciente | `200`, `status: ready` | `503`, `status: not_ready` y `category` saneada |

Las categorías de preparación son solo `configuration`, `authentication`,
`tls`, `storage`, `capability` y `canary_stale`. La respuesta omite
intencionadamente proveedores, endpoints, nombres de bucket, claves de
objeto, credenciales y errores en bruto.

```bash theme={null}
curl --fail --silent --show-error \
  'https://<casebender-host>/api/health/live'
curl --fail --silent --show-error \
  'https://<casebender-host>/api/health/ready'
```

No use la liveness para decidir que las escrituras son seguras. No ponga
una credencial en la URL de una sonda.

## Canario profundo

El canario profundo programado escribe bytes aleatorios en `ephemeral`,
registra metadatos SHA-256, lee y calcula el hash de los bytes exactos,
los copia y verifica, y después elimina ambos objetos. La preparación
informa `canary_stale` cuando no existe un canario exitoso dentro de la
ventana de frescura.

Para un canario obsoleto:

1. confirme que la instrumentación web inició el programador del
   canario;
2. inspeccione `storage.readiness`, `storage.operation.*` y la latencia
   del proveedor;
3. confirme que `ephemeral` permite creación condicional, lectura,
   copia y eliminación;
4. compruebe el reloj de worker/web y la saturación del bucle de
   eventos;
5. verifique que la política de ciclo de vida no esté eliminando
   objetos canario durante la transacción; y
6. ejecute el contrato del proveedor desde el mismo contexto de red e
   identidad.

No alargue de forma permanente el umbral de antigüedad para ocultar
fallos.

## Triaje por categoría

### `configuration`

Valide la legibilidad/modo de `STORAGE_CONFIG_FILE` y el JSON estricto;
deben existir los tres perfiles. Use los identificadores canónicos de
proveedor `s3`, `gcs`, `azure` o `local`. La producción no puede usar
`local`.

### `authentication`

Compruebe el enlace de identidad de carga de trabajo, el alcance del
rol, la audiencia del token, el solapamiento de rotación de
credenciales y las denegaciones de auditoría del proveedor. Web y
worker necesitan acceso coincidente. No imprima tokens, no ejecute
`env` ni copie datos de Secret a un ticket.

### `tls`

Compruebe el DNS/SAN del endpoint, el montaje de CA privada, la cadena
emisora completa, la caducidad, la confianza del proxy y el reinicio
del pod después de la rotación de CA. Mantenga la verificación
habilitada; nunca use HTTP, `--insecure` ni
`rejectUnauthorized: false`.

### `storage`

Confirme el bucket/contenedor existente, la ruta, el DNS, el egreso, la
cuota, la limitación, la capacidad y las operaciones de objeto
requeridas. Las comprobaciones de salud no crean el almacenamiento
faltante.

### `capability`

Cuando se requiera WORM, verifique el `requireWorm` del perfil, el
versionado, la retención/inmutabilidad de objetos y la retención legal.
Vuelva a ejecutar la cualificación en vivo después de cambios de
política.

## Interrupción del escáner

Los síntomas incluyen el aumento de `storage.quarantine.depth`,
`storage.quarantine.oldest_age_seconds`, `storage.scanner.failure`,
reintentos del outbox y, eventualmente, dead letters.

Compruebe el socket/host de `clamd`, la CA TLS, el nombre del servidor,
el límite de tamaño, el tiempo de espera, la política de red, la salud
del motor y el estado de actualización de firmas. Restaure el escáner
y, a continuación, permita los reintentos idempotentes normales o use
el procedimiento de replay aprobado. Los objetos deben permanecer en
cuarentena hasta un veredicto limpio terminal; nunca los marque como
limpios de forma manual ni omita el escaneo.

## Dead letters de mutación

Supervise `storage.outbox.deadletter`, `storage.outbox.pending` y
`storage.outbox.deadlettered`. Inspeccione los registros protegidos de
`StorageMutationOutbox` por ID/estado/operación sin exportar cargas
útiles ni claves de objeto de forma innecesaria.

1. clasifique el fallo de escáner, permiso, retención, TLS, objeto
   faltante o proveedor;
2. repare la causa;
3. confirme que el objeto sigue coincidiendo con su SHA-256
   almacenado y su versión exacta;
4. reproduzca a través de la operación de cola idempotente aprobada;
   y
5. confirme la finalización y la evidencia de auditoría.

Nunca elimine una fila de dead-letter para poner un dashboard en
verde. Las eliminaciones bloqueadas por retención son fallos de
política que hay que resolver, no objetos que forzar a eliminar.

## Migración y reconciliación

Supervise `storage.migration.result`,
`storage.reconciliation.missing`,
`storage.reconciliation.orphan_observed`,
`storage.reconciliation.orphan_confirmed` y las métricas de
reparación del outbox de reconciliación.

* Los objetos esperados faltantes se devuelven a un estado de
  cuarentena/integridad fallida.
* Los huérfanos se observan primero y se confirman solo después del
  período de gracia.
* Los reintentos de migración pueden llegar a `DEAD_LETTER`;
  conserve el origen e investigue antes del replay.

No elimine automáticamente los huérfanos confirmados. Correlacione
con las sesiones de carga, los ledgers de migración, las versiones
del proveedor, la retención y las retenciones legales.

## Validación segura

Use un prefijo dedicado y una identidad equivalente a la de la carga
de trabajo:

```bash theme={null}
STORAGE_TEST_PROVIDER=s3 \
STORAGE_TEST_BUCKET='<dedicated-test-bucket>' \
AWS_REGION='<region>' \
./scripts/storage/validate-storage.sh
```

Para ODF/Ceph, use `./scripts/storage/validate-ceph-rgw.sh` con la
versión exacta y la CA privada. Sanee las salidas antes de adjuntarlas
a un incidente.