檔案分享

分享與公開發佈不同

分享使用隨機 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 時，可由所有者重新創建合適的分享，並撤銷舊記錄。