Skip to content

Latest commit

 

History

History
822 lines (633 loc) · 44 KB

re.md

File metadata and controls

822 lines (633 loc) · 44 KB

re.md — CloudDrive 代码回顾与串联指南

面向:user / file 由你实现,storage 及部署、文档部分由 AI 生成,现在要整体回顾。 目标:不靠通读全部文件,而是掌握一套“从任意接口出发,把整条链路串到数据库/对象存储”的方法,并知道 AI 代码里哪些地方需要重点核对。

配套文档:README.md、docs/architecture.md、docs/upload-design.md、docs/consistency.md、docs/database.md、docs/security.md。


0. 怎么用这份文档

建议分三遍读,不要从 main.go 开始逐个文件向下翻:

遍数 目标 看什么
第一遍(30 分钟) 建立骨架 第 1、2、3 节:6 个进程、go-zero 分层、一条请求的通用路径
第二遍(2 小时) 串一条主链路 第 5 节挑“初始化上传 + 分片上传 + 完成上传”,按文件顺序跟到底
第三遍(按需) 回顾 storage 第 4.3 节 + 第 6 节 + 第 9 节复核清单

一个关键约定:

  • 契约文件(.api、.proto)和 logic / middleware / model 自定义方法 是手写的,要精读。
  • *_gen.go、*.pb.go、internal/types/types.go、*client/*.go、internal/server/*.go 是生成的,只在需要确认字段映射时查,不要通读。
  • routes.go 是 goctl 生成后手工改过的:路由以 routes.go 为准,不要只看 .api。

1. 先建立六个进程的心智模型

                         Client
                           │ HTTP + JWT
          ┌────────────────┼──────────────────┐
          ▼                ▼                  ▼
     user-api :8000   file-api :8001    storage-api :8002
     (账号)          (业务编排)        (数据面/字节流)
          │                │                  │
          │ gRPC           │ gRPC             │ gRPC(只做校验/记录)
          ▼                ▼                  ▼
     user.rpc :9000   file.rpc :9001    storage.rpc :9002
          │                │                  │
          ▼                ▼                  ▼
      users/quotas    folders/files/     upload_tasks/
      refresh_tokens  versions/shares    upload_parts/
                                          storage_objects
                                               │
                                               ▼
                                             MinIO
进程 入口 角色 是否直接访问 DB 关键配置
user-api user.go 注册/登录/令牌/用户/配额查询 否,全部走 user.rpc UserRpc、Limit
user.rpc user.go 账号、令牌、配额账本 是 Mysql、CacheRedis、Salt、JwtSecret
file-api file.go 文件业务编排 否,走 file.rpc + 跨服务 RPC 三个 RPC client、StorageApi、Internal、Share、Upload
file.rpc file.go 文件/目录/版本/分享元数据 是 Mysql、CacheRedis
storage-api storage.go 分片上传、对象下载(数据面) 否,只调 storage.rpc + MinIO Minio、Internal.Token、MaxChunkBytes
storage.rpc storage.go 上传任务状态机、对象元数据(控制面) 是 Mysql、CacheRedis、Minio、Maintenance

三条服务边界,记住这三句话就不会迷路:

  1. RPC 服务是数据的唯一属主:谁的表现在谁手里,跨服务只能走 RPC。
  2. file-api 是编排者:一次上传要跨 file/user/storage 三个服务,顺序与补偿集中在 file-api 的 logic 里。
  3. storage 拆成控制面 + 数据面:storage.rpc 管状态,storage-api 只搬字节(见 ADR-0002)。

2. go-zero 的分层:一条请求的 7 个落点

以任意一个 HTTP 接口为例,代码永远按这个顺序展开:

① 契约      service/<svc>/api/<svc>.api
② 路由      service/<svc>/api/internal/handler/routes.go
③ Handler   service/<svc>/api/internal/handler/xxxhandler.go
④ API logic service/<svc>/api/internal/logic/xxxlogic.go
⑤ RPC 调用   service/<svc>/api/internal/svc/servicecontext.go 里的 XxxRpc
⑥ RPC logic service/<svc>/rpc/internal/logic/xxxlogic.go
⑦ Model     service/<svc>/model/*.go → MySQL / Redis

外加两条横切线:

  • 中间件:internal/middleware/(鉴权、限流、内部令牌)
  • 公共能力:common/(JWT、密码、ctxdata、错误响应、指标、MinIO 封装)

2.1 生成代码 vs 手写代码

类型 文件 阅读价值
契约(手写) file.api、storage.api、user.api、*.proto ★★★★★ 先看这个
路由(生成后手改) internal/handler/routes.go ★★★★★ 实际路由以它为准
Handler(生成) internal/handler/*handler.go ★★★ 看参数解析和调用哪个 logic
API logic(手写) internal/logic/*logic.go ★★★★★ 业务编排
ServiceContext(手写) internal/svc/servicecontext.go ★★★★ 看依赖从哪来
RPC Server(生成) internal/server/*.go ★★ 只是分发到 logic
RPC logic(手写) internal/logic/*logic.go ★★★★★ 业务核心
类型(生成) types/types.go、types/**.pb.go ★ 字段对照时查
Client 封装(生成) *client/*.go ★★ 方法签名对照时查
Model(生成 + 手写) *_gen.go 生成;*model.go 手写扩展 ★★★★ 表和查询都在这里

注意:routes.go 顶部虽然写着 “Code generated by goctl. DO NOT EDIT.”,但这个项目为了分组挂中间件、手工注册流式接口,已经改过它。重新执行 goctl 会覆盖这些改动,回顾时不要把它当纯生成文件。


3. 通用请求链路与错误处理

3.1 HTTP 请求的一生

HTTP 请求
  → web.RequestID                       // 生成/透传 X-Request-Id
  → 路由级中间件
       ├─ AuthMiddleware                // Bearer token → user.rpc.ValidateToken
       ├─ RateLimitMiddleware           // user-api 登录/注册/刷新
       └─ InternalTokenMiddleware       // storage-api 内部下载
  → handler                             // httpx.Parse + NewXxxLogic
  → API logic                           // 取 userId、编排 RPC
  → zrpc client(etcd 服务发现)
  → RPC server → RPC logic
  → model → MySQL / Redis

相关文件:

3.2 错误是怎么变成 HTTP 响应的

RPC logic 返回 gRPC status → API logic 原样 return err → handler 调 httpx.ErrorCtx → web.ErrorHandler 映射:

gRPC code HTTP 响应 code
InvalidArgument / OutOfRange 400 invalid_argument / out_of_range
Unauthenticated 401 unauthenticated
PermissionDenied 403 permission_denied
NotFound 404 not_found
AlreadyExists / Aborted / FailedPrecondition 409 对应字符串
ResourceExhausted 429 resource_exhausted
Unavailable / DeadlineExceeded 503 / 504 对应字符串
非 gRPC error 400 invalid_argument(兜底不是 500)

两个容易踩的点:

  • 参数绑定/校验失败是普通 error,会被当作 400,而不是 500。
  • 如果 RPC logic 直接 return err 而没有 status.Error,也会被当成 400。

3.3 鉴权的分工

  • API 层不知道 JWT 密钥,只调 user.rpc.ValidateToken。
  • ValidateToken 做两件事:jwtx.Parse 验签 + 查 users 确认账号仍存在且 status=1。
  • 校验通过后把 userId 写入 context;业务 logic 第一行通常是 ctxdata.UserIdFromCtx(l.ctx)。

4. 三个服务分别怎么读

4.1 user 服务(你写的,快速对照)

先看契约和模型,再对着 RPC 方法表扫一遍即可。

RPC logic 文件 读/写表 关键点
Register registerlogic.go 读 users,写 users + user_quotas 事务;唯一索引兜底;裸 SQL 后必须 Invalidate 清负缓存
Login loginlogic.go 读 users,写 refresh_tokens scrypt 校验;access 15min,refresh 30 天
RefreshToken refreshtokenlogic.go 读写 refresh_tokens,读 users 轮换:先插新 token,再撤销旧的
Logout logoutlogic.go 读写 refresh_tokens 不传 refreshToken 时撤销全部设备
ValidateToken validatetokenlogic.go 读 users 每次请求查库,禁用立即生效
GetUser / GetQuota getuserlogic.go、getquotalogic.go users / user_quotas 走 go-zero 缓存
ReserveQuota reservequotalogic.go 写 user_quotas 条件原子 UPDATE:used + reserved + bytes <= total
CommitQuota commitquotalogic.go 写 user_quotas used += bytes, reserved -= bytes
ReleaseQuota releasequotalogic.go 写 user_quotas 取消上传时归还预占
ReleaseUsedQuota releaseusedquotalogic.go 写 user_quotas 删除文件时归还已用

配额是理解整个系统的钥匙:

上传初始化:reserved += size
上传完成:  used += size, reserved -= size
取消上传:  reserved -= size
删除文件:  used -= releasedBytes

不变式 used + reserved <= total 由 userquotasmodel.go 里的条件 UPDATE 保证,不靠应用层判断。

4.2 file 服务(你写的,重点看编排)

file-api 的路由以 routes.go 为准:

  • 需登录组:文件/目录/版本/分享管理/上传编排。
  • 下载组:GET /v1/files/:fileId/content,单独 rest.WithTimeout(0)。
  • 公开组:POST /v1/shares/:token/access、GET /v1/shares/:token/content。

file-api 的 logic 风格要分清两类:

类型 例子 职责
薄透传 listfileslogic.go、renamefilelogic.go 取 userId → 调 file.rpc → 映射字段
编排 inituploadlogic.go、completeuploadlogic.go、deletefilelogic.go 调多个服务 + 失败补偿

file.rpc 的 RPC 方法表:

RPC logic 读/写表 说明
CreateFile createfilelogic.go folders、files 幂等键 (owner_id, request_id);version=0、status=uploading
GetFile getfilelogic.go files owner 不符或已删除返回 404
UpdateFileStatus updatefilestatuslogic.go files 禁止直接改成 available
ListFiles listfileslogic.go folders、files 目录全量 + 文件分页,total 是两者之和
CreateFolder createfolderlogic.go folders 父目录归属 + 重名校验
RenameFile renamefilelogic.go files / folders 先按文件查,再按目录查
MoveFile movefilelogic.go files / folders 环检测最多 64 层
DeleteFile deletefilelogic.go files、file_versions、shares 软删 + 撤销分享 + 汇总待删对象
DeleteFolder deletefolderlogic.go folders、files、file_versions、shares BFS 递归,批量软删
CreateShare createsharelogic.go files、shares token 只存 SHA-256;密码 bcrypt
ListShares listshareslogic.go shares、files 每条分享单独查文件名(N+1)
RevokeShare revokesharelogic.go shares 幂等
AccessShare accesssharelogic.go shares、files 校验 status/过期/次数/密码,一条 UPDATE 完成计数
AddVersion addversionlogic.go files、file_versions 事务 + FOR UPDATE + (file_id, request_id) 幂等
ListVersions listversionslogic.go files、file_versions 按版本倒序
RestoreVersion restoreversionlogic.go files、file_versions 回滚 = 追加新版本,不改历史

model 层的关键自定义方法:

  • fileversionsmodel.go 的 AppendVersion:唯一能把文件置为 available 的地方,事务内同时写版本行和更新 files 指针。
  • filesmodel.go / foldersmodel.go 的 MarkDeleted:批量软删并失效缓存。
  • sharesmodel.go 的 IncrementAccess:校验与计数在同一条 SQL 完成,防并发超发。

4.3 storage 服务(AI 生成,重点回顾)

先记住“控制面 / 数据面”这张表

能力 进程 入口 是否碰 MinIO 是否碰 DB
创建上传任务 storage.rpc InitUpload 否 是
校验任务/分片号 storage.rpc GetUploadTask 否 是
记录分片 storage.rpc RecordPart 否 是
合并、校验、落对象 storage.rpc CompleteUpload 是 是
取消任务 storage.rpc AbortUpload 是(删临时分片) 是
删除对象 storage.rpc DeleteObject 是 是
写分片字节 storage-api PUT /v1/uploads/:id/parts/:n 是 否
读对象字节 storage-api GET /internal/v1/storage/objects/content 是 否

storage-api 启动与路由

实际路由:

方法/路径 Handler 中间件 下游
GET /healthz HealthHandler 无 进程存活
GET /readyz ReadyHandler 无 Store.Ping
GET /v1/uploads/:uploadId GetUploadProgressHandler Auth StorageRpc.GetUploadTask
DELETE /v1/uploads/:uploadId AbortUploadHandler Auth StorageRpc.AbortUpload
PUT /v1/uploads/:uploadId/parts/:partNumber UploadPartHandler(手写) Auth + 无超时 + MaxBytes GetUploadTask → MinIO → RecordPart
GET /internal/v1/storage/objects/content DownloadObjectHandler(手写) 内部令牌 + 无超时 Store.Stat / OpenRange

为什么这两个接口不写在 storage.api 里:原始字节流和 http.ResponseWriter 需要手写,goctl 的 JSON 绑定不适用。

storage-rpc 启动与 RPC 映射

RPC logic 读写表 MinIO 操作
InitUpload inituploadlogic.go upload_tasks 无
GetUploadTask getuploadtasklogic.go upload_tasks、upload_parts 无
RecordPart recordpartlogic.go upload_parts(upsert)、upload_tasks 无
CompleteUpload completeuploadlogic.go upload_tasks、upload_parts、storage_objects Copy / Compose / Stat / VerifySHA256 / Remove
AbortUpload abortuploadlogic.go upload_tasks、upload_parts 删除临时分片
DeleteObject deleteobjectlogic.go storage_objects Remove
GetObjectInfo getobjectinfologic.go storage_objects 无
CheckObject checkobjectlogic.go 不读写表 Stat / SHA256

数据面细节(dataplane.go)

UploadPartHandler 的校验顺序值得单独记:

  1. 从 context 取 userId。
  2. 解析 uploadId、partNumber。
  3. StorageRpc.GetUploadTask 校验归属、状态、是否过期。
  4. 校验 partNumber <= totalChunks。
  5. 计算该分片的精确大小(非末片 = chunkSize,末片 = 剩余)。
  6. 校验不超过 MaxChunkBytes。
  7. objkey.Part 生成临时对象 Key。
  8. Store.PutStream 流式写 MinIO,同时算 SHA-256,并校验实际字节数。
  9. 多发字节检查。
  10. StorageRpc.RecordPart 写元数据;失败则尽力删除刚写的对象。

DownloadObjectHandler:

  1. 内部令牌中间件通过后才进入。
  2. objectKey 来自查询参数(由 file-api 传入)。
  3. Store.Stat 判断存在。
  4. 设置 Content-Type、Accept-Ranges、Content-Disposition。
  5. parseRange 只支持单段 Range;非法返回 416。
  6. Store.OpenRange + 64 KiB 缓冲流式转发。

后台任务(maintenance.go)

service/storage/rpc/internal/jobs/maintenance.go 每 Interval 秒跑一次:

步骤 做什么
expireUploads 把过期 initiated/uploading 任务置 failed,删临时分片
recoverStuckCompleting 停留超过 15 分钟的 completing 放回 uploading
retryObjectDeletes 重试 status=deleting 的对象删除
cleanupOrphanParts 清理 48 小时前的 parts/ 孤儿对象
refreshGauges 刷新活跃上传任务数、GC 积压指标

MinIO 封装与对象 Key

  • common/objectstore/objectstore.go:PutStream、Copy、Compose、OpenRange、Stat、VerifySHA256、Remove、List。
  • common/objkey/objkey.go:
    • 最终对象:u/{userId}/{uploadId}{ext}
    • 分片对象:parts/{uploadId}/{partNumber:%05d}
    • 扩展名只保留安全字符,长度上限 16。
  • 为什么单拆一个包:控制面和数据面必须拼出完全一致的 Key,规则只能有一个来源。

5. 八条主链路:把代码串起来

下面每条链路都按“HTTP → handler → API logic → RPC → RPC logic → model”列出文件。跟着任意一条走一遍,就掌握了整套代码的阅读方法。

5.1 注册

POST /v1/users/register
→ user-api routes.go(限流中间件)
→ handler/registerhandler.go
→ logic/registerlogic.go(只透传)
→ userclient.Register
→ user.rpc server/userserver.go
→ rpc/logic/registerlogic.go
   ├─ 预检查 users(username/email)
   ├─ cryptx.PasswordEncrypt(salt, password)
   ├─ 事务:INSERT users + INSERT user_quotas(10GiB)
   └─ UsersModel.Invalidate(清负缓存)

相关文件:service/user/api/user.api、routes.go、registerlogic.go、usersmodel.go。

5.2 登录与后续鉴权

POST /v1/users/login
→ loginlogic.go(API)→ user.rpc Login
   ├─ FindOneByUsername
   ├─ constant-time 比较 password hash
   ├─ jwtx.Generate(HS256,15 分钟)
   └─ 插入 refresh_tokens(只存 SHA-256)

任意受保护接口
→ AuthMiddleware
→ user.rpc.ValidateToken
   ├─ jwtx.Parse
   └─ users.FindOne 确认 status=1
→ ctxdata.WithUserId

相关文件:authmiddleware.go、validatetokenlogic.go、common/jwtx/jwt.go。

5.3 初始化上传(最典型的跨服务编排)

POST /v1/uploads(file-api)
→ inituploadlogic.go
   1. normalizeRequestId(idempotencyKey)  // 空则生成 UUID
   2. FileRpc.CreateFile
        → file.rpc createfilelogic.go
          写 files:version=0, status=uploading, request_id=幂等键
   3. 首次创建(!Existed)才 ReserveQuota
        → user.rpc reservequotalogic.go
          UPDATE user_quotas SET reserved += size WHERE used+reserved+size <= total
   4. StorageRpc.InitUpload(uploadId = requestId)
        → storage.rpc inituploadlogic.go
          写 upload_tasks:chunk_size=8MiB, total_chunks, object_key, expires_at

补偿顺序:

CreateFile 失败            → 直接返回
ReserveQuota 失败          → files.status = failed
InitUpload 失败            → ReleaseQuota + files.status = failed

相关文件:inituploadlogic.go、quota.go、createfilelogic.go、storage/inituploadlogic.go。

5.4 分片上传(客户端直连 storage-api)

PUT http://storage-api:8002/v1/uploads/{uploadId}/parts/{n}
→ storage-api dataplane.go UploadPartHandler
   1. GetUploadTask(归属/状态/分片号)
   2. objkey.Part(uploadId, n)
   3. Store.PutStream → MinIO PutObject + SHA-256 + 字节数校验
   4. 多发字节检查
   5. StorageRpc.RecordPart
        → storage.rpc recordpartlogic.go
          upsert upload_parts:(upload_id, part_number) 唯一
          更新 upload_tasks:uploaded_chunks / uploaded_bytes / status=uploading

断点续传:

GET /v1/uploads/:id(file-api 或 storage-api)
→ StorageRpc.GetUploadTask
→ 返回 parts + missingParts

相关文件:dataplane.go、recordpartlogic.go、getuploadtasklogic.go、getuploadprogresslogic.go。

5.5 完成上传(幂等链最长的一条)

POST /v1/uploads/:id/complete(file-api)
→ completeuploadlogic.go
   1. StorageRpc.CompleteUpload
        → storage.rpc completeuploadlogic.go
          ├─ 已 completed:直接返回(幂等)
          ├─ ClaimForComplete:uploading → completing(只有一个赢家)
          ├─ validateParts:数量、连续性、每片大小、总大小
          ├─ 单片 Copy / 多片 Compose
          ├─ Stat 校验大小
          ├─ 可选 VerifySHA256
          ├─ upsert storage_objects(status=available)
          ├─ 删除临时分片对象
          └─ upload_tasks.status = completed
   2. FileRpc.GetFile(拿 content type)
   3. FileRpc.AddVersion(幂等键 = uploadId)
        → file.rpc addversionlogic.go
          → fileversionsmodel.go AppendVersion
            事务:FOR UPDATE files → 插入 file_versions → 更新 files 指针
   4. 仅 versionResp.Changed == true 时 CommitQuota
        → user.rpc:used += size, reserved -= size

幂等键对照:

步骤 幂等键 唯一索引
CreateFile (owner_id, request_id) uk_files_owner_request
InitUpload upload_id uk_upload_tasks_upload_id
RecordPart (upload_id, part_number) uk_upload_parts_upload_part
CompleteUpload upload_id + ClaimForComplete 条件 UPDATE
AddVersion (file_id, request_id) uk_file_versions_file_request
CommitQuota 依赖 AddVersion.Changed —

相关文件:completeuploadlogic.go(file-api)、completeuploadlogic.go(storage)、addversionlogic.go、fileversionsmodel.go。

5.6 下载

GET /v1/files/:fileId/content(file-api)
→ handler/download.go DownloadFileHandler
   1. FileRpc.GetFile(owner + 未删除 + status=available)
   2. proxyObject:
      GET {StorageBase}/internal/v1/storage/objects/content?objectKey=...&filename=...
      Header: X-Internal-Token
      转发 Range
   3. storage-api InternalTokenMiddleware
   4. DownloadObjectHandler:Stat → parseRange → OpenRange
   5. file-api 把上游 200/206 和头部原样转回客户端

关键设计:

  • 客户端永远拿不到 objectKey。
  • 内部下载只认 X-Internal-Token;INTERNAL_TOKEN 为空时拒绝所有请求。
  • file-api 和 storage-api 的下载路由都 rest.WithTimeout(0),否则 http.TimeoutHandler 会缓冲整个响应体。

相关文件:download.go、getfilelogic.go、internaltoken.go、dataplane.go。

5.7 删除文件 / 文件夹

DELETE /v1/files/:fileId
→ deletefilelogic.go(API)
   → FileRpc.DeleteFile
      → file.rpc deletefilelogic.go
         ├─ 已删除:changed=false(幂等)
         ├─ VersionsModel.FindByFileId
         ├─ collectObjects:当前对象 + 所有版本对象,按 object_key 去重
         ├─ SharesModel.RevokeByFile
         └─ FilesModel.MarkDeleted(deleted_at + status=deleting)
   → cleanupObjects:逐个 StorageRpc.DeleteObject(失败只记日志)
   → ReleaseUsedQuota(失败只记日志)

目录删除把 BFS 换成递归收集,再批量 MarkDeleted;其余步骤相同。

为什么这个顺序:先让数据库不可见,再删对象、还配额。外部副作用(MinIO)失败可以由 GC 和对账兜底,但如果先删对象再软删,失败窗口里文件会“看得见、下不到”。

相关文件:deletefilelogic.go(API)、deletefilelogic.go(RPC)、deletefolderlogic.go、storage/deleteobjectlogic.go。

5.8 分享与版本回滚

分享:

POST /v1/shares(需登录)
→ FileRpc.CreateShare
   token = 32 字节随机数,只存 SHA-256
   可选 bcrypt 密码、expires_at、max_access_count

POST /v1/shares/:token/access(公开)
→ FileRpc.AccessShare
   校验 status / 过期 / 次数 / 密码
   IncrementAccess 一条条件 UPDATE 完成“校验 + 计数”

GET /v1/shares/:token/content(公开)
→ AccessShare → 代理到 storage-api

版本回滚:

POST /v1/files/:fileId/versions/:version/restore
→ FileRpc.RestoreVersion
   ├─ 找到目标版本
   ├─ 已是当前内容:changed=false
   └─ 否则 AppendVersion:把旧版本内容作为新版本追加

回滚不修改历史行,也不动配额:对象一直都在,只是 files 指针换了目标。


6. 数据模型与状态机

三份 schema 在同一个 MySQL 库,但服务之间不 JOIN、不建外键:

6.1 表的主线

服务 表 一句话
user users 唯一索引保证并发注册正确性
user user_quotas used + reserved <= total 由原子 UPDATE 维持
user refresh_tokens 只存 SHA-256,撤销即 revoked_at
file folders 树结构,parent_id=0 是根
file files 当前版本指针 + 上传状态
file file_versions 只追加的版本历史
file shares token 摘要 + 访问计数
storage upload_tasks 上传状态机的唯一来源
storage upload_parts (upload_id, part_number) 唯一,重传幂等
storage storage_objects 对象元数据;非 available 视为不存在

6.2 两个关键状态机

upload_tasks:
  initiated ──首片 RecordPart──> uploading
  uploading ──ClaimForComplete──> completing
  completing ──成功──> completed
  completing ──失败──> failed
  initiated/uploading ──Abort──> aborted
  initiated/uploading ──过期──> failed(维护任务)

files:
  uploading ──AddVersion──> available
  uploading ──失败补偿──> failed
  available ──Delete──> deleting(同时写 deleted_at)

规则:只有 AddVersion 能把文件置为 available。UpdateFileStatus 明确禁止直接改成 available,这是为了保证版本行和文件指针在同一事务里更新。

6.3 缓存前缀

前缀 内容
cache:users:id: / username: / email: 用户
cache:userQuotas:userId: 配额
cache:refreshTokens:tokenHash: 刷新令牌
cache:files:id: / ownerId:requestId: 文件
cache:folders:id: 目录
cache:fileVersions:... 版本
cache:shares:id: / tokenHash: 分享

列表类查询统一走 QueryRowsNoCacheCtx,避免分页缓存键爆炸。


7. 公共基础设施

包 作用 关键函数
common/jwtx JWT 签发/解析 Generate、Parse
common/cryptx scrypt 密码哈希 PasswordEncrypt
common/ctxdata context 传 userId WithUserId、UserIdFromCtx
common/web 请求 ID、统一错误、日志 RequestID、Setup、ErrorHandler
common/metrics 业务指标 上传/下载字节、配额拒绝、GC 积压
common/objectstore MinIO 封装 PutStream、Compose、OpenRange
common/objkey 对象 Key 规则 Object、Part、SafeExt
common/ratelimit 进程内令牌桶 New、Allow

部署侧:


8. 跑起来与验收

8.1 全容器

cp .env.example .env
docker compose up -d --build
docker compose ps
go run ./scripts/e2e

8.2 本地服务 + 容器基础设施

docker compose up -d mysql redis etcd minio

go run ./service/user/rpc    -f service/user/rpc/etc/user.yaml
go run ./service/file/rpc    -f service/file/rpc/etc/file.yaml
go run ./service/storage/rpc -f service/storage/rpc/etc/storage.yaml
go run ./service/user/api    -f service/user/api/etc/user-api.yaml
go run ./service/storage/api -f service/storage/api/etc/storage-api.yaml
go run ./service/file/api    -f service/file/api/etc/file-api.yaml

注意:本地配置里的 RPC ListenOn 是 127.0.0.1,容器里是 0.0.0.0;etcd 注册的地址必须对调用方可达,不要混用两套。

8.3 e2e 脚本就是功能清单

scripts/e2e/main.go 按顺序验证:

  1. 健康检查
  2. 注册 / 重复注册 / 登录 / 无 token / 错密码
  3. 建目录 / 重名
  4. 初始化上传 / 幂等 / 分片 / 错误分片大小 / 进度 / 完成 / 重复完成
  5. 下载 + SHA-256 校验 + Range
  6. 版本列表 + 回滚
  7. 分享密码 / 次数 / 撤销
  8. 越权(bob 访问 alice)
  9. 删除 + 配额归还
  10. 目录递归删除

想确认某个行为时,先看 e2e 里对应的断言,比翻文档快。


9. AI 代码重点复核清单

以下是回顾 storage 及跨服务代码时,已对照源码确认的问题或待确认设计。建议按严重程度逐条决定“修 / 接受并写进文档”。

高优先级

  1. CompleteUpload 失败后无法重试,与注释和文档矛盾

    • 位置:completeuploadlogic.go:56-66
    • 函数头注释写“中途失败把任务置为 failed,重复调用会重新走一遍(合并是幂等的覆盖写)”,但 switch 里 case "failed" 直接返回 FailedPrecondition。
    • 结果:合并失败一次后任务永久不可重试;只有 completing 卡住被维护任务放回 uploading 才可能继续。
    • 需要决定:是改成允许 failed 重试,还是把注释和文档改成“失败即终态”。
  2. 过期上传的预占配额没有归还

    • 位置:abortuploadlogic.go:59、maintenance.go:129
    • storage.rpc 的 expireUploads 只改任务状态、删分片,不知道配额;file-api 的取消逻辑只在状态为 initiated/uploading 时归还,而 GetUploadTask 会把过期任务返回成 "expired"。
    • 结果:用户上传中断且不主动取消时,reserved_bytes 会一直泄漏。
    • 需要补:过期任务的对账/归还机制,或在 file-api 增加定时清理。

中优先级

  1. Store.Copy 的 contentType 参数未使用

    • 位置:objectstore.go:193
    • 单片上传走 CopyObject,多片走 ComposeObject,都没有设置目标 Content-Type;临时分片固定写 application/octet-stream。
    • 对外下载时 file-api 用文件元数据覆盖了响应头,所以用户通常感知不到,但 MinIO 里对象的 Content-Type 可能不对。
  2. 完成上传后不清理 upload_parts 行

    • 位置:completeuploadlogic.go:153-158
    • 只删了 MinIO 临时对象,没有 PartsModel.DeleteByUploadId。成功上传越多,upload_parts 越大。
    • 若保留是为了可查询进度,需要在文档里说明;否则应清理或归档。
  3. InitUpload 对已存在任务不看状态

    • 位置:inituploadlogic.go:39-45
    • 只要 upload_id 存在且属于同一用户,就直接返回旧任务,不管它是 aborted、failed 还是 completed。
    • 结合 file-api 用 idempotencyKey 当 uploadId 的约定:客户端用同一个 key 重传,会拿到旧任务,可能无法重新开始。需要确认这是期望的幂等语义。
  4. 内部下载接口不校验 storage_objects.status

    • 位置:dataplane.go 的 DownloadObjectHandler
    • 只 Stat MinIO,不看数据库状态。授权完全依赖 file-api;只要拿到内部令牌和 objectKey,就能读到 MinIO 中仍存在的对象。
    • 需要确认是否可接受,或在 storage 侧增加一次 GetObjectInfo 校验。
  5. 重名校验是应用层 SELECT count(*),没有唯一索引兜底

    • 位置:helpers.go:90
    • folders / files 都没有 (owner_id, parent_id, name) 唯一索引,并发创建/改名存在竞争窗口。

低优先级 / 设计确认

  1. objkey 不校验 uploadId 字符集

    • 位置:objkey.go
    • uploadId 直接拼进对象 Key。正常路径由 file-api 的 normalizeRequestId 限制为 [A-Za-z0-9._-]{8,64},但 storage.rpc 作为内部服务没有防御性校验。
  2. Store.Get 的 Range 参数有边界缺陷

    • 位置:objectstore.go:252-259
    • offset > 0 && length <= 0 会算出 end = offset-1,产生非法 Range。当前没有调用方使用这种组合,OpenRange 是正确实现。
  3. WithMaxBytes 依赖 MaxChunkBytes 配置非零

    • 位置:storage-api routes.go:59
    • 使用 MaxChunkBytes + 1;若配置缺失(值为 0),上限会变成 1 字节。Config 结构体没有默认值兜底。
  4. 后台任务多副本没有互斥

    • 位置:maintenance.go
    • 注释说可重入,但没有 leader 选举或数据库锁;多副本会同时执行,操作基本幂等,但会产生重复日志和外部请求。
  5. GetObjectInfo / CheckObject 没有业务调用方

    • 目前 tools/reconcile 直接使用 objectstore.Store + 原始 SQL,不经过这两个 RPC。若后续没有计划,考虑是否保留。
  6. RevokeByFile 缓存失效最多覆盖 1000 条分享

    • 位置:sharesmodel.go:89
    • FindByOwner(ownerId, 0, 1000) 收集缓存 key;分享数超过 1000 的用户可能有缓存未失效窗口。
  7. ListShares 存在 N+1 查询

    • 每条分享单独 FilesModel.FindOne 取文件名。分享数量大时考虑批量查询。
  8. 部分状态枚举未被实现

    • upload_parts.status=0 从未使用;storage_objects.status 的 uploading/failed 未使用;files.status 的 pending/processing 基本未用。
    • 文档里的状态表比实现宽,回顾时以代码实际写入值为准。
  9. user 服务的少量错误码细节

    • GetUser / GetQuota 在记录不存在时直接返回 model.ErrNotFound,没有转成 codes.NotFound,经统一错误处理会变成 HTTP 400 而不是 404。
    • 影响不大,但属于“文档说 404、实际 400”的偏差。

10. 推荐的回顾顺序(可执行)

第一遍:骨架(约 30 分钟)

  1. 看第 1 节的进程表和图,记住 6 个进程与 3 个数据属主。
  2. 打开 file/api/file.go 和 routes.go,确认启动顺序和路由分组。
  3. 打开一个最简单的 handler + logic(推荐 ListFiles),确认 7 个落点。
  4. 看 common/web/errorhandler.go,理解错误如何映射。

第二遍:串主链路(约 2 小时)

按这个顺序跟代码,每一步都打开对应文件:

  1. 初始化上传:inituploadlogic.go → createfilelogic.go → quota.go → storage/inituploadlogic.go
  2. 分片上传:storage/api/dataplane.go → recordpartlogic.go
  3. 完成上传:file/completeuploadlogic.go → storage/completeuploadlogic.go → addversionlogic.go → fileversionsmodel.go → commitquotalogic.go
  4. 下载:file/api/download.go → getfilelogic.go → storage/api/dataplane.go
  5. 删除:deletefilelogic.go(两个)→ filesmodel.go → storage/deleteobjectlogic.go

每跟完一条,回到第 5 节对照一遍,确认自己没有漏掉“补偿”或“幂等”分支。

第三遍:storage 深挖(按需)

  1. storage.proto → 逐个 logic,重点 CompleteUpload、AbortUpload、RecordPart。
  2. maintenance.go:理解每个清理任务的前置条件。
  3. objectstore.go + objkey.go:确认流式语义和 Key 规则。
  4. 对照第 9 节清单,逐条做“修 / 接受 / 补文档”的决定。

第四遍:横向校验


11. 速查:按问题找文件

我想知道… 去哪看
某个 HTTP 接口存在吗 file.api、user.api、storage.api
实际注册了哪些路由、挂了什么中间件 各服务的 internal/handler/routes.go
这个接口做了什么 对应 internal/logic/*logic.go
这个服务依赖谁 internal/svc/servicecontext.go + etc/*.yaml
表和字段 model/*.sql + model/*_gen.go
自定义查询 model/*model.go(非 _gen)
跨服务调用了谁 grep Rpc. 或 client
错误码为什么是 4xx/5xx common/web/errorhandler.go
对象 Key 怎么来的 common/objkey/objkey.go
MinIO 怎么读写 common/objectstore/objectstore.go
上传状态机 storage.sql + docs/upload-design.md
幂等/补偿设计 docs/consistency.md + 第 5 节
怎么跑验收 scripts/e2e/main.go + 第 8 节
AI 代码哪里要复查 第 9 节

12. 最后:一个可以练手的检查方法

随便挑一个接口,回答下面 6 个问题;答不上来的那一步,就是下次要读的文件:

  1. 契约在哪?路由在哪注册?挂了哪些中间件?
  2. handler 解析了哪些参数?调用了哪个 logic?
  3. API logic 取了 userId 吗?调了哪几个 RPC?失败时补偿是什么?
  4. RPC logic 做了哪些校验?读写哪几张表?幂等键是什么?
  5. 数据库索引/状态机能否支撑这个操作?并发下会不会出错?
  6. 出错时返回什么 code?会不会留下孤儿对象或错误配额?

用这个模板走一遍“初始化上传 → 分片 → 完成 → 下载 → 删除”,整个项目就串起来了。