跳到主要内容

存储增强(对象存储与图片处理)

nebula-storage 本批新增四块能力:S3 兼容对象存储后端、图片派生版本(缩略图)、存储后端迁移工具、对象存储直连下载。四者的默认配置都不改变现有行为(S3 需显式切换、图片处理默认关闭、迁移工具需主动调用、直连下载默认关闭)。

1. S3 兼容对象存储后端​

1.1 定位​

新增 S3 兼容的 StorageBinaryStore(nebula.storage.content.type=s3),一份实现覆盖阿里云 OSS / 腾讯云 COS / 七牛 / MinIO 等。此前对象存储只有 MinIO 实现。

正式内容存储类型由 nebula.storage.content.type 决定,取值:filesystem(默认)/ db / minio / s3。分派点是 StorageStoreFactory。

1.2 配置​

nebula:
storage:
content:
type: s3
s3:
endpoint: ${NEBULA_STORAGE_S3_ENDPOINT:}
region: ${NEBULA_STORAGE_S3_REGION:}
access-key: ${NEBULA_STORAGE_S3_ACCESS_KEY:}
secret-key: ${NEBULA_STORAGE_S3_SECRET_KEY:}
bucket: ${NEBULA_STORAGE_S3_BUCKET:}
path-style-access: ${NEBULA_STORAGE_S3_PATH_STYLE:true}
create-bucket-if-missing: ${NEBULA_STORAGE_S3_CREATE_BUCKET:false}
配置项默认值说明
endpoint无服务地址,如 https://oss-cn-hangzhou.aliyuncs.com 或 http://minio:9000
region无区域;多数云厂商必填,MinIO 可留空(代码回退 us-east-1)
access-key / secret-key无AK/SK,只走环境变量
bucket无Bucket 名称
path-style-accesstrue见下方「path-style 的坑」
create-bucket-if-missingfalse是否自动建桶

凭据只走环境变量:AK/SK 不允许写入数据库、仓库或日志;S3ObjectAddress 仅做寻址诊断,不含签名与凭据。

1.3 path-style-access 的坑​

path-style-access 决定对象的寻址形态:

  • true(默认):scheme://host[:port]/bucket/key,例如 http://minio:9000/nebula-storage/a.jpg
  • false:scheme://bucket.host[:port]/key,例如 http://nebula-storage.minio:9000/a.jpg

配错会得到 404 或签名错误,不是明显的配置报错:

  • MinIO / 自建网关:需要 true(false 时子域无法解析)。
  • 多数云厂商(OSS/COS/七牛):需要 false(除非使用厂商的 path-style 兼容端点)。

region 留空时回退 us-east-1;create-bucket-if-missing 默认 false——多数云厂商的 AK 没有建桶权限,生产建议保持 false。

1.4 装配与校验​

  • 配置不完整(endpoint / bucket / accessKey / secretKey 任一为空)→ S3_CONFIG_INCOMPLETE(24020)。
  • create-bucket-if-missing=false 且 bucket 不存在 → 同样 S3_CONFIG_INCOMPLETE。
  • 实现基于 AWS SDK v2(software.amazon.awssdk:s3),强制 path-style 由 forcePathStyle(...) 控制。

2. 图片派生版本(缩略图)​

2.1 定位​

新增 storage_file_variant 表,保存图片的派生版本(当前只有 thumb)。上传后按配置生成;派生是「可选存在」——未开启或处理失败时没有派生行,读取端回退原图。

2.2 配置​

nebula:
storage:
image:
enabled: false # 默认关闭,关闭时行为与改造前完全一致
thumb-width: 320
thumb-height: 320
thumb-quality: 0.8
max-width: 0 # 原图宽度上限,0 表示不限制
max-height: 0 # 原图高度上限,0 表示不限制
配置项默认值说明
enabledfalse是否开启图片处理(缩略图派生与尺寸上限校验)
thumb-width / thumb-height320 / 320缩略图目标尺寸(不放大:scale = min(target/src, 1.0))
thumb-quality0.8缩略图压缩质量(0~1),输出固定为 jpeg
max-width / max-height0原图尺寸上限,0 不限制

2.3 生成与去重​

  • 生成时机:bindUploadTask 保存正式文件后调用 generateVariants;已存在 thumb 派生则跳过。
  • 内容按 (fileHash, variant) 寻址去重:多个业务引用同一张图只存一份缩略图,contentKey 形如 variant/thumb/<fileHash>.jpg。

2.4 防解压炸弹​

解码前先读图片头部尺寸:

  • 格式白名单:jpeg / jpg / png / bmp / gif。
  • 像素总数硬上限 50_000_000;字节上限 64 MiB。
  • 超过像素或字节上限直接拒绝(IMAGE_DIMENSION_EXCEEDED,24021);非图片或畸形输入返回「无派生」而不是硬试。

2.5 读取与回退​

  • GET /api/storage/download 新增可选 variant 参数:缺省/null/空白 → 原图;variant=thumb → 缩略图。
  • GET /api/storage/download-location 同样接受 variant,直连模式下发的是该派生的预签名直链。
  • 请求的派生版本不存在时回退原图并记 WARN,不抛 VARIANT_NOT_FOUND——避免移动端列表页因缺少缩略图而整块空白。
  • 文件详情响应新增 variants(可用派生版本与尺寸)。
  • 签名下载 download-signed 不带 variant,恒返回原图。
  • 删除文件时会删除派生行,若某 contentKey 不再被任何行引用则删除正式内容。

VARIANT_NOT_FOUND(24023)已定义但当前实现未抛出(读取走回退原图)。


3. 存储后端迁移工具​

3.1 能力​

StorageMigrationService.migrate(source, target) 在 StorageBinaryStore 之间做一次性迁移:

  • 遍历全部正式文件,逐条迁移。
  • 逐项 MD5 校验:源内容 MD5 与 fileHash 不一致 → MIGRATION_CHECKSUM_MISMATCH(24025);写入目标后复核一次。
  • 可重入跳过:目标已存在且哈希匹配的文件直接跳过。
  • 不删除源内容:调用方在「双写 + 校验完成」后自行切换读取配置,最后清理旧内容。
  • 返回 MigrationReport(total, migrated, skipped)。

支持的方向:db → filesystem 与 db → s3(代码对源/目标泛化,任意组合皆可)。

注意:该工具尚未交付触发入口——管理接口与命令行均未提供,目前只能在测试或集成代码中显式调用 migrate()。接入方如需使用需自行封装触发方式。

3.2 迁移期间拒写​

StorageMigrationGuard 在迁移进行中拒绝正式写入(bindUploadTask 开头 requireWritable(),命中抛 MIGRATION_IN_PROGRESS,24024)。上传到临时区(简单上传 / 分片 / complete)不经过该闸门,只有正式写入被拒。守卫是进程内状态(AtomicBoolean),不跨实例共享——迁移的前提是迁移期间应用单实例运行;多实例部署需自行安排整体停写。

3.3 分阶段步骤​

1. 停写窗口(安排停机/维护公告)
2. 启动迁移:db → 目标后端,逐项 MD5 校验
3. 迁移完成(migrated + skipped 覆盖全部正式文件)
4. 切换 nebula.storage.content.type 指向目标后端并重启
5. 抽样校验读取(原图 + 派生)
6. 确认无误后清理旧后端内容

3.4 回滚​

  • 迁移不删除源内容,因此第 4 步切换后若发现问题,把 nebula.storage.content.type 改回原值并重启即可回滚。
  • 迁移期间写入被拒,需安排停机窗口;不要在写入高峰期执行。

4. 对象存储直连下载​

4.1 定位​

新增 GET /api/storage/download-location:由服务端决议本次下载走直链还是走代理,客户端不需要知道后端类型,也不自己选路。filesystem / db 恒为代理;对象存储(minio / s3)在开启直连开关后返回预签名直链。

定位方式二选一:

  • 给 fileId:解析单个文件的下载位置;
  • 给 sourceEntity + sourceId(可选 sourceType):一次解析该业务实体下全部附件,省掉「先 list-by-source 再逐个解析」的两跳。

响应恒为数组(单文件解析只有一个元素),客户端可直接遍历渲染多项。variant 两种方式都支持。

4.2 响应​

data 为数组,每项:

字段说明
fileId正式文件ID
fileName文件名,供列表页直接展示
fileMimeType文件 MIME;请求派生版本时为该派生内容的类型
fileSize文件字节数
modeDIRECT(url 是对象存储预签名直链)或 PROXY(url 指回 /api/storage/download)
urlDIRECT 为临时直链;PROXY 为带好 fileId/variant 的服务端下载地址
expiresAtEpochSecond仅 DIRECT 有值,直链过期时间

filename 有值 ⇒ 附件下载(attachment);为空 ⇒ 内联预览(inline)。预览场景不传 filename。

按业务归属批量解析时按预览语义处理:不会把调用方传的 filename 套到批量结果上(否则一键改掉全部附件的文件名没有意义)。需要带文件名的单个下载,请按 fileId 单独解析。

4.3 配置​

直连开关位于对象存储各自的配置节点下,默认关闭:

nebula:
storage:
content:
type: s3
s3:
direct-download-enabled: ${NEBULA_STORAGE_S3_DIRECT_DOWNLOAD_ENABLED:false}
direct-download-expire-seconds: ${NEBULA_STORAGE_S3_DIRECT_DOWNLOAD_EXPIRE_SECONDS:300}
# minio 同名配置项:direct-download-enabled / direct-download-expire-seconds
配置项默认值说明
direct-download-enabledfalse是否允许签发直链
direct-download-expire-seconds300直链有效期,上限 3600,超出按上限截断

4.4 能力声明与降级​

  • StorageBinaryStore.supportsDirectAccess() 默认 false;filesystem / db 用默认实现即自动降级为服务端流式转发。
  • S3StorageBinaryStore 在「开关开启 且 客户端支持预签名」时才返回 true(S3ObjectClient.supportsPresign());MinioStorageBinaryStore 只需开关开启(MinIO 客户端恒支持预签名)。
  • S3ObjectClient 以 supportsPresign() + presignGetObject(...) 暴露预签名能力;MinIO 客户端走 getPresignedObjectUrl。

4.5 安全边界​

  • 预签名直链是凭据:不写日志、不入审计快照、不回显到错误信息;代码只记录 describeObjectLocation(key) 这类寻址信息。
  • 直链有效期受上限截断,权限校验只在签发时发生一次。
  • 签名分享下载 download-signed 恒经服务端代理,不因直连开关而改变——它需要强制次数与时效,不能绕过。

5. 接口与权限码​

方法 + 路径权限码说明
GET /api/storage/download-locationSTORAGE_FILE_QUERY解析下载位置,返回数组;fileId 或 sourceEntity+sourceId 二选一定位,DIRECT 返直链、PROXY 返代理地址
GET /api/storage/downloadSTORAGE_FILE_QUERY新增可选 variant 参数
POST /api/storage/files/list-by-sourceSTORAGE_FILE_QUERY由内部能力开放为正式接口(按业务实体查附件,供移动端列表页取图)
DELETE /api/storage/files/{fileId}STORAGE_FILE_DELETE补齐权限码
其余上传/查询接口STORAGE_UPLOAD / STORAGE_FILE_QUERY见业务功能

POST /api/storage/files/list-by-source 请求:sourceEntity(必填)、sourceId(必填)、sourceType(可选);响应为文件列表(不含 variants,variants 只在文件详情接口返回)。

6. 错误码​

错误码名称说明
24020S3_CONFIG_INCOMPLETES3 兼容对象存储配置不完整
24021IMAGE_DIMENSION_EXCEEDED图片尺寸超过上限
24022IMAGE_PROCESS_FAILED图片处理失败
24023VARIANT_NOT_FOUND请求的派生版本不存在(当前实现走回退原图,未抛出)
24024MIGRATION_IN_PROGRESS存储后端迁移进行中,暂不接受写入
24025MIGRATION_CHECKSUM_MISMATCH迁移校验失败,内容哈希不一致
24026STORAGE_BACKEND_MISMATCH文件不属于当前存储后端,拒绝删除

7. 数据表​

storage_file_variant 的字段与索引见 Storage 数据表。