配额与空间

先看四个数

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 说明也不代表每个用户都能自行修改额度。如果你的上传被配额拒绝了，记下状态码和发生时间，联系运营者即可。不要尝试清理数据库或存储桶来绕过记账。详见用户管理。