跳到主要内容

Nebula Storage 使用方式

1. 接入方式总览​

nebula-storage 支持两种主要接入方式:

  • 单体模式:业务应用直接引入 nebula-storage-local
  • 微服务模式:独立部署 nebula-storage-service,业务应用引入 nebula-storage-remote

无论哪种方式,业务代码最好都面向 IStorageService 及其 command/query/dto 契约编程。


2. 单体应用接入​

2.1 Maven 依赖​

<dependency>
<groupId>com.cludix</groupId>
<artifactId>nebula-storage-local</artifactId>
</dependency>

2.2 适合场景​

适用于:

  • 单体后台系统
  • 已经使用 nebula-app-starter 的场景
  • 文件存储能力直接随主应用一起运行

2.3 运行方式​

此时:

  • StorageController 直接对外提供接口
  • IStorageService 由 StorageServiceImpl 本地实现
  • temp 区与 formal 区都在当前应用中处理

3. 独立存储服务接入​

3.1 启动独立服务​

mvn spring-boot:run -pl nebula-storage/nebula-storage-service

3.2 当前服务配置​

从 nebula-storage-service/src/main/resources/application.yml 可确认:

  • 默认端口:17783
  • nebula.storage.mode=local

即独立服务本身暴露的是本地实现接口,对外作为 storage provider 服务运行。

3.3 消费方依赖​

业务服务作为消费者时,应引入:

<dependency>
<groupId>com.cludix</groupId>
<artifactId>nebula-storage-remote</artifactId>
</dependency>

3.4 remote 配置示例​

nebula:
storage:
mode: remote
remote:
service-name: nebula-storage-service
service-url: http://localhost:17783

3.5 适合场景​

适用于:

  • 多个业务服务共用一套附件中心
  • 文件上传下载能力需要集中治理
  • 希望对象存储配置与附件逻辑统一收口

4. 配置说明​

4.1 基础示例​

nebula:
storage:
mode: local
temp-dir: /data/nebula/storage/temp
signed-download:
enabled: true
secret: change-me-storage-signed-secret
default-expire-seconds: 300
max-expire-seconds: 1800
default-max-download-count: 3
max-download-count-limit: 10
content:
type: minio
filesystem:
base-dir: /data/nebula/storage/content
minio:
endpoint: http://127.0.0.1:9000
access-key: minioadmin
secret-key: minioadmin
bucket: nebula-storage
create-bucket-if-missing: true
direct-download-enabled: false
direct-download-expire-seconds: 300

4.2 temp-dir​

作用:

  • 存普通上传临时文件
  • 存分片文件
  • 存分片合并结果

注意:

  • temp 区固定走文件系统目录
  • bind 成功后会通过事件和定时任务清理
  • 不适合当长期存储区使用

4.3 content.type​

可选值:

  • filesystem
  • db
  • minio
  • s3(S3 兼容,覆盖阿里云 OSS / 腾讯云 COS / 七牛等)

它决定的是正式文件内容区如何保存,而不是业务元数据表落在哪里。

4.4 signed-download​

关键参数:

  • enabled
  • secret
  • default-expire-seconds
  • max-expire-seconds
  • default-max-download-count
  • max-download-count-limit

建议:

  • secret 使用独立高强度随机值
  • 不要把有效期设置过长
  • 对对外分享场景可以增加下载次数限制

5. 业务侧如何使用​

5.1 普通附件上传​

推荐流程:

  1. 前端选择文件
  2. 调用 /api/storage/upload
  3. 后端根据最终文件名推导扩展名与 MIME,并返回临时上传任务详情 taskId
  4. 业务表单保存成功
  5. 调用 /api/storage/upload-tasks/{taskId}/bind
  6. 保存返回的正式 fileId

适合:

  • 合同附件
  • 公告附件
  • 单据附件
  • 用户头像、图片、文档附件

5.2 分片上传​

推荐流程:

  1. 先创建上传任务
  2. 前端循环上传分片
  3. 调用 complete 合并分片,并由后端按最终文件名补齐 MIME
  4. 业务保存成功后调用 bind
  5. 持久化 fileId

适合:

  • 视频
  • 导入包
  • 大压缩包
  • 超大附件

5.3 查询和展示附件​

常见做法:

  • 业务表只保存 fileId 或文件关联关系
  • 列表页通过 /api/storage/files/page 或业务侧附件关系回表展示
  • 详情页调用 /api/storage/files/{fileId} 回显文件元信息

5.4 平台内部下载​

推荐先解析下载位置,再按返回的 mode 取文件:

  1. GET /api/storage/download-location?fileId=...(可带 filename、variant)
  2. mode=DIRECT:把 url 当作裸 URL 直接取文件,不附加 Authorization
  3. mode=PROXY:GET /api/storage/download?fileId=...,带 Authorization

也可以跳过第 1 步直接调用 /api/storage/download——服务端代理路径始终可用;download-location 只是让客户端在对象存储开启直连时少走一趟应用带宽。

接口恒返回数组。要一次拿到某个业务单据下的全部附件,改用业务归属定位,省掉「先 list-by-source 再逐个解析」:

GET /api/storage/download-location?sourceEntity=deliveryOrder&sourceId=1870000000000000001&sourceType=signPhoto&variant=thumb

响应每项带 fileId / fileName / fileMimeType / fileSize / mode / url,列表页可直接遍历渲染。fileId 与 sourceEntity+sourceId 二选一,都不给报 DOWNLOAD_LOCATION_PARAM_INVALID(24027)。

适用场景:

  • 已登录后台用户下载
  • 平台前端自己下载
  • 移动端图片预览(variant=thumb,直连时用直链、否则走 blob)
  • 业务单据的全部附件/签名照片一次性取下载位置

注意:filesystem / db 后端恒返回 PROXY;对象存储的直连开关默认关闭。预览场景不要传 filename,否则语义会从 inline 变成 attachment;按业务归属批量解析本身即按预览语义处理,传了也会被忽略。

5.5 对外分享下载​

推荐做法:

  1. 用户点击“生成分享链接”
  2. 调用 POST /api/storage/generate-signed-url
  3. 后端先校验原始下载权限
  4. 返回短时有效 url
  5. 将 URL 分享给第三方

不建议:

  • 在普通附件列表里批量预生成签名地址
  • 把签名下载当成平台内部下载主链路
  • 生成长期不失效的公开链接

6. 业务系统如何扩展权限​

nebula-storage 当前提供了扩展点:

  • StoragePermissionChecker

默认实现 DefaultStoragePermissionChecker 会直接放行,因此如果业务系统需要更精细的下载权限,应自行实现 Bean 覆盖。

示意:

@Component
public class ContractStoragePermissionChecker implements StoragePermissionChecker {

@Override
public boolean canDownload(UserContextDto currentUser, StorageFileDetailDto fileDetail) {
if (!"contract".equals(fileDetail.getSourceEntity())) {
return true;
}
return hasContractReadPermission(currentUser, fileDetail.getSourceId());
}

private boolean hasContractReadPermission(UserContextDto currentUser, String contractId) {
// 这里接业务权限逻辑
return true;
}
}

这样可以按:

  • 业务单据可见范围
  • 组织权限
  • 租户范围
  • 上传人归属
  • 角色授权

进行下载控制。


7. provider 选型建议​

7.1 filesystem​

建议用于:

  • 本地开发
  • 单机测试
  • 小规模环境

优点:

  • 简单直接
  • 无额外依赖

缺点:

  • 不适合多节点共享
  • 容灾能力弱

7.2 db​

建议用于:

  • 不方便接对象存储的环境
  • 文件量不大、集中数据库治理的场景

优点:

  • 运维简单
  • 统一落数据库

缺点:

  • 数据库压力更大
  • 大文件场景不够友好

7.3 minio​

建议用于:

  • 生产环境
  • 多节点部署
  • 较大附件规模

优点:

  • 更适合正式文件内容存储
  • 可扩展性更好

8. 前端接入建议​

8.1 上传侧​

前端一般需要保存:

  • taskId
  • 上传进度
  • fileId(bind 成功后)

建议区分两类组件:

  1. 普通上传组件

    • 直接走 /api/storage/upload
    • 适合图片、文档、小文件
  2. 分片上传组件

    • 先申请 task
    • 再逐片上传
    • 最后 complete + bind

8.2 下载侧​

建议区分两类按钮:

  1. 下载附件

    • 先调 /api/storage/download-location 解析位置:DIRECT 用返回的裸 URL,PROXY 走 /api/storage/download
  2. 复制分享链接

    • 先调用 /api/storage/generate-signed-url
    • 再复制返回的 data.url

这样用户心智更清晰,也更符合 storage 模块设计边界。


9. 常见落地建议​

9.1 业务表如何关联文件​

建议至少记录:

  • fileId
  • 业务主键
  • 文件用途(可选)
  • 排序号(可选)

9.2 bind 调用时机​

推荐在:

  • 业务主表写入成功之后
  • 明确拿到业务主键之后

不要在:

  • 表单刚打开时
  • 业务还没保存成功时
  • 还不知道 sourceEntity/sourceId 时

9.3 删除策略​

如果业务删除附件关系后希望同步删除正式文件,可以显式调 storage 删除接口; 如果只是解除业务关联、不想删物理文件,则应在业务侧单独控制,不要直接调用 storage 删除正式文件。


10. 小结​

storage 模块的最佳使用方式可以概括为:

  • 上传时先拿临时任务,不急着视为正式附件
  • 业务保存成功后再 bind 转正
  • 平台内部下载走鉴权下载
  • 外部分享走签名下载
  • 正式内容区优先考虑 MinIO 等对象存储
  • 业务权限通过 StoragePermissionChecker 自行补强

这样才能真正发挥 nebula-storage 作为统一附件中心的价值。