Skip to content
agent-cms
가이드 / 파일 관리자

가이드 / file-manager

파일 관리자

저장소 버킷을 폴더별로 있는 그대로 봐요. CMS로 올리지 않은 파일도 옮기고, 공유하고, 지울 수 있어요.

수정 2026년 11월 21일편집 docs seed버전 2
이 페이지

note

npm에서는 0.10.0부터 쓸 수 있어요.

미디어 라이브러리는 CMS가 아는 파일을 보여줘요. 파일 관리자(npx @mainsoft/agent-cms add cms-files, <CmsFiles />를 둔 페이지)는 버킷을 폴더별로 있는 그대로 보여줘요. 다른 프로그램이 넣은 파일도 보여요. 사이드바의 "파일"은 저장소를 둘러볼 수 있는 사람에게만 보여요. 기본은 그 저장소를 읽을 수 있는 사람이고, 저장소의 access.browse로 좁힐 수 있어요.

CMS가 모르던 파일#

  • CMS가 모르던 파일은 누가 열거나, 태그를 달거나, 공유하거나, 에이전트가 등록할 때 행이 생겨요. 그때부터 다른 파일처럼 문서에 쓸 수 있어요. npx @mainsoft/agent-cms storage sync [--store name] [--folder path]는 한꺼번에 등록하고, CMS는 알지만 버킷에서 사라진 파일을 알려줘요(아무것도 지우지 않아요).
  • 여러 파일과 폴더를 한 번에 옮기거나 지울 수 있어요(요청 하나에 1000개까지). 옮기기는 파일을 하나씩 복사하고 지워요. 실패한 파일은 알려주고, 다시 옮기면 남은 것만 옮겨요. 옮길 곳에 같은 이름이 있으면 번호를 붙여요. 덮어쓰는 일은 없어요. 지울 때는 그 파일을 쓰는 문서를 먼저 보여줘요.
  • "링크 만들기"는 바깥 사람에게 줄 주소를 만들어요. 비공개 저장소의 링크는 1시간, 24시간, 7일 동안 유효하고 되돌릴 수 없어요(서명된 주소라서요). 공개 저장소는 파일의 공개 주소를 줘요. 그 저장소에서 삭제할 권한이 있어야 만들 수 있고, 감사 로그에 남아요.
  • CMS가 쓰는 폴더(_cms/, 썸네일)는 보이지 않고 건드릴 수 없어요.

에이전트#

에이전트 도구가 세 개 늘어요. list_store_files(read), register_asset(write), create_share_link(publish)예요.

REST#

GET /stores/:store/files?folder=는 폴더 하나를 보여줘요. POST /stores/:store/files/_register, _move, _delete는 키(경로)로 동작해요. 삭제에 check: true를 주면 지워질 개수와 그 파일을 쓰는 문서만 세어 줘요. POST /assets/:id/share에 { ttl: "1h" | "24h" | "7d" }를 보내면 링크를 만들어요.