미디어 라이브러리 | EmDash CMS Everything

EmDash에는 이미지, 문서 및 기타 파일을 관리하는 미디어 라이브러리가 포함되어 있습니다. 이 가이드에서는 콘텐츠에서 미디어를 업로드하고, 정리하고, 사용하는 방법을 설명합니다.

미디어 라이브러리 열기

관리 사이드바에서 Media를 클릭해 미디어 라이브러리를 엽니다. 라이브러리에는 업로드된 모든 파일이 미리보기, 파일 이름, 업로드 날짜와 함께 표시됩니다.

업로드 버튼이 있는 이미지 그리드로 표시된 EmDash 미디어 라이브러리

파일 업로드

미디어 라이브러리에서

관리 사이드바에서 Media 클릭
Upload를 클릭하거나 파일을 업로드 영역으로 끌어다 놓기
컴퓨터에서 파일을 하나 이상 선택
업로드가 끝날 때까지 대기

콘텐츠 편집기에서

리치 텍스트 편집기에서 이미지 버튼 클릭
미디어 선택기에서 Upload 클릭
컴퓨터에서 파일 선택
대체 텍스트를 입력하고 Insert 클릭

지원하는 파일 형식

EmDash는 일반적인 웹 파일 형식을 지원합니다.

범주	확장자
이미지	`.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.avif`, `.svg`
문서	`.pdf`, `.doc`, `.docx`, `.xls`, `.xlsx`, `.ppt`, `.pptx`
동영상	`.mp4`, `.webm`, `.mov`
오디오	`.mp3`, `.wav`, `.ogg`

스토리지 백엔드

EmDash는 여러 스토리지 백엔드를 지원합니다. Astro 설정에서 스토리지를 구성합니다.

Local Storage

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

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

파일은 ./uploads 디렉터리에 저장됩니다. 개발 및 단일 서버 배포에 적합합니다.

Cloudflare R2

import { defineConfig } from "astro/config";
import emdash, { r2 } from "emdash/astro";

export default defineConfig({
  integrations: [
    emdash({
      storage: r2({
        binding: "MEDIA_BUCKET",
        publicUrl: "https://media.example.com",
      }),
    }),
  ],
});

wrangler.jsonc에 R2 버킷이 구성되어 있어야 합니다.

{
	"r2_buckets": [
		{
			"binding": "MEDIA_BUCKET",
			"bucket_name": "my-media-bucket",
		},
	],
}

S3-Compatible

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

export default defineConfig({
  integrations: [
    emdash({
      storage: s3({
        endpoint: "https://s3.amazonaws.com",
        bucket: "my-media-bucket",
        accessKeyId: process.env.S3_ACCESS_KEY_ID,
        secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
        region: "us-east-1",
        publicUrl: "https://media.example.com",
      }),
    }),
  ],
});

Cloudflare R2(S3 API 경유), MinIO 및 기타 S3 호환 서비스와 함께 사용할 수 있습니다.

업로드 동작 방식

EmDash는 서명 URL로 안전하게 업로드합니다.

클라이언트가 API에 업로드 URL을 요청합니다.
서버가 만료 시간이 있는 서명 URL을 생성합니다.
클라이언트가 서명 URL을 사용해 스토리지에 직접 업로드합니다.
서버가 데이터베이스에 파일 메타데이터를 기록합니다.

이 방식으로 대용량 파일이 애플리케이션 서버를 거치지 않고 클라우드 스토리지로 직접 올라갈 수 있습니다.

미디어 정리

폴더

미디어를 폴더로 정리할 수 있습니다.

미디어 라이브러리에서 New Folder 클릭
폴더 이름 입력
Create 클릭
파일을 폴더로 끌어다 놓아 정리

검색

검색 상자로 파일 이름을 찾습니다. 파일 이름의 일부와 일치합니다.

필터

다음 기준으로 미디어를 필터링합니다.

Type — 이미지, 문서, 동영상, 오디오
Date — 업로드 날짜 범위
Folder — 특정 폴더

콘텐츠에서 미디어 사용

리치 텍스트 편집기에서

이미지를 넣을 위치에 커서를 둡니다.
도구 모음의 이미지 버튼을 클릭합니다.
미디어 라이브러리에서 이미지를 선택하거나 새로 업로드합니다.
대체 텍스트를 입력합니다.
Insert를 클릭합니다.

대표 이미지로

편집기에서 콘텐츠 항목을 엽니다.
사이드바에서 Featured Image 필드를 찾습니다.
Select Image를 클릭합니다.
미디어 라이브러리에서 선택하거나 업로드합니다.
Save를 클릭합니다.

사용자 정의 필드에서

이미지 또는 파일 형식으로 설정된 필드는 필드를 클릭하면 미디어 선택기가 열립니다.

템플릿에서 미디어 표시

콘텐츠 데이터에서 미디어 URL에 접근합니다.

---
import { getEmDashEntry } from "emdash";

const { entry: post } = await getEmDashEntry("posts", Astro.params.slug);
---

{post?.data.featured_image && (
  <img
    src={post.data.featured_image}
    alt={post.data.featured_image_alt ?? ""}
  />
)}

반응형 이미지

반응형 이미지는 외부 URL에 Astro의 Image 컴포넌트를 사용합니다.

반응형 이미지

반응형 이미지는 외부 URL에 Astro의 Image 컴포넌트를 사용합니다.

---
import { Image } from "astro:assets";
import { getEmDashEntry } from "emdash";

const { entry: post } = await getEmDashEntry("posts", Astro.params.slug);
---

{post?.data.featured_image && (
  <Image
    src={post.data.featured_image}
    alt={post.data.featured_image_alt ?? ""}
    width={800}
    height={450}
  />
)}

Tip

외부 URL로 Image 컴포넌트를 쓰려면 astro.config.mjs에서 허용할 이미지 도메인을 설정하세요.

export default defineConfig({
	image: {
		domains: ["media.example.com"],
	},
});

미디어 삭제

삭제할 파일을 선택합니다.
Delete를 클릭합니다.
삭제를 확인합니다.

미디어 API

관리 API로 프로그래밍 방식으로 미디어에 접근합니다.

파일 업로드

multipart 폼 데이터로 미디어를 업로드합니다.

POST /_emdash/api/media
Content-Type: multipart/form-data
Authorization: Bearer YOUR_API_TOKEN

file=<binary file data>

응답:

{
	"success": true,
	"data": {
		"item": {
			"id": "01ABC123",
			"filename": "hero-image.jpg",
			"mime_type": "image/jpeg",
			"storage_key": "media/abc123/hero-image.jpg",
			"width": 1200,
			"height": 800
		}
	}
}

미디어 목록

GET /_emdash/api/media?prefix=images/&limit=20
Authorization: Bearer YOUR_API_TOKEN

미디어 삭제

DELETE /_emdash/api/media/images/hero.jpg
Authorization: Bearer YOUR_API_TOKEN

미디어 제공자

로컬 스토리지 외에 EmDash는 전문 이미지·동영상 호스팅을 위한 외부 미디어 제공자를 지원합니다. 제공자는 미디어 선택기에서 탭으로 표시되어 여러 소스 중에서 고를 수 있습니다.

사용 가능한 제공자

Cloudflare Images

Cloudflare Images는 자동 최적화, 리사이즈, 포맷 변환이 있는 이미지 호스팅을 제공합니다.

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { cloudflareImages } from "@emdash-cms/cloudflare";

export default defineConfig({
  integrations: [
    emdash({
      // ... database, storage config
      mediaProviders: [
        cloudflareImages({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_IMAGES_TOKEN,
          // Optional: custom delivery domain
          deliveryDomain: "images.example.com",
        }),
      ],
    }),
  ],
});

기능:

관리 화면에서 이미지 탐색 및 업로드
자동 이미지 최적화 및 포맷 변환
URL 기반 변환(크기, 자르기, 포맷)
반응형 이미지를 위한 유연한 변형

Cloudflare Stream

Cloudflare Stream는 HLS/DASH 적응 스트리밍이 있는 동영상 호스팅을 제공합니다.

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { cloudflareStream } from "@emdash-cms/cloudflare";

export default defineConfig({
  integrations: [
    emdash({
      // ... database, storage config
      mediaProviders: [
        cloudflareStream({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_STREAM_TOKEN,
          // Optional: player settings
          controls: true,
          autoplay: false,
          loop: false,
        }),
      ],
    }),
  ],
});

기능:

관리 화면에서 동영상 탐색·검색·업로드
HLS 및 DASH 적응 스트리밍
썸네일 자동 생성
대용량 파일 직접 업로드

여러 제공자 사용

여러 제공자를 구성할 수 있으며, 각각 미디어 선택기의 탭으로 표시됩니다.

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { cloudflareImages, cloudflareStream } from "@emdash-cms/cloudflare";

export default defineConfig({
  integrations: [
    emdash({
      database: d1({ binding: "DB" }),
      storage: r2({ binding: "MEDIA" }),
      mediaProviders: [
        cloudflareImages({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_IMAGES_TOKEN,
        }),
        cloudflareStream({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_STREAM_TOKEN,
        }),
      ],
    }),
  ],
});

로컬 미디어 라이브러리(「Library」 탭)는 구성한 제공자와 항상 함께 사용할 수 있습니다.

제공자 미디어 렌더링

미디어를 렌더링하려면 Image 컴포넌트를 사용합니다.

---
import { Image } from "emdash/ui";
import { getEmDashEntry } from "emdash";

const { entry: post } = await getEmDashEntry("posts", Astro.params.slug);
---

{post?.data.featured_image && (
  <Image
    image={post.data.featured_image}
    width={800}
    height={450}
  />
)}

컴포넌트는 자동으로:

저장된 값에서 제공자를 감지합니다.
최적화된 <img> 요소를 렌더링합니다.
제공자별 최적화(예: Cloudflare Images 변환)를 적용합니다.

MediaValue 타입

미디어 필드는 제공자 정보가 담긴 MediaValue 객체를 저장합니다.

interface MediaValue {
  provider?: string;    // Provider ID, defaults to "local"
  id: string;           // Provider-specific ID
  src?: string;         // Direct URL (for local media or legacy data)
  previewUrl?: string;  // Preview URL for admin display (external providers)
  filename?: string;    // Original filename
  mimeType?: string;    // MIME type
  width?: number;       // Image/video width
  height?: number;      // Image/video height
  alt?: string;         // Alt text
  meta?: Record<string, unknown>; // Provider-specific metadata
}

호스팅 위치와 관계없이 EmDash가 미디어를 올바르게 렌더링할 수 있습니다.

다음 단계

Working with Content — 콘텐츠에서 미디어 사용
Create a Blog — 블로그 글에 이미지 추가
Querying Content — 템플릿에서 미디어 표시