> ## 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

# 파일 스토리지

객체 스토리지 계약을 통한 워크스페이스 스코프 업로드.

## 초보자 연습

전제 조건: 아래 두 개의 초보자 가이드를 읽고, 웹 로컬 설정을 완료하고, 편집기의 루트에서 이 모노레포를 엽니다. 웹 설정은 `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=
# Local MinIO Compose overrides: MINIO_ROOT_USER / MINIO_ROOT_PASSWORD
```


## 업로드 경계 재사용

배송된 경로에는 `/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)


## 설치 및 설정

STORAGE_PROVIDER가 어댑터를 선택합니다: 테스트와 로컬 개발에는 memory, S3 호환 버킷에는 s3(STORAGE_BUCKET, STORAGE_ENDPOINT, STORAGE_ACCESS_KEY_ID, STORAGE_SECRET_ACCESS_KEY, STORAGE_PUBLIC_BASE_URL). 자격 증명은 서버 전용입니다.

packages/storage는 ObjectStorage 계약(객체 로케이터에 대한 put/get/delete)과 assertWorkspaceObjectKey, buildWorkspaceObjectKey를 소유해 모든 저장 객체가 워크스페이스와 목적(avatar, file, logo)으로 네임스페이스화됩니다.

```
Uploads and reads go through authenticated routes:
  /api/storage/objects
  /api/storage/avatar
  /api/storage/logo
  /api/storage/organization-logo
```


## 구현 워크플로

업로드는 인증된 라우트 계층 뒤에 두세요: 워크스페이스를 해석하고, 콘텐츠 타입과 크기를 검증하고, 워크스페이스 스코프 키를 구축한 다음 어댑터로 저장합니다. 객체가 의도적으로 공개되지 않는 한 읽기도 같은 방식으로 제공합니다.

아바타와 조직 로고는 자체 검증을 가진 전용 라우트를 가지며, 임의의 프로덕트 파일은 선언된 목적과 함께 /objects를 통과합니다.


## 검증 및 문제 해결

익명 업로드가 거부되는지, 한 워크스페이스가 다른 워크스페이스의 객체 키를 읽을 수 없는지, 너무 크거나 허용되지 않는 콘텐츠 타입이 실패하는지, 삭제된 객체가 해석되지 않는지 확인합니다. 테스트에는 memory 어댑터를, 실제 버킷은 선택적 smoke 경로로 검증하세요.


## 다음

[AI 기능](https://supastack.dev/ko/docs/web/ai.md)