元数据与控制面
元数据与控制面
object-metadata 不碰对象字节,它维护的是“有哪些 Bucket、每个 Bucket 里有哪些对象、谁在分享、什么进了回收站”。对象索引不是上传时同步写的,而是消费 object-storage 发出的事件补上的。所以这个服务的很多行为要放在“索引可能滞后”的前提下理解。
1. 控制面管什么
| 能力 | 入口 | 数据表 |
|---|---|---|
| 登录、当前用户、登出 | AuthController | user_info、Redis 黑名单 |
| Bucket 创建/列举/删除/HEAD | BucketController | bucket_info、object_info |
| ListObjectsV2 与 JSON 列表 | BucketController | object_info |
| 对象索引与 Bucket 用量 | ObjectCreatedConsumer、ObjectDeletedConsumer | object_info、bucket_info |
| 回收站 | RecycleController | object_info |
| 分享链接 | ShareController | share_link、object_info |
它同时是 XXL-Job 的执行器,挂着回收站清理任务。Outbox 重试任务挂在 object-storage。
2. 登录、JWT 与黑名单
登录只做一件事:按用户名取 user_info,用 bcrypt 比对密码,然后签发 HS256 的 JWT。
| 项 | 值 | 出处 |
|---|---|---|
| subject | user_info.id | AuthServiceImpl.login |
| 有效期 | 7 天 | 同上 |
| 密钥 | jwt.secret,长度不足 32 字节启动直接失败 | 构造函数里的 WeakKeyException |
| 密码存储 | bcrypt($2b$12$...) | sql/init.sql 的 admin 行 |
| 登出 | 按 token 剩余有效期写 jwt:blacklist:{token} | AuthServiceImpl.logout |
密码错误返回的是 403 AccessDenied,不是 401。401 留给网关的“没带 token / token 无效 / 已进黑名单”。
网关验签通过后把 X-User-Id 写进请求头,控制面直接读这个头,不再解析 token。/me 返回 user_info 里的 total_space 与 used_space,这两个字段没有任何写入路径会更新,实际一直是初始值 10 GB 与 0。
登出时如果 token 已经过期,remainingMillis <= 0,方法直接返回,不会浪费一条黑名单记录。token 解析失败则按 7 天写入,防止无效 token 被反复重放。
3. Bucket 生命周期
创建:
- 按
bucket_name + status=ACTIVE查重,存在就抛BucketAlreadyExists(409)。 region缺省us-east-1,storage_type缺省MINIO。owner_user_id取X-User-Id;为空时落成1。- 插入后删
buckets:list:{userId}缓存。
列举:
- 只查
status=ACTIVE;带了userId就再按owner_user_id过滤,按创建时间倒序分页。 - Controller 对每条记录再查两次
object_info(countByBucketId、sumSizeByBucketId),返回Name、CreationDate、ObjectCount、TotalSize、StorageType。每页 20 条就是 40 次附加查询。
删除:
- 先
headBucket确认存在。 countByBucketId统计NORMAL对象,大于 0 抛BucketNotEmpty(409)。- 把
status改成DELETED,不做物理删除。
删除 Bucket 不会清 bucket:storage:{bucketName} 这个 Redis 缓存。bucket_info 已经不是 ACTIVE,但缓存还能活 1 小时。在这段时间里,StorageBackendFactory 仍能解析出存储类型,对象读写不会因为 Bucket 被软删而立即失败。这是缓存优先于状态判断的直接结果。
headBucket 只按名称与状态查,不校验 owner_user_id。列举按 owner 过滤,但 HEAD/DELETE 不校验,两个接口的权限口径并不一致。
4. 对象索引:消费者怎么写行
ObjectCreatedConsumer 拿到 bucketName、objectKey、etag、size、md5Hash、contentType、userId 后:
- 按名称查
bucket_info;查不到只记 error 并返回,消息被确认,事件丢失。 - 按
bucket_id + object_key查object_info。 - 存在则更新 ETag、大小、类型、MD5、上传者;不存在则插入一行,状态
NORMAL。 - 计算
sizeDelta = 新大小 - 旧大小(新对象就是新大小),调updateUsedBytes做used_bytes = used_bytes + delta的原子更新。 - 删
object:info:{bucket}:{key}缓存。
ObjectDeletedConsumer 只做一件事:把对应行改成 RECYCLED。它不改 used_bytes,也不删缓存。used_bytes 因此只增不减,删对象后 Bucket 的“已用空间”仍包含它。
消费者带 @Transactional,UPSERT 与用量更新在同一个本地事务里;事件本身是至少一次投递,重复消费时 sizeDelta 会算成 0(新大小等于旧大小),不会重复累加。
事件里的 objectKey 带前导 /,写入 object_info.object_key 的也是这个形式。列表、删除、分享都按这个字符串匹配。
5. 分库与读写分离

ShardingSphereConfig 不是 YAML,而是 Java 里手写 DataSource:
| 数据源 | 库 | 角色 |
|---|---|---|
ds_master / ds_slave | cloud_disk | bucket_info、share_link、user_info、outbox_table |
ds0_master / ds0_slave | cloud_disk_0 | object_info 分片 0 |
ds1_master / ds1_slave | cloud_disk_1 | object_info 分片 1 |
规则有三条:
- 读写分离:
rw_default、rw_0、rw_1三组,写走 master,读按ROUND_ROBIN走 slave。 - 分片:
object_info的路由表达式是rw_$->{bucket_id % 2},分片键bucket_id。 - 其余表落在
rw_default。
由此带来两个必须知道的行为:
- 同一 Bucket 的列表是单库查询。
ListObjectsV2与 JSON 列表都先按名称查出bucket_id,再带着它查object_info,路由到单个分片。 - 跨 Bucket 的查询会广播。 回收站列表先查用户的所有 Bucket,再用
IN (bucketIds)查object_info;没有单一分片键,ShardingSphere 会发到两个库再合并。
读写分离的方向由 SQL 语义决定,不是由方法名决定。listBuckets 是读,走从库。如果主从复制还没追上,刚创建的 Bucket 可能不在列表里。CLAUDE.md 把这种现象记成“创建/登录成功但 list/head 返回 404 或空数据”,根因是复制初始化没完成或已断开。写操作走主库,所以插入本身不会失败。
6. 回收站
回收站不是独立的表,它是 object_info.status = 'RECYCLED' 的一个视图。
| 操作 | 方法 | 做了什么 |
|---|---|---|
| 列表 | listRecycled | 先查用户拥有的 Bucket,再按 status=RECYCLED 分页;bucketId 可选 |
| 恢复 | restoreObject | 把行状态改回 NORMAL,只此一步 |
| 永久删除 | permanentDelete | 校验 Bucket owner,调 object-storage 的 DELETE,再删行 |
| 清空 | emptyRecycleBin | 遍历用户所有 Bucket 下的 RECYCLED 行,逐个删文件、删行 |
| 过期清理 | cleanExpiredObjects | XXL-Job 每天 03:00,超过 30 天的分批处理 |
永久删除与清空都会调 object-storage 的 DELETE /{bucket}/{key}。这个接口本身会先删存储文件,再发 OBJECT_DELETED;消费者收到后会把行改成 RECYCLED,随后本方法再把行删掉。顺序上会有一次“刚删的行又被事件标记”的竞态,最终以行被删除为准。
cleanExpiredObjects 按 100 条一批循环:标记 DELETED → 调存储删除 → 删行。存储删除返回 4xx 时当作“文件已不存在”继续删行;其它异常 continue,这一条留到下一轮。
恢复只改状态。删除对象时 DeleteObject 已经调过 removeObject,存储里的字节不在了;恢复后的行指向一个不存在的对象,下载会 404。这条链路的实际语义与“30 天可恢复”不是一回事,细节见已知边界。
7. 分享链接
创建分享时:
- 按名称查 Bucket(不过滤 owner)。
- 生成 8 字节随机数,Base64URL 无填充,得到短码 token。
user_id直接取 Bucket 的owner_user_id,不是请求者。- 对象列表序列化成 JSON;密码非空则 bcrypt;有效期默认 1440 分钟;下载上限默认 0(不限)。
- 插入
share_link,状态ACTIVE。
访问分享:
POST /share/{token}/verify:查 token → 状态必须 ACTIVE → 过期则改成 EXPIRED → 有密码必须匹配 → 用一条带条件的UPDATE原子增加下载次数(max_downloads = 0 OR current_downloads < max_downloads),更新 0 行说明次数用完,标记 EXPIRED。GET /share/{token}/files:查 token、状态、过期时间,不校验密码,按objectKeys精确匹配NORMAL对象后返回 key/size/type/etag。GET /admin/shares:按user_id分页,按创建时间倒序。POST /admin/share/{id}/revoke:校验分享所属 Bucket 的 owner 与当前用户一致,状态改 REVOKED。
创建接口不校验请求者是不是 Bucket owner,撤销接口校验;这是两处不一致的口径。分享的密码只在 verify 里校验,而文件列表接口不校验,所以“有密码的分享”在列表层是公开的。
8. 缓存与失效
| Key | 谁写 | 谁删 |
|---|---|---|
buckets:list:{userId} | 无写入方 | createBucket |
object:info:{bucket}:{key} | 无写入方 | ObjectCreatedConsumer |
jwt:blacklist:{token} | logout | TTL 到期 |
前两个 key 的读写路径都不完整:只有失效,没有填充。改这部分代码时不要假设它们是有效缓存,否则会把“删了缓存”当成“数据已经刷新”。