57 lines
5.3 KiB
Markdown
57 lines
5.3 KiB
Markdown
# HTTP API（v0.1）
|
||
|
||
所有路径以 `/api/v1` 开始。JSON 错误为 `{"error":"说明"}`。修改请求带 `Origin`，应匹配 `public_url` 或 `access_urls` 中的完整站点地址。前端请求另携带 `X-Bluebird-Origin: location.origin`，该值也必须匹配入口且与Origin一致，便于反向代理转发后仍正确识别协议。浏览器使用同源 HttpOnly cookie，不开放 CORS。无 cookie 的脚本可使用匿名管理 Bearer 凭据；不要在 URL 中传凭据。
|
||
|
||
| 方法/路径 | 用途 |
|
||
| --- | --- |
|
||
| GET `/health` | 存活/初始化状态 |
|
||
| GET `/policy` | 公开有效策略、当前入口及可用入口 URL、初始化 7 天匿名会话 |
|
||
| POST `/uploads` | 清单声明、完整容量预留、生成上传会话与管理凭据 |
|
||
| PUT `/uploads/{id}/files/{file}` | 原始文件字节流，需同会话 cookie 或管理 Bearer |
|
||
| GET `/uploads/{id}` | 查询上传状态，需所有权凭据 |
|
||
| POST `/uploads/{id}/publish` | 所有文件就绪后发布，仅首次返回取件码 |
|
||
| GET `/mine` | 当前匿名会话最近100个包裹 |
|
||
| POST `/parcels/{id}/revoke` | 提前撤销 |
|
||
| POST `/parcels/{id}/code` | 重生成取件码，旧码/授权失效 |
|
||
| POST `/pickup/resolve` | `{code,password}`，校验后设置10分钟取件 cookie |
|
||
| GET `/pickup` | 当前授权包裹的文件清单 |
|
||
| GET `/pickup/files/{file}/download` | 附件下载；忽略 Range，HEAD 不扣次数 |
|
||
| POST `/admin/login` | `{username,password}`，设置8小时管理员 cookie |
|
||
| POST `/admin/logout` | 删除管理员会话 |
|
||
| GET `/admin/status` | 登录状态 |
|
||
| GET `/admin/stats` | 实体、逻辑、预留、预算及并发统计 |
|
||
| GET `/admin/parcels?page=1&page_size=10` | 分页包裹及文件；支持 `q`（文件名/包裹ID片段）、`state` |
|
||
| POST `/admin/parcels/{id}/delete` | 撤销包裹，后台回收 |
|
||
| POST `/admin/files/{id}/delete` | 删除单份文件引用，后台回收 |
|
||
| POST `/admin/parcels/{id}/reissue` | 显式重发恢复待审核包裹，使用当前默认期限/次数 |
|
||
| GET/PUT `/admin/policy` | 读取/修改完整业务策略 |
|
||
| GET/PUT `/admin/runtime` | 文件/数据预算、磁盘余量及审计天数/条数/内容预算 |
|
||
| GET `/admin/audit?page=1&page_size=20` | 分页审计；支持 `action`、`source`、`target`、`from`、`to` |
|
||
| POST `/admin/cleanup` | 触发清理 |
|
||
|
||
上传清单示例：
|
||
|
||
```json
|
||
{"files":[{"name":"example.zip","size":12345}],"days":7,"downloads":5,"password":"optional-password","renew":true}
|
||
```
|
||
|
||
响应包含 `id`、`manage_token` 和带服务生成文件 ID 的 `files`。凭据只保存到受控位置，不转发给收件人。实际文件长度必须与清单相符。会话最长1小时，进程重启会撤销尚未发布的会话。已就绪的文件重发 PUT 幂等返回成功；失败文件可重新完整上传。每次失败重试的传入内容计入日上传流量。
|
||
|
||
下载成功是服务器输出完整响应体，无法证明用户已保存。请求开始即扣次数，中断保守计一次；开始前确定没有发送内容则返还。仅成功传输且仍有剩余次数才续期；默认 `到期时间 = min(max(旧到期,完成时刻)+3天,发布时间+30天)`。另一模式为 `min(max(旧到期,完成时刻+3天),总期限上限)`。取件授权到期需重新输入取件码。
|
||
|
||
`GET /policy` 另返回 `visitor_expires`（当前浏览器身份到期Unix时间）。管理凭据用于所有权，过期/删除记录不开放重新取件，已清理记录返回404。
|
||
|
||
## 管理列表分页与搜索
|
||
|
||
包裹和审计列表统一返回 `{items,total,page,page_size,pages}`，其中 `total` 是符合当前筛选条件的总条数，`pages` 是总页数。空结果仍返回 `items:[]`、`page:1`、`pages:1`。页码从1开始；默认包裹每页10个、审计每页20条，`page_size` 支持1至100。超出最后一页时自动回到最后一页；非法页码、条数或筛选值返回400。分页仅加载当前页，数据库保留条数与页面每页条数相互独立。
|
||
|
||
包裹 `q` 匹配文件名或包裹ID片段，`state` 为精确状态。审计 `action` 匹配完整操作代码，`source` 和 `target` 匹配字面片段（百分号和下划线无通配作用）；`from`、`to` 为Unix秒数，两端均包含，可以仅设置一端，开始时间不能晚于结束时间。多个条件同时满足才匹配。审计按事件ID倒序，包裹按寄出时间、ID倒序，保证同一秒内多条记录的排序明确。
|
||
|
||
示例：`/admin/audit?action=admin.delete&source=192.168.1.&from=1791158400&to=1791244800&page=1&page_size=20`。界面时间输入按管理员设备本地时区转换成Unix秒数；搜索和每页条数改变后回到第一页。
|
||
|
||
## 多入口与分享链接
|
||
|
||
`GET /policy` 的 `public_url` 返回当前访问入口，`access_urls` 返回所有配置入口。发布、重新生成取件码、管理员重新发布返回的 `url` 使用当前入口，`urls` 为可选分享入口列表 `[{label,url}]`；同一取件码在各入口下均有效，下载次数和期限共享。二维码随分享入口切换。
|
||
|
||
HTTP与HTTPS并存时，HTTP cookie使用 `_http` 后缀，HTTPS沿用原名称并设置Secure，防止同一域名的两种协议互相覆盖。不同入口的浏览器身份、登录状态及管理凭据存储可能独立；这不会改变文件及取件码。未知Origin、相互不一致的来源头和跨站请求仍被拒绝，不开放任意CORS。
|