面向:user / file 由你实现,storage 及部署、文档部分由 AI 生成,现在要整体回顾。 目标:不靠通读全部文件,而是掌握一套“从任意接口出发,把整条链路串到数据库/对象存储”的方法,并知道 AI 代码里哪些地方需要重点核对。
配套文档:README.md、docs/architecture.md、docs/upload-design.md、docs/consistency.md、docs/database.md、docs/security.md。
建议分三遍读,不要从 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。
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 |
三条服务边界,记住这三句话就不会迷路:
- RPC 服务是数据的唯一属主:谁的表现在谁手里,跨服务只能走 RPC。
- file-api 是编排者:一次上传要跨 file/user/storage 三个服务,顺序与补偿集中在 file-api 的 logic 里。
- storage 拆成控制面 + 数据面:
storage.rpc管状态,storage-api只搬字节(见 ADR-0002)。
以任意一个 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 封装)
| 类型 | 文件 | 阅读价值 |
|---|---|---|
| 契约(手写) | 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 会覆盖这些改动,回顾时不要把它当纯生成文件。
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
相关文件:
- 请求 ID:common/web/context.go
- 统一错误:common/web/errorhandler.go
- 鉴权中间件示例:service/file/api/internal/middleware/authmiddleware.go
- userId 在 context 里的传递:common/ctxdata/ctxdata.go
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。
- API 层不知道 JWT 密钥,只调
user.rpc.ValidateToken。 ValidateToken做两件事:jwtx.Parse验签 + 查users确认账号仍存在且status=1。- 校验通过后把
userId写入 context;业务 logic 第一行通常是ctxdata.UserIdFromCtx(l.ctx)。
先看契约和模型,再对着 RPC 方法表扫一遍即可。
- 契约:service/user/api/user.api、service/user/rpc/user.proto
- 路由:service/user/api/internal/handler/routes.go(健康检查 / 限流组 / 鉴权组)
- 表结构:service/user/model/user.sql
| 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 保证,不靠应用层判断。
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 完成,防并发超发。
| 能力 | 进程 | 入口 | 是否碰 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 |
是 | 否 |
- 入口:service/storage/api/storage.go
- 配置:config.go + storage-api.yaml
- 路由:routes.go
- 数据面实现:dataplane.go
实际路由:
| 方法/路径 | 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 绑定不适用。
- 入口:service/storage/rpc/storage.go
- 配置:config.go + storage.yaml
- 契约:storage.proto
- 启动后台任务:
Maintenance开启时jobs.NewMaintenance(svcCtx).Start(ctx)
| 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 |
UploadPartHandler 的校验顺序值得单独记:
- 从 context 取 userId。
- 解析
uploadId、partNumber。 StorageRpc.GetUploadTask校验归属、状态、是否过期。- 校验
partNumber <= totalChunks。 - 计算该分片的精确大小(非末片 = chunkSize,末片 = 剩余)。
- 校验不超过
MaxChunkBytes。 objkey.Part生成临时对象 Key。Store.PutStream流式写 MinIO,同时算 SHA-256,并校验实际字节数。- 多发字节检查。
StorageRpc.RecordPart写元数据;失败则尽力删除刚写的对象。
DownloadObjectHandler:
- 内部令牌中间件通过后才进入。
objectKey来自查询参数(由 file-api 传入)。Store.Stat判断存在。- 设置
Content-Type、Accept-Ranges、Content-Disposition。 parseRange只支持单段 Range;非法返回 416。Store.OpenRange+ 64 KiB 缓冲流式转发。
service/storage/rpc/internal/jobs/maintenance.go 每 Interval 秒跑一次:
| 步骤 | 做什么 |
|---|---|
expireUploads |
把过期 initiated/uploading 任务置 failed,删临时分片 |
recoverStuckCompleting |
停留超过 15 分钟的 completing 放回 uploading |
retryObjectDeletes |
重试 status=deleting 的对象删除 |
cleanupOrphanParts |
清理 48 小时前的 parts/ 孤儿对象 |
refreshGauges |
刷新活跃上传任务数、GC 积压指标 |
- 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,规则只能有一个来源。
下面每条链路都按“HTTP → handler → API logic → RPC → RPC logic → model”列出文件。跟着任意一条走一遍,就掌握了整套代码的阅读方法。
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。
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。
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。
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。
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。
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。
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。
分享:
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 指针换了目标。
三份 schema 在同一个 MySQL 库,但服务之间不 JOIN、不建外键:
| 服务 | 表 | 一句话 |
|---|---|---|
| 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 视为不存在 |
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,这是为了保证版本行和文件指针在同一事务里更新。
| 前缀 | 内容 |
|---|---|
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,避免分页缓存键爆炸。
| 包 | 作用 | 关键函数 |
|---|---|---|
| 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 |
部署侧:
- docker-compose.yml:基础设施 + 6 个服务;配置用
deploy/config/*.yaml挂载。 - Dockerfile:一个 Dockerfile +
SERVICE_DIR构建参数。 - deploy/config/:
${VAR}由 go-zero 的os.ExpandEnv替换。 - deploy/kubernetes/:Deployment + StatefulSet + ConfigMap/Secret。
- .github/workflows/ci.yml:gofmt、vet、test、build 6 个镜像、compose 校验。
cp .env.example .env
docker compose up -d --build
docker compose ps
go run ./scripts/e2edocker 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 注册的地址必须对调用方可达,不要混用两套。
scripts/e2e/main.go 按顺序验证:
- 健康检查
- 注册 / 重复注册 / 登录 / 无 token / 错密码
- 建目录 / 重名
- 初始化上传 / 幂等 / 分片 / 错误分片大小 / 进度 / 完成 / 重复完成
- 下载 + SHA-256 校验 + Range
- 版本列表 + 回滚
- 分享密码 / 次数 / 撤销
- 越权(bob 访问 alice)
- 删除 + 配额归还
- 目录递归删除
想确认某个行为时,先看 e2e 里对应的断言,比翻文档快。
以下是回顾 storage 及跨服务代码时,已对照源码确认的问题或待确认设计。建议按严重程度逐条决定“修 / 接受并写进文档”。
-
CompleteUpload失败后无法重试,与注释和文档矛盾- 位置:completeuploadlogic.go:56-66
- 函数头注释写“中途失败把任务置为 failed,重复调用会重新走一遍(合并是幂等的覆盖写)”,但
switch里case "failed"直接返回FailedPrecondition。 - 结果:合并失败一次后任务永久不可重试;只有
completing卡住被维护任务放回uploading才可能继续。 - 需要决定:是改成允许
failed重试,还是把注释和文档改成“失败即终态”。
-
过期上传的预占配额没有归还
- 位置:abortuploadlogic.go:59、maintenance.go:129
storage.rpc的expireUploads只改任务状态、删分片,不知道配额;file-api的取消逻辑只在状态为initiated/uploading时归还,而GetUploadTask会把过期任务返回成"expired"。- 结果:用户上传中断且不主动取消时,
reserved_bytes会一直泄漏。 - 需要补:过期任务的对账/归还机制,或在 file-api 增加定时清理。
-
Store.Copy的contentType参数未使用- 位置:objectstore.go:193
- 单片上传走
CopyObject,多片走ComposeObject,都没有设置目标 Content-Type;临时分片固定写application/octet-stream。 - 对外下载时 file-api 用文件元数据覆盖了响应头,所以用户通常感知不到,但 MinIO 里对象的 Content-Type 可能不对。
-
完成上传后不清理
upload_parts行- 位置:completeuploadlogic.go:153-158
- 只删了 MinIO 临时对象,没有
PartsModel.DeleteByUploadId。成功上传越多,upload_parts越大。 - 若保留是为了可查询进度,需要在文档里说明;否则应清理或归档。
-
InitUpload对已存在任务不看状态- 位置:inituploadlogic.go:39-45
- 只要
upload_id存在且属于同一用户,就直接返回旧任务,不管它是aborted、failed还是completed。 - 结合 file-api 用
idempotencyKey当uploadId的约定:客户端用同一个 key 重传,会拿到旧任务,可能无法重新开始。需要确认这是期望的幂等语义。
-
内部下载接口不校验
storage_objects.status- 位置:dataplane.go 的
DownloadObjectHandler - 只
StatMinIO,不看数据库状态。授权完全依赖 file-api;只要拿到内部令牌和 objectKey,就能读到 MinIO 中仍存在的对象。 - 需要确认是否可接受,或在 storage 侧增加一次
GetObjectInfo校验。
- 位置:dataplane.go 的
-
重名校验是应用层
SELECT count(*),没有唯一索引兜底- 位置:helpers.go:90
folders/files都没有(owner_id, parent_id, name)唯一索引,并发创建/改名存在竞争窗口。
-
objkey不校验uploadId字符集- 位置:objkey.go
uploadId直接拼进对象 Key。正常路径由 file-api 的normalizeRequestId限制为[A-Za-z0-9._-]{8,64},但 storage.rpc 作为内部服务没有防御性校验。
-
Store.Get的 Range 参数有边界缺陷- 位置:objectstore.go:252-259
offset > 0 && length <= 0会算出end = offset-1,产生非法 Range。当前没有调用方使用这种组合,OpenRange是正确实现。
-
WithMaxBytes依赖MaxChunkBytes配置非零- 位置:storage-api routes.go:59
- 使用
MaxChunkBytes + 1;若配置缺失(值为 0),上限会变成 1 字节。Config 结构体没有默认值兜底。
-
后台任务多副本没有互斥
- 位置:maintenance.go
- 注释说可重入,但没有 leader 选举或数据库锁;多副本会同时执行,操作基本幂等,但会产生重复日志和外部请求。
-
GetObjectInfo/CheckObject没有业务调用方- 目前
tools/reconcile直接使用objectstore.Store+ 原始 SQL,不经过这两个 RPC。若后续没有计划,考虑是否保留。
- 目前
-
RevokeByFile缓存失效最多覆盖 1000 条分享- 位置:sharesmodel.go:89
FindByOwner(ownerId, 0, 1000)收集缓存 key;分享数超过 1000 的用户可能有缓存未失效窗口。
-
ListShares存在 N+1 查询- 每条分享单独
FilesModel.FindOne取文件名。分享数量大时考虑批量查询。
- 每条分享单独
-
部分状态枚举未被实现
upload_parts.status=0从未使用;storage_objects.status的uploading/failed未使用;files.status的pending/processing基本未用。- 文档里的状态表比实现宽,回顾时以代码实际写入值为准。
-
user 服务的少量错误码细节
GetUser/GetQuota在记录不存在时直接返回model.ErrNotFound,没有转成codes.NotFound,经统一错误处理会变成 HTTP 400 而不是 404。- 影响不大,但属于“文档说 404、实际 400”的偏差。
- 看第 1 节的进程表和图,记住 6 个进程与 3 个数据属主。
- 打开 file/api/file.go 和 routes.go,确认启动顺序和路由分组。
- 打开一个最简单的 handler + logic(推荐
ListFiles),确认 7 个落点。 - 看 common/web/errorhandler.go,理解错误如何映射。
按这个顺序跟代码,每一步都打开对应文件:
- 初始化上传:
inituploadlogic.go→createfilelogic.go→quota.go→storage/inituploadlogic.go - 分片上传:
storage/api/dataplane.go→recordpartlogic.go - 完成上传:
file/completeuploadlogic.go→storage/completeuploadlogic.go→addversionlogic.go→fileversionsmodel.go→commitquotalogic.go - 下载:
file/api/download.go→getfilelogic.go→storage/api/dataplane.go - 删除:
deletefilelogic.go(两个)→filesmodel.go→storage/deleteobjectlogic.go
每跟完一条,回到第 5 节对照一遍,确认自己没有漏掉“补偿”或“幂等”分支。
- storage.proto → 逐个 logic,重点
CompleteUpload、AbortUpload、RecordPart。 - maintenance.go:理解每个清理任务的前置条件。
- objectstore.go + objkey.go:确认流式语义和 Key 规则。
- 对照第 9 节清单,逐条做“修 / 接受 / 补文档”的决定。
- docs/consistency.md 的每个“已知窗口”是否成立?
- docs/security.md 的每条声明是否有代码支撑?
- scripts/e2e/main.go 的断言是否覆盖了你关心的失败路径?
go test ./...、go vet ./...、go run ./scripts/e2e是否仍然通过?
| 我想知道… | 去哪看 |
|---|---|
| 某个 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 节 |
随便挑一个接口,回答下面 6 个问题;答不上来的那一步,就是下次要读的文件:
- 契约在哪?路由在哪注册?挂了哪些中间件?
- handler 解析了哪些参数?调用了哪个 logic?
- API logic 取了 userId 吗?调了哪几个 RPC?失败时补偿是什么?
- RPC logic 做了哪些校验?读写哪几张表?幂等键是什么?
- 数据库索引/状态机能否支撑这个操作?并发下会不会出错?
- 出错时返回什么 code?会不会留下孤儿对象或错误配额?
用这个模板走一遍“初始化上传 → 分片 → 完成 → 下载 → 删除”,整个项目就串起来了。