Depolama modülü

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.

• Başlamadan önce
• Terminal temelleri
• Web yerel kurulumu
• Aracı istemleri ve proje belleği

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=

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.

• Supabase Depolama kurulumu
• Rota envanterini yükle

Kurulum ve yapılandırma

packages/storage, ObjectStorage arayüzünü tanımlar — nesne konumlarına karşı putObject, getObject ve deleteObject — deterministik testler için MemoryObjectStorage ve üretim kovaları için S3CompatibleObjectStorage ile.

Nesne anahtarları buildWorkspaceObjectKey ile oluşturulur ve assertWorkspaceObjectKey ile kontrol edilir, böylece depolanan her dosya çalışma alanı ve amaç (avatar, dosya, logo) ile ad alanına alınır. Anahtar çalışma alanından kaçtığında WorkspaceScopedStorageError fırlatılır.

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}

Uygulama iş akışı

Uygulama rotaları çalışma alanını çözer, yüklemeyi doğrular, kapsamlı anahtarı oluşturur ve bağdaştırıcıyı çağırır — depolama asla ham istemci yolu görmez. Bağdaştırıcıyı sunucu ortamında STORAGE_PROVIDER ve kimlik bilgileriyle seçin.

Okumaları aynı yetkilendirme sınırı üzerinden sunun; yalnızca ürünün bilinçli yayınladığı nesneler için herkese açık URL'ler servis edin.

Doğrulama ve sorun giderme

MemoryObjectStorage birim testlerini deterministik tutar — anahtarları, içerik tiplerini ve çalışma alanları arası retleri orada doğrulayın. Yüklemeleri göndermeden önce S3 bağdaştırıcısını gerçek kovaya karşı etkinleştirilen smoke yoluyla doğrulayın.