9Drive API 密钥与外部上传接口实战:用 API Key 从脚本和 CI 自动上传文件
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,即使密钥泄露,攻击者也拿不到读取或删除文件的权限。
第一步:在 API Keys 页面创建 9Drive API 密钥
登录后在左侧边栏点击 API Keys 进入 API Management 页面,点击 Create API Key,填写一个便于识别的名称(如 CI artifact uploader),提交即可:
这个页面就是密钥管理的全部,信息一目了然:
- 复制密钥:创建后弹出一个蓝色卡片,显示完整的
9d_live_...密钥。密钥只显示这一次,服务器端只保存它的 SHA-256 哈希(见 backend/src/utils/crypto.ts 的hashToken),页面一关就再也看不到,请务必存入密码管理器或 CI 环境变量。 - 查看密钥列表:每张密钥卡片显示状态(
active/revoked)、密钥前缀、创建时间、最近使用时间和权限范围(Scope)。最近使用时间来自每次请求时的记录(backend/src/middleware/api-key.middleware.ts),能帮你判断某个密钥还在不在被使用。 - 吊销密钥:点 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 等均可)只需三步:
- 创建密钥:在 9Drive 的 API Keys 页面新建一个密钥(如
CI artifact uploader),只授予files:upload。 - 配置变量:把密钥存为 CI Secret(如
NINEDRIVE_API_KEY),服务地址存为普通变量(如NINEDRIVE_API_URL)。密钥永远不要写进代码仓库。 - 加一个上传步骤:
- 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):
三种模式在 Quota Tracker 页面可随时切换:
| 模式 | 行为 | 适用场景 |
|---|---|---|
most_available(默认) |
总是选剩余空间最多的账号 | 通用场景,保持空间均衡 |
round_robin |
在可用账号间轮流写入 | 想均匀利用多个账号 |
priority |
按你设定的优先级顺序选择 | 有主力账号时 |
API 上传与网页上传走同一策略,所以你在 Quota Tracker 里调整路由后,脚本和 CI 的上传行为立即同步生效。
验证上传结果:在仪表盘确认文件与活动日志
脚本跑完后,回到 9Drive 网页端两处确认即可。
All Files 页面:新上传的文件会按存储账号标注在 Access 列,和手动上传的文件混排在一起:
Activity Log 页面:每次上传都会留下 FILE_UPLOAD 审计记录(见 backend/src/utils/audit.ts),包含文件名和时间,排障时非常有用:
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 中的上传实现源码。




