> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 스토리지 모듈

하나의 ObjectStorage 계약, memory와 S3 호환 어댑터.

## 초보자 연습

전제 조건: 아래 두 개의 초보자 가이드를 읽고, 웹 로컬 설정을 완료하고, 편집기의 루트에서 이 모노레포를 엽니다. 웹 설정은 `apps/web/.env.local`에 속합니다. Next.js는 ​​루트 `.env`를 읽지 않습니다. 기본 가짜 모드의 `/dashboard`는 데이터베이스가 없는 데모입니다. `/auth`에는 마이그레이션된 데이터베이스가 필요합니다.

빠른 용어: 작업 영역은 한 팀의 별도 사용자, 데이터 및 설정입니다. 서버는 신뢰할 수 있는 백엔드입니다. 제공업체 키를 브라우저 및 전화 코드에 보관하세요. 마이그레이션은 테이블을 생성하거나 업데이트하는 버전이 지정된 데이터베이스 변경입니다. AI 모델은 응답하는 엔진입니다. 모델 카탈로그는 서버의 사용 가능한 모델 ID 및 가격 목록입니다. 공급자는 AI, 이메일, 청구 서비스와 같은 외부 서비스입니다. 자격은 작업 영역에서 기능을 사용할 수 있도록 하는 부여입니다. 웹훅은 한 서비스가 다른 서비스의 URL에 보내는 메시지입니다.

1. 자격 증명 없음 체험판의 경우 `STORAGE_PROVIDER=memory`를 유지하세요. 이 체크아웃에 눈에 띄는 업로드 컨트롤이 없는 경우 작은 샘플 이미지를 연결하기 전에 코딩 에이전트에게 `apps/web/app/api/storage/avatar/route.ts`, `apps/web/app/api/storage/logo/route.ts`, `apps/web/app/api/storage/organization-logo/route.ts` 및 일치하는 설정 페이지를 검사하도록 요청하세요.

2. 지속성을 확인하려면 `apps/web/.env.local`에서 `STORAGE_PROVIDER=s3`, `STORAGE_REGION` 및 `STORAGE_BUCKET`를 설정하고 서버 전용 테스트 자격 증명을 로컬로 추가한 후 다시 시작합니다.

3. 이미지가 저장소에서 다시 로드되어야 합니다. 프로세스가 다시 시작되면 메모리 파일이 사라집니다. S3 오류의 경우 버킷, 엔드포인트, 액세스 정책을 확인하세요.

사용자 정의 코드의 경우 제공된 `prompts/README.md`로 시작하고 가장 가까운 프롬프트(앱 화면의 경우 `prompts/new-app-screen.md`, 공개 페이지의 경우 `prompts/new-landing-page.md`)를 복사합니다. 서버, 데이터베이스 또는 공급자 작업의 경우 코딩 에이전트에게 이 가이드의 작업을 제공하고 `AGENTS.md`, `.ai/PROJECT_CONTEXT.md` 및 일치하는 `.ai/` 미러를 읽도록 요청하세요. 여기에 이름이 지정된 정확한 소스 파일을 검사하십시오. 편집하기 전에 파일을 나열하고 확인합니다. 작업 공간 소유권과 서버 전용 비밀을 보존합니다. 차이점을 보여주세요. 원하는 동작, 입력 및 출력 필드, 허용된 역할, 예상되는 성공 및 오류, 테스트 계정, 공급자 또는 장치를 알려주십시오. 샘플 값을 사용하십시오. 절대 진짜 비밀을 붙여넣지 마세요.

[시작하기 전에](https://supastack.dev/ko/docs/web/before-you-start.md)

[단말기 기본사항](https://supastack.dev/ko/docs/web/terminal-basics.md)

[웹 로컬 설정](https://supastack.dev/ko/docs/web/ship-in-5-minutes.md)

[에이전트 프롬프트 및 프로젝트 메모리](https://supastack.dev/ko/docs/web/agents.md)


## 스토리지 백엔드 선택

`STORAGE_PROVIDER=memory`는 자격 증명이 필요 없는 기본값입니다. `local`은 단일 서버 배포를 위해 `STORAGE_LOCAL_DIR`(기본값 `./.data/storage`, 프로덕션에서는 명시적 설정 필수) 아래 디스크에 객체를 기록하고 `/api/storage/local/[...key]`의 HMAC 서명된 만료 URL(`STORAGE_LOCAL_SIGNING_SECRET`, 미설정 시 `AUTH_SECRET` 사용)을 통해 스트리밍합니다. `s3`는 `apps/web/src/storage-runtime.ts`를 사용해 간결한 `@supastack/storage` 계약 위에 AWS SDK 클라이언트를 구성하며, 기본적으로 경로 스타일 URL이 활성화된 Supabase Storage 및 MinIO를 지원합니다.

```
STORAGE_PROVIDER=s3
STORAGE_REGION=us-east-1
STORAGE_BUCKET=your-product-bucket
# Set STORAGE_ACCESS_KEY_ID and STORAGE_SECRET_ACCESS_KEY on the server.
# Optional: STORAGE_ENDPOINT, STORAGE_FORCE_PATH_STYLE, STORAGE_PUBLIC_BASE_URL
# Self-hosted single-server disk storage:
# STORAGE_PROVIDER=local
# STORAGE_LOCAL_DIR=./.data/storage
# STORAGE_LOCAL_SIGNING_SECRET=
```


## 업로드 경계 재사용

배송된 경로에는 `/api/storage/` 아래 개체, 아바타, 프로필 로고 및 조직 로고가 포함됩니다. ID/작업 공간 권한을 확인하고 저장하기 전에 업로드 형태를 확인합니다. 임의의 클라이언트 개체 키를 허용하는 대신 선택한 경로의 크기/유형 정책을 검사하세요.

공개 URL은 인증이 아닌 표시입니다. 애플리케이션의 확인된 읽기 경계 뒤에 보호된 콘텐츠를 유지하고 제품 데이터에 대한 버킷/CDN 정책을 구성합니다.


## 실제 스토리지 동작 테스트

허용/거부된 업로드, MIME 및 크기 거부, 외부 작업 공간 경로, 누락된 개체 및 공급자 오류를 테스트합니다. 메모리 모드는 프로세스 간에 지속되지 않습니다. 릴리스 전에 선택한 백엔드에 대한 저장 및 검색을 확인합니다.

[Supabase 저장소 설정](https://supastack.dev/ko/docs/web/project-structure.md)

[노선 인벤토리 업로드](https://supastack.dev/ko/docs/web/project-structure.md)


## 설치 및 설정

packages/storage는 ObjectStorage 인터페이스(객체 로케이터에 대한 put, get, delete)를 정의하며 결정적 테스트용 MemoryObjectStorage와 프로덕션 버킷용 S3CompatibleObjectStorage를 제공합니다.

객체 키는 buildWorkspaceObjectKey로 구축되고 assertWorkspaceObjectKey로 검사되어 모든 저장 파일이 워크스페이스와 목적(avatar, file, logo)으로 네임스페이스화됩니다. 키가 워크스페이스를 벗어나면 WorkspaceScopedStorageError가 발생합니다.

```
interface ObjectStorage {
  putObject(input: PutObjectInput): Promise<StoredObject>
  getObject(locator: ObjectLocator): Promise<StoredObject | undefined>
  deleteObject(locator: ObjectLocator): Promise<boolean>
  getPublicUrl(locator: ObjectLocator): string
}

key = {workspaceId}/{purpose}/{safeName}
```


## 구현 워크플로

애플리케이션 라우트는 워크스페이스를 해석하고, 업로드를 검증하고, 스코프 키를 구축하고 어댑터를 호출합니다 — 스토리지는 원시 클라이언트 경로를 보지 않습니다. 어댑터는 STORAGE_PROVIDER와 그 자격 증명으로 서버 환경에서 선택합니다.

읽기는 동일한 인가 경계를 통해 노출하고, 공개 URL은 프로덕트가 의도적으로 공개하는 객체에만 제공합니다.


## 검증 및 문제 해결

MemoryObjectStorage가 단위 테스트를 결정적으로 유지합니다 — 키, 콘텐츠 타입, 워크스페이스 간 거부를 거기서 어서트하세요. S3 어댑터는 업로드를 출시하기 전에 실제 버킷에 대한 선택적 smoke 경로로 검증합니다.


## 다음

[API 모듈](https://supastack.dev/ko/docs/modules/api.md)