文件与对象存储

文件中心把元数据放在 MySQL，把内容放在本地或云对象存储。访问统一经过文件 API，不应把上传目录或私有桶直接作为公共静态目录。

选择存储

类型	YAML 值	需要准备
本地	local	可写且持久化的 app.upload-path
阿里云 OSS	aliyun	endpoint、应用访问凭据、私有 bucket
MinIO	minio	endpoint、应用访问凭据、私有 bucket

配置位于当前环境的外置 YAML，例如：

art:
  storage:
    type: minio
    minio:
      endpoint: http://minio.internal:9000
      access-key: "填写应用访问账号"
      secret-key: "填写访问密钥"
      bucket-name: "填写私有桶名"

选中云存储会启用对应适配器并检查必填项。Docker 修改后执行 sh scripts/deploy.sh config，直接运行应用则重启，再实际验证上传与读取。

旧文件不会随配置自动迁移

每个资产保存 provider + bucket + object_key。更改默认提供方或 art.storage.object-key-prefix 只影响新上传，不搬迁旧对象。仍需访问历史云存储时，显式保留该提供方的 enabled: true 和原凭据；仅保存凭据不一定会加载旧适配器。

每个提供方当前支持一个桶；桶名、端点或本地根目录变化，应先安排停写、迁移对象和定位信息验证。不能把“配置加载成功”当成历史文件可读。

文件目录是业务目录。移动文件夹关系只更新数据库 folder_id，不会同步重命名对象键。

例：新文件改存本地，历史 MinIO 文件继续可读

在当前 YAML 的现有 art.storage 下合并以下设置，并保留 MinIO 的原 endpoint、账号、密钥与 bucket-name：

art:
  storage:
    type: local       # 新上传使用本地目录
    minio:
      enabled: true   # 继续加载适配器，用于读取旧 MinIO 对象

历史 OSS 文件对应设置 art.storage.aliyun.enabled: true。变更后分别上传一个新文件、读取一个旧文件，确认两条链路都成功。

使用随包生产 MinIO

1. 检查生产 YAML 的 MinIO 地址为 http://minio:9000，账号、密钥、桶名已填写。
2. 执行 sh scripts/deploy.sh minio，启动可选服务；dev 只启动 MySQL/Redis，update 不自动启动 MinIO。
3. 在 MinIO 准备私有桶及应用访问权限。9000 是对象 API，9001 是控制台，应用 endpoint 不填写控制台端口。
4. 将 art.storage.type 改为 minio，执行 sh scripts/deploy.sh config。
5. 验证上传、预览、下载和重启后读取。

本机 Java 开发使用 MinIO 时，另行准备可从本机访问的服务，填写实际地址；不要把生产容器内的 minio 服务名直接用于本机。

私有访问与公开链接

文件生命周期、可见性、所有者或业务引用共同决定访问。短期下载地址是凭证，不写入普通日志或长期保存作固定链接。

图片、PDF、纯文本及明确允许的音视频可内联预览；HTML、SVG、XML 等按附件策略处理。不要通过放开静态目录来绕过预览限制。

审批附件使用文件域公开端口，并额外检查实例参与范围、附件引用和字段可见性。被业务引用的文件不能随意通过文件中心清理。

上传与恢复

数据库与对象存储没有共享事务。上传先登记资产与会话，实际写对象后验证并激活；失败状态保留到恢复器清理。彻底删除也先持久化意图，再执行可重复的对象删除与结果回写。

恢复器处理过期上传与未完成清理。对象存储中断时先恢复连接并观察持久化状态，不直接把数据库行改为 ACTIVE 或 SUCCESS。上传大小还受 Spring multipart、业务票据及网关限制，三处需一致。

MinIO 的前端适配

Java 返回提供方 MINIO；共享前端当前没有对应类型、标签和筛选选项。启用后上传、预览、下载链路可以使用，但应同步扩展：

• src/types/api/files.d.ts 中的存储类型。
• 文件中心列表的提供方选项及显示映射。
• 预览、详情等使用提供方标签的位置。

文档说明差异不等于已经修改交付前端。其他提供方也以实际后端支持为准。

验证与定位

上传一个文件，验证私有访问、授权预览、下载、回收恢复和重启后持久化。云存储还需验证旧对象可读及无权限用户拒绝访问。

源码从 files/controller → files/service → files/mapper、art-common-oss 定位。恢复规则和多实例细节见 备份与升级 与随包 docs/guides/identity-storage.md。