스토리지 옵션

EmDash는 업로드된 미디어(이미지, 문서, 비디오)를 구성 가능한 스토리지 백엔드에 저장합니다. 배포 플랫폼과 요구 사항에 따라 선택하세요.

개요

스토리지	최적 용도	특징
R2 바인딩	Cloudflare Workers	제로 구성, 빠름
S3	모든 플랫폼	서명된 업로드, CDN 지원
로컬	개발 환경	간단한 파일 시스템 스토리지

Cloudflare R2 (바인딩)

가장 빠른 통합을 위해 Cloudflare Workers에 배포할 때 R2 바인딩을 사용하세요.

astro.config.mjs

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

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

구성

옵션	타입	설명
binding	string	wrangler.jsonc의 R2 바인딩 이름
publicUrl	string	버킷의 선택적 공개 URL

설정

Wrangler 구성에 R2 바인딩을 추가하세요:

wrangler.jsonc

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

wrangler.toml

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

공개 접근

공개 미디어 URL을 위해 R2 버킷에서 공개 접근을 활성화하세요:

1. Cloudflare 대시보드 > R2 > 해당 버킷으로 이동
2. 설정에서 공개 접근 활성화
3. 구성에 공개 URL 추가:

storage: r2({
  binding: "MEDIA",
  publicUrl: "https://pub-xxxx.r2.dev",
});

팁

R2에 사용자 정의 도메인을 연결하여 https://media.example.com.`과 같은 브랜드 URL을 사용하세요.

참고

R2 바인딩은 서명된 업로드 URL을 지원하지 않습니다. 클라이언트 직접 업로드가 필요한 경우, 대신 R2 자격 증명과 함께 S3 어댑터를 사용하세요.

S3 호환 스토리지

S3 어댑터는 Cloudflare R2(S3 API 통해), MinIO 및 기타 S3 호환 서비스와 작동합니다.

js title="astro.config.mjs"
import emdash, { s3 } from "emdash/astro";

export default defineConfig({
  integrations: [
    emdash({
      storage: s3({
        endpoint: process.env.S3_ENDPOINT,
        bucket: process.env.S3_BUCKET,
        accessKeyId: process.env.S3_ACCESS_KEY_ID,
        secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
        region: "auto", // Optional, defaults to "auto"
        publicUrl: process.env.S3_PUBLIC_URL, // Optional CDN URL
      }),
    }),
  ],
});

구성

옵션	타입	설명
endpoint	string	S3 엔드포인트 URL
bucket	string	버킷 이름
accessKeyId	string	액세스 키
secretAccessKey	string	시크릿 키
region	string	리전 (기본값: "auto")
publicUrl	string	선택적 CDN 또는 공개 URL

S3 API를 통한 R2

서명된 업로드 URL과 같은 기능을 위해 R2와 함께 S3 자격 증명을 사용하세요:

storage: s3({
  endpoint: "https://<account-id>.r2.cloudflarestorage.com",
  bucket: "emdash-media",
  accessKeyId: process.env.R2_ACCESS_KEY_ID,
  secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
  publicUrl: "https://pub-xxxx.r2.dev",
});

Cloudflare 대시보드의 R2 > R2 API 토큰 관리에서 R2 API 자격 증명을 생성하세요.

MinIO

storage: s3({
  endpoint: "https://minio.example.com",
  bucket: "emdash-media",
  accessKeyId: process.env.MINIO_ACCESS_KEY,
  secretAccessKey: process.env.MINIO_SECRET_KEY,
  publicUrl: "https://minio.example.com/emdash-media",
});

로컬 파일 시스템

개발 환경에는 로컬 스토리지를 사용하세요. 파일은 디스크의 디렉터리에 저장됩니다.

js title="astro.config.mjs"
import emdash, { local } from "emdash/astro";

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

구성

옵션	타입	설명
directory	string	파일 저장을 위한 디렉터리 경로
baseUrl	string	파일 제공을 위한 기본 URL

사용자 정의 정적 파일 서버를 구성하지 않는 한, baseUrl은 EmDash의 미디어 파일 엔드포인트(/_emdash/api/media/file)와 일치해야 합니다.

주의

로컬 스토리지는 서명된 업로드 URL을 지원하지 않습니다. 파일은 서버를 통해 업로드되며, 대용량 파일의 경우 속도가 느릴 수 있습니다.

환경 기반 구성

환경에 따라 스토리지 백엔드를 전환하세요:

js title="astro.config.mjs"
import emdash, { s3, 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;
}

이 일관성 덕분에 애플리케이션 코드를 변경하지 않고 스토리지 백엔드를 전환할 수 있습니다.