JavaScript SDK를 사용하여 파일 저장 및 제공
버킷 관리, 단일 및 멀티파트 업로드, 스트리밍 다운로드, HMAC 서명된 URL, 휴지통 복원 등 일상적인 스토리지는 client.storage를 통해 흐릅니다.
이 페이지는 자동으로 번역되었습니다. 영어 버전은 권위가 있습니다.
버킷 관리#
버킷은 파일을 그룹화하고 공개 여부를 결정합니다. 버킷을 생성하고 삭제하려면 service_role 키가 필요합니다. 버킷을 나열하려면 로그인한 사용자 또는 service_role 키가 필요합니다(익명 키는 403 FORBIDDEN를 수신함).
typescript
// 공개 버킷 생성(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을 반환합니다.
업로드, 다운로드, 나열, 제거#
typescript
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)#
typescript
// 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())로 식별됩니다. 퍼블릭 버킷과 프라이빗 버킷 모두에서 사용자는 다른 사용자의 객체를 덮어쓰거나 삭제할 수 없습니다.
이동, 복사, 메타데이터 및 휴지통#
typescript
// 파일 복사(원본 콘텐츠 유형 및 사용자 정의 메타데이터 유지)
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 참조을 참조하세요.