配額與空間

先看四個數

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 文件也不代表每位使用者都有權限修改額度。上傳被配額拒絕時，保留好狀態碼和發生時間，聯繫運營者處理就好；請不要自行清理資料庫或存儲桶來繞過記帳。相關管理操作請見使用者管理。