> ## 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

# 儲存模組

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

[開始之前](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=
```


## 重用上傳邊界

已發貨路線涵蓋`/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)


## 安裝與配置

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 介面卡。


## 下一篇

[API 模組](https://supastack.dev/zh-tw/docs/modules/api.md)