配額與空間

先看四個數

GET /api/v1/quota 返回十進制字符串：limitBytes、reservedBytes、committedBytes、availableBytes。

availableBytes = limitBytes - reservedBytes - committedBytes

limitBytes 是帳戶上限；reservedBytes 是正在進行的上傳已預留的量；committedBytes 是完成後記帳的量。新上傳必須先拿到預留，不能只看當前檔案列表的大小決定是否還有空間。

一個不含真實帳戶資料的計算例子

假設上限 1000 位元組，已記帳 600 位元組，正在預留 200 位元組，可用就是 200 位元組。200 位元組的上傳完成後，預留轉入記帳；可用量不會因為進度條完成而額外增加。取消或到期釋放尚未完成的預留後，可用空間才相應回升。

數值使用字符串避免 JavaScript 大整數精度丟失；自行編寫客戶端時用 BigInt 計算，並在顯示層選擇 B、MiB 或 GiB。不要對位元組字符串進行字典序大小比較。

新使用者沒有統一的免費容量承諾

新帳戶上限由運營者的 DEFAULT_USER_QUOTA_BYTES 決定，管理員也可以修改單個使用者的額度。本地 setup 生成的開發設定使用 10737418240 位元組（10 GiB），它不是每個線上使用者必然獲得的容量，也不是商業套餐承諾。

預留、替換與真實磁盤

上傳意圖通常保留 15 分鐘；到期預留在配額相關處理時釋放，不應承諾瀏覽器倒計時歸零的同一瞬間已刷新。失敗取消也可能失敗，要重讀 /quota 並檢查後台狀態。

committedBytes 與物理對象位元組不是同一個指標。檔案版本、歷史對象或暫時未協調完成的存儲都可能影響物理佔用；不能把 committedBytes 直接當成存儲桶實際大小。替換上傳仍需完整新版本的預留；完成時按新版本完整大小增加 committedBytes，不扣除舊版本大小。舊版物件的存在也不構成自動回收空間的承諾。

管理員調整額度

PATCH /api/v1/admin/users/{userId}/quota 的 limitBytes 必須是非負十進制字符串。上限低於當前已記帳與已預留之和會返回 409。先核對目標帳戶與當前佔用，再調整；把上限設為 0 不等於刪除檔案。

當前個人中心沒有完整配額管理控件，API 說明不代表每個使用者都能修改額度。上傳受配額拒絕時，保留狀態碼和發生時間，聯繫運營者；不要清理資料庫或存儲桶來繞過記帳。見使用者管理。