存储数据面
存储数据面
object-storage 是唯一接触对象字节的服务。它不维护对象索引,Bucket 是否存在、用哪种后端,都靠 StorageBackendFactory 现查 MySQL 或 Redis。下面按请求方向拆开:写、读、分片、后端选择。
1. 数据面接住哪些请求
| 请求 | Controller 方法 | 说明 |
|---|---|---|
PUT /{bucket}/{*objectKey} | ObjectController.putObject | 普通上传;带 x-cloud-disk-md5 时先判秒传 |
GET /{bucket}/{*objectKey} | getObject | 默认 302 到预签名 URL |
GET ...?proxy=true | getObjectProxy | 强制由数据面转发字节 |
HEAD /{bucket}/{*objectKey} | headObject | 返回 ETag、长度、类型、修改时间 |
DELETE /{bucket}/{*objectKey} | deleteObject | 先删后端对象,再发删除事件 |
POST /{bucket}?delete | deleteObjects | 批量删除,逐 key 发事件 |
PUT + x-copy-source | copyObject | 跨 Bucket 复制 |
POST ...?presigned-url | generatePresignedUrl | GET/PUT,1–604800 秒 |
POST ...?uploads、PUT ...?partNumber&uploadId、POST ...?uploadId、DELETE ...?uploadId、GET ...?uploadId | MultipartController | 分片上传五步 |
Spring 把 {*objectKey} 的捕获值连同前导 / 一起交给 Controller,所以 putObject("bucket", "/dir/a.txt", ...) 里的 key 是 /dir/a.txt,不是 dir/a.txt。ObjectControllerTest 把这一点固定成了断言。MinIO 在服务端会把前导斜杠归一化:向 /bucket//k 写入后,用 /bucket/k 能读到同一个对象。于是三条路径仍指向同一对象:
- 写入与读取原样透传带斜杠的 key;
- 预签名入口显式
substring(1)去掉斜杠; object_info.object_key保存的是事件载荷里的原样字符串,带前导/。这一点在真实 MySQL 数据里能看到,列表接口返回的 key 也带。
这条差异只在对 key 做精确匹配时才会露出来,分享列表就是一个例子,见已知边界。
2. 上传:先判秒传,再写后端

ObjectServiceImpl.putObject 的顺序是固定的,任何一步失败都会改变返回码或留下待补的事件:
- 有
x-cloud-disk-md5才判秒传。 用upload:hash:{md5}:{size}作为逻辑 key,HotKeyUtil.hotKeyForRead随机挑一个{shard:N}:副本读。 - 命中后必须二次校验。 拿到上次记录的 objectKey,调
statObject确认文件还在;存在才返回instant=true,不存在就删掉这个副本的 key,继续正常上传。 - 确认 Bucket。
ensureBucketExists先bucketExists,不存在就makeBucket;并发创建失败时再查一次,避免两个线程同时建桶报错。存储类型本身由工厂决定(下一节)。 - 写入后端。
backend.putObject,然后立刻statObject取 ETag。取 ETag 失败只记空字符串,不影响上传结果。 - 写秒传缓存。 有 MD5 时把 objectKey 写到三个副本,TTL 365 天。写入是三个 key 各写一次,没有事务。
- 发事件。
ObjectEventProducer先插outbox_table(PENDING),再发 RabbitMQ,成功后把该行改成 SUCCESS。 - 事件失败就回滚对象。 捕获异常后调
removeObject删掉刚写的对象,再把异常抛给调用方。回滚本身失败时只记日志,对象会留下但没有索引。
返回码区分两件事:秒传命中返回 200,正常写入返回 201,响应体都是 Result<UploadInitResponse>。
秒传的代价写在缓存一致性上:命中校验失败时只删了当前读到的那一个副本,另外两个副本仍然指向失效的 objectKey。随机读最多还会命中两次脏数据,每次命中会删掉对应的那个副本。
3. 下载:302 优先,代理兜底

GET 的默认行为不是转发字节,而是生成 300 秒有效的预签名 URL,返回 302 与 Location。客户端跟随后直连 MinIO,Gateway 与 object-storage 都不再参与这次传输。
这条路径依赖两个地址一致:容器内访问 MinIO 用 minio:9000,客户端访问用 MINIO_PUBLIC_ENDPOINT(默认 http://host.docker.internal:39000)。S3 V4 签名绑定 Host,所以 MinioConfig 建了两个客户端:
@Primary minioClient // 内部端点,CRUD 用
@Qualifier("presignMinioClient") // 公开端点,只生成预签名MinioStorageBackend 的 presignGetObject / presignPutObject 用后者,其余方法用前者。docker-compose.yml 给 object-storage 加了 extra_hosts: host.docker.internal:host-gateway,否则容器里解析不到这个名字。
三种情况会走代理:
| 情况 | 判定 | 结果 |
|---|---|---|
| 后端不支持预签名(本地、OSS) | UnsupportedOperationException | 自动 getObjectWithMeta 流式返回 |
显式 ?proxy=true | 单独的映射方法 | 直接流式返回 |
| 预签名生成抛其它异常 | 不捕获 | 500 |
代理模式用 StreamingResponseBody,把 InputStream 直接 transferTo 响应流,设置 Content-Type、ETag、Content-Length。
?presigned-url 是另一条入口,支持 method=GET|PUT、expiry=1..604800,参数越界返回 400;本地与 OSS 后端返回 501。
4. 分片上传:Redis 存会话,后端负责合并

| 步骤 | Redis | 后端 |
|---|---|---|
| Init | parts:{uploadId} 写 -1=init,TTL 24 小时 | MinIO/本地返回 null,由服务生成 UUID v7;OSS 返回原生 uploadId |
| UploadPart | HSET parts:{id} {partNumber} "{etag}|{size}" | MinIO 把分片存成 {uploadId}/{objectKey}/part-0001;本地写临时文件;OSS 走原生 uploadPart |
| Complete | 校验分片存在、ETag 匹配、partNumber 严格升序 | MinIO composeObject;本地 FileChannel.transferTo;OSS 原生 complete |
| Abort | 删除整个 Hash | 清理临时分片/目录 |
| ListParts | 读 Hash,过滤 -1 | 不访问后端 |
几个实现细节:
- MinIO 用的不是原生 multipart。
initiateMultipartUpload返回null,每个分片是一个独立对象,Complete 时用composeObject合并,然后逐个删除临时分片。composeObject的源数量上限是 1000,代码在超过时直接抛错。 - Complete 只校验升序,不校验连续性。 客户端传
[1, 3]能通过;缺号由后端合并结果决定,服务不拦。 - ETag 比较兼容引号。 上传分片的响应头是
"etag",Complete 请求体可能带引号也可能不带,代码两种都比一次。 - 单分片上限写的是 5 GiB,实际受堆限制。 Controller 先判
Content-Length > 5 GiB,然后把整片读进byte[]。-Xmx256m下能通过的分片远小于这个数;管理台上传用的是 5 MB 分片。 - Complete 发事件时不带 MD5。 分片合并路径的
sendObjectCreatedEvent把md5Hash传成null,所以分片上传的对象不会进秒传缓存。 - Redis 过期即会话结束。 24 小时后
parts:{uploadId}消失,UploadPart 与 Complete 都会报NoSuchUpload,Abort 则直接返回成功。
5. 存储后端:接口、工厂与三种实现

StorageBackend 是唯一的抽象点,方法分成 Bucket、对象 CRUD、Multipart、预签名四组。StorageBackendFactory 在启动时把三个实现装进 Map<StorageType, StorageBackend>,请求时按 Bucket 取。
解析顺序是 Redis → MySQL → 回写 Redis:
- 逻辑 key
bucket:storage:{bucketName},随机读一个热 key 副本; - 未命中就查
SELECT storage_type FROM bucket_info WHERE bucket_name = ? AND status = 'ACTIVE'; - 查不到抛
BucketNotFoundException; - 查到后写三个副本,TTL 1 小时。
三种实现的差异集中在能力与一致性上:
| 能力 | MinIO | 本地 | OSS |
|---|---|---|---|
| 对象 CRUD | 是 | 是 | 是 |
| 分片 | 独立对象 + composeObject | 临时文件 + FileChannel | 原生 multipart |
| 预签名 | 是(双客户端) | 否(501) | 否(501) |
| ETag | 服务端返回值 | 文件 MD5 | 服务端返回值 |
| 凭据 | 固定 minioadmin(配置项) | 无 | access-key 为空则整个后端不可用 |
OSS 的客户端在 @PostConstruct 时按凭据是否存在决定建不建;没配凭据时只打一条 warn,但 Bucket 若指向 OSS,第一次请求就会在 ensureClient 抛 IllegalStateException。
6. Redis 键与缓存语义
| Key | 类型 | 值 | TTL | 读/写 |
|---|---|---|---|---|
{shard:N}:upload:hash:{md5}:{size} | STRING | objectKey | 365 天 | 随机读一个副本,写三个副本 |
parts:{uploadId} | HASH | partNumber -> "etag|size",-1=init | 24 小时 | 读写同一个 key |
{shard:N}:bucket:storage:{bucket} | STRING | MINIO/LOCAL/OSS | 1 小时 | 随机读,写三个 |
jwt:blacklist:{token} | STRING | 1 | token 剩余有效期 | 网关读,登出时写 |
buckets:list:{userId} | STRING | 序列化列表 | 无固定值 | 创建 Bucket 时删 |
object:info:{bucket}:{key} | STRING | 序列化对象信息 | 无固定值 | 事件消费后删 |
后两个 key 目前只有删除动作,没有读写路径。buckets:list: 在 createBucket 里被删;object:info: 在 ObjectCreatedConsumer 里被删。没有任何代码写入或读取它们。
热 key 打散的规则在 HotKeyUtil:固定 3 个副本,{shard:0}、{shard:1}、{shard:2} 作为 HashTag 前缀。读用 ThreadLocalRandom 挑一个,写必须三个都写。Redis Cluster 按 HashTag 分槽,三个前缀落在不同 slot 上,才能分散到三台 master。
7. 失败路径
| 失败点 | 代码行为 | 外部看到 |
|---|---|---|
| 秒传缓存命中但对象不存在 | 删当前副本 key,继续正常上传 | 正常上传 |
| 后端写入失败 | 包装成 InternalError 抛出 | 500,无对象 |
statObject 取 ETag 失败 | ETag 置空,继续 | 上传成功,索引 ETag 为空 |
| Outbox 插入失败 | 走进同一个 catch,回滚对象后抛出 | 500,无对象、无记录 |
| MQ 投递失败 | 删除已写对象后抛出 | 500,Outbox 留 PENDING(对象已回滚,重试会补一条指向不存在对象的索引) |
| 删除时后端报错 | 记录 warn 后继续发删除事件 | 200,对象可能还在存储里 |
| 预签名生成失败 | 没有回退到代理(生成阶段直接抛) | 500 |
| 分片 Redis 过期 | InvalidPart / NoSuchUpload | 400 |
MQ 投递失败那条有个顺序问题:对象已经被回滚删除,但 PENDING 的 Outbox 记录还在,XXL-Job 重试时会把这条事件补投出去,控制面于是给一个不存在的对象建索引。这是“至少一次投递 + 本地回滚”组合出来的结果,不是消费者能判断的。