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 /zh-tw/docs/modules/storage.md (or send Accept: text/markdown).
儲存模組
一個 ObjectStorage 契約、memory 與 S3 相容介面卡。
初學者演練
先決條件：閱讀下面的兩個初學者指南，完成 Web 本地設定，並在編輯器的根目錄中開啟此 monorepo。網頁設定屬於apps/web/.env.local； Next.js不讀取根.env。預設fake模式下的/dashboard是無資料庫演示； /auth 需要遷移資料庫。
簡而言之：工作區是一個團隊的單獨使用者、資料和設定。伺服器是可信後端；讓提供商金鑰遠離瀏覽器和電話程式碼。遷移是建立或更新表的版本化資料庫更改。人工智慧模型是回答的引擎；型號目錄是伺服器上可用型號 ID 和價格的列表。提供商是一種外部服務，例如人工智慧、電子郵件或計費服務。權利是允許工作區使用某項功能的授權。 Webhook 是一個服務傳送到另一個服務的 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 簽名限時連結（STORAGE_LOCAL_SIGNING_SECRET，未設定時回退到 AUTH_SECRET）提供流式讀取。s3 使用 apps/web/src/storage-runtime.ts 在精簡的 @supastack/storage 契約之上組裝 AWS SDK 客戶端，支援 Supabase Storage 與 MinIO，且預設啟用路徑風格 URL。
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/下的物品、頭像、頭像、頭像、組織標識。他們解析身份/工作空間許可權並在儲存之前驗證上傳形狀。檢查所選路由的大小/型別策略，而不是接受任意客戶端物件金鑰。
公共 URL 是表示，而不是授權。將受保護的內容保留在應用程式經過驗證的讀取邊界後面，併為您的產品資料配置儲存桶/CDN 策略。
測試真實的儲存行為
測試允許/拒絕上傳、MIME 和大小拒絕、外部工作空間路徑、丟失物件和提供程式故障。記憶體模式不會跨程式持續存在；在釋出之前驗證所選後端的儲存和檢索。
安裝與配置
packages/storage 定義 ObjectStorage 介面 —— 對物件定位符的 putObject、getObject 和 deleteObject —— 配有用於確定性測試的 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 讓單元測試保持確定性 —— 在其中斷言金鑰、內容型別和跨工作區拒絕。在釋出上傳之前,通過可選的 smoke 路徑針對真實桶驗證 S3 介面卡。