文件与对象存储

本文面向需要接入文件中心、对象存储和上传下载链路的研发与运维团队。它说明文件中心支持的能力，以及上线时需要确认的存储配置。

当前已包含的能力

文件中心不只是简单上传，而是已经覆盖了完整文件链路：

• 文件列表与详情
• 直传上传凭证
• 代理上传
• 上传完成确认
• 下载地址生成
• 公开访问链接
• 文件删除、恢复、彻底删除
• 批量移动、批量删除、回收站处理
• 目录管理

接口形态

文件模块主要挂在：

/api/v1/files

控制器中已经覆盖文件生命周期相关接口，可作为前端文件中心联调和扩展开发的主要依据。

支持的存储提供商

当前环境变量已经预留：

• 阿里云 OSS
• 腾讯云 COS
• 七牛云

选择哪一个，主要由 STORAGE_PROVIDER 和对应密钥组决定。

配置建议

基础接入

可以先明确：

• 存储桶
• 公网访问域名
• 上传大小限制
• 允许的扩展名和 MIME 类型

生产配置

建议进一步确认：

• 私有/公开文件策略
• 签名 URL 有效期
• 回收站清理策略
• 项目是否要求走内网或专线存储

与前端的关系

前端文件中心页面已经依赖这套接口模型，因此部署时需要一起确认：

• 上传方式用直传还是代理
• 公开链接是否允许
• 生产域名和下载域名是否一致

常见问题

上传成功但预览失败

优先检查：

• STORAGE_PUBLIC_BASE_URL
• 对象存储桶公开访问策略
• 生成的对象 key 是否正确

代理上传报错

优先检查：

• 服务端上传大小限制
• 存储密钥配置
• 反向代理是否限制了请求体大小

检查清单

文件能力配置完成后，建议确认：

• 上传、下载、预览、删除、恢复和彻底删除流程均可用。
• STORAGE_PROVIDER、存储桶、公开访问域名和密钥配置正确。
• 前端展示的文件地址与生产域名或对象存储域名一致。
• 上传大小、MIME 类型和扩展名限制符合项目要求。