配额与空间

先看四个数

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 说明不代表每个用户都能修改额度。上传受配额拒绝时，保留状态码和发生时间，联系运营者；不要清理数据库或存储桶来绕过记账。见用户管理。