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

# ストレージヘルスとトラブルシューティング

> レディネス、スキャナー、CA、権限、カナリア、およびデッドレター障害を診断する

ヘルス応答はルーティングとサニタイズしたトリアージに使用します。診断には、保護されたログ、
メトリクス、プロバイダー監査記録、およびデータベース状態を使用します。

## Webヘルスエンドポイント

| エンドポイント             | 意味                             | 成功                    | 失敗                                               |
| ------------------- | ------------------------------ | --------------------- | ------------------------------------------------ |
| `/api/health/live`  | Webプロセスが稼働中。外部チェックなし           | `200 {"status":"ok"}` | プロセス/ネットワーク障害                                    |
| `/api/health/ready` | ストレージプロファイルに到達可能で、ディープカナリアが新しい | `200`、`status: ready` | `503`、`status: not_ready` およびサニタイズされた `category` |

レディネスカテゴリは `configuration`、`authentication`、`tls`、
`storage`、`capability`、および `canary_stale` のみです。応答は意図的に
プロバイダー、エンドポイント、バケット名、オブジェクトキー、資格情報、および生エラーを省略します。

```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'
```

書き込みが安全であると判断するためにライブネスを使用しないでください。プローブURLに
資格情報を入れないでください。

## ディープカナリア

スケジュールされたディープカナリアは、ランダムバイトを `ephemeral` に書き込み、SHA-256
メタデータを記録し、正確なバイトを読み取ってハッシュし、コピーして検証し、その後
両方のオブジェクトを削除します。新鮮さウィンドウ内に成功した
カナリアが存在しない場合、レディネスは `canary_stale` を報告します。

古いカナリアの場合:

1. Webインストルメンテーションがカナリアスケジューラーを開始したことを確認する
2. `storage.readiness`、`storage.operation.*`、およびプロバイダーレイテンシを検査する
3. `ephemeral` が条件付き作成、読み取り、コピー、および削除を許可することを確認する
4. ワーカー/Webのクロックとイベントループ飽和を確認する
5. ライフサイクルポリシーがトランザクション中にカナリアオブジェクトを削除していないことを
   検証する
6. 同じネットワークおよびアイデンティティコンテキストからプロバイダー契約を実行する

障害を隠すために経過時間しきい値を恒久的に延長しないでください。

## カテゴリトリアージ

### `configuration`

`STORAGE_CONFIG_FILE` の読み取り可能性/モードと厳密なJSONを検証します。3つの
プロファイルすべてが存在する必要があります。正規プロバイダーID `s3`、`gcs`、`azure`、または
`local` を使用します。本番では `local` を使用できません。

### `authentication`

ワークロードアイデンティティのバインディング、ロールスコープ、トークンオーディエンス、資格情報
ローテーションのオーバーラップ、およびプロバイダー監査拒否を確認します。Webとワーカーには一致する
アクセスが必要です。トークンを表示したり、`env` を実行したり、Secretデータをチケットにコピーしたりしないでください。

### `tls`

エンドポイントDNS/SAN、プライベートCAマウント、完全な発行チェーン、有効期限、
プロキシ信頼、およびCAローテーション後のポッド再起動を確認します。検証を有効のままにし、
HTTP、`--insecure`、または `rejectUnauthorized: false` を使用してはなりません。

### `storage`

既存のバケット/コンテナ、ルート、DNS、Egress、クォータ、スロットリング、
容量、および必須のオブジェクト操作を確認します。ヘルスチェックは欠損した
ストレージを作成しません。

### `capability`

WORMが必要な場合、プロファイルの `requireWorm`、バージョニング、オブジェクト
保持/不変性、およびリーガルホールドを検証します。ポリシー
変更後は実環境適格性確認を再実行します。

## スキャナー障害

症状には、増加する `storage.quarantine.depth`、
`storage.quarantine.oldest_age_seconds`、`storage.scanner.failure`、アウトボックス
再試行、および最終的なデッドレターが含まれます。

`clamd` ソケット/ホスト、TLS CA、サーバー名、サイズ制限、タイムアウト、ネットワーク
ポリシー、エンジンヘルス、およびシグネチャ更新状態を確認します。スキャナーを復旧してから、
通常の冪等再試行を許可するか、承認済みリプレイ手順を使用します。オブジェクトは
最終的なクリーン判定まで隔離されたままにする必要があります。手動でクリーンとマークしたり、
スキャンを迂回したりしてはなりません。

## ミューテーションデッドレター

`storage.outbox.deadletter`、`storage.outbox.pending`、および
`storage.outbox.deadlettered` を監視します。ペイロードやオブジェクトキーを不必要にエクスポートせずに、
保護された `StorageMutationOutbox` 記録をID/状態/操作で
検査します。

1. スキャナー、権限、保持、TLS、欠損オブジェクト、またはプロバイダー
   障害に分類する
2. 原因を修復する
3. オブジェクトが保存されたSHA-256と正確なバージョンにまだ一致することを確認する
4. 承認済みの冪等キュー操作でリプレイする
5. 完了と監査エビデンスを確認する

ダッシュボードを緑にするためにデッドレター行を削除してはなりません。保持でブロックされた
削除は、強制削除するオブジェクトではなく、解決すべきポリシー障害です。

## 移行とリコンシリエーション

`storage.migration.result`、
`storage.reconciliation.missing`、
`storage.reconciliation.orphan_observed`、
`storage.reconciliation.orphan_confirmed`、およびリコンシリエーションアウトボックス修復
メトリクスを監視します。

* 期待される欠損オブジェクトは、隔離/整合性失敗
  状態に戻されます。
* 孤児はまず観測され、猶予期間後にのみ確認されます。
* 移行再試行は `DEAD_LETTER` に達する可能性があります。ソースを保持し、リプレイ前に
  調査します。

確認済み孤児を自動削除しないでください。アップロード
セッション、移行台帳、プロバイダーバージョン、保持、およびリーガルホールドと相関させます。

## 安全な検証

専用プレフィックスとワークロード相当のアイデンティティを使用します。

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

ODF/Cephについては、正確なバージョンとプライベートCAを指定して `./scripts/storage/validate-ceph-rgw.sh` を使用します。
インシデントに添付する前に出力をサニタイズします。