统一约定:
- 请求/响应均为 JSON(分片上传与文件下载例外:请求体/响应体是原始字节)。
- 认证:
Authorization: Bearer <accessToken>。未标注"公开"的接口都需要它。 - 成功响应直接返回资源对象;失败响应统一为:
{
"code": "invalid_argument",
"message": "size must not be negative",
"requestId": "8f3c1e2a9b7d4551"
}- 每个响应都带
X-Request-Id头(客户端也可以自己传,服务端会沿用),日志里用同一个 ID。 - 错误码到 HTTP 状态的映射:
| code | HTTP | 典型场景 |
|---|---|---|
invalid_argument |
400 | 参数缺失/非法、分片大小不符 |
unauthenticated |
401 | 没有 token、token 过期、密码错误 |
permission_denied |
403 | 访问他人资源、分享密码错误 |
not_found |
404 | 文件/目录/上传任务不存在 |
already_exists |
409 | 同目录重名 |
failed_precondition |
409 | 上传未完成就完成、上传已取消 |
resource_exhausted |
429 | 配额不足、触发限流 |
unavailable |
503 | 下游服务或对象存储不可用 |
internal |
500 | 其他 |
{ "username": "alice", "password": "Passw0rd!123", "email": "[email protected]" }约束:用户名 3-32 字符;密码至少 8 位(scrypt 上限 72 字节)。
200 → { "userId": 1, "username": "alice" }
409 → 用户名或邮箱已存在
429 → 触发限流(按 IP,默认 5 rps / 突发 10)
{ "username": "alice", "password": "Passw0rd!123" }200 → { "accessToken": "...", "refreshToken": "...", "expiresAt": 1767225600 }
expiresAt 是 access token 的过期时间(Unix 秒),有效期 15 分钟。
用户名不存在与密码错误返回同样的 401 unauthenticated,避免枚举用户名。
{ "refreshToken": "..." }200 → 新的 accessToken + 新的 refreshToken(旧的立即失效,轮换使用)。
{ "refreshToken": "..." }- 传
refreshToken:只撤销这一个会话; - 不传:撤销该用户全部有效会话。
200 → { "success": true, "revokedCount": 2 }
200 → { "userId": 1, "username": "alice", "email": "...", "createdAt": 1767000000 }
200 → { "totalBytes": 10737418240, "usedBytes": 4096, "reservedBytes": 0 }
usedBytes + reservedBytes <= totalBytes 恒成立。
列出某个目录的直接子项。目录全量返回、文件按页返回,目录在前。pageSize 上限 100。
{
"items": [
{ "fileId": 3, "parentId": 0, "name": "docs", "size": 0, "contentType": "",
"isFolder": true, "status": "", "version": 0, "createdAt": 1767000000, "updatedAt": 1767000000 },
{ "fileId": 7, "parentId": 0, "name": "a.txt", "size": 1024,
"contentType": "text/plain", "isFolder": false, "status": "available",
"version": 1, "createdAt": 1767000100, "updatedAt": 1767000200 }
],
"total": 2, "page": 1, "pageSize": 20
}注意:
fileId与目录 id 共用一个整数空间但来自两张表, 对"文件"操作(如/v1/files/{id}/content)传入目录 id 会得到 404。
{ "parentId": 0, "name": "docs" }200 → { "folderId": 3 };同目录重名 → 409 already_exists。
递归删除目录及其全部内容(204-less:返回 200 与释放的字节数):
{ "success": true, "releasedBytes": 2048 }删除是不可恢复的(当前版本没有回收站)。历史版本的对象也会一起清理。
200 → { "file": { ...FileItem } };不存在或非本人 → 404(不区分"不存在"和"不属于你",避免泄露资源存在性)。
{ "name": "new-name.txt" }200 → true(空 body)。同目录重名 → 409。
移动文件/目录,可同时改名:
{ "targetParentId": 3, "name": "optional-new-name.txt" }- 目标目录必须是自己的;
- 目录移动不能进入自己的子树(
400 invalid_argument); - 目标目录下不能重名(
409)。
{ "success": true, "releasedBytes": 1024 }行为:软删文件(含历史版本)→ 撤销该文件所有分享 → 归还配额 → 删除对象。
重复删除是幂等的:返回 200、success=true、releasedBytes=0,不会重复归还配额。
对象删除失败不影响接口成功,由后台 GC 重试。
下载文件内容,返回原始字节流。
- 支持
Range: bytes=0-1023,命中时返回206与Content-Range; - 响应头带
Content-Disposition与Accept-Ranges: bytes; - 文件状态不是
available时返回409。
非本人文件返回 404(与 GET /v1/files/{id} 一致,不泄露资源存在性)。
{ "items": [ { "version": 2, "size": 1024, "contentType": "text/plain",
"contentHash": "…", "current": true, "createdAt": 1767000200 } ] }{ "size": 2048, "contentType": "text/plain", "contentHash": "可选 sha256" }200 → 与 POST /v1/uploads 相同的结构(uploadId/chunkSize/totalChunks)。
上传完成后照旧调用 POST /v1/uploads/{uploadId}/complete,会产生 version+1。
{ "success": true, "version": 3 }回滚是"追加一个新版本",不会删除或改写历史版本。 对当前版本回滚是幂等的(不产生新版本)。
{
"parentId": 3,
"name": "big.bin",
"size": 104857600,
"contentType": "application/octet-stream",
"contentHash": "可选,sha256 hex",
"idempotencyKey": "可选,8-64 位 [A-Za-z0-9._-]"
}200 →
{ "uploadId": "3f1b…", "fileId": 9, "chunkSize": 8388608,
"totalChunks": 13, "expiresAt": 1767260000 }- 同一个
idempotencyKey重复调用返回同一个fileId/uploadId; - 配额不足 →
429 resource_exhausted; - 单文件超过
Upload.MaxFileBytes(默认 10 GiB)→429。
请求体是原始字节,长度必须精确等于该分片应有的长度:
| 分片 | 期望长度 |
|---|---|
part < totalChunks |
chunkSize |
part == totalChunks |
size - (totalChunks-1) * chunkSize |
200 →
{ "uploadId": "3f1b…", "partNumber": 1, "size": 8388608, "etag": "…",
"contentHash": "…", "progress": { "uploadedChunks": 1, "uploadedBytes": 8388608, "totalChunks": 13 } }- 长度不符 →
400; - 非本人任务 →
403; - 分片号越界 →
400 out_of_range; - 重复上传同一片安全(覆盖写)。
断点续传用。返回 status、uploadedChunks、missingParts(还缺哪些片)、
parts(已上传分片的 ETag)、expiresAt。
{ "fileId": 9, "version": 1, "status": "available" }- 分片不齐 →
409 failed_precondition,任务标记为失败; - 摘要不匹配 →
400 invalid_argument,已合并对象会被删除; - 重复调用 → 返回同一个版本,不重复扣配额。
取消上传:标记任务 aborted、清理临时分片、归还预占配额、文件标记为 failed。 重复取消是幂等的。
{ "fileId": 9, "password": "可选", "expiresAt": 1767300000, "maxAccessCount": 5 }200 →
{ "shareId": 1, "token": "kQ2…", "url": "http://127.0.0.1:8001/v1/shares/kQ2…", "expiresAt": 1767300000 }token 只在这里返回一次,数据库只存它的 SHA-256。
列出自己创建的分享,包含已失效的(active=false)。
撤销分享。重复撤销幂等。
{ "password": "可选" }200 →
{ "granted": true, "fileName": "a.txt", "size": 1024,
"contentType": "text/plain", "downloadUrl": "http://127.0.0.1:8001/v1/shares/kQ2…/content" }被拒绝时返回 granted: false(仍是 200),并附原因:
share not found / share was revoked / share has expired / share access limit reached /
invalid share password / file is not available。
每次成功调用都会占用一次访问额度。
下载分享文件。密码也可以通过 X-Share-Password 头传(推荐,避免密码进访问日志)。
支持 Range。
| 接口 | 服务 | 语义 |
|---|---|---|
GET /healthz |
三个 API | 进程存活(不检查依赖) |
GET /readyz |
storage-api | 依赖就绪(MinIO 可用、bucket 存在) |
GET :6060/healthz |
全部六个服务 | go-zero dev server 的健康检查 |
GET :6060/metrics |
全部六个服务 | Prometheus 指标 |
POST /v1/uploads
HTTP/1.1 429 Too Many Requests
X-Request-Id: 8f3c1e2a9b7d4551
Content-Type: application/json
{"code":"resource_exhausted","message":"quota exceeded: insufficient quota","requestId":"8f3c1e2a9b7d4551"}GET /v1/files/999
HTTP/1.1 404 Not Found
{"code":"not_found","message":"file not found","requestId":"…"}