既存CMSのストレージ基盤をCloudflare R2へ移行

プロジェクト概要

対応の背景

対象のCMSでは、ファイルの保存、取得、コピー、削除、ダウンロードなどの処理が、サーバーのローカルファイルシステムを前提に実装されていました。そのため、保存先をCloudflare R2へ変更するには、設定だけではなく、システム内に分散していたファイル処理を確認し、ストレージへ直接依存している箇所を段階的に見直す必要がありました。

また、既存ファイルの移行とあわせて、ファイルアップロード時のMIMEタイプやサイズの検証方法も整理することになりました。

ローカルディスクに密結合したファイル処理を整理

ファイルの保存先に依存しない構成へ変更するため、保存、取得、コピー、存在確認、削除、URL生成などの操作を、共通のストレージサービスを経由して実行するように整理しました。本番環境ではCloudflare R2、ローカル開発環境ではMinIOを使用し、同じインターフェースから操作できる構成としています。

各機能がR2やMinIOを直接操作するのではなく、共通の処理を経由することで、ストレージに関する変更箇所を限定し、テストしやすい構成へ改修しました。

既存機能への影響を分けた段階的移行

既存CMSには、単純なファイル保存以外にも、複数のファイル処理が存在していました。主な対象は、ファイルの新規保存、既存ファイルのコピー、ZIPファイルの生成、メール添付ファイルの保存、画像リサイズキャッシュ、ファイルダウンロード、ファイルの存在確認です。

これらを一度に置き換えるのではなく、ストレージ基盤、保存処理、コピー処理、ZIP・メール添付、画像キャッシュ、ダウンロードの順に分けて対応しました。

既存ファイルを移行するバッチ処理

新規ファイルの保存先を変更するだけでなく、すでにローカルディスクに保存されていたファイルをCloudflare R2へ移行するコマンドも実装しました。移行処理では、ファイル数が増えた場合にも対応できるよう、複数ファイルの並列アップロードに対応しています。

また、処理を役割ごとに分離し、移行対象ファイルのパス解決、ファイルのアップロード、移行結果の集約、移行ログの記録、例外発生時の記録を個別に確認できる構成としました。

ファイルアップロードの検証を強化

ストレージ移行とあわせて、CMS内のファイルアップロード処理も見直しました。ファイル名や拡張子だけではなく、ファイル内容をもとにMIMEタイプを判定し、許可した形式だけを受け付ける構成へ変更しています。また、アップロード可能なファイル形式とサイズ上限を設定ファイルへ集約しました。

MIMEタイプの判定については、OSコマンドに依存した処理をPHPのfinfo拡張へ置き換え、実行環境への依存と外部コマンド呼び出しを減らしました。

保守しやすいコードへの整理

今回の変更では、R2への対応だけでなく、関連する既存コードの整理も行いました。主な対応は、重複していたバリデーション処理の共通化、MIMEタイプ判定処理の集約、コメントアウトされた旧コードの削除、マジックナンバーの定数化、ダウンロード処理の統一、エラー発生時に画面操作を再開できるUI処理の修正、アップロード失敗時に一時ファイルを削除する処理の追加です。

Unitテスト・Featureテストの整備

ストレージ操作、アップロード検証、ファイル移行処理について、UnitテストとFeatureテストを追加しました。主な確認対象は、ストレージへの保存・取得・コピー・削除、ファイルサイズとMIMEタイプの検証、ファイルパスの解決、移行結果の集約、移行ログの記録、移行コマンドの実行、R2を使用した一連のファイル操作です。

対応内容のまとめ

• ローカルディスク前提のファイル処理を調査
• ストレージ操作を共通サービスへ集約
• Cloudflare R2とMinIOに対応
• 機能ごとに段階的な移行を実施
• 既存ファイルの移行バッチを実装
• 並列アップロードと移行ログに対応
• ファイルアップロードの検証処理を共通化
• MIMEタイプ判定をファイル内容ベースへ変更
• 関連コードをリファクタリング
• Unitテスト・Featureテストを追加

このようなご相談に対応します

• ローカルディスクのファイルをオブジェクトストレージへ移行したい
• Cloudflare R2やS3互換ストレージへ対応したい
• 既存ファイルを安全に一括移行したい
• ファイルアップロードの検証方法を見直したい
• Laravelの既存コードを整理したい
• 改修にあわせてテストを追加したい
• 既存機能への影響を分けながら段階的に改修したい

既存システムの構成や影響範囲が分からない場合も、現在のファイル処理の調査から対応します。