> ## 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/docs/web/before-you-start.md)

[终端基础知识](https://supastack.dev/zh/docs/web/terminal-basics.md)

[网络本地设置](https://supastack.dev/zh/docs/web/ship-in-5-minutes.md)

[座席提示和项目内存](https://supastack.dev/zh/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/docs/web/project-structure.md)

[上传航线清单](https://supastack.dev/zh/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/docs/web/setup-observability.md)》。


## 下一篇

[存储模块](https://supastack.dev/zh/docs/modules/storage.md)