メディアストレージの選択

概要

Cloudflare R2バインディング

Cloudflare Workersでは、R2バインディングのアダプターを使います。実行時にバインディングがアクセス手段を提供するため、サイトにR2のアクセスキーは必要ありません。

import emdash from "emdash/astro";
import { r2 } from "@emdash-cms/cloudflare";

export default defineConfig({
	integrations: [
		emdash({
			storage: r2({ binding: "MEDIA" }),
		}),
	],
});

設定項目

セットアップ

Wranglerの設定にR2バインディングを追加します。

{
  "r2_buckets": [
    {
      "binding": "MEDIA",
      "bucket_name": "emdash-media"
    }
  ]
}

[[r2_buckets]]
binding = "MEDIA"
bucket_name = "emdash-media"

公開アクセス

公開バケットからメディアを配信するには、Cloudflare APIでカスタムドメインを接続し、そのオリジンを publicUrl に設定します。Cloudflareの r2.dev の開発用URLにはレート制限があり、本番のトラフィックを想定したものではありません。

storage: r2({
	binding: "MEDIA",
	publicUrl: "https://media.example.com",
});

同じバケットに自動のJSONバックアップも保存している場合、公開バケットのオリジンから backups/ 配下のオブジェクトが見えてしまうことがあります。非公開のバケットとEmDashのメディア用ルートを使うか、公開オリジンをメディアのオブジェクトだけに制限します。詳しくはバックアップを参照してください。

S3互換ストレージ

S3アダプターは、Node.js上で、Cloudflare R2のS3 API、AWS S3、MinIO、およびその互換サービスと組み合わせて動作します。

次の設定では、Node.jsのプロセスの起動時に、エンドポイント、バケット、資格情報、リージョン、任意の公開URLを S3_* の変数から読み込みます。

import emdash, { s3 } from "emdash/astro";

export default defineConfig({
	integrations: [
		emdash({
			storage: s3(),
		}),
	],
});

設定項目

* accessKeyId と secretAccessKey は、両方を指定するか、両方を省略します。

環境変数からのS3設定の読み込み

s3({...}) で省略したフィールドは、プロセスの起動時に、対応する S3_* の環境変数から読み込まれます。これにより、コンテナーイメージを一度ビルドし、再ビルドせずに起動時に資格情報を注入できます。s3({...}) に明示した値は、常に環境変数より優先されます。

環境変数は、プロセスの起動時に process.env から読み込まれます。これはNode.js専用の機能です。

s3() を引数なしで呼び出すと、すべてのフィールドを S3_* の環境変数から読み込みます。

import emdash, { s3 } from "emdash/astro";

export default defineConfig({
	integrations: [
		emdash({
			// s3() with no args: all fields from S3_* environment variables
			storage: s3(),

			// Or mix: override one field, rest from environment
			// storage: s3({ publicUrl: "https://cdn.example.com" }),
		}),
	],
});

S3 API経由のR2

R2への署名付きの直接アップロードが必要な場合は、Node.js上でS3アダプターを使います。Cloudflare APIまたはCLIで、範囲を限定したR2のAPI資格情報を作成し、次の実行時の変数を設定します。

S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
S3_BUCKET=emdash-media
S3_ACCESS_KEY_ID=<r2-access-key-id>
S3_SECRET_ACCESS_KEY=<r2-secret-access-key>
S3_REGION=auto
S3_PUBLIC_URL=https://media.example.com

実際の値は、Node.jsのホスティング環境のシークレット管理機能に保存します。公開URLは任意で、アップロードに使うS3 APIのエンドポイントの代わりにはなりません。

MinIO

同じ実行時の変数をMinIOに向けます。S3_ENDPOINT にはMinIOのAPIのオリジン、S3_BUCKET にはバケット名、2つの資格情報の変数には範囲を限定したMinIOのアクセスキーを設定します。S3_PUBLIC_URL は、そのオリジンがバケットのオブジェクトを公開で配信する場合だけ設定します。

ローカルのファイルシステム

ローカルストレージは、開発時か、永続ディスクを持つ1台のNode.jsサーバーで使います。ファイルは、そのディスク上のディレクトリに保存されます。

import emdash, { local } from "emdash/astro";

export default defineConfig({
	integrations: [
		emdash({
			storage: local({
				directory: "./uploads",
				baseUrl: "/_emdash/api/media/file",
			}),
		}),
	],
});

設定項目

独自の静的ファイルサーバーを設定する場合を除き、baseUrl はEmDashのメディアファイルのエンドポイント（/_emdash/api/media/file）に合わせます。

環境ごとのストレージの使い分け

次の設定では、開発中はローカルのディレクトリを使い、Cloudflareの本番ビルドではR2を使います。

import emdash, { local } from "emdash/astro";
import { r2 } from "@emdash-cms/cloudflare";

const storage = import.meta.env.PROD
	? r2({ binding: "MEDIA" })
	: local({
			directory: "./uploads",
			baseUrl: "/_emdash/api/media/file",
		});

export default defineConfig({
	integrations: [emdash({ storage })],
});

署名付きアップロード

S3アダプターは署名付きアップロードURLに対応しています。これにより、クライアントはサーバーを経由せずに、ストレージへ直接アップロードできます。大きなファイルのアップロードが速くなります。

S3アダプターを使う場合、署名付きアップロードは自動で使われます。管理画面は、使える場合に署名付きアップロードを使います。

署名付きアップロードに対応するアダプター：

• S3（S3 API経由のR2を含む）

署名付きアップロードに対応しないアダプター：

• R2バインディング（代わりにR2の資格情報を使ってS3アダプターを使います）
• ローカル

ストレージのインターフェース

すべてのストレージアダプターは、同じインターフェースを実装しています。

interface Storage {
	upload(options: {
		key: string;
		body: Buffer | Uint8Array | ReadableStream;
		contentType: string;
	}): Promise<UploadResult>;

	download(key: string): Promise<DownloadResult>;
	delete(key: string): Promise<void>;
	exists(key: string): Promise<boolean>;
	list(options?: ListOptions): Promise<ListResult>;
	getSignedUploadUrl(options: SignedUploadOptions): Promise<SignedUploadUrl>;
	getPublicUrl(key: string): string;
}

インターフェースが共通なので、アプリケーションのコードを変えずにストレージのバックエンドを切り替えられます。