Asset Service

多数后台框架交付的是“上传到本地目录、返回一个 URL”。它在开发环境能跑，进生产就出问题：容器重启或扩容后文件消失、私有文件没有访问校验、URL 长期暴露、每个项目重写一遍 OSS/S3 适配、大文件上传占满应用服务器带宽。

StackRivet 把文件作为一等的 Asset Service：在一处统一管理资产元数据、存储适配、上传下载安全和业务引用。

核心规则：存 `assetId`，不存 URL

业务表存 assetId，绝不存裸文件 URL。URL 在需要时通过 Asset API 获取——因此它可以短期有效、经过权限校验、且与你用哪种存储后端无关。

业务行 → assetId → Asset API →（权限校验）→ 短期 signed URL

这正是私有文件保持私有、且能在不改业务代码的情况下切换存储后端的关键。

一个存储适配器，三种后端

单一 StorageAdapter 接口覆盖 Local Dev、S3 兼容（如 MinIO、AWS S3）和阿里云 OSS。该适配器：

绝不把云厂商 SDK 对象泄露到业务层。
把错误转换为统一异常类型。
从配置注入 endpoint / bucket / region / 凭据（环境变量，绝不提交进代码仓库）。
默认签发短期 signed URL。

从本地存储切到 S3 或 OSS 是改配置（STACKRIVET_STORAGE_TYPE），不是改代码。见配置对象存储指南。

系统生成的 object key

存储 object key 由系统生成——用户无法控制，原始文件名只保存在元数据里：

{tenantId}/{yyyy}/{MM}/{assetId}.{extension}
# 例如 default/2026/05/01JABC.pdf

私有文件永不返回永久 URL。

生命周期

资产走一个小状态机：

stateDiagram-v2
  [*] --> pending
  pending --> active: 上传完成
  pending --> deleted: 取消 / 过期
  active --> deleted: 软删除
  deleted --> [*]

Community 实现 pending、active、deleted。Enterprise 环境可按合规与安全要求扩展生命周期状态。

上传路径由能力接口决定

客户端先读取 GET /api/v1/assets/capabilities，再选择上传路径；不能只根据后端名称或文件大小推断是否支持直传。

声明的能力	路径
中转（所有后端）	后端先执行配额与内容策略，再通过存储适配器写入准确字节。本地与阿里云 OSS 始终走这条路径。
`supportsPresignedUpload`（目前仅 S3）	短期 PUT 能力绑定声明的 `Content-Length`；完成接口验证对象后，资产才进入 active。
`supportsMultipartUpload`（目前仅 S3）	initiate / complete / abort 会话使用确定的分片计划与绑定字节数的分片 URL。

任一直传能力未声明时，客户端都会回退到带配额约束的服务端中转。这条 fail-closed 规则避免仅因为 Local 或 OSS SDK 暴露了预签名原语，就把它误当成安全的客户端直传路径。

上传响应会返回稳定的 assetId，客户端围绕资产记录重试，不需要保存裸 URL 或云厂商 object key。

私有访问在服务端校验

私有文件的下载 URL 只有在权限校验之后才签发，经由 AssetAccessPolicy SPI：

public interface AssetAccessPolicy {
    boolean canRead(
        AssetEntity asset,
        String callerUserId,
        Collection<? extends GrantedAuthority> authorities
    );
}

默认公开资产可读、资产 owner 可读，具备管理员级权限的用户可在同租户内读取。未知或未授权的私有下载按 not found 处理，避免调用方探测其他租户私有资产是否存在；超限或禁止类型的上传返回 413 或 415。

版本边界

Community 包含 Local / S3 兼容 / 阿里云 OSS、私有签名下载、按能力路由的上传、安全校验和业务引用。回收站、CDN、图片处理、恶意文件扫描、保留策略和额外适配器属于 Roadmap 或明确合同范围——见价格页。