For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /tr/docs/web/setup-storage.md (or send Accept: text/markdown).

Dosya depolamayı kurun

Bellek ya da herhangi bir S3 uyumlu kovada çalışma alanı kapsamlı yüklemeler.

Bu kılavuz hakkında sor

Başlangıç seviyesinde izlenecek yol

Önkoşullar: Aşağıdaki iki başlangıç kılavuzunu okuyun, Web yerel kurulumunu tamamlayın ve bu monorepo'yu düzenleyicinizde kökünden açın. Web ayarları apps/web/.env.local'ye aittir; Next.js, .env kökünü okumaz. Varsayılan sahte modda /dashboard, veritabanı olmayan bir demodur; /auth'nin taşınan bir veritabanına ihtiyacı var.

Kısa terimler: Çalışma alanı, bir ekibin ayrı kullanıcıları, verileri ve ayarlarıdır. Sunucu güvenilir arka uçtur; sağlayıcı anahtarlarını tarayıcı ve telefon kodundan uzak tutun. Geçiş, tabloları oluşturan veya güncelleyen sürümlü bir veritabanı değişikliğidir. Yapay zeka modeli yanıt veren motordur; model kataloğu, sunucunun mevcut model kimlikleri ve fiyatlarının listesidir. Sağlayıcı yapay zeka, e-posta veya faturalandırma hizmeti gibi bir dış hizmettir. Yetki, bir çalışma alanının bir özelliği kullanmasına olanak tanıyan bir yetkidir. Web kancası, bir hizmetin başka bir hizmetin URL'sine gönderdiği bir mesajdır.

1. Kimlik bilgisi olmayan bir deneme için STORAGE_PROVIDER=memory'yi saklayın. Bu ödemede görünür bir yükleme kontrolü yoksa kodlama temsilcinizden küçük bir örnek görüntü bağlamadan önce 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 ve eşleşen ayarlar sayfasını incelemesini isteyin.

2. Kalıcılığı kontrol etmek için apps/web/.env.local'de STORAGE_PROVIDER=s3, STORAGE_REGION ve STORAGE_BUCKET'yi ayarlayın, yalnızca sunucu test kimlik bilgilerini yerel olarak ekleyin ve yeniden başlatın.

3. Görüntü depolama alanından yeniden yüklenmelidir. İşlem yeniden başlatıldığında bellek dosyaları kaybolur; S3 hataları için grubu, uç noktayı ve erişim politikasını kontrol edin.

Özel kod için, sağlanan prompts/README.md ile başlayın ve en yakın istemi kopyalayın: Bir uygulama ekranı için prompts/new-app-screen.md veya genel bir sayfa için prompts/new-landing-page.md. Sunucu, veritabanı veya sağlayıcı çalışması için kodlama temsilcinize bu kılavuzun görevini verin ve ondan AGENTS.md, .ai/PROJECT_CONTEXT.md ve eşleşen .ai/ aynalarını okumasını isteyin; burada adı geçen kaynak dosyaların tamamını inceleyin; düzenlemeden önce dosyaları ve kontrolleri listeleyin; çalışma alanı sahipliğini ve yalnızca sunucuya ait sırları koruyun; ve size farkı göstereceğim. İstediğiniz davranışı, giriş ve çıkış alanlarını, izin verilen rolleri, beklenen başarıyı ve hataları ve test hesabını, sağlayıcıyı veya cihazı ona bildirin. Örnek değerleri kullanın; asla gerçek bir sırrı yapıştırmayın.

Depolama arka ucunu seçin

STORAGE_PROVIDER=memory kimlik bilgisi gerektirmeyen varsayılan seçenektir. local, tek sunuculu kurulumlar için nesneleri STORAGE_LOCAL_DIR (varsayılan ./.data/storage, üretimde açıkça belirtilmesi zorunludur) altında diske yazar ve /api/storage/local/[...key] üzerinden HMAC imzalı süreli URL’ler (STORAGE_LOCAL_SIGNING_SECRET, yoksa AUTH_SECRET kullanılır) ile sunar. s3, AWS SDK istemcisini yalın @supastack/storage sözleşmesi üzerinde oluşturmak için apps/web/src/storage-runtime.ts dosyasını kullanır ve varsayılan olarak yol stili URL’lerle Supabase Storage ile MinIO’yu destekler.

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

Yükleme sınırlarını yeniden kullanın

Gönderilen rotalar, /api/storage/ kapsamındaki nesneleri, avatarları, profil logolarını ve kuruluş logolarını kapsar. Kimlik/çalışma alanı izinlerini çözerler ve depolamadan önce yükleme şeklini doğrularlar. Rastgele istemci nesne anahtarlarını kabul etmek yerine, seçilen rotanın boyut/tür politikasını inceleyin.

Genel URL'ler yetkilendirme değil sunumdur. Korunan içeriği uygulamanın doğrulanmış okuma sınırının arkasında tutun ve ürününüzün verileri için paket/CDN politikasını yapılandırın.

Gerçek depolama davranışını test edin

İzin verilen/reddedilen yüklemeleri, MIME ve boyut reddini, yabancı çalışma alanı yollarını, eksik nesneleri ve sağlayıcı hatasını test edin. Bellek modu işlemler arasında kalıcı değildir; Yayınlanmadan önce seçilen arka uçta depolamayı ve almayı doğrulayın.

Kurulum ve yapılandırma

1. STORAGE_PROVIDER=memory (varsayılan) yüklemeleri süreç içinde tutar — geliştirme ve testler için doğru.

2. Gerçek dosyalar için STORAGE_PROVIDER=s3 ile bir kova ve bir erişim anahtarı çifti ayarlayın. STORAGE_ENDPOINT herhangi bir S3 uyumlu hizmeti seçer — https://<ref>.supabase.co/storage/v1/s3 adresindeki Supabase Storage, MinIO ya da AWS'nin kendisi.

3. Bir uç nokta ayarlandığında STORAGE_FORCE_PATH_STYLE varsayılan olarak true olur — Supabase ve MinIO bunu gerektirir. Yalnızca sanal-barındırmalı özel bir uç nokta için false ayarlayın.

4. İsteğe bağlı olarak STORAGE_PUBLIC_BASE_URL'yi bir CDN'e yöneltin, böylece herkese açık nesne URL'leri oradan çözülür.

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

Uygulama iş akışı

Yüklemeler ve okumalar önce çalışma alanını çözen kimliği doğrulanmış rotalardan geçer — /api/storage/objects artı ayrılmış avatar ve logo rotaları. Depolanan her anahtar buildWorkspaceObjectKey ile {workspaceId}/{purpose}/{safeName} olarak ad alanına alınır.

Kimlik bilgileri yalnızca sunucuda kalır; tarayıcı kovayı ya da anahtarları asla görmez.

Yüklemeler çalışıyor mu? Gözlemlenebilirliği kurun ile devam edin.

Doğrulama ve sorun giderme

Bir yüklemenin gidiş-dönüş yaptığını, ikinci bir çalışma alanının nesneyi okuyamadığını ve büyük ya da izin verilmeyen içerik tiplerinin başarısız olduğunu doğrulayın. Supabase ya da MinIO'ya karşı imza ya da 403 hataları genellikle STORAGE_FORCE_PATH_STYLE'ın uç nokta için yanlış olduğu anlamına gelir.

Kuruluma devam etmek için Gözlemlenebilirliği kurun kılavuzunu okuyun.