文件分享

分享与公开发布不同

分享使用随机 token，可设置口令、过期时间和次数。当前应用没有专用分享接收页面；接收者需使用运营者提供的 API 客户端交换 token，不能自行拼出 /s/ 链接。token 不应进入公开索引。无需口令的分享链接本身就是访问凭据；有口令也不等于文件内容被端到端加密。

当前个人中心没有分享创建和管理面板。以下管理操作需要文件所有者使用已认证 API；接收也需要 API 客户端。要让文件进入匿名目录，阅读公开发布。

创建与保存

POST /api/v1/files/{fileId}/shares，请求体可为 {}，或带以下字段：

| 字段 | 规则 | | --- | --- | | password | 非空字符串，UTF-8 最多 1024 字节；不设置则无需口令 | | expiresAt | 将来的规范 UTC ISO 时间，形如 YYYY-MM-DDTHH:mm:ss.sssZ | | maxDownloads | 1 到 2147483647 的整数；省略表示不设此项上限 |

成功为 201。创建响应中的原始 token 只在创建时返回，服务端保存其摘要；分享列表不会替你找回原始 token。安全保存创建结果，只发给预期接收者，不要记录在公开日志。

GET /api/v1/files/{fileId}/shares 查看该文件的分享记录；用返回记录的 shareId 调用 POST /api/v1/shares/{shareId}/revoke 撤销，成功为 204。shareId 和接收链接 token 是不同的值。

接收与次数消耗

接收者使用运营者提供的客户端，按需要输入口令并申请下载。客户端调用 POST /api/v1/shares/{token}/download-ticket；有口令时请求体含 password。票据签发时，share 的 downloadCount 就增加一次。

因此 maxDownloads 限制的是成功签发下载票据的次数，**不是完整下载到本地的次数**。即使之后连接中断，也可能已经消耗一次。不要通过预取或自动重试票据请求来探测分享是否可用。

拿到的 downloadGrant 有效 60 秒且只能消费一次；用它请求返回的 objectKey 对应对象。分享会在签发时选择当时的当前版本，不能把长期分享视为固定历史版本链接。

失效和撤销后的边界

口令错误、过期、次数耗尽、撤销或文件不可用通常统一返回 404 share unavailable，这是有意不透露具体原因。接收者应联系发送者核对，不要据此断言文件已删除。

撤销阻止后续票据签发，不保证撤回已经签发且仍有效的 grant，也不能删除别人已保存的副本。需要改变限制或丢失原始 token 时，可由所有者重新创建合适的分享，并撤销旧记录。