> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 檔案儲存

通過物件儲存契約進行的工作區級上傳。

## 初學者演練

先決條件：閱讀下面的兩個初學者指南，完成 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/` 映象；檢查此處指定的確切原始檔；列出檔案並在編輯前進行檢查；保留工作區所有權和僅限伺服器的機密；並向您展示差異。告訴它您想要的行為、輸入和輸出欄位、允許的角色、預期的成功和錯誤以及測試帳戶、提供程式或裝置。使用樣本值；永遠不要貼上真正的秘密。

[開始之前](https://supastack.dev/zh-tw/docs/web/before-you-start.md)

[終端基礎知識](https://supastack.dev/zh-tw/docs/web/terminal-basics.md)

[網路本地設定](https://supastack.dev/zh-tw/docs/web/ship-in-5-minutes.md)

[座席提示和專案記憶體](https://supastack.dev/zh-tw/docs/web/agents.md)


## 選擇儲存後端

`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 和大小拒絕、外部工作空間路徑、丟失物件和提供程式故障。記憶體模式不會跨程式持續存在；在釋出之前驗證所選後端的儲存和檢索。

[Supabase 儲存設定](https://supastack.dev/zh-tw/docs/web/project-structure.md)

[上傳航線清單](https://supastack.dev/zh-tw/docs/web/project-structure.md)


## 安裝與配置

STORAGE_PROVIDER 選擇介面卡:memory 用於測試和本地開發,s3 用於任何 S3 相容桶(STORAGE_BUCKET、STORAGE_ENDPOINT、STORAGE_ACCESS_KEY_ID、STORAGE_SECRET_ACCESS_KEY、STORAGE_PUBLIC_BASE_URL)。憑據僅限伺服器。

packages/storage 擁有 ObjectStorage 契約 —— 對物件定位符的 putObject、getObject 與 deleteObject —— 加上 assertWorkspaceObjectKey 和 buildWorkspaceObjectKey,因此每個儲存的物件都按工作區和用途(avatar、file、logo)名稱空間化。

```
Uploads and reads go through authenticated routes:
  /api/storage/objects
  /api/storage/avatar
  /api/storage/logo
  /api/storage/organization-logo
```


## 實現流程

將上傳保持在認證路由層之後:解析工作區、驗證內容型別和大小、構建工作區級金鑰,然後通過介面卡儲存。除非物件被有意公開,否則以相同方式提供讀取。

頭像和組織徽標有帶各自驗證的專用路由;任意產品檔案通過 /objects 並攜帶宣告的用途。


## 驗證與排障

驗證匿名上傳被拒絕、一個工作區無法讀取另一個工作區的物件金鑰、過大或不允許的內容型別失敗,以及已刪除的物件不再可解析。測試中使用 memory 介面卡;通過可選的 smoke 路徑驗證真實桶。


## 下一篇

[AI 功能](https://supastack.dev/zh-tw/docs/web/ai.md)