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

# 設定檔案儲存

在記憶體或任意相容 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=
# 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)


## 安裝與配置

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


如果你想繼續完成設定，可以閱讀《[設定可觀測性](https://supastack.dev/zh-tw/docs/web/setup-observability.md)》。


## 下一篇

[儲存模組](https://supastack.dev/zh-tw/docs/modules/storage.md)