9Drive API 密钥与外部上传接口实战:用 API Key 从脚本和 CI 自动上传文件

原创2026-10-29 18:38:351,689 阅读

9Drive API 密钥与外部上传接口实战:用 API Key 从脚本和 CI 自动上传文件

9Drive 是一个把多个 Google Drive 和 S3 账号汇聚成一个虚拟存储网关的 Web 应用。本文带你用 9Drive 的 API Key 和外部上传接口(POST /api/v1/uploads),实现从脚本和 CI 流水线自动上传文件——无需登录、无需浏览器,一行 curl 就能把构建产物、日志或备份推到网盘。

一句话上手:在 9Drive 的 API Keys 页面创建一个以 9d_live_ 开头的密钥,然后带着 Authorization: Bearer <你的密钥> 头调用 POST /api/v1/uploads,文件就会按路由策略自动落到空间充足的存储账号上。

快速信息 说明
上传接口 POST /api/v1/uploads
鉴权方式 Authorization: Bearer 9d_live_xxx(API Key)
请求格式 multipart/form-data(最多 25 个文件/次)
单文件上限 默认 5 GB,可通过 MAX_UPLOAD_BYTES 调整
密钥权限 固定为 files:upload(只能上传,无法读取/删除)

为什么需要 9Drive 外部上传接口

9Drive 本身提供网页界面,但真实场景里"上传"往往发生在人之外:

  • 📦 CI 流水线:每次构建后把 release 包、日志归档推上网盘;
  • 🔁 定时备份:crontab 里跑一条 curl,把数据库导出文件传上去;
  • 📡 服务器采集:监控脚本把报告文件批量上报到统一存储;
  • 🧩 自有应用集成:让后端服务代替用户存文件,省去逐个 Drive 账号的 OAuth 流程。

这些场景的共同点是:没有登录会话,只有 API Key。这正是 9Drive 外部上传接口的设计目标——密钥权限被限定为 files:upload,即使密钥泄露,攻击者也拿不到读取或删除文件的权限。

9Drive 项目演示动画:多账号 Google Drive 虚拟存储网关

第一步:在 API Keys 页面创建 9Drive API 密钥

登录后在左侧边栏点击 API Keys 进入 API Management 页面,点击 Create API Key,填写一个便于识别的名称(如 CI artifact uploader),提交即可:

9Drive API 管理页面:创建 API Key 并复制上传示例

这个页面就是密钥管理的全部,信息一目了然:

  1. 复制密钥:创建后弹出一个蓝色卡片,显示完整的 9d_live_... 密钥。密钥只显示这一次,服务器端只保存它的 SHA-256 哈希(见 backend/src/utils/crypto.ts 的 hashToken),页面一关就再也看不到,请务必存入密码管理器或 CI 环境变量。
  2. 查看密钥列表:每张密钥卡片显示状态(active/revoked)、密钥前缀、创建时间、最近使用时间和权限范围(Scope)。最近使用时间来自每次请求时的记录(backend/src/middleware/api-key.middleware.ts),能帮你判断某个密钥还在不在被使用。
  3. 吊销密钥:点 Revoke 立即失效。密钥还可以带过期时间 expiresAt 创建(见 backend/src/modules/api-keys/api-key.routes.ts)。

给不同用途建不同密钥是个好习惯:CI artifact uploader 给流水线用,Website backups 给备份脚本用——吊销互不影响,泄露也能精准止损。

9Drive 上传接口的请求格式:POST /api/v1/uploads

接口本身只有一行注册代码:backend/src/modules/public-api/public-api.routes.ts,但它的上传处理器 handleUpload 与网页上传完全共用同一套逻辑,包括自动选择存储账号、配额同步和文件夹归属,所以 API 上传的文件在网页端体验和手动上传一模一样。

请求要点:

项目 要求
方法 / 路径 POST /api/v1/uploads
请求头 Authorization: Bearer 9d_live_xxx
Content-Type multipart/form-data(必须)
filesMeta JSON 数组,必须放在文件字段之前,每项为 { fieldName, fileName, mimeType, sizeBytes, folderId? }
文件字段 file-0、file-1……与 filesMeta 中的 fieldName 一一对应
sizeBytes 声明的文件字节数,服务端会用实际字节数校验,不一致会报 UPLOAD_SIZE_MISMATCH

单文件上传的最小 cURL 示例(来自 README.md 的 Upload API 章节):

curl -X POST "http://localhost:4000/api/v1/uploads" \
  -H "Authorization: Bearer 9d_live_xxx" \
  -F 'filesMeta=[{"fieldName":"file-0","fileName":"hello.txt","mimeType":"text/plain","sizeBytes":"12"}]' \
  -F "file-0=@hello.txt;type=text/plain"

成功时返回 201:单文件返回 { "file": {...} },多文件返回 { "files": [...], "failed": [...] }。每个文件独立成功或失败,failed 数组里会带具体的错误码,方便脚本做重试判断。

💡 如果你更习惯写 JavaScript,API Management 页面里的 Upload API Docs 卡片内置了可直接复制的 cURL 和 JavaScript 示例,一键复制即用(前端实现见 frontend/src/pages/ApiManagementPage.tsx)。

从脚本自动上传:一条命令搞定

以"批量上传整个目录"为例,把上面的单文件示例包一层循环即可:

API_URL="http://localhost:4000"
API_KEY="9d_live_xxx"

for f in dist/*.zip; do
  size=$(stat -c%s "$f")
  curl -sf -X POST "$API_URL/api/v1/uploads" \
    -H "Authorization: Bearer $API_KEY" \
    -F "filesMeta=[{\"fieldName\":\"file-0\",\"fileName\":\"$(basename $f)\",\"mimeType\":\"application/zip\",\"sizeBytes\":\"$size\"}]" \
    -F "file-0=@$f;type=application/zip" \
  && echo "uploaded: $f"
done

几个实用细节:

  • 指定目标文件夹:在 filesMeta 里加 folderId(在网页端文件夹详情里可以看到 ID)。如果该文件夹绑定到某个存储账号,文件会强制落到对应账号,跳过自动路由。
  • 批量单次上传:一次请求最多 25 个文件,用 file-0、file-1… 依次追加,比循环更快。
  • 官方冒烟测试:仓库里自带一个端到端测试脚本,演示了从建密钥、上传到清理的完整流程,非常适合当参考模板:backend/src/scripts/test-api-upload.ts。

CI 流水线接入:三步完成自动化

把上面的逻辑搬进 CI(GitHub Actions、GitLab CI 等均可)只需三步:

  1. 创建密钥:在 9Drive 的 API Keys 页面新建一个密钥(如 CI artifact uploader),只授予 files:upload。
  2. 配置变量:把密钥存为 CI Secret(如 NINEDRIVE_API_KEY),服务地址存为普通变量(如 NINEDRIVE_API_URL)。密钥永远不要写进代码仓库。
  3. 加一个上传步骤:
- name: Upload artifact to 9Drive
  run: |
    size=$(stat -c%s release-$GITHUB_SHA.zip)
    curl -sf -X POST "$NINEDRIVE_API_URL/api/v1/uploads" \
      -H "Authorization: Bearer $NINEDRIVE_API_KEY" \
      -F "filesMeta=[{\"fieldName\":\"file-0\",\"fileName\":\"release-$GITHUB_SHA.zip\",\"mimeType\":\"application/zip\",\"sizeBytes\":\"$size\"}]" \
      -F "file-0=@release-$GITHUB_SHA.zip;type=application/zip"

之后每次提交都会自动产出一个带提交号的归档并入库。配合 curl -sf 的静默失败行为,上传失败会直接让流水线报错,方便定位。

上传路由策略:文件自动落到空间充足的账号

这是 9Drive 外部上传接口最有价值的地方:你不需要关心文件到底存到哪个 Drive 或 S3 账号,后端会先同步各账号配额,再按路由策略挑选(upload.routes.ts 的 selectAccount):

9Drive 配额跟踪页面:查看各存储账号剩余空间并配置上传路由模式

三种模式在 Quota Tracker 页面可随时切换:

模式 行为 适用场景
most_available(默认) 总是选剩余空间最多的账号 通用场景,保持空间均衡
round_robin 在可用账号间轮流写入 想均匀利用多个账号
priority 按你设定的优先级顺序选择 有主力账号时

API 上传与网页上传走同一策略,所以你在 Quota Tracker 里调整路由后,脚本和 CI 的上传行为立即同步生效。

验证上传结果:在仪表盘确认文件与活动日志

脚本跑完后,回到 9Drive 网页端两处确认即可。

All Files 页面:新上传的文件会按存储账号标注在 Access 列,和手动上传的文件混排在一起:

9Drive 全部文件列表:API 上传的文件与手动上传的文件统一管理

Activity Log 页面:每次上传都会留下 FILE_UPLOAD 审计记录(见 backend/src/utils/audit.ts),包含文件名和时间,排障时非常有用:

9Drive 活动日志:FILE_UPLOAD 等文件操作审计记录

API Key 安全最佳实践

  • 🔐 密钥只显示一次:创建后立即存入密码管理器或 CI Secret,别留在聊天记录里。
  • 🔑 一用途一密钥:CI、备份、临时调试各建各的密钥,出问题随时定点吊销。
  • 🗓️ 设置过期时间:临时任务用的密钥加上 expiresAt,到期自动失效,杜绝"僵尸密钥"。
  • 👀 盯住最近使用时间:API Keys 页面的 Last used 字段能暴露长期未动的密钥;再配合 Activity Log 的审计记录,异常上传一目了然。
  • 🛡️ 权限天然最小化:密钥固定只有 files:upload,无法读取、分享或删除文件,泄露面被压到最低。
  • ✅ 校验字节数:接口会核对实际字节与声明的 sizeBytes,脚本里务必用 stat 之类工具取真实大小,避免 UPLOAD_SIZE_MISMATCH。

常见错误与排查

请求失败时,响应体都是统一的 { "code": "...", "message": "..." } 结构,按 code 快速定位:

HTTP code 含义与处理
401 API_KEY_REQUIRED 请求头缺少 Authorization: Bearer ...
401 API_KEY_INVALID 密钥不存在、已吊销或已过期——重新创建
403 API_KEY_FORBIDDEN 密钥缺少 files:upload 权限
400 UPLOAD_INVALID_CONTENT_TYPE 必须使用 multipart/form-data
400 NO_ACCOUNT_WITH_ENOUGH_SPACE 所有已连接账号空间都不足,去 Quota Tracker 扩容或清理
400 UPLOAD_TOO_LARGE 超过单文件上限(默认 5 GB)
400 UPLOAD_SIZE_REQUIRED 文件字段前没有先发送 sizeBytes/filesMeta

排查顺序建议:先看 code 判断是鉴权问题(401/403)还是容量/格式问题(400);鉴权问题九成是密钥被吊销或过期,去 API Keys 页面看一眼 Last used 和状态即可。

小结

你学到了 对应能力
在 API Keys 页面创建/查看/吊销密钥 密钥只显示一次、哈希存储、记录最近使用
POST /api/v1/uploads 的 multipart 请求格式 filesMeta 先行、fieldName 对应文件字段
脚本批量上传与 CI 三步接入 curl 循环、Secret 变量、上传步骤
路由策略(most_available / round_robin / priority) 文件自动落到空间充足的 Drive 或 S3 账号
用 All Files 与 Activity Log 验证 审计留痕、按账号溯源

至此,9Drive 就从"网页上点点点"升级成了可编程的存储后端:脚本和 CI 只需要一把 9d_live_ 密钥,上传、路由、配额、审计全部交给 9Drive 处理。想继续深入接口细节,可以查看 README.md 中的 Upload API 与完整 REST API 概览,以及 backend/src/modules/uploads/upload.routes.ts 中的上传实现源码。

登录后查看全文
9drive