导读
2026/11/4约 1267 字大约 4 分钟
导读
这一栏是一套「S3 兼容对象存储服务」的设计文档。项目是 Java 21 + Spring Cloud Alibaba 的微服务:gateway 统一入口,object-storage 管对象字节,object-metadata 管 MySQL 里的索引,admin-ui 是 React 管理台;对象与索引之间用 Outbox + RabbitMQ 做最终一致。
规模:89 个 Java 文件,3 个业务服务,18 个 compose service(16 常驻 + 2 一次性),57 个 @Test,9 个 JMeter 场景。它能做的事与做不到的事都写在代码里,文档按代码写,与 README 冲突处以代码为准。
阅读顺序
- 架构总览 —— 三个进程、两条链路、数据落在哪、十项关键决定与代价。
- 存储数据面 —— 上传与秒传、下载 302、预签名双客户端、分片五步、三种后端、Redis 键与失败路径。
- 元数据与控制面 —— 登录与黑名单、Bucket 生命周期、索引消费、ShardingSphere 分库读写分离、回收站、分享。
- 事件与一致性 —— Outbox 的写入与投递顺序、消费幂等、对象状态机、定时补偿,以及没有收敛的几处不一致。
- 网关与鉴权 —— 路由表与匹配顺序、JWT、全链路非阻塞、Sentinel 热更新、认证与授权的边界。
- 部署与运维 —— 18 个服务与端口、启动依赖链、内存预算、配置来源、主从与 Cluster 初始化、故障排查、双机部署。
- 基准测试与性能 —— 9 个场景、尖峰从 32.61% 错误到 0、JTL 复算方法、这些数字不能证明什么。
- 已知边界 —— 授权、回收站、分享、列表分页、计量、事务、后端限制,逐条给改动入口。
简历主线与对应模块
| 简历关键词 | 对应模块 | 先看 |
|---|---|---|
| 数据面/控制面分离 + Outbox | 三个服务的分工与事件流 | 架构总览、事件与一致性 |
| 全链路非阻塞 Gateway | AuthFilter + RedissonReactiveClient | 网关与鉴权 |
| 多存储后端(策略模式) | StorageBackend + StorageBackendFactory | 存储数据面 |
| 秒传与分片上传 | ObjectServiceImpl、MultipartUploadServiceImpl | 存储数据面 |
| ShardingSphere 分库 + 读写分离 | ShardingSphereConfig(Java 手写) | 元数据与控制面 |
| Redis Cluster 热 key 打散 | HotKeyUtil、3 副本 HashTag | 存储数据面 |
| JMeter 压测与调优 | 9 个 JMX 与 JTL | 基准测试与性能 |
关键数字
| 数字 | 含义 | 出处 |
|---|---|---|
| 18 / 16 / 2 | compose service 总数 / 常驻 / 一次性 | docker-compose.yml |
| 3 | 业务服务数 | gateway、object-storage、object-metadata |
| 57 / 6 | @Test 数 / 测试类数 | */src/test/java |
| 42 | 冒烟测试的 HTTP 采样步数 | benchmark/reports/20260523-170807/00-smoke.jtl |
| 9,739 / 0 | 尖峰测试请求数 / 错误数 | benchmark/reports/20260517-024732/08-spike.jtl |
| 32.61% | 修复前的尖峰错误率 | benchmark/reports/20260517-013304/08-spike.jtl |
| 2–6 ms | 尖峰前与恢复后的 P50 | 同上两份 JTL,按 label 复算 |
| 5.6 GB | 全部容器内存限制之和 | docker-compose.yml |
| 365 天 | 秒传缓存 TTL | RedisKeyConstants.UPLOAD_HASH_TTL_DAYS |
| 24 小时 | 分片会话 TTL | RedisKeyConstants.UPLOAD_EXPIRE_HOURS |
| 30 天 | 回收站保留天数 | BusinessConstants.RECYCLE_RETENTION_DAYS |
| 1440 分钟 | 分享默认有效期 | BusinessConstants.DEFAULT_SHARE_EXPIRE_MINUTES |
| 1000 | ListObjectsV2 默认 max-keys | BusinessConstants.DEFAULT_MAX_KEYS |
| 100 | Outbox 重试与回收站清理的批大小 | OutboxRetryService.BATCH_SIZE、cleanExpiredObjects |
几条先知道的结论
- 下载默认返回 302,不是网关转发字节;本地与 OSS 后端不支持预签名时自动回退代理。
- 上传接口返回时,对象列表里不一定已经有这个对象;索引是异步补的。
- 回收站恢复只恢复
object_info的状态,删除时字节已经被移除。 - 任何登录用户知道 Bucket 名就能读写;对象级授权没有实现。
- 业务服务没有 Actuator,健康检查只能看容器状态与登录接口。
- 分片状态只在 Redis,
multipart_upload表建了但没读写。
这些结论在对应篇目里有代码位置与边界条件;要改的话,已知边界 的最后一节按代价排了顺序。
与项目仓库现有文档的关系
项目仓库里已有 docs/architecture.md、deployment.md、development.md、interview-prep.md、nacos-config.md。这一栏没有搬运它们的章节,只把事实重新按代码核对了一遍;与代码冲突的地方以代码为准,冲突清单收在已知边界。
性能数字只有尖峰那一组能在提交的 JTL 里复算;其余场景的 JTL 是修复前的失败运行,不能当读数,基准测试与性能里写明了原因。