架构总览
架构总览
cloud-disk 是一个 S3 形状的对象存储服务:Bucket 与 Object 的路径风格 API、ListObjectsV2 的 XML 响应、Multipart Upload 的 Init/Part/Complete/Abort 都能对上 AWS S3 的语义。认证不走 S3 SigV4,走 JWT,所以 aws-cli、s3cmd 这类只签 SigV4 的客户端不能直接接入,能复用的是 HTTP 形状与预签名 URL。
它的边界由三个进程划开:gateway 只做转发与身份校验,object-storage 碰对象字节,object-metadata 碰 MySQL 里的索引与业务表。对象写完到索引可见之间有一段异步窗口,靠 Outbox 表和 RabbitMQ 补。
1. 一句话定位与不做的部分
| 做 | 落到哪 |
|---|---|
| 多存储后端,每个 Bucket 独立选择 | bucket_info.storage_type + StorageBackend 三种实现 |
| 秒传(内容去重) | upload:hash:{md5}:{size},命中后二次 statObject |
| 分片上传 | Redis parts:{uploadId} + 后端合并 |
| 预签名下载/上传 | 双 MinioClient,302 跳转或代理回退 |
| 软删除与回收站 | object_info.status 状态机 + XXL-Job 清理 |
| 分享链接 | share_link + bcrypt 密码 + 下载次数 |
明确没有实现的部分,读代码时不要假设它们存在:
- 版本控制、Bucket Policy、Object Lock、跨区域复制、生命周期规则;
- S3 SigV4 客户端签名;网关只认
Authorization: Bearer <JWT>; - 对象级/桶级授权。登录用户知道 Bucket 名就能读写,见已知边界;
- Kubernetes 编排与多实例共享会话;部署形态是单机 Docker Compose 和一份双机 compose。
2. 三个进程与一个前端
| 进程 | 端口 | 技术形态 | 常驻内容 | 主要入口 |
|---|---|---|---|---|
gateway | 38080 | Spring Cloud Gateway(WebFlux + Reactor Netty) | JWT 签名密钥、Redis 响应式客户端、Sentinel 规则 | AuthFilter、application.yml 的 routes |
object-storage | 38081 | Spring MVC + 虚拟线程 | MinIO/OSS 客户端、Redis 连接、RabbitMQ、Outbox Mapper | ObjectController、MultipartController |
object-metadata | 38082 | Spring MVC(平台线程池) | MySQL(ShardingSphere)、Redis、RabbitMQ 监听器、XXL-Job 执行器 | AuthController、BucketController、RecycleController、ShareController |
admin-ui | 5173(dev) | React 19 + Vite + TanStack Router/Query | 浏览器里的 SPA | pages/*、api/* |
虚拟线程只在 object-storage 打开(spring.threads.virtual.enabled: true)。object-metadata 的 application.yml 没有这一项,它仍然是常规的 Tomcat 线程池。

3. 两条链路:对象链路与索引链路
对象链路是同步的。 上传请求在 object-storage 里完成 putObject 才返回;下载默认返回 302,让客户端直连 MinIO,只有后端不支持预签名或显式带 ?proxy=true 时才由 object-storage 转发字节。这条链路上没有 object-metadata。
索引链路是异步的。 object-storage 把 OBJECT_CREATED / OBJECT_DELETED 写进 outbox_table,再投递到 RabbitMQ;object-metadata 的监听器消费后 UPSERT object_info、更新 bucket_info.used_bytes、删缓存。上传接口返回时,列表里未必已经能看到这个对象。
| 环节 | 同步/异步 | 失败时看到什么 |
|---|---|---|
| 网关验签、黑名单 | 同步 | 401,请求不进入后端 |
| 对象写入 | 同步 | 5xx,没有对象 |
| Outbox 落库 | 同步(上传线程内) | 插入失败则整个上传失败并回滚已写对象 |
| MQ 投递 | 同步尝试 | 失败则上传失败并回滚对象,PENDING 记录留给定时任务 |
| 索引 UPSERT | 异步 | 对象可下载,列表暂时看不到 |
4. 数据落在哪
| 数据 | 存放位置 | 键 / 表 | 能否重建 |
|---|---|---|---|
| 对象字节 | MinIO、本地盘或 OSS,按 Bucket 决定 | {bucket}/{key} | 取决于后端,服务内没有扫描重建工具 |
| Bucket 与对象索引 | MySQL | bucket_info、object_info(按 bucket_id % 2 分库) | object_info 只能从事件流补,事件丢了就没有补扫通道 |
| 秒传缓存 | Redis Cluster | {shard:N}:upload:hash:{md5}:{size} | 可重建,丢了只是退化为正常上传 |
| 分片会话 | Redis Cluster | parts:{uploadId} | 不可重建,Redis 丢了这次上传就作废 |
| JWT 黑名单 | Redis Cluster | jwt:blacklist:{token} | 不可重建;丢了就只能等 token 自然过期 |
| Bucket 存储类型缓存 | Redis Cluster | {shard:N}:bucket:storage:{bucket} | 可从 bucket_info 重建,TTL 1 小时 |
| Outbox | MySQL | outbox_table | 不可重建,是事件流的唯一副本 |
| 分享链接 | MySQL | share_link | 不可重建 |
sql/init.sql 里还有一张 multipart_upload 表,运行时没有任何读写路径。分片状态只存在 Redis,这是事件与一致性和已知边界都会提到的一个前提。
5. 一次请求经过谁
Gateway 的匹配顺序决定了一个路径落到哪个服务,三条规则最容易混淆:
GET /是列 Bucket,去object-metadata;GET /{bucket}?list-type=2才是列对象。/{bucket}上的PUT/DELETE/HEAD是 Bucket 管理,去object-metadata;一旦路径多出一段,就归object-storage。- 带
uploads、uploadId、partNumber任一查询参数的对象路径优先匹配分片路由;/share/**的 order 是-1,必须排在对象路由之前。
完整路由表、匹配顺序与鉴权放行清单在网关与鉴权。
6. 技术选型
| 组件 | 版本 | 用在哪 |
|---|---|---|
| Java | 21 | 三个服务;object-storage 开虚拟线程 |
| Spring Boot | 3.3.7 | 父 POM |
| Spring Cloud | 2023.0.3 | Gateway、负载均衡 |
| Spring Cloud Alibaba | 2023.0.1.0 | Nacos 注册/配置、Sentinel |
| MyBatis-Plus | 3.5.9 | object_info、bucket_info、share_link、outbox_table |
| ShardingSphere-JDBC | 5.5.1 | 读写分离 + object_info 分库(Java Config 手写 DataSource) |
| Redisson | 3.40.0 | 同步客户端 + 网关的 RedissonReactiveClient |
| MySQL | 8.0.34 | 主从两台,端口 33306/33307 |
| Redis | 7(6 节点 Cluster) | 三主三从,端口 37000–37005 |
| RabbitMQ | 3.13.7 | Topic Exchange cloud-disk.object |
| MinIO | RELEASE.2025-04-22 | 默认后端,SDK 8.5.15 |
| 阿里云 OSS SDK | 3.18.1 | OSS 后端 |
| XXL-Job | 2.4.2 | 三个定时任务 |
| Nacos | 2.4.3 | 注册与 Sentinel 规则配置 |
| Sentinel | 1.8.7 | 网关流控 |
| JJWT | 0.12.6 | 签发与验签 |
| JMeter | 5.6.3 | 9 个基准场景 |
7. 决定清单
| 决定 | 原因 | 代价 |
|---|---|---|
| 数据面与控制面拆成两个服务 | 文件 IO 与元数据查询的资源曲线不同,可分别扩容 | 两份数据,必须处理一致性 |
| 用 Outbox 而不是双写或同步 RPC | 双写会一半成功一半失败;同步 RPC 把控制面故障传导到上传 | 索引有延迟,需要定时重试与死信清理 |
| 上传路径只写对象,不写索引 | 不让 MySQL 出现在字节流的关键路径上 | 列表短时间滞后 |
| 分片会话放 Redis | Complete 前只是临时状态,TTL 自动过期 | Redis 丢数据会丢整个上传会话 |
| 每个 Bucket 选后端 | 冷热数据可以放不同介质 | 跨后端复制、预签名能力不一致 |
| 下载默认 302 | 不让 GB 级的字节流穿过 Gateway | 客户端要能访问 MINIO_PUBLIC_ENDPOINT |
| 热点 key 做 3 份 HashTag 副本 | 单个秒传 key 会把一个 slot 打热 | 写放大 3 倍,读随机挑副本 |
| 网关用响应式 Redis 客户端 | 同步调用会占住 Netty event loop | 代码里不能出现任何阻塞调用 |
object_info 按 bucket_id 分库 | 同一 Bucket 的列表查询落在单库 | 跨 Bucket 聚合要广播 |
| 用 RECYCLED 状态代替直接删索引 | 回收站里还能看到这条记录 | 字节在 DeleteObject 时已删,恢复只恢复索引 |
回收站恢复的是 object_info 的状态,不是存储里的文件。删除链路实际做了什么,见事件与一致性与已知边界。
8. 目录与入口
| 目录 | 内容 | 先看哪个文件 |
|---|---|---|
common/ | DTO、S3 错误码、异常、StorageBackend 接口、Redis key 常量、热 key 工具 | storage/StorageBackend.java、constant/RedisKeyConstants.java |
gateway/ | 路由、JWT 过滤器、Sentinel 规则、CORS、Netty 参数 | filter/AuthFilter.java、resources/application.yml |
object-storage/ | 对象与分片的 Controller/Service、三种后端、Outbox 生产与重试 | service/impl/ObjectServiceImpl.java、backend/StorageBackendFactory.java |
object-metadata/ | 登录、Bucket、索引消费者、回收站、分享 | service/impl/*.java、consumer/*.java |
admin-ui/ | 文件浏览、上传(含分片)、分享、回收站 | src/pages/FileBrowserPage.tsx、src/api/* |
sql/ | 建库、建表、分片库、XXL-Job 表 | init.sql、init-shard.sql |
benchmark/ | 9 个 JMX、数据生成、报告 | README.md、scripts/run-all.sh |