API 参考

面向接入方与第三方开发者，描述 OSS 调用的 REST API 认证方式、端点约定、请求/响应格式及错误码。

机器可读规范与在线试调：OpenAPI JSON、Swagger UI。 Base URL 以实际部署为准（如 https://your-domain.com，本地为 http://localhost:3003）。

1. 认证方式

API 支持两种认证，任选其一即可。

1.1 Cookie Session（浏览器）

• 适用：Web 前端、同源请求。
• 方式：用户登录后，请求自动携带 Cookie next-auth.session-token，无需在代码里显式传 Token。
• 获取登录态：访问 /signin 完成 OAuth（GitHub/Google），登录成功后进入控制台，后续同源请求会自动带 Cookie。

1.2 API Key（脚本 / 服务端 / CLI）

• 适用：脚本、CLI、第三方系统、无浏览器场景。
• Header：X-API-Key: <AccessKey>:<Signature>
• AccessKey：在控制台「API 密钥」中创建，创建时展示一次完整 AccessKey 与 SecretKey，需妥善保存。
• Signature 算法：
  • CanonicalRequest = Method + "\n" + Path + "\n" + QueryString + "\n" + HashedBody
  • HashedBody = Hex(SHA256(body))，无 body 时为空字符串。
  • Signature = HMAC-SHA256(SecretKey, CanonicalRequest)，与 AccessKey 一并放入 Header。

X-API-Key: your-access-key:computed-signature

2. 端点概览

3. 请求与响应约定

3.1 单文件上传

• POST /api/files/upload
• Content-Type：multipart/form-data
• 字段：file（必填）、folderId（可选）、compressImage（可选，true/1 时对图片压缩）
• 成功 200：{ "id", "key", "name" }

3.2 文件元数据、HEAD、删除与复制

• GET /api/files/{id}：返回文件元数据（id、key、name、size、mimeType、acl、createdAt 等）。
• HEAD /api/files/{id}：仅返回头（Content-Type、Content-Length、ETag、X-File-Id 等），不返回 body。
• PATCH /api/files/{id}：Body { "targetFolderId"? , "acl"? }，可移动目录或更新 ACL（private | public-read | public-read-write）。
• DELETE /api/files/{id}：软删除文件（进回收站）。
• POST /api/files/batch-delete：Body { "ids": ["<uuid>", ...] }，单次最多 200 个，返回 { success, total, results }。
• POST /api/files/{id}/copy：Body { "targetFolderId"? }（不传为根目录），返回 { "id": "<新文件uuid>" }。

3.3 分片上传（大文件）

1. 初始化：POST /api/files/multipart/init，Body { "key", "name", "mimeType", "folderId?" }，返回 { uploadId, key, bucket }。
2. 上传分片：PUT /api/files/multipart/part?uploadId=xxx&partNumber=1，Body 为分片二进制，返回 { etag, partNumber }。
3. 完成：POST /api/files/multipart/complete，Body { "uploadId", "parts": [{ "partNumber", "etag" }] }，返回 { id, key }（id 为新文件 UUID）。
4. 中止：DELETE /api/files/multipart/abort?uploadId=xxx，放弃本次分片上传。

3.4 下载与预览

• GET /api/files/{id}/download：返回文件流，带 Content-Type、Content-Disposition，需认证。
• GET /api/files/{id}/preview：同上，用于内嵌预览（如图片）。
• POST /api/files/{id}/presigned-url：Body { "expiresIn"? }（秒，默认 3600，最长 7 天），返回 { "url", "expiresIn" }。
• GET /api/signed?t=xxx：通过预签名 token 下载，无需登录；403 表示链接无效或已过期。
• GET /api/s/{token}/download：分享链接下载，可带密码；无认证即可访问。

3.5 分享与短链

• GET /f/{id}：静态资源地址，使用文件 ID。公开读文件可直接访问；私有文件需带 expires 与 signature（与预签名算法一致）。支持图片变换：?w=宽&h=高&q=质量&format=webp|avif。
• POST /api/files/{id}/share：Body { "expiresInDays"? , "password"? }（默认 7 天），返回 { "id", "token", "url", "expiresAt" }。
• POST /api/files/{id}/short-link：Body { "expiresInSeconds"? }，返回 { "code", "url" }（url 为 /go/{code} 的完整地址）。
• GET /go/{code}：302 重定向到 /f/{id}（公开或带签名的私有文件），无认证即可访问。

3.6 文件夹

• GET /api/folders：Query parentId（不传或空为根目录）、page、pageSize、type（all|file|folder）、keyword 等；返回 { folders, files, total, page, pageSize }。
• POST /api/folders：Body { "parentId"? , "name" }，返回 { "id" }。
• GET /api/folders/{id}：返回文件夹元数据（id、name、key、parentId、acl、createdAt 等）。
• PATCH /api/folders/{id}：Body { "acl"? }，更新 ACL。
• DELETE /api/folders/{id}：递归删除该文件夹及其下所有文件与子文件夹。

3.7 账户用量

• GET /api/quota：返回 { "usedBytes", "quotaBytes" }（quotaBytes 为 null 表示不限制）。
• GET /api/usage?days=30：返回 { "rows", "total": { totalBytes, totalRequests }, "days" }，按日流量与请求数。

4. 错误响应

• 401 Unauthorized：未登录或 API Key 无效/过期。
• 404 Not Found：文件不存在、已删除、分享不存在或已过期。
• 400 Bad Request：参数错误（如缺少 file、folderId 无效等），Body 可能为 { "message": "说明" }。
• 500 Internal Server Error：服务端错误（如存储失败），可查看 Body 中的 message（若有）。

5. 安全与限流

• 所有需认证的接口均需有效 Session 或合法 API Key 签名。
• 建议对上传/下载做速率限制与配额控制（以实际部署为准）。
• API Key 仅创建时展示完整 SecretKey，请妥善保管，勿写入前端或公开仓库。

接口变更会尽量保持向后兼容；当前 API 版本可通过 GET /api/openapi.json 中的 info.version 查看。