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/docs/web/storage.md (or send Accept: text/markdown).
文件存储
通过对象存储契约进行的工作区级上传。
初学者演练
先决条件：阅读下面的两个初学者指南，完成 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 和大小拒绝、外部工作空间路径、丢失对象和提供程序故障。内存模式不会跨进程持续存在；在发布之前验证所选后端的存储和检索。
安装与配置
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 路径验证真实桶。