django-storages-s3

Django Storages S3

django-storages と boto3 を使って AWS S3 上で本番環境に適したファイルストレージを実現する、Django のシニアスペシャリストです。公開・非公開メディア、静的ファイル、署名付き URL、CloudFront に対応します。

このスキルを使用する場面

• ローカルファイルシステムの代わりに、AWS S3 から静的ファイルやメディアファイルを配信する場合
• Django 4.2 以降の STORAGES dict、または従来の DEFAULT_FILE_STORAGE を設定する場合
• 公開（CDN 配信）用と非公開（署名付き）用のファイルバックエンドを分ける場合
• 署名付きのダウンロード URL、またはブラウザーから S3 に直接アップロードする URL を生成する場合
• S3 の前段に CloudFront を配置し、最小権限の IAM ポリシーを作成する場合
• コードを変更せずに、ローカルの FileField／ImageField ストレージを S3 に移行する場合
• S3 に接続せずにストレージコードをテストする場合

基本的なワークフロー

1. インストールと登録 — pip install django-storages[s3] boto3 を実行し、"storages" を INSTALLED_APPS に追加します
2. 認証情報の設定 — 環境変数から読み込むか、アタッチされた IAM ロールを使用します。ハードコードは避けてください
3. STORAGES dict の設定 — default（メディア）と staticfiles のバックエンドを設定し、それぞれ異なる location プレフィックスを指定します
4. 名前付きバックエンドの追加 — 必要に応じて、STORAGES のエントリを追加し、公開用と非公開用のバケット／ACL を分けます
5. 確認とテスト — collectstatic を実行してアップロードが S3 に保存されることを確認し、テストでは InMemoryStorage または moto で S3 をモックします

リファレンスガイド

状況に応じて詳細なガイダンスを参照してください。

トピック	リファレンス	参照するタイミング
設定と STORAGES	references/configuration.md	基本設定、4.2 以降と従来方式の違い、CloudFront
カスタムバックエンド	references/custom-backends.md	公開／非公開バケット、フィールドごとのストレージ
署名付き URL	references/presigned-urls.md	ダウンロードリンク、ブラウザーからの直接アップロード
テストと IAM	references/testing-storages.md	S3 のモック、IAM ポリシー、よくある落とし穴

最小限の動作例

以下のスニペットでは、必ず守るべき基本要件を示します。環境変数からの認証情報の読み込み、STORAGES dict、メディアと静的ファイルで異なる保存先、メディアバックエンドでの default_acl=None です。

# settings.py
import os

AWS_STORAGE_BUCKET_NAME = os.environ["AWS_STORAGE_BUCKET_NAME"]
AWS_S3_REGION_NAME = os.environ.get("AWS_S3_REGION_NAME", "us-east-1")
AWS_S3_CUSTOM_DOMAIN = f"{AWS_STORAGE_BUCKET_NAME}.s3.{AWS_S3_REGION_NAME}.amazonaws.com"
# On EC2/ECS/Lambda, omit keys entirely — boto3 uses the attached IAM role.

STORAGES = {
    "default": {  # media uploads
        "BACKEND": "storages.backends.s3boto3.S3Boto3Storage",
        "OPTIONS": {
            "bucket_name": AWS_STORAGE_BUCKET_NAME,
            "location": "media",
            "default_acl": None,        # rely on bucket policy, not per-object ACLs
            "file_overwrite": False,
            "querystring_auth": False,  # public objects → clean URLs
        },
    },
    "staticfiles": {
        "BACKEND": "storages.backends.s3boto3.S3StaticStorage",
        "OPTIONS": {
            "bucket_name": AWS_STORAGE_BUCKET_NAME,
            "location": "static",
        },
    },
}

MEDIA_URL = f"https://{AWS_S3_CUSTOM_DOMAIN}/media/"
STATIC_URL = f"https://{AWS_S3_CUSTOM_DOMAIN}/static/"

# models.py — uploads go straight to S3 on save()
from django.db import models

class Document(models.Model):
    file = models.FileField(upload_to="docs/")  # uses STORAGES["default"]

既存の設定の監査

すでに S3 を使用しているプロジェクトを確認する場合（新規構築ではない場合）は、以下のチェックリストに沿って確認してください。各項目は、以下の制約を「X を探し、Y を確認する」という形で言い換えたものです。

1. 認証情報 — grep -rn "AWS_SECRET_ACCESS_KEY\|aws_secret" settings/ → 値が os.environ／django-environ または IAM ロールから取得され、リポジトリにコミットされたリテラルではないことを確認します。
2. ACL — grep -rn "default_acl\|AWS_DEFAULT_ACL" . → 2023 年 4 月以降に作成されたバケットでは、すべての値が None である必要があります。"public-read"／"private" のいずれかを指定すると AccessControlListNotSupported が発生します。公開アクセスはバケットポリシーで設定します。
3. ストレージバックエンド — Django 4.2 以降では、DEFAULT_FILE_STORAGE／STATICFILES_STORAGE ではなく STORAGES dict を使用していることを確認します（これらの設定は Django 5.1 で削除されているため、5.1／5.2／6.0 では無視されます）。また、静的ファイル用クラスが架空の名前ではなく S3StaticStorage であることを確認します。
4. 保存先 — default（メディア）と staticfiles に異なる location プレフィックスまたはバケットが設定され、collectstatic とアップロードが競合しないことを確認します。
5. リージョン — region_name（またはグローバル設定の AWS_S3_REGION_NAME）がバケットの実際のリージョンと一致し、us-east-1 以外のバケットでは AWS_S3_CUSTOM_DOMAIN にリージョンのセグメントが含まれていることを確認します。
6. 署名付き URL — 非公開バックエンドでは querystring_auth=True かつ custom_domain=None であることを確認します。また、署名付き .url() の結果が AWS_QUERYSTRING_EXPIRE の期限を超えてキャッシュされないことを確認します。
7. 上書き時のクリーンアップ — file_overwrite=False の場合、置き換えられたファイルが明示的に削除されることを確認します（削除されないと、古いオブジェクトが残ります）。
8. IAM — ポリシーで許可されているのがバケット ARN に対する Get/Put/Delete/ListBucket のみであり、より広範な S3 アクセスが付与されていないことを確認します。

制約

必ず行うこと

• AWS の認証情報は、環境変数またはアタッチされた IAM ロールから読み込みます
• バケットポリシー（オブジェクト ACL ではありません）でアクセスを制御できるよう、default_acl=None を設定します
• 静的ファイルとメディアファイルには、別々の location プレフィックスまたは別々のバケットを使用します
• Django 4.2 以降では STORAGES 辞書を使用します（5.2 LTS および 6.0 でも同じ設定を使用できます）。DEFAULT_FILE_STORAGE／STATICFILES_STORAGE は 5.1 で削除されたため、4.2 未満でのみ使用します
• 署名付き URL を発行するバックエンドには、custom_domain=None を設定します
• テストでは実際のバケットに接続せず、S3 をモックします（InMemoryStorage または moto を使用します）

絶対に行わないこと

• AWS_SECRET_ACCESS_KEY を settings.py にハードコードしたり、コミットしたりしないでください
• querystring_auth=True と custom_domain を併用しないでください（署名付き URL の生成に失敗します）
• 静的ファイルとメディアファイルを同じプレフィックスに混在させないでください
• IAM ユーザーに、バケット ARN に対する Get/Put/Delete/ListBucket より広い権限を付与しないでください
• 2023 年 4 月以降に作成されたバケットで、オブジェクトごとの ACL に依存しないでください（ACL はデフォルトで無効です）

ナレッジリファレンス

django-storages、S3Boto3Storage、S3StaticStorage、boto3、STORAGES 辞書、署名付き URL、generate_presigned_post、CloudFront、IAM ポリシー、InMemoryStorage、moto

関連スキル

• django-expert — このスキルが S3 に永続化するファイルを生成する、Django のコアモデル、DRF、ORM
• fullstack-guardian — 保存されたファイルの安全なエンドツーエンドのアップロードフローとアクセス制御
• devops-engineer — このスキルが対象とする S3 バケット、IAM ロール、CloudFront ディストリビューションのプロビジョニング

ドキュメント