5.3 KiB
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 |
触发清理 |
上传清单示例：
{"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。