가이드 / 미디어 라이브러리
가이드 / media-library
미디어 라이브러리
사진, 영상, 파일을 내 버킷에 둬요. 올릴 때는 브라우저에서 저장소로 바로 보내요.
note
npm에서는 0.10.0부터 쓸 수 있어요 (0.8.0과 0.9.0은 npm에 따로 올리지 않았어요). createCms에 media를 넣지 않으면 기능이 꺼져 있고 아무것도 달라지지 않아요.
문서에 이미지, 영상, 파일을 넣을 수 있어요. 파일은 내 저장소 버킷에 있고, CMS는 파일마다 행 하나만 가져요. 브라우저는 서명된 주소를 받아 저장소로 바로 올려요. 앱 서버를 거치지 않으니 서버리스 호스트에서도 5GB 영상을 올릴 수 있어요.
설정#
import { s3Storage } from "@mainsoft/agent-cms/storage-s3";
const s3 = (bucket: string, publicUrl?: string) =>
s3Storage({ bucket, region: "auto", endpoint: process.env.S3_ENDPOINT, accessKeyId: process.env.S3_KEY!, secretAccessKey: process.env.S3_SECRET!, publicUrl });
export const cms = createCms({
// …
media: {
stores: {
// The first store is the default. `public`: anyone with the address can read.
public: { label: "Public", visibility: "public", adapter: s3("site-media", "https://media.example.com") },
// `private`: opened through the CMS after a permission check, with a link that works for 5 minutes.
private: { label: "Private", visibility: "private", adapter: s3("site-private"), accept: ["application/pdf"], maxFileSize: 100 * 1024 ** 2 },
},
// accept: ["image/*", "video/*", ".pdf"], // what every store takes; default below
// maxFileSize: 5 * 1024 ** 3, // default 5GB
imageUrl: ({ url, width }) => `/_next/image?url=${encodeURIComponent(url)}&w=${width}&q=75`,
},
});s3Storage는 AWS S3(endpoint는 빼고 region을 넣어요), Cloudflare R2(region: "auto"와 계정의 S3 endpoint), MinIO를 비롯한 S3 호환 서버에서 동작해요. 요청 서명을 직접 하므로(aws4fetch) AWS SDK를 설치하지 않아요. 다른 종류의 저장소는 StorageAdapter(./storage)를 구현해 연결해요.
Cloudflare R2는 2026-11-20에 실제 버킷으로 확인했어요(CI가 S3 호환 서버에 돌리는 것과 같은 테스트예요). 브라우저에서 한 번에 올리기와 조각으로 올리기, 서명된 링크, 복사, 목록, CORS 규칙이 모두 동작해요. 알아 둘 것은 세 가지예요. R2 키는 그 버킷으로 한정한 Object Read & Write 토큰으로 만드세요. 공개 저장소에는 버킷의 공개 주소(pub-….r2.dev 주소나 커스텀 도메인)를 publicUrl로 넣어야 해요. S3 endpoint는 서명 없이는 파일을 내주지 않아요. 그리고 CORS 규칙은 대시보드(R2, 버킷, Settings, CORS policy)나 Cloudflare API로 넣어요. 사이트 주소와 GET, HEAD, PUT을 허용하세요. 빠져 있으면 storage check가 알려 줘요.
Vercel Blob#
0.11.0부터 쓸 수 있어요. @vercel/blob을 설치하고 저장소에 Blob 어댑터를 주세요.
import { vercelBlobStorage } from "@mainsoft/agent-cms/storage-vercel-blob";
stores: {
public: { visibility: "public", adapter: vercelBlobStorage({ token: process.env.BLOB_READ_WRITE_TOKEN!, access: "public" }) },
private: { visibility: "private", adapter: vercelBlobStorage({ token: process.env.BLOB_PRIVATE_READ_WRITE_TOKEN!, access: "private" }) },
}access는 Blob 저장소를 만들 때 고른 값이에요. 비공개 저장소의 파일은 서명된 링크로만 열려요. prefix를 주면 모든 파일이 저장소의 그 폴더 아래에 들어가요.
| S3 호환 | Vercel Blob | |
|---|---|---|
| 브라우저가 저장소로 바로 올리기 | 돼요 | 돼요 |
| 큰 파일 | 16MB 조각을 네 개씩 | 파일 하나를 요청 하나로 |
| 실패한 조각만 다시 보내기 | 돼요 | 이 저장소에서는 지원하지 않아요. 파일을 처음부터 다시 올려요 |
| 새로 고친 뒤 이어 올리기 | 돼요 | 이 저장소에서는 지원하지 않아요 |
| CORS 규칙 | 직접 설정해요 | 설정할 것이 없어요 |
| 저장되는 형식 | CMS가 서명한 값 | Blob이 확장자에서 읽어요 |
| 파일 관리자, 공유 링크, 바꾸기, 이미지 크기 | 돼요 | 돼요 |
서명된 주소는 올리기 전에 밝힌 크기까지만 받아요. 공유 링크는 길어야 7일이에요. 150MB 파일을 요청 하나로 올려 봤고 올라갔어요. Vercel은 100MB가 넘으면 조각으로 올리라고 권하는데 이 어댑터는 조각을 쓰지 못하니, 저장소의 maxFileSize를 정해 두는 편이 좋아요. 2026-11-20에 실제 공개 저장소와 비공개 저장소로 확인했어요(@vercel/blob 2.9.0).
CORS#
버킷에는 사이트가 PUT할 수 있게 하는 CORS 규칙이 있어야 해요. agent-cms.config.ts에 같은 media 객체를 넣고 실행하세요.
npx @mainsoft/agent-cms storage check --origin https://your-site.example모든 저장소에 시험 파일을 실제로 올리고, 읽고, 옮기고, 지워요. 조각으로 나눠 올리기와 브라우저 방식의 서명 주소도 확인해요. CORS 규칙을 시험하고, 버킷에 붙여 넣을 규칙을 출력하고, 저장소마다 받는 형식을 보여줘요. npx @mainsoft/agent-cms storage cleanup은 시작만 하고 끝내지 않은 업로드를 지워요. 그런 업로드가 있으면 doctor가 알려줘요.
올릴 수 있는 파일#
무엇을 받을지는 세 단계로 정해요. 앱 전체는 media.accept, 저장소 하나는 stores.<name>.accept(앱 전체 목록을 대신해요), 필드 하나는 admin.fields.<field>.accept(그 저장소의 목록을 더 좁혀요)예요. 항목은 MIME 형식(image/png), 묶음(image/*), 확장자(.pdf)로 쓰고, ["*/*"]는 무엇이든 받아요. 정하지 않으면 기본값(DEFAULT_ACCEPT)이 이미지, 영상, 소리, PDF, 오피스 문서, 텍스트, ZIP을 받아요. 웹 페이지와 프로그램은 목록에 직접 넣었을 때만 받아요. maxFileSize도 같은 세 단계예요.
서버는 업로드를 시작할 때 이름과 선언한 형식을 확인하고, 끝날 때 실제로 도착한 파일의 앞부분을 확인해요. 이름만 photo.png인 웹 페이지는 다시 지워요(asset_type_mismatch).
직접 하는 검사#
media.scan은 파일이 도착할 때마다 한 번 불려요. 브라우저 업로드가 끝났을 때, 서버가 파일을 가져오거나 저장했을 때, 버킷에 이미 있던 파일을 등록할 때예요. 바이러스 검사나 콘텐츠 정책을 여기에 넣어요.
media: {
stores: { /* … */ },
scan: async ({ url, bytes, name, mime, size }) => {
// `url`: a signed address that works for 10 minutes. `bytes` instead when the CMS holds the file in memory.
const verdict = await myScanner.check(url ?? bytes);
return verdict.clean ? true : { ok: false, reason: verdict.name };
},
},거부한 파일은 저장소에서 지워지고 쓸 수 없어요(등록하려던 파일은 있던 자리에 그대로 둬요). 호출한 쪽은 asset_rejected를 받고, 감사 로그에 이유가 남아요. 검사 함수가 오류를 던져도 거부예요.
문서 안에서#
파일은 id로 가리켜요. 그래서 옮기거나 이름을 바꿔도 페이지가 깨지지 않아요.

Read [the full report](asset:r7w2k9m4x1pa/report-2026.pdf).한 줄을 통째로 차지한 이미지 문법은 미디어 블록이에요. 파일 형식에 따라 사진, 영상 플레이어, 다운로드 카드가 돼요. 는 바깥 이미지를 보여줘요. 필드에는 image나 file 위젯을 쓰고, 값은 파일의 id예요.
import { assetId } from "@mainsoft/agent-cms";
fields: z.object({ cover: assetId().optional(), brochure: assetId().optional() }),
admin: { fields: { cover: { widget: "image" }, brochure: { widget: "file", accept: [".pdf"], maxFileSize: 20 * 1024 ** 2 } } },
media: { requireAlt: true }, // an image without alt text stops a save (default: a warning)저장할 때 문서가 가리키는 파일을 확인해요. 없는 파일이거나 필드와 종류가 맞지 않으면 오류예요. 대체 텍스트가 없거나 공개 문서에 비공개 파일이 있으면 경고예요.
내 페이지에서#
문서가 쓰는 파일을 받아서, 전처럼 블록 트리를 그리면 돼요.
const doc = await cms.get(anon, "posts", slug);
const files = await cms.assetsFor(doc); // { [id]: { url, width, height, alt, kind, mime, … } }
const cover = files[doc.fields.cover];
<img src={cms.imageUrl(cover, { width: 1200 })} width={cover.width} height={cover.height} alt={cover.alt} />parseMarkdown은 { t: "media", asset, alt, caption } 블록을 줘요. asset을 files에서 찾으세요. 기본으로는 CMS가 원본만 보관하고, 크기 바꾸기는 media.imageUrl을 통해 프레임워크나 CDN이 맡아요.
이미지 크기#
0.11.0부터는 CMS가 직접 만들 수도 있어요. 선택 모듈이에요. sharp를 설치하고 크기에 이름을 붙이세요. Node 런타임에서만 돌아가요. Edge 런타임이면 앱이 시작할 때 이유와 함께 멈춰요.
import { sharpTransforms } from "@mainsoft/agent-cms/image-sharp";
media: {
stores: { … },
transforms: sharpTransforms({
presets: { thumb: { width: 480 }, card: { width: 800, height: 450, fit: "cover" }, full: { width: 1600 } },
formats: ["webp"], // webp(기본), avif, jpeg, png
}),
}<img
src={cms.imageUrl(cover, { size: "card" })}
style={{ objectPosition: cover.focal ? `${cover.focal.x * 100}% ${cover.focal.y * 100}%` : undefined }}
alt={cover.alt}
/>- 이름을 붙인 크기만 있어요. 주소는
/api/cms/files/<id>/<이름>?size=card예요. 없는 이름은 404(unknown_image_size)예요. - 처음 요청받을 때 만들어서 같은 저장소의
_cms/derived/아래에 둬요. 그다음부터는 만들어 둔 파일로 넘겨요. 원본을 지우거나 바꾸면 함께 지워요. - 한도: 긴 쪽 4096px, 동시에 4개, 한 건에 10초, 입력 40MB. 한도를 넘거나 sharp가 실패하면 원본을 내보내요. SVG와 GIF는 그대로 내보내요. 원본보다 크게 만들지 않아요.
- 모듈을 켜면 에이전트가 가져온 이미지와 CLI로 올린 이미지의 목록용 썸네일을 서버가 만들어요.
초점. 파일 패널의 "초점"을 누르고 사진에서 꼭 보여야 하는 곳을 찍어요. 화살표 키로도 옮겨요. fit: "cover"인 크기는 그 점을 중심으로 잘리고, assetsFor가 focal: { x, y }(0에서 1)로 돌려줘요. 에이전트는 update_asset으로 정해요. 자르기 편집기는 없어요. 원본은 바뀌지 않아요.
누가 무엇을 할 수 있나#
파일 목록 보기와 비공개 파일 열기는 로그인한 사람과 키가 할 수 있어요. 올리기, 가져오기, 대체 텍스트, 태그, 새 폴더는 관리자와 write 키가 해요. 옮기기, 이름 바꾸기, 삭제는 관리자와 publish 키가 해요. 저장소의 access: { read, write, delete }로 셋 중 무엇이든 바꿀 수 있어요. 문서가 쓰고 있는 파일을 지우려 하면 asset_in_use와 문서 목록이 돌아오고, 확인해야 지워져요. 올리기, 옮기기, 삭제는 감사 로그에 남아요.
파일 경로는 GET /api/cms/files/<id>/<name>이에요. 권한을 확인한 뒤 공개 주소나 잠깐만 유효한 서명 주소(media.linkTtlSeconds, 기본 300초)로 보내요. 핸들러가 /api/cms가 아닌 곳에 있으면 media.filesUrl을 정하세요.
어드민에서#
화면을 추가하고(npx @mainsoft/agent-cms add cms-media) 페이지를 만들어요. 앱에 라이브러리가 있으면 사이드바에 "미디어"가 저절로 보여요.
// app/admin/media/page.tsx
"use client";
import { CmsMedia } from "@/components/cms/cms-media";
export default function MediaPage() {
return <CmsMedia />;
}브라우저는 파일을 저장소로 바로 보내요. 큰 파일은 조각 네 개씩 보내고, 실패한 조각은 세 번까지 다시 시도해요. "다시 시도"는 아직 못 보낸 조각만 보내요. 이미지와 영상은 라이브러리에 쓸 작은 그림(480px, WebP)도 만들고, 너비와 높이와 길이를 읽어요. "URL에서 가져오기"는 공개 https 주소의 파일을 열려 있는 폴더로 가져와요(내부망 주소는 에이전트와 똑같이 거부해요). 파일 패널의 연필은 이름을 바꿔요. 확장자는 그대로라서 형식이 바뀌지 않아요. 자세한 것은 미디어 화면에 있어요. "바꾸기"는 파일의 주소를 그대로 둔 채 내용만 새 파일로 바꾸고, media.stripMetadata는 사진을 보내기 전에 카메라 정보를 지워요.
에이전트와 CLI#
앱에 미디어 라이브러리가 있으면 에이전트 도구가 여섯 개 늘어요. list_assets, get_asset(read), import_asset(https 주소의 파일을 라이브러리로 가져와요. 내부망 주소는 거부해요), update_asset(write), move_asset, delete_asset(publish)이에요. 터미널에서는 이렇게 올려요.
npx @mainsoft/agent-cms upload ./hero.png ./talk.mp4 --folder launch --alt "The launch screen" --tag launch버킷 전체#
라이브러리는 CMS가 아는 파일을 보여줘요. 파일 관리자는 버킷을 있는 그대로 보여줘요.