728x90

Supabase Storage 매뉴얼

이 매뉴얼은 Supabase Storage를 설정하고 사용하는 단계별 가이드를 제공합니다. Supabase Storage는 Postgres와 메타데이터 관리를 통합한 S3 호환 객체 스토리지 서비스로, 이미지, 비디오, 문서 등 다양한 파일 유형을 저장하기에 적합합니다. 확장성, 글로벌 CDN 지원, 그리고 Postgres 행 수준 보안(RLS)을 사용한 세밀한 접근 제어를 제공합니다. 이 가이드는 설정, 기본 작업, 로컬 개발을 위한 테스트를 다룹니다.

자세한 내용은 공식 저장소인 supabase/storage를 참조하세요.

사전 준비

시작하기 전에 다음이 필요합니다:

Docker: Supabase 스택을 로컬에서 실행하기 위해 필요합니다.
Node.js 및 npm: 스토리지 서버와 테스트를 실행하기 위해 필요합니다.
Postgres: Supabase Storage는 메타데이터 저장을 위해 Postgres를 사용합니다.
cURL: 버킷 작업을 테스트하기 위해 API 요청을 보낼 때 필요합니다.
Supabase 프로젝트 또는 로컬 개발 환경.

Supabase Storage 로컬 설정

Supabase Storage는 Docker를 사용해 로컬에서 실행할 수 있어, 외부 서비스 없이 테스트 및 개발이 가능합니다. 다음 단계를 따라 환경을 설정하세요:

저장소 복제
Supabase Storage 저장소를 로컬 머신에 복제합니다:
```
git clone https://github.com/supabase/storage.git
cd storage
```
의존성 설치
필요한 Node.js 의존성을 설치합니다:
```
npm install
```
Postgres 데이터베이스 및 PostgREST 시작
Docker를 사용해 Postgres 데이터베이스와 PostgREST를 로컬에서 설정합니다:
```
npm run infra:restart
```
이 명령은 메타데이터 관리를 위한 Postgres 및 PostgREST 컨테이너를 초기화합니다.
스토리지 서버 시작
스토리지 서버를 실행하여 http://localhost:5000에서 동작하도록 합니다:
```
npm run dev
```
이제 서버가 버킷 및 파일 작업을 처리할 준비가 되었습니다.

기본 버킷 작업

Supabase Storage는 파일과 폴더를 버킷이라는 컨테이너에 정리합니다. 아래는 cURL을 사용해 버킷을 생성하고 목록을 조회하는 방법입니다.

버킷 생성

avatars라는 이름의 버킷을 생성하려면 다음 cURL 명령을 사용하세요:

curl --location --request POST 'http://localhost:5000/bucket' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoic2VydmljZV9yb2xlIiwiaWF0IjoxNjEzNTMxOTg1LCJleHAiOjE5MjkxMDc5ODV9.th84OKK0Iz8QchDyXZRrojmKSEZ-OuitQm_5DvLiSIc' \
--header 'Content-Type: application/json' \
--data-raw '{ "name": "avatars" }'

이 명령은 POST 요청을 보내 avatars라는 이름의 버킷을 생성합니다. Authorization 헤더는 service_role 권한이 있는 JWT 토큰을 사용합니다.

버킷 목록 조회

모든 버킷 목록을 조회하려면 다음 cURL 명령을 사용하세요:

curl --location --request GET 'http://localhost:5000/bucket' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoic2VydmljZV9yb2xlIiwiaWF0IjoxNjEzNTMxOTg1LCJleHAiOjE5MjkxMDc5ODV9.th84OKK0Iz8QchDyXZRrojmKSEZ-OuitQm_5DvLiSIc'

이 GET 요청은 프로젝트 내 모든 버킷 목록을 반환합니다.

설정 테스트

Supabase Storage 설정이 올바르게 작동하는지 확인하려면 저장소에 포함된 테스트 스위트를 실행하세요:

npm test

이 명령은 버킷 및 파일 작업이 예상대로 작동하는지 확인하는 테스트를 실행합니다.

로컬 개발을 위한 구성

로컬에서 Supabase Storage를 실행할 때 환경 변수를 구성해야 할 수 있습니다. 저장소에는 템플릿으로 사용할 수 있는 샘플 구성 파일(.env.sample)이 포함되어 있습니다. 주요 설정은 다음과 같습니다:

서버 구성:
```
SERVER_HOST=0.0.0.0
SERVER_PORT=5000
```

데이터베이스 구성:

DATABASE_URL=postgresql://postgres:postgres@127.0.0.1/postgres

인증 구성:

AUTH_JWT_SECRET=f023d3db-39dc-4ac9-87b2-b2be72e9162b
AUTH_JWT_ALGORITHM=HS256

.env.sample 파일을 .env로 복사하고 필요에 따라 값을 수정하세요. 자세한 내용은 샘플 구성 파일을 참조하세요.

클라이언트 라이브러리로 Supabase Storage 사용

Supabase는 Storage와 프로그래밍 방식으로 상호작용할 수 있는 클라이언트 라이브러리를 제공합니다. 아래는 JavaScript 클라이언트 라이브러리(@supabase/storage-js)를 사용한 예제입니다:

JavaScript 클라이언트 설치

npm을 통해 라이브러리를 설치합니다:

npm install @supabase/storage-js

예제: 버킷 생성

import { StorageClient } from '@supabase/storage-js'

const STORAGE_URL = 'https://<project_ref>.supabase.co/storage/v1'
const SERVICE_KEY = '<service_role>'
const storageClient = new StorageClient(STORAGE_URL, {
  apikey: SERVICE_KEY,
  Authorization: `Bearer ${SERVICE_KEY}`,
})

async function createBucket() {
  const { data, error } = await storageClient.createBucket('test_bucket', { public: false })
  if (error) {
    console.error('버킷 생성 오류:', error)
  } else {
    console.log('버킷 생성 완료:', data)
  }
}

createBucket()

이 코드는 test_bucket이라는 비공개 버킷을 생성합니다. <project_ref>와 <service_role>은 각각 Supabase 프로젝트 참조와 서비스 역할 키로 대체하세요.

Supabase Storage의 주요 기능

S3 호환성: S3 호환 도구 및 워크플로우와 원활하게 통합됩니다.
글로벌 CDN: 전 세계 285개 이상의 도시에서 파일을 제공하여 낮은 지연 시간을 보장합니다.
이미지 최적화: 실시간으로 이미지 크기 조정 및 압축을 지원합니다.
접근 제어: Postgres RLS를 사용해 세밀한 접근 정책을 정의할 수 있습니다.
재개 가능 업로드: TUS 프로토콜을 지원하여 안정적인 파일 업로드를 제공합니다.
확장성: 인프라 관리 없이 많은 파일과 높은 트래픽을 처리할 수 있습니다.

셀프 호스팅 관련 참고 사항

Supabase Storage를 셀프 호스팅할 때 파일은 기본적으로 S3 호환 스토리지 또는 로컬 파일 시스템에 저장됩니다. 로컬 개발에서는 파일 기반 백엔드가 사용되며, 파일은 호스트의 파일 시스템에 저장됩니다. .env 파일에서 스토리지 백엔드를 file로 설정하여 구성하세요(예: S3 대신). 자세한 내용은 셀프 호스팅 구성 가이드를 참조하세요.

문제 해결

CORS 오류: 로컬에서 TUS 프로토콜 사용 시 CORS 문제가 발생하면 올바른 엔드포인트를 사용 중인지 확인하세요. supabase status를 실행하여 정확한 스토리지 엔드포인트(예: http://127.0.0.1:54321/storage/v1/upload/resumable)를 확인하세요.
RLS 설정: 로컬 개발에서는 Supabase Studio UI가 지원되지 않으므로 bucket 및 object 테이블에 대해 SQL을 사용해 행 수준 보안(RLS)을 수동으로 설정해야 합니다. Storage RLS 가이드를 참조하세요.
테스트 오류: 테스트를 실행하기 전에 서버가 실행 중인지(npm run dev)와 JWT 토큰이 유효한지 확인하세요.

dma-ai

AI Insights & Innovations