追跡しない原本画像を、どこに置くかを決めた話
今回やったこと
記事用に生成した画像の原本を、Gitの追跡対象から外し、オブジェクトストレージへ退避する運用に整理した。画像の所在をGit履歴に固定せず、生成した機材にまず置き、定期処理で保管先へ送る。処理の対象や記録はJSONで追跡する。
ここで分けたのは、同じ raw/ ディレクトリにあるファイルでも、画像とサイドカーJSONでは正本の場所が違うという点だ。画像はR2の raw-masters/ に保存し、索引はマニフェストで管理する。一方、生成プロンプトなどのサイドカーJSONはGitで追跡する。この区別を曖昧にすると、「未追跡だから回収が必要」「同じ場所にあるから画像もコミットしてよい」という誤判断につながる。
Gitに画像を残さない理由
この設計の理由は、単にリポジトリの容量を節約することではない。画像生成は生成環境のある機材で行われ、原本はまずそのディスクに存在する。各機から毎日動く退避処理が、原本をR2へ送る。Gitには画像本体を含めず、索引やサイドカーのような小さな管理情報だけを残す。
この方針では、生成直後の画像が未追跡であることは異常を意味しない。既存の退避処理も、コミット対象を索引JSONとサイドカーJSONに限定する許可リストを持ち、画像をコミットする経路を設けていない。ファイルの状態だけを見て判断せず、「どの種類のデータか」「どこが正本か」を合わせて見る必要がある。
| ファイル | Gitでの扱い | 正本 | 日常の扱い |
|---|---|---|---|
featured.png などの原本画像 | 追跡しない | R2の raw-masters/ | 定期退避に任せる |
prompts.json などのサイドカー | 追跡する | Git | 退避レッグが回収する |
事故から増えた確認点
過去には、未追跡の原本画像を「まだ回収されていない」と判断し、手作業でGitへ追加したことがあった。後から対象画像がすでにR2へ退避済みだと分かった。Gitに入った画像は、その後ファイルを削除したり変更を取り消したりしても、履歴に残る。したがって、追跡済みの古い画像が存在することを現在のルールと読み替えず、未追跡画像を手作業でPR化しないことが重要になる。
サイドカーには別の問題がある。退避処理がサイドカーをPRに写した後、マージを確認する前に元ファイルを消すと、PRが閉じられた場合に原本を失う。逆に、マージ後も元ファイルを未追跡のまま残すと、次のfast-forward更新を塞ぐ可能性がある。そのため、マージを確認し、同じパスに同一内容が追跡ファイルとして入った場合に限って原本を掃除する。内容が違うものや、まだmainに無いものは残す。
運用に持ち込むときの手順
新しい種類の生成物を扱う場合、まずファイル単位で正本と追跡方針を決める。ディレクトリ名だけで一括判断しない。次に、定期処理が送る対象とGitに写す対象を許可リストで分離する。最後に、成功時だけでなく、PRがマージされない場合、内容が更新された場合、退避が遅れた場合に原本が残るかを確認する。
この分離により、画像本体を誤って履歴へ積む経路と、サイドカーの原本を早まって失う経路を別々に扱える。運用上の指標は「未追跡ファイルがゼロか」ではなく、画像が保管先へ届いたか、管理情報が版管理へ取り込まれたかである。未追跡という一つの表示だけから、成功・失敗を決めないことがこの設計の要点だ。
適用範囲と注意点
この方法は、生成元の機材に原本があり、定期退避が動く構成を前提とする。退避前に機材のディスクが失われる場合や、定期処理が長く停止する場合まで、Gitの分離だけで保護できるわけではない。保管先の確認や退避ジョブの監視は別の運用として必要になる。
更新履歴
- 2026-10-12: 初稿を作成。
訂正履歴
- なし。