파일 스토리지 설정

초보자 연습

전제 조건: 아래 두 개의 초보자 가이드를 읽고, 웹 로컬 설정을 완료하고, 편집기의 루트에서 이 모노레포를 엽니다. 웹 설정은 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/ 미러를 읽도록 요청하세요. 여기에 이름이 지정된 정확한 소스 파일을 검사하십시오. 편집하기 전에 파일을 나열하고 확인합니다. 작업 공간 소유권과 서버 전용 비밀을 보존합니다. 차이점을 보여주세요. 원하는 동작, 입력 및 출력 필드, 허용된 역할, 예상되는 성공 및 오류, 테스트 계정, 공급자 또는 장치를 알려주십시오. 샘플 값을 사용하십시오. 절대 진짜 비밀을 붙여넣지 마세요.

• 시작하기 전에
• 단말기 기본사항
• 웹 로컬 설정
• 에이전트 프롬프트 및 프로젝트 메모리

스토리지 백엔드 선택

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 저장소 설정
• 노선 인벤토리 업로드

설치 및 설정

1. STORAGE_PROVIDER=memory(기본)는 업로드를 프로세스 안에 둡니다 — 개발과 테스트에 적합합니다.

2. 실제 파일에는 STORAGE_PROVIDER=s3와 버킷, 액세스 키 쌍을 설정하세요. STORAGE_ENDPOINT는 어떤 S3 호환 서비스든 선택합니다 — https://<ref>.supabase.co/storage/v1/s3의 Supabase Storage, MinIO, AWS 자체.

3. 엔드포인트가 설정되면 STORAGE_FORCE_PATH_STYLE은 기본 true입니다 — Supabase와 MinIO가 요구합니다. virtual-hosted 커스텀 엔드포인트에만 false로 설정하세요.

4. 선택적으로 STORAGE_PUBLIC_BASE_URL을 CDN으로 향하게 해 공개 객체 URL이 거기서 해석되게 하세요.

STORAGE_PROVIDER=s3
STORAGE_ENDPOINT=https://<ref>.supabase.co/storage/v1/s3
STORAGE_REGION=us-east-1            # Supabase: project region
STORAGE_BUCKET=<bucket>
STORAGE_ACCESS_KEY_ID=…
STORAGE_SECRET_ACCESS_KEY=…
STORAGE_PUBLIC_BASE_URL=https://cdn.example.com   # optional

# No bucket yet? Local S3-compatible storage ships in compose:
docker compose --profile storage up -d minio    # console on :9001

구현 워크플로

업로드와 읽기는 먼저 워크스페이스를 해석하는 인증된 라우트 — /api/storage/objects와 전용 아바타·로고 라우트 — 를 통과합니다. 모든 저장 키는 buildWorkspaceObjectKey로 {workspaceId}/{purpose}/{safeName}으로 네임스페이스됩니다.

자격 증명은 서버 전용입니다. 브라우저는 버킷이나 키를 보지 않습니다.

업로드가 작동하나요? 옵저버빌리티 설정으로 계속하세요.

검증 및 문제 해결

업로드가 왕복되는지, 두 번째 워크스페이스가 객체를 읽을 수 없는지, 너무 크거나 허용되지 않는 콘텐츠 타입이 실패하는지 확인하세요. Supabase나 MinIO에 대한 서명 또는 403 오류는 대개 STORAGE_FORCE_PATH_STYLE이 엔드포인트에 맞지 않다는 뜻입니다.