私有文件中心

文件中心由 system.module/files 扩展提供，首次安装默认停用。在 /system/extensions 显式启用后，按角色用途分配文件动作权限和数据范围。

存储位置

文件通过认证接口读取，原始目录不作为静态资源公开。默认使用应用的 storage/app/files-private-v1，也可以指定稳定的绝对路径：

FILES_PRIVATE_ROOT=/srv/modu/files/v1
FILES_PRIVATE_HISTORY_ROOTS=[]

目录由运行服务的账户拥有并可写，文件目录放在持久卷上。多实例必须在相同的规范化绝对路径挂载同一个文件系统，并在目标环境验证其持久化语义。

上传、绑定与回收

上传产生的未绑定文件处于 staging 阶段；业务附件绑定后，读取还需要满足父记录授权通过父记录的授权检查。公告附件不能仅凭文件 ID 绕过公告的访问限制。

默认配置如下，实际值以当前扩展配置为准：

项目	默认值
单文件大小	20 MiB
multipart 总请求上限	21 MiB
逻辑容量	10 GiB
未绑定 staging 保留时间	24 小时
回收站保留时间	30 天

回收站文件仍占用逻辑容量。失败或取消的上传可能仍有待清理字节，因此预留容量不会在收到错误时立即全部释放。

清理任务每 15 分钟调度。停用扩展会暂停新访问、绑定和清理，并保留对象和待办；重新启用后继续。

更换目录

更换当前根根目录只影响新文件，旧文件仍引用原存储位置。保留旧目录，并将其绝对路径加入 FILES_PRIVATE_HISTORY_ROOTS。修改环境变量不会自动搬运已有文件。

备份需要同时覆盖数据库和所有仍被引用的私有目录。具体部署与恢复步骤以同版本核心源码中的 docs/FILE_STORAGE.md 为准。

常见问题

• 上传被拒绝：核对单文件大小、网关总请求上限、类型限制和逻辑容量。
• 文件不可见：核对文件动作权限、数据范围及父记录授权。
• 容量未释放：核对回收保留期、待清理任务和历史目录是否可访问。
• 扩展启用后仍不可用：检查迁移、扩展配置和服务日志。

逻辑容量与磁盘可用空间是两项指标；上传临时目录也需要足够空间。