オレンジ色のケーブルが接続されたパッチパネル
現場の実践

S3署名付きPUTアップロードでCORSエラーが消えない5つの原因

目次を見る

ブラウザから画像や動画をS3互換ストレージへ直接アップロードする構成を運用していて、特定の環境だけでアップロードが失敗する、という相談を受けることがあります。生成AIで作った画像をユーザーのブラウザから直接クラウドストレージに送る「direct upload」構成は、サーバー経由のアップロードに比べて帯域コストを抑えられる反面、障害が起きたときの切り分けが難しくなりがちです。クラウド移行でオンプレのファイルサーバーからS3やCloud Storageに切り替えたプロジェクトで、この種の障害に遭遇した方の参考になればと思います。

何が起きるか

典型的な事象は、ローカルの開発環境やcurlコマンドでは成功するのに、本番のブラウザからのアップロードだけが失敗するというものです。

ブラウザの開発者ツールでネットワークタブを見ると、PUTリクエストの前にOPTIONSメソッドのリクエストが飛んでいて、それが失敗しています。これは「プリフライトリクエスト」と呼ばれる仕組みで、ブラウザが異なるオリジン(ドメイン・ポート・プロトコルの組み合わせ)へリクエストを送る前に、サーバー側がそのリクエストを許可しているかを事前確認する動作です。

影響範囲はユーザー体験だけにとどまりません。アップロードが失敗した場合でも、アプリケーション側のデータベースには「アップロード予定」のレコードが残り続け、ストレージ側には孤立したオブジェクトが残ることもあります。これが積み重なると、ストレージ利用量とデータベースの整合性にじわじわとズレが生じます。

なぜ起きるか:2つの契約を混同している

根本原因は、ブラウザのCORSポリシーと署名付きURL(presigned URL)という、本来別々の仕組みを一つの「CORSエラー」として扱ってしまうことです。

署名付きURLは、特定のHTTPメソッド・有効期限・リクエストヘッダーの組み合わせに対して発行者が許可を与える仕組みです。これはサーバー側(ストレージサービス側)の認可の話です。

一方でCORSは、ブラウザというクライアント側が「このオリジンからのこのリクエストを送ってよいか」を実行前にチェックする仕組みです。署名付きURLが正しくても、ストレージバケットのCORS設定がブラウザの送信元オリジンを許可していなければ、プリフライトの段階で止まります。

この2つを混同すると、トラブルシューティングが迷走します。たとえば「CORSエラーが出た」という報告を受けて、バケットのCORS設定をすべてのオリジンに開放してテストを通してしまうケースです。これは診断を認可の全面見直しに変えてしまい、あとから証跡を追うのが難しくなります。一時的な動作確認のつもりが、セキュリティ上の緩すぎる設定として本番に残ってしまう危険もあります。

さらに障害の原因は、実際には5つの異なる境界に分解できます。

  • アプリケーション認可: 呼び出し元・テナント・想定キーが無効
  • ブラウザポリシー: プリフライトがオリジン・メソッド・ヘッダーを許可しない
  • 署名リクエストの契約: 署名の有効期限切れ、または送信リクエストが署名時の内容と相違
  • 取り込み検証: アップロードされたオブジェクトやメタデータが待機中のジョブと紐付かない
  • 公開状態: 完了処理の重複実行で二重に公開レコードが作られる

これらすべてを「アップロード失敗」という一つのラベルで記録すると、ダッシュボード上は見やすくても、障害対応の現場では原因特定に時間がかかります。

自分のプロジェクトが該当するか確認する方法

まず、ブラウザの開発者ツールのネットワークタブで、最初に失敗しているリクエストを特定します。

PUTリクエストそのものが失敗しているのか、その前段のOPTIONSリクエストが失敗しているのかで、見るべき設定が変わります。

OPTIONSが失敗している場合は、ストレージサービスのCORS設定を確認します。AWS S3であればバケットの「アクセス許可」タブにあるCORS設定(JSON形式のCORSRule)を開き、AllowedOrigins・AllowedMethods・AllowedHeadersの3項目が、実際にブラウザが送っているOriginヘッダー、Access-Control-Request-Method、Access-Control-Request-Headersと一致しているかを照合します。

# S3バケットの現在のCORS設定を確認する例
aws s3api get-bucket-cors --bucket your-bucket-name

一方、PUTリクエスト自体が失敗している(403や400が返る)場合は、署名の問題です。署名付きURLの有効期限が切れていないか、PUT時に送っているContent-Typeヘッダーが署名生成時に指定したものと完全に一致しているかを確認します。多くのSDKでは、署名時に指定したヘッダーと実際の送信ヘッダーが1文字でも違うと、署名検証エラーとして拒否されます。

また、マルチリージョン構成(米国とEUでテナントを分けているSaaSなど)の場合は、署名を発行する前にテナントがどのリージョンに割り当てられているかを確認する設計になっているかも見ておきたいポイントです。リージョンごとにキーの名前空間を分けておくと、どのオブジェクトがどの地域の規約に基づいて保存されたかを後から監査できます。これはGDPR(EUの一般データ保護規則)の第5章が定める第三国への移転規制とも関わる話で、ストレージの物理的な設置場所だけでなく、ログ・サポートアクセス・バックアップ・生成処理・レプリケーションがどの地域をまたぐかを明示的に把握しておく必要があります。

対策の手順

切り分けと恒久対策は、以下の順で進めると整理しやすくなります。

1. 障害のフェーズを5つに分けてログに残す

サイニング(署名発行)・プリフライト観測・アップロード・完了処理の各段階で、フェーズ名・ステータス・レイテンシ・テナントを特定できるキー接頭辞・相関ID(一連の処理を追跡するための共通ID)を記録します。署名付きURLそのものはログに残さないようにします。URLに一時的な認可情報が含まれているため、ログ流出がそのままセキュリティインシデントになります。

2. アップロード完了を独立した状態として扱う

PUTが成功したことと、その画像が「公開可能」であることは別の判断です。PUTはバイト列がそのキーに受け入れられたことしか示しません。デコード可能か、モデレーションを通過したか、マルウェアスキャンを通過したか、想定したテナントのジョブと紐付いているかは、サーバー側の完了検証ハンドラーが別途チェックする必要があります。

# 完了検証の擬似フロー(アプリケーション側で実装するロジック)
# 1. クライアントがアップロード完了を通知
# 2. サーバーがストレージ側のオブジェクトメタデータを取得
# 3. 期待されるジョブIDとメタデータを照合
# 4. 一致すればDBレコードをavailableに更新

3. 放置されたオブジェクトはライフサイクルポリシーで自動削除する

アップロードが途中で失敗した場合、ストレージ上にはキーだけ存在して公開されない「孤児オブジェクト」が残ります。S3であればライフサイクルルールで一定期間後に自動削除する設定を入れておくと、ストレージコストの無駄な積み上がりを防げます。ただし他テナントから発見可能な状態にはしない設計が前提です。

4. CORS設定の緩和は一時措置として扱い、戻す手順を決めておく

動作確認のためにAllowedOriginsを*(すべて許可)にした場合は、検証後に必ず本来のオリジンリストへ戻すチケットを同時に起票しておきます。放置すると、次の障害対応時に「これは意図した設定か、デバッグの残骸か」を判断する手間が増えます。

まとめ

ブラウザ直接アップロード構成での障害は、CORSと署名付きURLという別々の契約を一つの「エラー」として扱ってしまうことで複雑化します。

まず最初に失敗しているリクエストがOPTIONSかPUTかをネットワークタブで特定し、前者ならバケットのCORS設定、後者なら署名の有効期限とヘッダー一致を確認する、という切り分けの順序が実務では効きます。

そのうえで、アップロード完了と公開可否を別の状態として扱い、フェーズごとに相関IDでログを残しておくと、次に同じ障害が起きたときの復旧時間を大きく縮められます。まずは手元の環境でget-bucket-corsを叩いて、現在のCORS設定が実際のフロントエンドのオリジンと一致しているか確認するところから始めてみてください。

参考

Generated Image Storage: Browser Direct Upload PUT Preflight Errors

AI 駆動開発のご相談は forva AI へ。

まずはお気軽にどうぞ。