ファイルストレージのセットアップ

初心者向けのウォークスルー

前提条件: 以下の 2 つの初心者向けガイドを読み、Web ローカルのセットアップを完了し、エディターでルートにあるこのモノリポジトリを開きます。 Web 設定は apps/web/.env.local に属します。 Next.js はルート .env を読み取りません。デフォルトのフェイク モードの /dashboard はデータベースなしのデモです。 /auth には移行されたデータベースが必要です。

簡単に説明すると、ワークスペースは 1 つのチームの個別のユーザー、データ、設定です。サーバーは信頼できるバックエンドです。プロバイダー キーがブラウザーや電話コードに含まれないようにします。移行は、テーブルを作成または更新する、バージョン管理されたデータベースの変更です。 AI モデルは答えを返すエンジンです。モデル カタログは、使用可能なモデル ID と価格のサーバーのリストです。プロバイダーは、AI、電子メール、請求サービスなどの外部サービスです。資格は、ワークスペースで機能を使用できるようにする付与です。 Webhook は、あるサービスが別のサービスの URL に送信するメッセージです。

1. 認証情報なしのトライアルの場合は、STORAGE_PROVIDER=memory を保持します。このチェックアウトに表示されるアップロード コントロールがない場合は、小さなサンプル イメージをワイヤリングする前に、コーディング エージェントに apps/web/app/api/storage/avatar/route.ts、apps/web/app/api/storage/logo/route.ts、apps/web/app/api/storage/organization-logo/route.ts、および一致する設定ページを検査するよう依頼してください。

2. 永続性を確認するには、apps/web/.env.local で STORAGE_PROVIDER=s3、STORAGE_REGION、および STORAGE_BUCKET を設定し、サーバーのみのテスト資格情報をローカルに追加して、再起動します。

3. イメージがストレージから再ロードされます。メモリ ファイルはプロセスが再起動されると消えます。 S3 エラーについては、バケット、エンドポイント、アクセス ポリシーを確認してください。

カスタム コードの場合は、提供された prompts/README.md から始めて、最も近いプロンプト (アプリ画面の場合は prompts/new-app-screen.md、パブリック ページの場合は prompts/new-landing-page.md) をコピーします。サーバー、データベース、またはプロバイダーの作業については、コーディング エージェントにこのガイドのタスクを与え、AGENTS.md、.ai/PROJECT_CONTEXT.md、および一致する .ai/ ミラーを読み取るように依頼します。ここで指定されている正確なソース ファイルを調べてください。ファイルをリストし、編集前にチェックします。ワークスペースの所有権とサーバーのみの秘密を保持します。そして差分を見せてください。必要な動作、入力フィールドと出力フィールド、許可されるロール、予想される成功とエラー、テスト アカウント、プロバイダー、またはデバイスを指定します。サンプル値を使用します。絶対に本当の秘密を貼り付けないでください。

• 始める前に

【端末の基本】(/docs/web/terminal-basics)

• Webローカル設定
• エージェント プロンプトとプロジェクト メモリ

ストレージ バックエンドを選択します

STORAGE_PROVIDER=memory は認証情報不要のデフォルトです。local は STORAGE_LOCAL_DIR（デフォルトは ./.data/storage、本番環境では明示的な指定が必須）配下のディスクにオブジェクトを書き込み、単一サーバー構成向けに /api/storage/local/[...key] の HMAC 署名付き期限付き URL（STORAGE_LOCAL_SIGNING_SECRET、未設定時は AUTH_SECRET にフォールバック）経由で配信します。s3 は apps/web/src/storage-runtime.ts を使用して @supastack/storage コントラクト上に AWS SDK クライアントを構成し、デフォルトでパススタイル URL が有効な Supabase Storage や MinIO をサポートします。

STORAGE_PROVIDER=s3
STORAGE_REGION=us-east-1
STORAGE_BUCKET=your-product-bucket
# Set STORAGE_ACCESS_KEY_ID and STORAGE_SECRET_ACCESS_KEY on the server.
# Optional: STORAGE_ENDPOINT, STORAGE_FORCE_PATH_STYLE, STORAGE_PUBLIC_BASE_URL
# Self-hosted single-server disk storage:
# STORAGE_PROVIDER=local
# STORAGE_LOCAL_DIR=./.data/storage
# STORAGE_LOCAL_SIGNING_SECRET=
# Local MinIO Compose overrides: MINIO_ROOT_USER / MINIO_ROOT_PASSWORD

アップロード境界を再利用する

出荷されるルートには、/api/storage/ の下のオブジェクト、アバター、プロフィール ロゴ、および組織ロゴが含まれます。 ID/ワークスペースの権限を解決し、保存する前にアップロードの形式を検証します。任意のクライアント オブジェクト キーを受け入れるのではなく、選択したルートのサイズ/タイプ ポリシーを検査します。

パブリック URL はプレゼンテーションであり、承認ではありません。保護されたコンテンツをアプリケーションの検証済み読み取り境界の内側に保持し、製品データのバケット/CDN ポリシーを構成します。

実際のストレージの動作をテストする

アップロードの許可/拒否、MIME とサイズの拒否、外部ワークスペースのパス、オブジェクトの欠落、プロバイダーの障害をテストします。メモリ モードはプロセス間で持続しません。リリース前に、選択したバックエンドに対してストレージと取得を検証します。

• Supabase ストレージのセットアップ
• ルート在庫のアップロード

インストールとセットアップ

1. STORAGE_PROVIDER=memory（デフォルト）はアップロードをプロセス内に保持します——開発とテストに適しています。

2. 実際のファイルには STORAGE_PROVIDER=s3 とバケット・アクセスキーのペアを設定します。STORAGE_ENDPOINT は任意の S3 互換サービスを選べます——https://<ref>.supabase.co/storage/v1/s3 の Supabase Storage、MinIO、AWS そのものです。

3. STORAGE_FORCE_PATH_STYLE はエンドポイントが設定されるとデフォルトで true になります——Supabase と MinIO はこれを必須とします。virtual-hosted 形式のカスタムエンドポイントの場合のみ false に設定してください。

4. 必要に応じて STORAGE_PUBLIC_BASE_URL を CDN に向けると、公開オブジェクト URL がそこで解決されます。

STORAGE_PROVIDER=s3
STORAGE_ENDPOINT=https://<ref>.supabase.co/storage/v1/s3
STORAGE_REGION=us-east-1            # Supabase: project region
STORAGE_BUCKET=<bucket>
STORAGE_ACCESS_KEY_ID=…
STORAGE_SECRET_ACCESS_KEY=…
STORAGE_PUBLIC_BASE_URL=https://cdn.example.com   # optional

# No bucket yet? Local S3-compatible storage ships in compose:
docker compose --profile storage up -d minio    # console on :9001

実装ワークフロー

アップロードと読み取りは、まずワークスペースを解決する認証済みルートを経由します——/api/storage/objects と専用のアバター・ロゴルート。保存されるすべてのキーは buildWorkspaceObjectKey により {workspaceId}/{purpose}/{safeName} として名前空間化されます。

認証情報はサーバー専用のままです；ブラウザはバケットやキーを見ることはありません。

アップロードは動きましたか？「オブザーバビリティのセットアップ」に進みます。

検証とトラブルシューティング

アップロードが往復すること、別のワークスペースがオブジェクトを読めないこと、大きすぎる・許可されていないコンテンツタイプが失敗することを検証します。Supabase や MinIO に対する署名エラーや 403 エラーは、たいてい STORAGE_FORCE_PATH_STYLE がそのエンドポイントに合っていないことを意味します。