OSS 文档

入门与操作说明

面向首次接入的开发者：如何获得访问权限、选择认证方式、发起第一个请求，以及 OSS 常见操作步骤。

1. 前置条件

  • 已拥有平台账号（通过 OAuth 如 GitHub/Google 登录）。
  • 若使用 API Key 调用，需在控制台创建并保存 AccessKey/SecretKey。
  • 知晓当前环境 Base URL（如生产域名或 http://localhost:3003）。

2. 获取访问权限

2.1 浏览器端（Cookie 登录）

  1. 打开登录页：{BaseURL}/signin。
  2. 使用 GitHub 或 Google 完成登录。
  3. 登录成功后进入控制台，同一浏览器下访问 {BaseURL}/api/* 时会自动携带 Session Cookie，无需在代码里写 Token。

2.2 脚本 / 服务端（API Key）

  1. 登录控制台 → 侧栏「API 密钥」。
  2. 创建新密钥，保存弹出的 AccessKey 与 SecretKey（SecretKey 仅展示一次）。
  3. 请求时在 Header 中按约定携带 X-API-Key: <AccessKey>:<Signature>（Signature 算法见 API 文档 - 认证）。

3. 第一个请求示例

3.1 使用 cURL（Cookie）

先浏览器登录，再从浏览器开发者工具复制 Cookie（如 next-auth.session-token=xxx），然后：

# 下载文件（将 {id} 换为文件 UUID，Cookie 换为实际值）
curl -v -H "Cookie: next-auth.session-token=YOUR_SESSION_TOKEN" \
  "https://your-domain.com/api/files/YOUR_FILE_ID/download" -o local-file.bin

3.2 使用 cURL（单文件上传）

curl -X POST \
  -H "Cookie: next-auth.session-token=YOUR_SESSION_TOKEN" \
  -F "file=@/path/to/your/file.jpg" \
  -F "folderId=OPTIONAL_FOLDER_UUID" \
  "https://your-domain.com/api/files/upload"

成功时返回 JSON：{ "id": "...", "key": "...", "name": "file.jpg" }。

3.3 使用 Swagger UI 试调

  1. 打开 {BaseURL}/api/docs。
  2. 若为 Cookie 登录：先在同一浏览器登录控制台，再在 Swagger 页点击「Try it out」发起请求。
  3. 若为 API Key：在页面顶部「Authorize」中填写 Key 与签名，再试调各接口。

4. 常见操作说明

4.1 上传小文件（< 约 100MB）

使用 POST /api/files/upload，multipart/form-data，字段 file（必填）、folderId（可选）。详见 API 文档 - 单文件上传。

4.2 上传大文件（分片）

  1. POST /api/files/multipart/init 获取 uploadId。
  2. 将文件按块（如 5MB～100MB）PUT /api/files/multipart/part?uploadId=xxx&partNumber=N 上传。
  3. POST /api/files/multipart/complete 提交 uploadId 与所有 parts（含 partNumber 与 etag）。

详见 API 文档 - 分片上传。

4.3 下载私有文件

使用 GET /api/files/{id}/download，并携带 Cookie 或 API Key 认证，将响应体保存为文件或流式处理。

4.4 分享给他人下载（免登录）

  • 在控制台为文件创建「分享链接」，或调用 POST /api/files/{id}/share（Body：{ "expiresInDays"? , "password"? }），获得形如 {BaseURL}/api/s/{token}/download 的 URL。
  • 对方直接访问该 URL 即可下载（若设置了密码，需在页面输入）。
  • 无需登录，无需 API Key。

4.5 短链与预签名链接

  • 短链：控制台生成或 POST /api/files/{id}/short-link，得到 {BaseURL}/go/{code}，访问后 302 重定向到实际文件。
  • 预签名：POST /api/files/{id}/presigned-url（Body：{ "expiresIn"? }）获取有时效的下载 URL，任何人持该链接即可下载，无需登录。

4.6 列出目录与创建文件夹

  • GET /api/folders?parentId=xxx（parentId 不传或空为根目录）可列出该目录下的文件与子文件夹，支持分页、筛选。
  • POST /api/folders，Body { "parentId"? , "name" } 可创建文件夹。详见 API 参考 - 端点概览。

4.7 查看用量与配额

GET /api/quota 返回当前用户存储用量与配额；GET /api/usage?days=30 返回流量与请求统计。

5. 文档与规范

6. 故障排查

  • 401：未登录或 API Key 无效/过期 → 检查 Cookie 或重新生成 Key 并核对签名算法。
  • 404：文件 ID 错误、文件已删除，或分享/短链已过期 → 核对 ID 或重新生成分享/短链。
  • 400：缺少必填参数（如 file）或 folderId 不属于当前用户 → 对照 API 文档 检查请求体与参数。

7. 下一步

在控制台创建文件夹、上传文件、生成分享链接与短链，熟悉完整流程；使用 /api/docs 或 Postman 导入 /api/openapi.json 逐接口试调。