ObjectOS 把文件放在哪里 —— 本地磁盘、S3、R2、MinIO、Spaces。

存储

ObjectOS 的文件（附件、上传内容、生成的文档）会经过存储服务——一个可插拔的抽象层，包含两类适配器：本地文件系统（默认）和 S3 兼容存储（生产）。

该服务由 @objectstack/service-storage 提供，在 standalone 和 project 启动时默认启用。

用户如何与之交互

入口	行为
Console 文件/图片字段	浏览器通过预签名 URL 直接上传到存储
REST `/api/v1/storage/*`	编程式上传/下载端点
对象 `file` / `image` 字段	渲染为上传控件；元数据持久化在 `sys_file`

文件以 sys_file 系统对象进行追踪，而非以原始路径出现在你的记录中。这让你的数据模型与存储后端解耦。

本地文件系统（默认）

适用于：开发、单节点部署、演示。

// objectstack.config.ts (or wherever you assemble plugins)
import { StorageServicePlugin } from '@objectstack/service-storage';

new StorageServicePlugin({
  adapter: 'local',
  local: {
    rootDir: './uploads',
    baseUrl: 'http://localhost:3000',  // for presigned URLs
    signingSecret: process.env.OS_STORAGE_SIGNING_SECRET, // optional; auto-generated if omitted
  },
  presignedTtl: 3600,   // seconds — TTL for presigned URLs
  sessionTtl: 86400,    // seconds — TTL for chunked upload sessions
});

在 standalone 模式（无项目执行 os start）下，运行时会自动在 .objectstack/data/uploads/ 下配置本地存储。可通过 OS_STORAGE_ROOT 环境变量覆盖根目录。

是否适合生产取决于部署形态：

✅ 桌面端应用、单节点内部工具、边缘 / 本地一体机 —— 本地存储完全可以，只要把 uploads/ 目录纳入文件系统备份（桌面端应用也可以把它放在用户控制的同步目录里）。
❌ 多节点、多可用区，或者任何需要跨区域持久化的场景 —— 请使用 S3 兼容存储。

S3 兼容存储（生产）

适用于：生产、多节点、持久化 + 生命周期管理。

pnpm add @aws-sdk/client-s3 @aws-sdk/s3-request-presigner

import { StorageServicePlugin } from '@objectstack/service-storage';

new StorageServicePlugin({
  adapter: 's3',
  s3: {
    bucket: 'my-bucket',
    region: 'us-east-1',
    // omit credentials to use the AWS SDK's default chain
    // (env, ~/.aws, IAM role)
  },
});

AWS SDK 按其正常的凭据链读取凭据：

来源	环境变量
标准 env	`AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY`、`AWS_REGION`
Session token	`AWS_SESSION_TOKEN`
共享配置	`~/.aws/credentials`、`AWS_PROFILE`
IAM 角色	在 EC2 / ECS / EKS / Lambda 上自动生效 —— 无需配置

Cloudflare R2

new StorageServicePlugin({
  adapter: 's3',
  s3: {
    bucket: 'my-bucket',
    region: 'auto',
    endpoint: 'https://<account-id>.r2.cloudflarestorage.com',
    forcePathStyle: false,
  },
});

凭据：R2 access key ID + secret，通过标准 AWS_* 环境变量或你的 secret manager 传入。

MinIO（自托管）

new StorageServicePlugin({
  adapter: 's3',
  s3: {
    bucket: 'my-bucket',
    region: 'us-east-1',
    endpoint: 'http://minio.internal:9000',
    forcePathStyle: true,
  },
});

DigitalOcean Spaces

new StorageServicePlugin({
  adapter: 's3',
  s3: {
    bucket: 'my-bucket',
    region: 'nyc3',
    endpoint: 'https://nyc3.digitaloceanspaces.com',
    forcePathStyle: false,
  },
});

S3 bucket 策略

存储使用预签名 PUT/GET URL。推荐的 bucket 策略：

阻止所有公共访问。
CORS：允许来自你的 ObjectOS 主机名的 PUT/GET。
生命周期：1–7 天后让未完成的 multipart 上传过期；24 小时后让带 temp=true 标签的对象过期。
Versioning + Object Lock：可选，在合规部署中推荐启用。

REST 接口

@objectstack/client 会调用以下接口 —— 通常你不直接调用：

方法	路径	用途
POST	`/api/v1/storage/upload/presigned`	获取预签名上传 URL
POST	`/api/v1/storage/upload/complete`	提交完成的上传
POST	`/api/v1/storage/upload/chunked`	开始分块上传
PUT	`/api/v1/storage/upload/chunked/:uploadId/chunk/:i`	上传一个分块
POST	`/api/v1/storage/upload/chunked/:uploadId/complete`	完成分块上传
GET	`/api/v1/storage/upload/chunked/:uploadId/progress`	轮询进度
GET	`/api/v1/storage/files/:fileId/url`	获取预签名下载 URL

每个文件的鉴权由 security 插件的权限求值器针对 sys_file 对象处理 —— 你无需独立的存储层 ACL。

实时配置

当 settings 服务启用时（默认即启用），管理员可以在 Console → Configuration → Storage 中切换存储适配器而无需重启：

选择适配器、bucket、region、endpoint；
粘贴凭据（在 sys_setting 中静态加密存储）；
保存前点击 Test connection。

变更在下一次请求时生效——无需重启。

容量规划

资源	默认值	可调项
预签名 URL TTL	1 小时	插件选项 `presignedTtl`
分块上传会话 TTL	24 小时	插件选项 `sessionTtl`
单次上传上限	取决于后端（S3 = 5 GB）	—
分块上传上限	取决于后端（S3 = 5 TB）	—

下一步

系统设置 —— 实时配置以及存储切换所使用的设置服务
Production Readiness —— 包含对象存储持久化与备份的清单
GitHub 上的 @objectstack/service-storage —— 源码与完整选项参考

存储

On this page