Stage File Proxy
開発環境で必要に応じて本番サーバーからファイルを自動的に取得し、大容量のファイルディレクトリを同期する必要をなくします。
stage_file_proxy
インストール
composer require 'drupal/stage_file_proxy:^3.1'
概要
Stage File Proxyは、Drupal開発ワークフローにおける一般的な問題を解決する必須の開発ツールです。その問題とは、ユーザーがアップロードした数ギガバイトにも及ぶコンテンツを手動でコピーすることなく、開発環境で本番ファイルを利用できるようにする必要性です。
ローカルに存在しないファイルがリクエストされると、Stage File Proxyはそのリクエストをインターセプトし、設定されたオリジンサーバー（通常は本番環境）からリアルタイムでファイルをダウンロードします。その後、ファイルはローカルに保存され、以降のリクエストに使用されるため、効率的なオンデマンドファイル同期システムが構築されます。
このモジュールはImage Styleの処理において特にインテリジェントで、設定時に処理済みの派生画像ではなく元の画像を取得するため、DrupalのImageシステムが適切なStyleをローカルで生成できます。このアプローチにより、同じ画像の他のStyleに対する将来のリクエストが高速化されます。
ローカルストレージが不要なシナリオでは、Stage File Proxyは「ホットリンク」モードで動作し、HTTP 301レスポンスを介して本番サーバーにリクエストを単純にリダイレクトできます。
Features
- ローカルにファイルが存在しない場合、リモートの本番サーバーからオンデマンドでファイルを取得
- リモートファイルの自動ダウンロードとローカルキャッシュによる後続リクエストへの対応
- 元の画像を取得しローカルサイトで派生画像を生成するインテリジェントなImage Style処理
- 301リダイレクトでオリジンサーバーから直接ファイルを配信するホットリンクモード
- HTTPS接続用のSSL証明書検証制御
- オリジンURLに埋め込まれたHTTP Basic認証資格情報のサポート
- 異なるパスを持つマルチサイトインストール用の設定可能なオリジンディレクトリ
- 特定のファイルタイプをプロキシから除外するファイル拡張子除外機能
- オリジンサーバーへのリクエスト用カスタムHTTPヘッダーサポート
- オリジンからすべての管理ファイルを一括ダウンロードするDrushコマンド
- 他のモジュールが特定のパスをプロキシから除外できるイベントシステム
- 並列リクエスト時のImage Style生成のリトライメカニズム
- CSS/JSアグリゲーションファイルがプロキシされることを防ぐ保護機能
- ディレクトリトラバーサル攻撃の防止
Use Cases
ファイル同期なしのローカル開発
主要なユースケース：ローカルで作業する開発者は、数ギガバイトのユーザーコンテンツをダウンロードすることなく、すべての本番ファイルにアクセスできます。本番URLをオリジンとして設定するだけで、ページを表示するとファイルがオンデマンドで取得されます。これにより、ローカル環境のセットアップ時間とディスク使用量が大幅に削減されます。
ステージング環境でのファイルアクセス
本番ファイルへのアクセスが必要だが重複を保存すべきではないステージング環境では、Stage File Proxyを使用して必要に応じてファイルを取得し、テストに対応しながらステージング環境をスリムに保つことができます。
ストレージ制限時のホットリンクモード
ローカルストレージが非常に限られている場合やファイルが一時的にのみ必要な場合は、ホットリンクモードを有効にしてすべてのファイルリクエストを本番環境にリダイレクトします。ファイルはローカルに保存されず、本番サーバーがすべてのファイル配信を処理します。注意：これにより本番サーバーの負荷が増加します。
マルチサイト開発
各サイトが異なるファイルパス（例：sites/site1/files vs sites/site2/files）を持つマルチサイトインストールでは、本番サイトのファイルパスに一致するようにorigin_dirを設定し、ローカルパスの違いに関係なく適切なファイルプロキシを可能にします。
一括ファイル同期
すべてのファイルをローカルに必要とする場合（例：オフライン作業前）、Drushコマンド'drush stage_file_proxy:dl'を使用して、オンデマンド取得を待つ代わりにすべての管理ファイルを一度にダウンロードします。
大容量メディアファイルの除外
サイトにプロキシしたくない大容量の動画や音声ファイルがある場合、excluded_extensionsに'mp4,mp3,ogg,webm'を設定して、画像やドキュメントはプロキシしながらこれらのファイルをスキップします。
Tips
- 設定が本番環境に同期されないよう、UIではなくsettings.phpまたはsettings.local.phpでStage File Proxyを設定してください
- UI設定と設定同期を一緒に使用する必要がある場合は、Configuration Splitモジュールを使用してください
- 初期セットアップを高速化するには、オンデマンド取得を待つ代わりに'drush stage_file_proxy:dl'を実行してすべてのファイルを一度にダウンロードしてください
- 'Image style Root'を有効にして元の画像を一度ダウンロードし、ローカルサイトで必要なすべての派生画像を生成させてください
- ファイル取得の問題をデバッグする際は、DrupalログでStage File Proxyのエラーを監視してください
- Apacheを使用していない場合はNGINX設定を更新してください - デフォルトのNGINX Drupal設定はファイル404でPHPをバイパスします
Technical Details
Admin Pages 1
/admin/config/system/stage_file_proxy
オリジンサーバーへの接続を設定し、ファイルの取得と処理方法を制御します。このページでは、管理者が本番サーバーURLの設定、SSL検証の制御、Image Style処理の設定、ファイル除外の管理を行えます。
権限 1
Drush Commands 1
drush stage_file_proxy:dl
ローカルに存在しないすべての管理ファイルをオリジンサーバーからダウンロードします。file_managedテーブルをクエリし、欠落している各パブリックファイルのダウンロードを試みます。
Troubleshooting 6
オリジンURLが正しくアクセス可能であることを確認してください。オリジンに末尾スラッシュがないことを確認してください。オリジンサーバーが開発IPからのリクエストを許可していることを確認してください。Stage File Proxyからの具体的なエラーメッセージをDrupalログで確認してください。
すべてのファイルリクエストをDrupal経由でルーティングするようにNGINX設定を更新してください。'location ~ ^/sites/.*/files/styles/'を'location ~ ^/sites/.*/files/'に変更し、'try_files $uri @rewrite;'を使用していることを確認してください。
オリジンに有効なSSL証明書がある場合、サーバーのCA証明書が最新であることを確認してください。自己署名証明書での開発では、'verify'をFALSEに設定してSSL検証を無効にできます（本番環境に近い環境では推奨されません）。
Stage File Proxyが派生画像ではなく元の画像を取得するように'Image style Root'が有効になっていることを確認してください。キャッシュをクリアし、Imageモジュールが正常に動作していることを確認してください。stylesディレクトリのファイル権限を確認してください。
オリジンURLで資格情報がURLエンコードされていることを確認してください。&などの特殊文字はエンコードする必要があります（例：%26）。形式：'http://username:password@example.com'。
Stage File ProxyにはImage Style生成のリトライロジックが含まれていますが、大量の同時負荷では問題が発生する可能性があります。重複リクエストを統合するリバースプロキシやCDNの使用、またはDrushダウンロードコマンドを使用したキャッシュのプレウォームを検討してください。
Security Notes 6
- このモジュールは本番環境では絶対に有効にしないでください - 外部サーバーへの依存関係を作成し、内部ファイルパスを公開する可能性があります
- オリジンURLには認証資格情報が含まれる場合があります - settings.phpに適切なファイル権限があり、バージョン管理で公開されていないことを確認してください
- オリジンURLでHTTP Basic認証を使用する場合、資格情報は設定にプレーンテキストで保存されます
- オリジンサーバーの真正性を確保するため、ステージング環境ではSSL検証を有効のままにしてください
- モジュールには'..'を含むパスを拒否することでディレクトリトラバーサル攻撃に対する保護が含まれています
- ホットリンクモードは本番サーバーのURL構造をエンドユーザーに公開するため、注意が必要です