본문으로 건너뛰기
아우라베이스 로고
아우라베이스

JavaScript SDK를 사용하여 파일 저장 및 제공

버킷 관리, 단일 및 멀티파트 업로드, 스트리밍 다운로드, HMAC 서명된 URL, 휴지통 복원 등 일상적인 스토리지는 client.storage를 통해 흐릅니다.

방법 가이드8분 읽기레벨 중급2026. 10. 28.에 개정됨

이 페이지는 자동으로 번역되었습니다. 영어 버전은 권위가 있습니다.

버킷 관리#

버킷은 파일을 그룹화하고 공개 여부를 결정합니다. 버킷을 생성하고 삭제하려면 service_role 키가 필요합니다. 버킷을 나열하려면 로그인한 사용자 또는 service_role 키가 필요합니다(익명 키는 403 FORBIDDEN를 수신함).

server/buckets.tstypescript
// 공개 버킷 생성(API 키 없이 누구나 객체를 읽을 수 있음)
await admin.storage.createBucket('avatars', { public: true })

// 프라이빗 버킷 생성(객체 소유자 또는 service_role만 읽을 수 있음)
await admin.storage.createBucket('invoices', {
  public: false,
  fileSizeLimit: 10 * 1024 * 1024, // 파일당 10MiB 제한
  allowedMimeTypes: ['application/pdf'],
})

// 액세스 가능한 버킷 나열
const { data: buckets, error } = await admin.storage.listBuckets()

버킷은 fileSizeLimit(바이트 단위) 및 allowedMimeTypes도 허용합니다. 너무 큰 업로드는 413 PAYLOAD_TOO_LARGE를 반환하고 허용되지 않는 유형은 400 BAD_REQUEST을 반환합니다.

업로드, 다운로드, 나열, 제거#

files.tstypescript
const bucket = aura.storage.from('invoices')

// 업로드: 파일, Blob, 버퍼 또는 Uint8Array
// 5MiB를 초과하는 파일은 자동으로 여러 부분으로 분할됩니다.
const { data, error } = await bucket.upload(`${user.id}/2026-10.pdf`, file, {
  contentType: 'application/pdf',
  onUploadProgress: (progress) => {
    console.log(`Upload progress: ${progress.percentage}%`)
  },
})
// → { 키, 버킷, URL, 크기, content_type, etag }

// 현재 사용자가 소유한 기존 파일 바꾸기
await bucket.upload(`${user.id}/2026-10.pdf`, newFile, { upsert: true })

// 접두사/폴더 아래의 파일 나열
const { data: files } = await bucket.list({ prefix: `${user.id}/` })

// 파일을 Blob으로 다운로드
const { data: blob, error: downloadError } = await bucket.download(`${user.id}/2026-10.pdf`)

// 전체 파일을 메모리에 로드하지 않고 스트리밍 다운로드
const { data: stream } = await bucket.download(`${user.id}/2026-10.pdf`).asStream()

// 파일 제거(기본적으로 30일 보존으로 휴지통으로 이동됨)
await bucket.remove([`${user.id}/2026-10.pdf`])

// 영구 삭제(휴지통을 우회하고 디스크 할당량을 즉시 해제)
await bucket.remove([`${user.id}/2026-10.pdf`], { permanent: true })

주요 런타임 동작:

  • upsert: true이 제공되지 않는 한 기존 경로를 업로드하면 409 CONFLICT이 반환됩니다.
  • 익명 업로드는 비공개 및 공개 버킷 모두에서 403 FORBIDDEN을(를) 사용하여 거부됩니다(쓰기에는 인증된 JWT 또는 서비스 키가 필요함).
  • 경로 순회 보호: .. 또는 잘못된 문자가 포함된 경로는 처리되지 않은 예외를 발생시키지 않고 400 INVALID_PATH을 반환합니다.
  • 사용자 격리: 한 사용자는 다른 사용자(owner_id = auth.uid())가 소유한 파일을 덮어쓰거나 삭제할 수 없습니다. ${user.id}/...와 같은 사용자 범위 폴더를 사용하여 구조 경로.

파일 공유(공개 및 서명된 URL)#

share.tstypescript
// 1. 퍼블릭 버킷: 직접 영구 URL(API 키 없이 제공)
const { data: { publicUrl } } = aura.storage.from('avatars').getPublicUrl('ada.png')
// → https://<slug>.localhost:8080/v1/storage/avatars/ada.png

// 사용자 정의 파일 이름을 사용하여 첨부 파일로 강제 다운로드
const downloadUrl = aura.storage.from('avatars').getPublicUrl('ada.png', {
  download: 'avatar-ada.png',
})

// 2. 프라이빗 버킷: 구성 가능한 TTL이 포함된 HMAC 서명된 URL
const { data, error } = await aura.storage.from('invoices').createSignedUrl(
  `${user.id}/2026-10.pdf`,
  300, // 300초(5분) 동안 유효
  { download: true }
)
// data.signedUrl 및 data.url에는 HMAC 서명된 URL이 포함되어 있습니다.

// 3. 비밀키 노출 없이 브라우저 직접 업로드
// 서버측(service_role):
const { data: uploadInfo } = await admin.storage.from('invoices').createSignedUploadUrl(
  `${user.id}/document.pdf`,
  600
)

// 브라우저 클라이언트(API 키가 필요하지 않음):
await aura.storage.uploadToSignedUrl(uploadInfo.signedUrl, file, {
  contentType: 'application/pdf',
})

서명된 URL은 HTTP 메서드(GET 또는 PUT), 버킷, 키 및 만료 타임스탬프를 봉인합니다. 만료되거나 객체가 삭제되면 요청은 403 FORBIDDEN를 받습니다.

누가 무엇을 할 수 있나요(액세스 매트릭스)#

액션익명 키(anon)로그인한 사용자(authenticated)서비스 역할(service_role)
퍼블릭 버킷의 파일 읽기예예예
프라이빗 버킷의 파일 읽기아니요(403)소유자 전용(owner_id = auth.uid())예
새 파일 업로드아니요(403)예(소유자가 됨)예
교체(upsert) 또는 삭제아니요(403)소유자만예
퍼블릭 버킷의 파일 나열예예예
프라이빗 버킷의 파일 나열아니요(403)소유자 전용(RLS 필터)예
버킷 생성, 업데이트 또는 삭제아니요(403)아니요(403)예
민트 서명 업로드 URL아니요(403)아니요(403)예

소유자는 JWT 주제(auth.uid())로 식별됩니다. 퍼블릭 버킷과 프라이빗 버킷 모두에서 사용자는 다른 사용자의 객체를 덮어쓰거나 삭제할 수 없습니다.

이동, 복사, 메타데이터 및 휴지통#

server/organise.tstypescript
// 파일 복사(원본 콘텐츠 유형 및 사용자 정의 메타데이터 유지)
await admin.storage.copy('invoices', '2026/draft.pdf', '2026/archive.pdf')

// 파일 이동 또는 이름 바꾸기
await admin.storage.move('invoices', '2026/draft.pdf', '2026/final.pdf')

// 객체 메타데이터(크기, MIME 유형, ETag, 사용자 정의 메타데이터) 검사
const { data: meta } = await admin.storage.getMetadata('invoices', '2026/final.pdf')

// 현재 휴지통에 있는 항목 나열(30일 보관)
const { data: trashItems } = await admin.storage.from('invoices').listTrash()

// 휴지통에서 개체 복원
await admin.storage.from('invoices').restore('2026/final.pdf')

실시간 이미지 변환(크기 조정, 형식 변환, 회전)에 대해서는 Storage SDK 참조을 참조하세요.