跳到主要内容

Nebula Storage 业务功能

1. 功能概览​

从当前代码和 README 可以确认，nebula-storage 对业务系统提供的能力主要包括六类：

  • 上传任务管理
  • 普通文件上传
  • 分片上传
  • 正式文件绑定与查询
  • 登录态文件下载
  • 分享链接下载与文件删除

这些能力围绕“附件生命周期”展开，而不是孤立的上传/下载接口。

2. 上传任务管理​

2.1 创建上传任务​

适用场景：

  • 大文件分片上传
  • 前端需要先申请一个任务 ID，再逐步上传分片
  • 需要在上传前声明文件名、文件大小、分片数等元信息

业务价值：

  • 给上传过程一个稳定主键
  • 让分片上传具备可追踪状态
  • 便于断点续传、排障与审计

2.2 查询上传任务详情​

适用场景：

  • 前端上传过程中轮询任务状态
  • 业务排查上传卡在哪一步
  • 页面刷新后恢复上传进度显示

当前任务详情里可以拿到：

  • 上传模式
  • 文件大小与 hash
  • 分片总数和已上传分片数
  • 当前状态
  • 最后分片时间
  • 是否已生成正式文件 ID

3. 普通文件上传​

3.1 直接上传并生成临时任务​

适用场景：

  • 常规附件上传
  • 页面里直接选一个文件上传
  • 文件不大，不需要分片

当前模块提供的普通上传入口是：

  1. 直接上传：由系统自动生成临时任务

3.2 业务含义​

普通上传完成后，文件已经进入系统临时区，但此时仍然不是正式业务文件。

也就是说：

  • 可以看见上传任务详情
  • 还不能把它当成长期业务附件
  • 仍需要业务在自己的保存流程成功后调用 bind 转正

这样做特别适合以下业务：

  • 表单先传附件，再点“保存”
  • 保存失败时不希望立即产生正式附件记录
  • 多个附件先上传，再统一绑定到单据

4. 分片上传​

4.1 分片写入​

适用场景：

  • 大文件上传
  • 网络不稳定
  • 需要断点续传
  • 前端按块并发/串行发送内容

当前模块支持：

  • 按 taskId + partNo 写入分片
  • 使用 partHash 进行分片一致性校验；如果调用方传入 partHash，服务端会在本次上传时校验它必须与实际内容一致
  • 对已存在分片进行幂等处理

4.2 完成上传任务​

所有分片都上传完成后，需要调用 complete：

  • 校验分片数量是否齐全
  • 合并分片
  • 生成临时完整文件
  • 计算完整文件 hash
  • 把任务标记为完成

4.3 业务价值​

分片上传解决的是“上传链路稳定性”，而不是“正式业务入库”。

它特别适合：

  • 视频、压缩包、批量导入文件
  • 浏览器长传输时间场景
  • 内网质量不稳定的办公环境

5. 绑定转正​

5.1 功能定位​

bind 是 storage 模块里最关键的业务动作。

它的作用是：

  • 将已完成的上传任务绑定到某个业务实体
  • 生成正式文件记录 storage_file
  • 补齐文件归属信息
  • 让文件进入长期可查询、可下载状态

5.2 当前绑定字段​

当前绑定时要求业务方提供：

  • sourceEntity
  • sourceId
  • sourceType（可选，默认 default）

这三个字段的业务含义可以理解为：

  • sourceEntity：文件属于哪个业务对象类型，例如 contract、notice、invoice
  • sourceId：具体是哪条业务记录
  • sourceType：进一步区分来源类型、分组或上下文

5.3 业务价值​

bind 把“文件内容”变成“业务附件”。

因此它适合放在：

  • 单据保存成功之后
  • 公告创建成功之后
  • 业务流程真正落库之后

而不建议在“文件刚上传完、业务还没成功”时就直接视为正式附件。

6. 正式文件查询​

6.1 文件详情​

适用场景：

  • 回显附件详情
  • 查询文件基本元数据
  • 下载前先取信息

当前可查询内容包括：

  • 文件名、扩展名、MIME 类型
  • 文件大小
  • 文件 hash
  • 业务归属信息
  • 上传任务 ID
  • 上传用户 ID
  • 创建更新时间

6.2 文件分页​

适用场景：

  • 附件列表页
  • 业务实体关联附件分页查看
  • 按上传人或来源实体查询文件

当前分页查询支持按以下条件过滤：

  • fileName
  • sourceEntity
  • sourceId
  • sourceType
  • uploadUserId

这足以支撑大多数后台附件管理页面。

7. 登录态下载​

7.1 功能定位​

这是给“系统内部用户自己下载文件”使用的标准入口。

典型场景：

  • 管理后台点击附件下载
  • 业务页面预览/下载附件
  • 已登录用户访问系统内附件

7.2 特点​

  • 依赖登录态
  • 会触发 StoragePermissionChecker 权限校验
  • 可以自定义下载时展示的文件名
  • 返回真实文件流

7.3 适用建议​

只要是平台用户自己下载，优先使用登录态下载，不建议为了内部下载而滥用签名下载。

8. 分享链接下载​

8.1 功能定位​

签名下载解决的不是“前端自己怎么下载”，而是：

一个已登录用户，想生成一个临时可分享链接，给别人下载。

8.2 当前能力​

模块当前支持：

  • 生成签名下载地址
  • 指定或默认下载文件名
  • 指定有效期
  • 指定最大下载次数
  • 第三方无登录态下载

8.3 适用场景​

例如：

  • 把合同文件发给外部合作方
  • 把压缩包分享给未登录用户
  • 给客户生成一个短时附件下载地址

8.4 使用边界​

签名下载适合“分享”，不适合作为平台内部下载主链路。

原因是：

  • 链接有时效
  • 链接一旦泄露就不再依赖平台登录态
  • 更适合短时外部流转而不是长期内部访问

9. 文件删除​

9.1 功能定位​

删除正式文件会删除 storage_file 业务记录。

但模块并不会无脑删底层内容，而是会检查：

  • 是否还有其他正式文件记录引用同一个物理文件位置

只有没有其他引用时，才会删除真实内容。

9.2 业务价值​

这对“内容复用”场景非常重要。

例如：

  • 同一个文件被多个业务实体引用
  • 同一个文件重复上传后复用了已有 storageKey

这种情况下删掉其中一个业务引用，不应该导致其他业务记录失效。

10. provider 相关业务能力​

虽然 provider 是技术实现，但对业务能力有直接影响。

10.1 filesystem​

适合：

  • 本地开发
  • 单机测试
  • 小规模部署

10.2 db​

适合：

  • 不想额外接对象存储
  • 文件规模相对可控
  • 希望所有数据统一落数据库

10.3 minio​

适合：

  • 生产环境
  • 多节点部署
  • 附件规模较大
  • 需要对象存储能力

从业务角度看，这三种 provider 不影响上层接口契约，切换成本主要在配置层。

11. 典型业务流程建议​

11.1 表单附件上传​

适合：

  • 公告、合同、工单、审批单附件

推荐流程：

  1. 前端直接上传普通文件
  2. 拿到临时上传任务详情
  3. 业务表单提交成功
  4. 后端调用 bind，把任务和业务记录关联
  5. 返回正式文件 ID

11.2 大文件上传​

适合：

  • 视频
  • 导入包
  • 归档文件

推荐流程：

  1. 创建上传任务
  2. 分片上传
  3. 调用 complete
  4. 业务保存成功后 bind
  5. 后续使用正式文件 ID 查询与下载

11.3 平台内下载​

适合：

  • 后台用户自己下载

推荐流程：

  1. 查文件 ID
  2. 调用 /api/storage/download
  3. 按业务权限校验后下载

11.4 对外分享下载​

适合：

  • 分享给外部人员

推荐流程：

  1. 已登录用户申请签名下载链接
  2. 平台返回短时分享 URL
  3. 将 URL 发给第三方
  4. 第三方使用 download-signed 下载

12. 小结​

从业务视角看，Nebula Storage 的真正价值不只是“上传文件”，而是提供了：

  • 一个可绑定业务归属的附件生命周期模型
  • 一个支持普通文件和大文件的统一上传体系
  • 一个支持内部下载与外部分享下载的双通道模型
  • 一个支持多存储 provider 的底层能力抽象

如果你的业务里涉及“附件先上传，再保存单据，再长期管理，再下载或分享”，那么 storage 模块已经基本覆盖了这条完整链路。