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/web/setup-storage.md (or send Accept: text/markdown).

設定檔案儲存

在記憶體或任意相容 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=
# Local MinIO Compose overrides: MINIO_ROOT_USER / MINIO_ROOT_PASSWORD

重用上傳邊界

已發貨路線涵蓋/api/storage/下的物品、頭像、頭像、頭像、組織標識。他們解析身份/工作空間許可權並在儲存之前驗證上傳形狀。檢查所選路由的大小/型別策略，而不是接受任意客戶端物件金鑰。

公共 URL 是表示，而不是授權。將受保護的內容保留在應用程式經過驗證的讀取邊界後面，併為您的產品資料配置儲存桶/CDN 策略。

測試真實的儲存行為

測試允許/拒絕上傳、MIME 和大小拒絕、外部工作空間路徑、丟失物件和提供程式故障。記憶體模式不會跨程式持續存在；在釋出之前驗證所選後端的儲存和檢索。

安裝與配置

1. 預設 STORAGE_PROVIDER=memory 會在程式內儲存上傳檔案，適合開發和測試。

2. 儲存真實檔案時，設定 STORAGE_PROVIDER=s3、儲存桶和訪問金鑰。STORAGE_ENDPOINT 可指向任意 S3 相容服務，例如 https://<ref>.supabase.co/storage/v1/s3、MinIO 或 AWS。

3. 設定端點後 STORAGE_FORCE_PATH_STYLE 預設為 true；Supabase 和 MinIO 需要該模式。只有虛擬主機式的自定義端點才應關閉它。

4. 可選：將 STORAGE_PUBLIC_BASE_URL 指向 CDN，使公開物件 URL 從 CDN 解析。

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 是否與端點匹配。

如果你想繼續完成設定，可以閱讀《設定可觀測性》。